Improve `npm run eject` description

Created by: btnwtn

I feel as if the description for npm run eject is incredibly vague. eject does more than just removing the tool and that should be explained to the user.

config/jest/CSSStub.js

+// @remove-on-eject-begin
 /**
  * Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
  *
@@ -7,5 +8,6 @@
  *
  * @flow
  */
+// @remove-on-eject-end
 
 module.exports = {};

config/jest/FileStub.js

+// @remove-on-eject-begin
 /**
  * Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
  *
@@ -7,5 +8,6 @@
  *
  * @flow
  */
+// @remove-on-eject-end
 
 module.exports = "test-file-stub";

config/jest/transform.js

+// @remove-on-eject-begin
 /**
  * Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
  *
@@ -5,6 +6,7 @@
  * LICENSE file in the root directory of this source tree. An additional grant
  * of patent rights can be found in the PATENTS file in the same directory.
  */
+// @remove-on-eject-end
 
 const babelDev = require('../babel.dev');
 const babelJest = require('babel-jest');

config/babel.dev.js

+// @remove-on-eject-begin
 /**
  * Copyright (c) 2015-present, Facebook, Inc.
  * All rights reserved.
@@ -6,37 +7,42 @@
  * LICENSE file in the root directory of this source tree. An additional grant
  * of patent rights can be found in the PATENTS file in the same directory.
  */
+// @remove-on-eject-end
+
+var path = require('path');
+var findCacheDir = require('find-cache-dir');
 
 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,
+  // It enables caching results in ./node_modules/.cache/react-scripts/
+  // directory for faster rebuilds.
+  cacheDirectory: findCacheDir({ name: 'react-scripts' }),
   presets: [
-    // let, const, destructuring, classes, modules
-    require.resolve('babel-preset-es2015'),
-    // exponentiation
-    require.resolve('babel-preset-es2016'),
+    // Latest stable ECMAScript features
+    require.resolve('babel-preset-latest'),
     // 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'),
+    [require.resolve('babel-plugin-transform-regenerator'), {
+      // Async functions are converted to generators by babel-preset-latest
+      async: false
+    }],
     // Polyfills the runtime needed for async/await and generators
     [require.resolve('babel-plugin-transform-runtime'), {
       helpers: false,
       polyfill: false,
-      regenerator: true
+      regenerator: true,
+      // Resolve the Babel runtime relative to the config.
+      // You can safely remove this after ejecting:
+      moduleName: path.dirname(require.resolve('babel-runtime/package'))
     }]
   ]
 };

config/babel.prod.js

+// @remove-on-eject-begin
 /**
  * Copyright (c) 2015-present, Facebook, Inc.
  * All rights reserved.
@@ -6,36 +7,43 @@
  * LICENSE file in the root directory of this source tree. An additional grant
  * of patent rights can be found in the PATENTS file in the same directory.
  */
+// @remove-on-eject-end
+
+var path = require('path');
 
 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'),
+    // Latest stable ECMAScript features
+    require.resolve('babel-preset-latest'),
     // 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'),
+    [require.resolve('babel-plugin-transform-regenerator'), {
+      // Async functions are converted to generators by babel-preset-latest
+      async: false
+    }],
     // Polyfills the runtime needed for async/await and generators
     [require.resolve('babel-plugin-transform-runtime'), {
       helpers: false,
       polyfill: false,
-      regenerator: true
+      regenerator: true,
+      // Resolve the Babel runtime relative to the config.
+      // You can safely remove this after ejecting:
+      moduleName: path.dirname(require.resolve('babel-runtime/package'))
     }],
     // Optimization: hoist JSX that never changes out of render()
-    require.resolve('babel-plugin-transform-react-constant-elements')
+    // Disabled because of issues:
+    // * https://github.com/facebookincubator/create-react-app/issues/525
+    // * https://phabricator.babeljs.io/search/query/pCNlnC2xzwzx/
+    // TODO: Enable again when these issues are resolved.
+    // require.resolve('babel-plugin-transform-react-constant-elements')
   ]
 };

config/env.js

+// @remove-on-eject-begin
 /**
  * Copyright (c) 2015-present, Facebook, Inc.
  * All rights reserved.
@@ -6,6 +7,7 @@
  * LICENSE file in the root directory of this source tree. An additional grant
  * of patent rights can be found in the PATENTS file in the same directory.
  */
