# Advanced topics

This section helps you to dig deeper into the project.

## Important files and directories

| Filename | Description |
|----------------|-------------|
| `dist/` | Build output |
| `dist/website/` | Compiled web server ready to run by itself or hosted on IIS |
| `dist/website/public/` | Bundled content and static assets |
| `dist/packages/web.zip` | Web server packed by MSDeploy and ready to deploy to Azure Web Apps |
| [`src/app.js`](src/app.js) | Depends on `NODE_ENV`, development mode serves content directly from [`web/`](web/), production mode serves content from `dist/website/public` |
| [`src/controllers/api.js`](src/controllers/api.js) | RESTful API hosted at [http://localhost/api](http://localhost/api) |
| [`src/iisnode.yml`](src/iisnode.yml) | [iisnode configuration](https://tomasz.janczuk.org/2012/05/yaml-configuration-support-in-iisnode.html) |
| [`src/web.config`](src/web.config) | `Web.config` for hosting under Azure Web App and IIS |
| [`scripts/`](scripts) | Gulpfile for building and packing the project |
| [`web/files/`](web/files) | Asset source files |
| [`web/src/`](web/src) | JavaScript source files |

## NPM scripts

To help building the project, there are several NPM scripts.

| Task name     | Description |
| ------------- | ----------- |
| `build`       | Start the build process |
| `deploy`      | Deploy the website to Azure Web App |
| `host:dev`    | Host a Webpack development server and bundle on-the-fly |
| `host:prod`   | Host a production server using pre-bundled files at `dist/website/` |
| `pack`        | Use MSDeploy to pack everything at `dist/website/` into `dist/packages/web.zip` |

## Building the website

To build the website, run `npm run build`. The build output will be located at `dist/website/`.

* Specify build favor by either
  * Set environment variable `NODE_ENV` to `production`, or
  * Run `npm run build -- --build production`
* Specify bundler by either
  * Set environment variable `BUNDLER` to `rollup` or `webpack`, or
  * Run `npm run build -- --bundler rollup`

> Currently, the build favor (either `development` or `production`) is only used by [`transform-node-env-inline`](https://babeljs.io/docs/plugins/transform-node-env-inline/). It helps reducing bundle size by excluding developer-friendly error messages in production build.

### What the build do

Source code can be found at [`scripts/build.js`](scripts/build.js).

* Copy server code from [`src/`](src) to `dist/website/`, exclude `node_modules` folder
  * After copy complete, will run `npm install --ignore-scripts --only=production` to install fresh packages
* Bundle source files from [`web/src/`](web/src) to `dist/website/public/dist/bundle.js`
  * Will use existing npm packages from `web/node_modules`
* Copy static assets from [`web/files/`](web/files) to `dist/website/public/`
  * Will minify image with [`gulp-imagemin`](https://www.npmjs.com/package/gulp-imagemin/)
  * Will minify HTML with [`gulp-htmlmin`](https://www.npmjs.com/package/gulp-htmlmin/)

## Webpack configuration

The configuration file is located at [`web/webpack.config.js`](web/webpack.config.js). It controls how files are getting bundled into a monolithic `dist/website/public/js/bundle.js`.

* [`web/src/*.js`](web/src) and [`web/src/*.jsx`](web/src)
  * Bundled by [`babel-loader`](https://www.npmjs.com/package/babel-loader)
    * Enable React JSX by [`preset-react`](https://babeljs.io/docs/plugins/preset-react/)
    * Enable ES2015 by [`preset-es2015`](http://babeljs.io/docs/plugins/preset-es2015/)
    * Escape ES3 reserved keywords
      * [`transform-es3-member-expression-literals`](https://babeljs.io/docs/plugins/transform-es3-member-expression-literals/)
      * [`transform-es3-property-literals`](https://babeljs.io/docs/plugins/transform-es3-property-literals/)
    * Transform `process.env.NODE_ENV` into `"development"` or `"production"` with [`transform-node-env-inline`](https://babeljs.io/docs/plugins/transform-node-env-inline/)
  * Entrypoint is [`web/src/index.js`](web/src/index.js)
* [`web/src/*.css`](web/src) and [`web/src/*.less`](web/src)
  * Bundled by [`less-loader`](https://www.npmjs.com/package/less-loader), then
  * [`css-loader`](https://www.npmjs.com/package/css-loader), then
  * [`style-loader`](https://www.npmjs.com/package/style-loader)

> We use rollup.js for bundling in production build. Since rollup.js currently only support single entrypoint and not code-splitting. If you want to enable these features, please build with `--bundler webpack` to use Webpack as bundler in production build.

## Webpack development mode configuration

When running Webpack development server, additional configurations are required, for example, hot module replacement.

When running under development server, we will add the following to [`webpack.config.js`](web/webpack.config.js):

* Serve assets from [`web/files/`](web/files/)
* Enable [source map](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/#toc-tools)
  * Use absolute path for source map for compatibility with Edge
* Also write a copy of `bundle.js` to `dist/webpack/bundle.js` for debugging purpose
* Hot module replacement
  * Support React component with [`react-hot`](https://github.com/gaearon/react-hot-loader) loader

## Rollup.js configuration

The configuration file is located at [`web/rollup.config.js`](web/rollup.config.js). It is similar to Webpack configuration.

* TBD: ~~[`web/src/*.less`](web/src)~~
  * ~~Bundled by [`rollup-plugin-less`](https://npmjs.com/package/rollup-plugin-less)~~
    * ~~Inject CSS styles into `<head>`~~
* [`web/src/*.js`](web/src)
  * Bundled by [`rollup-plugin-babel`](https://www.npmjs.com/package/rollup-plugin-babel)
    * Enable ES2015 with [`preset-es2015`](http://babeljs.io/docs/plugins/preset-es2015/)
    * Enable React JSX with [`preset-react`](https://babeljs.io/docs/plugins/preset-react/)
    * Escape ES3 reserved keywords
      * [`transform-es3-member-expression-literals`](https://babeljs.io/docs/plugins/transform-es3-member-expression-literals/)
      * [`transform-es3-property-literals`](https://babeljs.io/docs/plugins/transform-es3-property-literals/)
    * Entrypoint is [`web/src/index.js`](web/src/index.js)
  * Bundled by [`rollup-plugin-commonjs`](https://www.npmjs.com/package/rollup-plugin-commonjs)
    * Convert CommonJS `require` statement into ES2015 `import` statement, including [`fbjs`](https://npmjs.com/package/fbjs), [`object-assign`](https://npmjs.com/package/object-assign), [`react`](https://npmjs.com/package/react), and [`react-dom`](https://npmjs.com/package/react-dom)
  * Bundled by [`rollup-plugin-replace`](https://www.npmjs.com/package/rollup-plugin-replace)
    * String-replace `process.env.NODE_ENV` into `"development"` or `"production"`
  * Bundled by [`rollup-plugin-node-resolve`](https://www.npmjs.com/package/rollup-plugin-node-resolve)
    * Bundle dependencies into `bundle.js`

## Enable source map output in production mode

Run `npm run build -- --sourcemap true` to output `dist/website/public/js/bundle.js.map` for debugging purpose.

## Packing with MSDeploy

To pack the content and production server, `npm run pack`.

It will create a MSDeploy ZIP file that can be deployed to any IIS server, including [Azure Web App](https://azure.microsoft.com/en-us/services/app-service/web/). This ZIP file contains Express server code and website contents in production favor.

Additional parameters added to MSDeploy ZIP file:

| name                     | defaultValue       | tags     | kind           | scope    |
|--------------------------|--------------------|----------|----------------|----------|
| IIS Web Application Name | `Default Web Site` | `IisApp` | `ProviderPath` | `IisApp` |

Before packing the project, make sure your current build is up-to-date, or run `npm run build`.

> [MSDeploy](https://www.iis.net/downloads/microsoft/web-deploy) is only supported on Windows.

## iisnode configuration

We have overrode some defaults in [`iisnode.yml`](iisnode.yml).

* `debuggingEnabled` is set to `false`
* `devErrorsEnabled` is set to `false`
* `loggingEnabled` is set to `false`
* `nodeProcessCountPerApplication` is set to `0`
  * One worker process per CPU
* `node_env` is set to `production`
  * We assume hosting the site in IIS is always in production mode
  * Express is faster when environment variable `NODE_ENV` is set to `production`, details [here](http://apmblog.dynatrace.com/2015/07/22/the-drastic-effects-of-omitting-node_env-in-your-express-js-applications/)