Document configuration and build process (#362)

config/babel.dev.js

@@ -8,19 +8,31 @@
  */
 
 module.exports = {
+  // Don't try to find .babelrc because we want to force this configuration.
   babelrc: false,
+  // This is a feature of `babel-loader` for webpack (not Babel itself).
+  // It enables caching results in OS temporary directory for faster rebuilds.
   cacheDirectory: true,
   presets: [
+    // let, const, destructuring, classes, modules
     require.resolve('babel-preset-es2015'),
+    // exponentiation
     require.resolve('babel-preset-es2016'),
+    // JSX, Flow
     require.resolve('babel-preset-react')
   ],
   plugins: [
+    // function x(a, b, c,) { }
     require.resolve('babel-plugin-syntax-trailing-function-commas'),
+    // await fetch()
     require.resolve('babel-plugin-syntax-async-functions'),
+    // class { handleClick = () => { } }
     require.resolve('babel-plugin-transform-class-properties'),
+    // { ...todo, completed: true }
     require.resolve('babel-plugin-transform-object-rest-spread'),
+    // function* () { yield 42; yield 43; }
     require.resolve('babel-plugin-transform-regenerator'),
+    // Polyfills the runtime needed for async/await and generators
     [require.resolve('babel-plugin-transform-runtime'), {
       helpers: false,
       polyfill: false,

config/babel.prod.js

@@ -8,23 +8,34 @@
  */
 
 module.exports = {
+  // Don't try to find .babelrc because we want to force this configuration.
   babelrc: false,
   presets: [
+    // let, const, destructuring, classes, modules
     require.resolve('babel-preset-es2015'),
+    // exponentiation
     require.resolve('babel-preset-es2016'),
+    // JSX, Flow
     require.resolve('babel-preset-react')
   ],
   plugins: [
+    // function x(a, b, c,) { }
     require.resolve('babel-plugin-syntax-trailing-function-commas'),
+    // await fetch()
     require.resolve('babel-plugin-syntax-async-functions'),
+    // class { handleClick = () => { } }
     require.resolve('babel-plugin-transform-class-properties'),
+    // { ...todo, completed: true }
     require.resolve('babel-plugin-transform-object-rest-spread'),
-    require.resolve('babel-plugin-transform-react-constant-elements'),
+    // function* () { yield 42; yield 43; }
     require.resolve('babel-plugin-transform-regenerator'),
+    // Polyfills the runtime needed for async/await and generators
     [require.resolve('babel-plugin-transform-runtime'), {
       helpers: false,
       polyfill: false,
       regenerator: true
-    }]
+    }],
+    // Optimization: hoist JSX that never changes out of render()
+    require.resolve('babel-plugin-transform-react-constant-elements')
   ]
 };

config/env.js

@@ -7,6 +7,9 @@
  * of patent rights can be found in the PATENTS file in the same directory.
  */
 
+// Grab NODE_ENV and REACT_APP_* environment variables and prepare them to be
+// injected into the application via DefinePlugin in Webpack configuration.
+
 var REACT_APP = /^REACT_APP_/i;
 var NODE_ENV = JSON.stringify(process.env.NODE_ENV || 'development');
 

config/polyfills.js

@@ -6,4 +6,5 @@ if (typeof Promise === 'undefined') {
   window.Promise = require('promise/lib/es6-extensions.js');
 }
 
+// fetch() polyfill for making API calls.
 require('whatwg-fetch');

config/webpack.config.dev.js

@@ -16,22 +16,56 @@ var WatchMissingNodeModulesPlugin = require('../scripts/utils/WatchMissingNodeMo
 var paths = require('./paths');
 var env = require('./env');
 
+// This is the development configuration.
+// It is focused on developer experience and fast rebuilds.
+// The production configuration is different and lives in a separate file.
 module.exports = {
+  // This makes the bundle appear split into separate modules in the devtools.
+  // We don't use source maps here because they can be confusing:
+  // https://github.com/facebookincubator/create-react-app/issues/343#issuecomment-237241875
+  // You may want 'cheap-module-source-map' instead if you prefer source maps.
   devtool: 'eval',
+  // These are the "entry points" to our application.
+  // This means they will be the "root" imports that are included in JS bundle.
+  // The first two entry points enable "hot" CSS and auto-refreshes for JS.
   entry: [
+    // Include WebpackDevServer client. It connects to WebpackDevServer via
+    // sockets and waits for recompile notifications. When WebpackDevServer
+    // recompiles, it sends a message to the client by socket. If only CSS
+    // was changed, the app reload just the CSS. Otherwise, it will refresh.
+    // The "?/" bit at the end tells the client to look for the socket at
+    // the root path, i.e. /sockjs-node/. Otherwise visiting a client-side
+    // route like /todos/42 would make it wrongly request /todos/42/sockjs-node.
+    // The socket server is a part of WebpackDevServer which we are using.
+    // The /sockjs-node/ path I'm referring to is hardcoded in WebpackDevServer.
     require.resolve('webpack-dev-server/client') + '?/',
+    // Include Webpack hot module replacement runtime. Webpack is pretty
+    // low-level so we need to put all the pieces together. The runtime listens
+    // to the events received by the client above, and applies updates (such as
+    // new CSS) to the running application.
     require.resolve('webpack/hot/dev-server'),
+    // We ship a few polyfills by default.
     require.resolve('./polyfills'),
+    // Finally, this is your app's code:
     path.join(paths.appSrc, 'index')
+    // We include the app code last so that if there is a runtime error during
+    // initialization, it doesn't blow up the WebpackDevServer client, and
+    // changing JS code would still trigger a refresh.
   ],
   output: {
     // Next line is not used in dev but WebpackDevServer crashes without it:
     path: paths.appBuild,
+    // Add /* filename */ comments to generated require()s in the output.
     pathinfo: true,
+    // This does not produce a real file. It's just the virtual path that is
+    // served by WebpackDevServer in development. This is the JS bundle
+    // containing code from all our entry points, and the Webpack runtime.
     filename: 'static/js/bundle.js',
+    // In development, we always serve from the root. This makes config easier.
     publicPath: '/'
   },
   resolve: {
+    // These are the reasonable defaults supported by the Node ecosystem.
     extensions: ['.js', '.json', ''],
     alias: {
       // This `alias` section can be safely removed after ejection.
@@ -45,11 +79,16 @@ module.exports = {
       'babel-runtime/regenerator': require.resolve('babel-runtime/regenerator')
     }
   },
+  // Resolve loaders (webpack plugins for CSS, images, transpilation) from the
+  // directory of `react-scripts` itself rather than the project directory.
+  // You can remove this after ejecting.
   resolveLoader: {
     root: paths.ownNodeModules,
     moduleTemplates: ['*-loader']
   },
   module: {
+    // First, run the linter.
+    // It's important to do this before Babel processes the JS.
     preLoaders: [
       {
         test: /\.js$/,
@@ -58,22 +97,33 @@ module.exports = {
       }
     ],
     loaders: [
+      // Process JS with Babel.
       {
         test: /\.js$/,
         include: paths.appSrc,
         loader: 'babel',
         query: require('./babel.dev')
       },
+      // "postcss" loader applies autoprefixer to our CSS.
+      // "css" loader resolves paths in CSS and adds assets as dependencies.
+      // "style" loader turns CSS into JS modules that inject <style> tags.
+      // In production, we use a plugin to extract that CSS to a file, but
+      // in development "style" loader enables hot editing of CSS.
       {
         test: /\.css$/,
         include: [paths.appSrc, paths.appNodeModules],
         loader: 'style!css!postcss'
       },
+      // JSON is not enabled by default in Webpack but both Node and Browserify
+      // allow it implicitly so we also enable it.
       {
         test: /\.json$/,
         include: [paths.appSrc, paths.appNodeModules],
         loader: 'json'
       },
+      // "file" loader makes sure those assets get served by WebpackDevServer.
+      // When you `import` an asset, you get its (virtual) filename.
+      // In production, they would get copied to the `build` folder.
       {
         test: /\.(jpg|png|gif|eot|svg|ttf|woff|woff2)(\?.*)?$/,
         include: [paths.appSrc, paths.appNodeModules],
@@ -82,6 +132,8 @@ module.exports = {
           name: 'static/media/[name].[ext]'
         }
       },
+      // "url" loader works just like "file" loader but it also embeds
+      // assets smaller than specified size as data URLs to avoid requests.
       {
         test: /\.(mp4|webm)(\?.*)?$/,
         include: [paths.appSrc, paths.appNodeModules],
@@ -93,32 +145,44 @@ module.exports = {
       }
     ]
   },
+  // Point ESLint to our predefined config.
   eslint: {
     configFile: path.join(__dirname, 'eslint.js'),
     useEslintrc: false
   },
+  // We use PostCSS for autoprefixing only.
   postcss: function() {
     return [
       autoprefixer({
         browsers: [
           '>1%',
           'last 4 versions',
           'Firefox ESR',
-          'not ie < 9',
+          'not ie < 9', // React doesn't support IE8 anyway
         ]
       }),
     ];
   },
   plugins: [
+    // Generates an `index.html` file with the <script> injected.
     new HtmlWebpackPlugin({
       inject: true,
       template: paths.appHtml,
       favicon: paths.appFavicon,
     }),
+    // Makes some environment variables available to the JS code, for example:
+    // if (process.env.NODE_ENV === 'development') { ... }. See `env.js`.
     new webpack.DefinePlugin(env),
-    // Note: only CSS is currently hot reloaded
+    // This is necessary to emit hot updates (currently CSS only):
     new webpack.HotModuleReplacementPlugin(),
+    // Watcher doesn't work well if you mistype casing in a path so we use
+    // a plugin that prints an error when you attempt to do this.
+    // See https://github.com/facebookincubator/create-react-app/issues/240
     new CaseSensitivePathsPlugin(),
+    // If you require a missing module and then `npm install` it, you still have
+    // to restart the development server for Webpack to discover it. This plugin
+    // makes the discovery automatic so you don't have to restart.
+    // See https://github.com/facebookincubator/create-react-app/issues/186
     new WatchMissingNodeModulesPlugin(paths.appNodeModules)
   ]
 };