+// @remove-on-eject-end
 
 // Grab NODE_ENV and REACT_APP_* environment variables and prepare them to be
 // injected into the application via DefinePlugin in Webpack configuration.

config/eslint.js

+// @remove-on-eject-begin
 /**
  * Copyright (c) 2015-present, Facebook, Inc.
  * All rights reserved.
@@ -6,6 +7,7 @@
  * LICENSE file in the root directory of this source tree. An additional grant
  * of patent rights can be found in the PATENTS file in the same directory.
  */
+// @remove-on-eject-end
 
 // Inspired by https://github.com/airbnb/javascript but less opinionated.
 
@@ -21,7 +23,7 @@ module.exports = {
 
   parser: 'babel-eslint',
 
-  // import plugin is termporarily disabled, scroll below to see why
+  // import plugin is temporarily disabled, scroll below to see why
   plugins: [/*'import', */'flowtype', 'jsx-a11y', 'react'],
 
   env: {
@@ -45,7 +47,7 @@ module.exports = {
   settings: {
     'import/ignore': [
       'node_modules',
-      '\\.(json|css|jpg|png|gif|eot|svg|ttf|woff|woff2|mp4|webm)$',
+      '\\.(json|css|jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm)$',
     ],
     'import/extensions': ['.js'],
     'import/resolver': {
@@ -62,7 +64,6 @@ module.exports = {
     'dot-location': ['warn', 'property'],
     eqeqeq: ['warn', 'allow-null'],
     'guard-for-in': 'warn',
-    'new-cap': ['warn', { newIsCap: true }],
     'new-parens': 'warn',
     'no-array-constructor': 'warn',
     'no-caller': 'warn',
@@ -116,13 +117,13 @@ module.exports = {
       'LabeledStatement',
       'WithStatement',
     ],
-    'no-return-assign': 'warn',
     'no-script-url': 'warn',
     'no-self-assign': 'warn',
     'no-self-compare': 'warn',
     'no-sequences': 'warn',
     'no-shadow-restricted-names': 'warn',
     'no-sparse-arrays': 'warn',
+    'no-template-curly-in-string': 'warn',
     'no-this-before-super': 'warn',
     'no-throw-literal': 'warn',
     'no-undef': 'warn',

config/paths.js

+// @remove-on-eject-begin
 /**
  * Copyright (c) 2015-present, Facebook, Inc.
  * All rights reserved.
@@ -6,63 +7,70 @@
  * LICENSE file in the root directory of this source tree. An additional grant
  * of patent rights can be found in the PATENTS file in the same directory.
  */
-
-// TODO: we can split this file into several files (pre-eject, post-eject, test)
-// and use those instead. This way we don't need to branch here.
+// @remove-on-eject-end
 
 var path = require('path');
 
-// True after ejecting, false when used as a dependency
-var isEjected = (
-  path.resolve(path.join(__dirname, '..')) ===
-  path.resolve(process.cwd())
-);
+// We support resolving modules according to `NODE_PATH`.
+// This lets you use absolute paths in imports inside large monorepos:
+// https://github.com/facebookincubator/create-react-app/issues/253.
 
-// Are we developing create-react-app locally?
-var isInCreateReactAppSource = (
-  process.argv.some(arg => arg.indexOf('--debug-template') > -1)
-);
+// It works similar to `NODE_PATH` in Node itself:
+// https://nodejs.org/api/modules.html#modules_loading_from_the_global_folders
 
-function resolveOwn(relativePath) {
-  return path.resolve(__dirname, relativePath);
-}
+// We will export `nodePaths` as an array of absolute paths.
+// It will then be used by Webpack configs.
+// Jest doesn’t need this because it already handles `NODE_PATH` out of the box.
+
+var nodePaths = (process.env.NODE_PATH || '')
+  .split(process.platform === 'win32' ? ';' : ':')
+  .filter(Boolean)
+  .map(p => path.resolve(p));
 
 function resolveApp(relativePath) {
   return path.resolve(relativePath);
 }
 
-if (isInCreateReactAppSource) {
-  // create-react-app development: we're in ./config/
-  module.exports = {
-    appBuild: resolveOwn('../build'),
-    appHtml: resolveOwn('../template/index.html'),
-    appFavicon: resolveOwn('../template/favicon.ico'),
-    appPackageJson: resolveOwn('../package.json'),
-    appSrc: resolveOwn('../template/src'),
-    appNodeModules: resolveOwn('../node_modules'),
-    ownNodeModules: resolveOwn('../node_modules')
-  };
-} else if (!isEjected) {
-  // before eject: we're in ./node_modules/react-scripts/config/
-  module.exports = {
-    appBuild: resolveApp('build'),
-    appHtml: resolveApp('index.html'),
-    appFavicon: resolveApp('favicon.ico'),
-    appPackageJson: resolveApp('package.json'),
-    appSrc: resolveApp('src'),
-    appNodeModules: resolveApp('node_modules'),
-    // this is empty with npm3 but node resolution searches higher anyway:
-    ownNodeModules: resolveOwn('../node_modules')
-  };
-} else {
-  // after eject: we're in ./config/
-  module.exports = {
-    appBuild: resolveApp('build'),
-    appHtml: resolveApp('index.html'),
-    appFavicon: resolveApp('favicon.ico'),
-    appPackageJson: resolveApp('package.json'),
-    appSrc: resolveApp('src'),
-    appNodeModules: resolveApp('node_modules'),
-    ownNodeModules: resolveApp('node_modules')
-  };
+// config after eject: we're in ./config/
+module.exports = {
+  appBuild: resolveApp('build'),
+  appHtml: resolveApp('index.html'),
+  appPackageJson: resolveApp('package.json'),
+  appSrc: resolveApp('src'),
+  testsSetup: resolveApp('src/setupTests.js'),
+  appNodeModules: resolveApp('node_modules'),
+  ownNodeModules: resolveApp('node_modules'),
+  nodePaths: nodePaths
+};
+
+// @remove-on-eject-begin
+function resolveOwn(relativePath) {
+  return path.resolve(__dirname, relativePath);
 }
+
+// config before eject: we're in ./node_modules/react-scripts/config/
+module.exports = {
+  appBuild: resolveApp('build'),
+  appHtml: resolveApp('index.html'),
+  appPackageJson: resolveApp('package.json'),
+  appSrc: resolveApp('src'),
+  testsSetup: resolveApp('src/setupTests.js'),
+  appNodeModules: resolveApp('node_modules'),
+  // this is empty with npm3 but node resolution searches higher anyway:
+  ownNodeModules: resolveOwn('../node_modules'),
+  nodePaths: nodePaths
+};
+// @remove-on-eject-end
+
+// @remove-on-publish-begin
+module.exports = {
+  appBuild: resolveOwn('../build'),
+  appHtml: resolveOwn('../template/index.html'),
+  appPackageJson: resolveOwn('../package.json'),
+  appSrc: resolveOwn('../template/src'),
+  testsSetup: resolveOwn('../template/src/setupTests.js'),
+  appNodeModules: resolveOwn('../node_modules'),
+  ownNodeModules: resolveOwn('../node_modules'),
+  nodePaths: nodePaths
+};
+// @remove-on-publish-end

config/polyfills.js

+// @remove-on-eject-begin
+/**
+ * Copyright (c) 2015-present, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree. An additional grant
+ * of patent rights can be found in the PATENTS file in the same directory.
+ */
+// @remove-on-eject-end
+
 if (typeof Promise === 'undefined') {
   // Rejection tracking prevents a common issue where React gets into an
   // inconsistent state due to an error, but it gets swallowed by a Promise,
@@ -8,3 +19,7 @@ if (typeof Promise === 'undefined') {
 
 // fetch() polyfill for making API calls.
 require('whatwg-fetch');
+
+// Object.assign() is commonly used with React.
+// It will use the native implementation if it's present and isn't buggy.
+Object.assign = require('object-assign');

config/webpack.config.dev.js

+// @remove-on-eject-begin
 /**
  * Copyright (c) 2015-present, Facebook, Inc.
  * All rights reserved.
@@ -6,6 +7,7 @@
  * LICENSE file in the root directory of this source tree. An additional grant
  * of patent rights can be found in the PATENTS file in the same directory.
  */
+// @remove-on-eject-end
 
 var path = require('path');
 var autoprefixer = require('autoprefixer');
@@ -65,18 +67,21 @@ module.exports = {
     publicPath: '/'
   },
   resolve: {
+    // This allows you to set a fallback for where Webpack should look for modules.
+    // We read `NODE_PATH` environment variable in `paths.js` and pass paths here.
+    // We use `fallback` instead of `root` because we want `node_modules` to "win"
+    // if there any conflicts. This matches Node resolution mechanism.
+    // https://github.com/facebookincubator/create-react-app/issues/253
+    fallback: paths.nodePaths,
     // These are the reasonable defaults supported by the Node ecosystem.
-    extensions: ['.js', '.json', ''],
+    // We also include JSX as a common component filename extension to support
+    // some tools, although we do not recommend using it, see:
+    // https://github.com/facebookincubator/create-react-app/issues/290
+    extensions: ['.js', '.json', '.jsx', ''],
     alias: {
-      // This `alias` section can be safely removed after ejection.
-      // We do this because `babel-runtime` may be inside `react-scripts`,
-      // so when `babel-plugin-transform-runtime` imports it, it will not be
-      // available to the app directly. This is a temporary solution that lets
-      // us ship support for generators. However it is far from ideal, and
-      // if we don't have a good solution, we should just make `babel-runtime`
-      // a dependency in generated projects.
-      // See https://github.com/facebookincubator/create-react-app/issues/255
-      'babel-runtime/regenerator': require.resolve('babel-runtime/regenerator')
+      // Support React Native Web
+      // https://www.smashingmagazine.com/2016/08/a-glimpse-into-the-future-with-react-native-for-web/
+      'react-native': 'react-native-web'
     }
   },
   // Resolve loaders (webpack plugins for CSS, images, transpilation) from the
@@ -91,7 +96,7 @@ module.exports = {
     // It's important to do this before Babel processes the JS.
     preLoaders: [
       {
-        test: /\.js$/,
+        test: /\.(js|jsx)$/,
         loader: 'eslint',
         include: paths.appSrc,
       }
@@ -99,7 +104,7 @@ module.exports = {
     loaders: [
       // Process JS with Babel.
       {
-        test: /\.js$/,
+        test: /\.(js|jsx)$/,
         include: paths.appSrc,
         loader: 'babel',
         query: require('./babel.dev')
@@ -111,36 +116,51 @@ module.exports = {
       // 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],
+        test: /\.(ico|jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2)(\?.*)?$/,
+        exclude: /\/favicon.ico$/,
         loader: 'file',
         query: {
-          name: 'static/media/[name].[ext]'
+          name: 'static/media/[name].[hash:8].[ext]'
+        }
+      },
+      // A special case for favicon.ico to place it into build root directory.
+      {
+        test: /\/favicon.ico$/,
+        include: [paths.appSrc],
+        loader: 'file',
+        query: {
+          name: 'favicon.ico?[hash:8]'
         }
       },
       // "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],
         loader: 'url',
         query: {
           limit: 10000,
-          name: 'static/media/[name].[ext]'
+          name: 'static/media/[name].[hash:8].[ext]'
+        }
+      },
+      // "html" loader is used to process template page (index.html) to resolve
+      // resources linked with <link href="./relative/path"> HTML tags.
+      {
+        test: /\.html$/,
+        loader: 'html',
+        query: {
+          attrs: ['link:href'],
         }
       }
     ]
@@ -168,7 +188,6 @@ module.exports = {
     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`.

config/webpack.config.prod.js

+// @remove-on-eject-begin
 /**
  * Copyright (c) 2015-present, Facebook, Inc.
  * All rights reserved.
@@ -6,6 +7,7 @@
  * LICENSE file in the root directory of this source tree. An additional grant
  * of patent rights can be found in the PATENTS file in the same directory.
  */
+// @remove-on-eject-end
 
 var path = require('path');
 var autoprefixer = require('autoprefixer');
@@ -60,18 +62,21 @@ module.exports = {
     publicPath: publicPath
   },
   resolve: {
+    // This allows you to set a fallback for where Webpack should look for modules.
+    // We read `NODE_PATH` environment variable in `paths.js` and pass paths here.
+    // We use `fallback` instead of `root` because we want `node_modules` to "win"
+    // if there any conflicts. This matches Node resolution mechanism.
+    // https://github.com/facebookincubator/create-react-app/issues/253
+    fallback: paths.nodePaths,
     // These are the reasonable defaults supported by the Node ecosystem.
-    extensions: ['.js', '.json', ''],
+    // We also include JSX as a common component filename extension to support
+    // some tools, although we do not recommend using it, see:
+    // https://github.com/facebookincubator/create-react-app/issues/290
+    extensions: ['.js', '.json', '.jsx', ''],
     alias: {
-      // This `alias` section can be safely removed after ejection.
-      // We do this because `babel-runtime` may be inside `react-scripts`,
-      // so when `babel-plugin-transform-runtime` imports it, it will not be
-      // available to the app directly. This is a temporary solution that lets
-      // us ship support for generators. However it is far from ideal, and
-      // if we don't have a good solution, we should just make `babel-runtime`
-      // a dependency in generated projects.
-      // See https://github.com/facebookincubator/create-react-app/issues/255
-      'babel-runtime/regenerator': require.resolve('babel-runtime/regenerator')
+      // Support React Native Web
+      // https://www.smashingmagazine.com/2016/08/a-glimpse-into-the-future-with-react-native-for-web/
+      'react-native': 'react-native-web'
     }
   },
   // Resolve loaders (webpack plugins for CSS, images, transpilation) from the
@@ -86,7 +91,7 @@ module.exports = {
     // It's important to do this before Babel processes the JS.
     preLoaders: [
       {
-        test: /\.js$/,
+        test: /\.(js|jsx)$/,
         loader: 'eslint',
         include: paths.appSrc
       }
@@ -94,7 +99,7 @@ module.exports = {
     loaders: [
       // Process JS with Babel.
       {
-        test: /\.js$/,
+        test: /\.(js|jsx)$/,
         include: paths.appSrc,
         loader: 'babel',
         query: require('./babel.prod')
@@ -113,40 +118,60 @@ module.exports = {
       // in the main CSS file.
       {
         test: /\.css$/,
-        include: [paths.appSrc, paths.appNodeModules],
         // "?-autoprefixer" disables autoprefixer in css-loader itself:
         // https://github.com/webpack/css-loader/issues/281
-        // We already have it thanks to postcss.
+        // We already have it thanks to postcss. We only pass this flag in
+        // production because "css" loader only enables autoprefixer-powered
+        // removal of unnecessary prefixes when Uglify plugin is enabled.
+        // Webpack 1.x uses Uglify plugin as a signal to minify *all* the assets
+        // including CSS. This is confusing and will be removed in Webpack 2:
+        // https://github.com/webpack/webpack/issues/283
         loader: ExtractTextPlugin.extract('style', 'css?-autoprefixer!postcss')
         // Note: this won't work without `new ExtractTextPlugin()` in `plugins`.
       },
+      // JSON is not enabled by default in Webpack but both Node and Browserify
+      // allow it implicitly so we also enable it.
       {
-        // 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 end up in the `build` folder.
+      // When you `import` an asset, you get its filename.
       {
-        // "file" loader makes sure those assets end up in the `build` folder.
-        // When you `import` an asset, you get its filename.
-        test: /\.(jpg|png|gif|eot|svg|ttf|woff|woff2)(\?.*)?$/,
-        include: [paths.appSrc, paths.appNodeModules],
+        test: /\.(ico|jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2)(\?.*)?$/,
+        exclude: /\/favicon.ico$/,
         loader: 'file',
         query: {
           name: 'static/media/[name].[hash:8].[ext]'
         }
       },
+      // A special case for favicon.ico to place it into build root directory.
+      {
+        test: /\/favicon.ico$/,
+        include: [paths.appSrc],
+        loader: 'file',
+        query: {
+          name: 'favicon.ico?[hash:8]'
+        }
+      },
       // "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],
         loader: 'url',
         query: {
           limit: 10000,
           name: 'static/media/[name].[hash:8].[ext]'
         }
+      },
+      // "html" loader is used to process template page (index.html) to resolve
+      // resources linked with <link href="./relative/path"> HTML tags.
+      {
+        test: /\.html$/,
+        loader: 'html',
+        query: {
+          attrs: ['link:href'],
+        }
       }
     ]
   },
@@ -175,7 +200,6 @@ module.exports = {
     new HtmlWebpackPlugin({
       inject: true,
       template: paths.appHtml,
-      favicon: paths.appFavicon,
       minify: {
         removeComments: true,
         collapseWhitespace: true,