diff --git a/docusaurus/docs/advanced-configuration.md b/docusaurus/docs/advanced-configuration.md index 413bca5051b..c0d96452f7a 100644 --- a/docusaurus/docs/advanced-configuration.md +++ b/docusaurus/docs/advanced-configuration.md @@ -3,21 +3,22 @@ id: advanced-configuration title: Advanced Configuration --- -You can adjust various development and production settings by setting environment variables in your shell or with [.env](adding-custom-environment-variables.md#adding-development-environment-variables-in-env). +You can adjust various development and production settings by setting environment variables in your shell or with [.env](adding-custom-environment-variables.md#adding-development-environment-variables-in-env). > Note: You do not need to declare `REACT_APP_` before the below variables as you would with custom environment variables. -| Variable | Development | Production | Usage | -| :------------------- | :---------: | :--------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| BROWSER | βœ… Used | 🚫 Ignored | By default, Create React App will open the default system browser, favoring Chrome on macOS. Specify a [browser](https://github.com/sindresorhus/opn#app) to override this behavior, or set it to `none` to disable it completely. If you need to customize the way the browser is launched, you can specify a node script instead. Any arguments passed to `npm start` will also be passed to this script, and the url where your app is served will be the last argument. Your script's file name must have the `.js` extension. | -| HOST | βœ… Used | 🚫 Ignored | By default, the development web server binds to `localhost`. You may use this variable to specify a different host. | -| PORT | βœ… Used | 🚫 Ignored | By default, the development web server will attempt to listen on port 3000 or prompt you to attempt the next available port. You may use this variable to specify a different port. | -| HTTPS | βœ… Used | 🚫 Ignored | When set to `true`, Create React App will run the development server in `https` mode. | -| PUBLIC_URL | 🚫 Ignored | βœ… Used | Create React App assumes your application is hosted at the serving web server's root or a subpath as specified in [`package.json` (`homepage`)](deployment#building-for-relative-paths). Normally, Create React App ignores the hostname. You may use this variable to force assets to be referenced verbatim to the url you provide (hostname included). This may be particularly useful when using a CDN to host your application. | -| CI | βœ… Used | βœ… Used | When set to `true`, Create React App treats warnings as failures in the build. It also makes the test runner non-watching. Most CIs set this flag by default. | -| REACT_EDITOR | βœ… Used | 🚫 Ignored | When an app crashes in development, you will see an error overlay with clickable stack trace. When you click on it, Create React App will try to determine the editor you are using based on currently running processes, and open the relevant source file. You can [send a pull request to detect your editor of choice](https://github.com/facebook/create-react-app/issues/2636). Setting this environment variable overrides the automatic detection. If you do it, make sure your systems [PATH]() environment variable points to your editor’s bin folder. You can also set it to `none` to disable it completely. | -| CHOKIDAR_USEPOLLING | βœ… Used | 🚫 Ignored | When set to `true`, the watcher runs in polling mode, as necessary inside a VM. Use this option if `npm start` isn't detecting changes. | -| GENERATE_SOURCEMAP | 🚫 Ignored | βœ… Used | When set to `false`, source maps are not generated for a production build. This solves out of memory (OOM) issues on some smaller machines. | -| NODE_PATH | βœ… Used | βœ… Used | Same as [`NODE_PATH` in Node.js](https://nodejs.org/api/modules.html#modules_loading_from_the_global_folders), but only relative folders are allowed. Can be handy for emulating a monorepo setup by setting `NODE_PATH=src`. | -| INLINE_RUNTIME_CHUNK | 🚫 Ignored | βœ… Used | By default, Create React App will embed the runtime script into `index.html` during the production build. When set to `false`, the script will not be embedded and will be imported as usual. This is normally required when dealing with CSP. | -| IMAGE_INLINE_SIZE_LIMIT | 🚫 Ignored | βœ… Used | By default, images smaller than 10,000 bytes are encoded as a data URI in base64 and inlined in the CSS or JS build artifact. Set this to control the size limit in bytes. Setting it to 0 will disable the inlining of images. | +| Variable | Development | Production | Usage | +| :---------------------- | :---------: | :--------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| BROWSER | βœ… Used | 🚫 Ignored | By default, Create React App will open the default system browser, favoring Chrome on macOS. Specify a [browser](https://github.com/sindresorhus/opn#app) to override this behavior, or set it to `none` to disable it completely. If you need to customize the way the browser is launched, you can specify a node script instead. Any arguments passed to `npm start` will also be passed to this script, and the url where your app is served will be the last argument. Your script's file name must have the `.js` extension. | +| HOST | βœ… Used | 🚫 Ignored | By default, the development web server binds to `localhost`. You may use this variable to specify a different host. | +| PORT | βœ… Used | 🚫 Ignored | By default, the development web server will attempt to listen on port 3000 or prompt you to attempt the next available port. You may use this variable to specify a different port. | +| HTTPS | βœ… Used | 🚫 Ignored | When set to `true`, Create React App will run the development server in `https` mode. | +| PUBLIC_URL | 🚫 Ignored | βœ… Used | Create React App assumes your application is hosted at the serving web server's root or a subpath as specified in [`package.json` (`homepage`)](deployment#building-for-relative-paths). Normally, Create React App ignores the hostname. You may use this variable to force assets to be referenced verbatim to the url you provide (hostname included). This may be particularly useful when using a CDN to host your application. | +| CI | βœ… Used | βœ… Used | When set to `true`, Create React App treats warnings as failures in the build. It also makes the test runner non-watching. Most CIs set this flag by default. | +| REACT_EDITOR | βœ… Used | 🚫 Ignored | When an app crashes in development, you will see an error overlay with clickable stack trace. When you click on it, Create React App will try to determine the editor you are using based on currently running processes, and open the relevant source file. You can [send a pull request to detect your editor of choice](https://github.com/facebook/create-react-app/issues/2636). Setting this environment variable overrides the automatic detection. If you do it, make sure your systems [PATH]() environment variable points to your editor’s bin folder. You can also set it to `none` to disable it completely. | +| CHOKIDAR_USEPOLLING | βœ… Used | 🚫 Ignored | When set to `true`, the watcher runs in polling mode, as necessary inside a VM. Use this option if `npm start` isn't detecting changes. | +| GENERATE_SOURCEMAP | 🚫 Ignored | βœ… Used | When set to `false`, source maps are not generated for a production build. This solves out of memory (OOM) issues on some smaller machines. | +| NODE_PATH | βœ… Used | βœ… Used | Same as [`NODE_PATH` in Node.js](https://nodejs.org/api/modules.html#modules_loading_from_the_global_folders), but only relative folders are allowed. Can be handy for emulating a monorepo setup by setting `NODE_PATH=src`. | +| INLINE_RUNTIME_CHUNK | 🚫 Ignored | βœ… Used | By default, Create React App will embed the runtime script into `index.html` during the production build. When set to `false`, the script will not be embedded and will be imported as usual. This is normally required when dealing with CSP. | +| IMAGE_INLINE_SIZE_LIMIT | 🚫 Ignored | βœ… Used | By default, images smaller than 10,000 bytes are encoded as a data URI in base64 and inlined in the CSS or JS build artifact. Set this to control the size limit in bytes. Setting it to 0 will disable the inlining of images. | +| EXTEND_ESLINT | βœ… Used | βœ… Used | When set to `true`, ESLint configs that extend `eslint-config-react-app` will be used by `eslint-loader`. Any rules that are set to `"error"` will stop the application from building. | diff --git a/docusaurus/docs/setting-up-your-editor.md b/docusaurus/docs/setting-up-your-editor.md index 869592d2915..844b9bc5da2 100644 --- a/docusaurus/docs/setting-up-your-editor.md +++ b/docusaurus/docs/setting-up-your-editor.md @@ -18,15 +18,7 @@ To configure the syntax highlighting in your favorite text editor, head to the [ Some editors, including Sublime Text, Atom, and Visual Studio Code, provide plugins for ESLint. -They are not required for linting. You should see the linter output right in your terminal as well as the browser console. However, if you prefer the lint results to appear right in your editor, there are some extra steps you can do. - -You would need to install an ESLint plugin for your editor first. Then, add a file called `.eslintrc.json` to the project root: - -```json -{ - "extends": "react-app" -} -``` +They are not required for linting. You should see the linter output right in your terminal as well as the browser console. If you prefer the lint results to appear right in your editor, please make sure you install an ESLint plugin/extension. If you're using TypeScript and Visual Studio Code, the [ESLint Visual Studio Code extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint#overview) currently [doesn't have TypeScript support enabled by default](https://github.com/Microsoft/vscode-eslint/issues/609). To enable TypeScript support in the ESLint extension, add the following to your project's Visual Studio Code settings file, located at `.vscode/settings.json` (you can create this file if it doesn't already exist): @@ -43,10 +35,46 @@ If you're using TypeScript and Visual Studio Code, the [ESLint Visual Studio Cod Now your editor should report the linting warnings. -Note that even if you edit your `.eslintrc.json` file further, these changes will **only affect the editor integration**. They won’t affect the terminal and in-browser lint output. This is because Create React App intentionally provides a minimal set of rules that find common mistakes. +Note that even if you customise your ESLint config, these changes will **only affect the editor integration**. They won’t affect the terminal and in-browser lint output. This is because Create React App intentionally provides a minimal set of rules that find common mistakes. If you want to enforce a coding style for your project, consider using [Prettier](https://github.com/jlongster/prettier) instead of ESLint style rules. +### Experimental: Extending the ESLint config + +We recognise that in some cases, further customisation is required. It is now possible to extend the base ESLint config by setting the `EXTEND_ESLINT` environment variable to `true`. See [advanced configuration](advanced-configuration.md) for more information on available environment variables. + +Note that any rules set to `"error"` will stop the project from building. + +There are a few things to remember: + +1. You must extend the base config, as removing it could introduce hard-to-find issues. +1. When working with TypeScript, you'll need to provide an `overrides` object for rules that should _only_ target TypeScript files. + +In the below example: + +- the base config has been extended by a shared ESLint config, +- a new rule has been set that applies to all JavaScript and TypeScript files, and +- a new rule has been set that only targets TypeScript files. + +```json +{ + "eslintConfig": { + "extends": ["react-app", "shared-config"], + "rules": { + "additional-rule": "warn" + }, + "overrides": [ + { + "files": ["**/*.ts?(x)"], + "rules": { + "additional-typescript-only-rule": "warn" + } + } + ] + } +} +``` + ## Debugging in the Editor **This feature is currently only supported by [Visual Studio Code](https://code.visualstudio.com) and [WebStorm](https://www.jetbrains.com/webstorm/).** diff --git a/packages/eslint-config-react-app/index.js b/packages/eslint-config-react-app/index.js index c06cfabfb43..df499e030e7 100644 --- a/packages/eslint-config-react-app/index.js +++ b/packages/eslint-config-react-app/index.js @@ -54,7 +54,7 @@ module.exports = { overrides: [ { - files: ['**/*.ts', '**/*.tsx'], + files: ['**/*.ts?(x)'], parser: '@typescript-eslint/parser', parserOptions: { ecmaVersion: 2018, diff --git a/packages/react-scripts/config/webpack.config.js b/packages/react-scripts/config/webpack.config.js index 771b06c94d1..25032e01b36 100644 --- a/packages/react-scripts/config/webpack.config.js +++ b/packages/react-scripts/config/webpack.config.js @@ -33,6 +33,7 @@ const getClientEnvironment = require('./env'); const ModuleNotFoundPlugin = require('react-dev-utils/ModuleNotFoundPlugin'); const ForkTsCheckerWebpackPlugin = require('react-dev-utils/ForkTsCheckerWebpackPlugin'); const typescriptFormatter = require('react-dev-utils/typescriptFormatter'); +const eslint = require('eslint'); // @remove-on-eject-begin const getCacheIdentifier = require('react-dev-utils/getCacheIdentifier'); // @remove-on-eject-end @@ -323,9 +324,29 @@ module.exports = function(webpackEnv) { formatter: require.resolve('react-dev-utils/eslintFormatter'), eslintPath: require.resolve('eslint'), // @remove-on-eject-begin - baseConfig: { - extends: [require.resolve('eslint-config-react-app')], - }, + baseConfig: (() => { + const eslintCli = new eslint.CLIEngine(); + let eslintConfig; + try { + eslintConfig = eslintCli.getConfigForFile(paths.appIndexJs); + } catch (e) { + // A config couldn't be found. + } + + // We allow overriding the config, only if it extends our config + // (`extends` can be a string or array of strings). + if ( + eslintConfig && + eslintConfig.extends && + eslintConfig.extends.includes('react-app') + ) { + return eslintConfig; + } else { + return { + extends: [require.resolve('eslint-config-react-app')], + }; + } + })(), ignore: false, useEslintrc: false, // @remove-on-eject-end diff --git a/packages/react-scripts/scripts/eject.js b/packages/react-scripts/scripts/eject.js index 746451e25e6..c4e7cffee49 100644 --- a/packages/react-scripts/scripts/eject.js +++ b/packages/react-scripts/scripts/eject.js @@ -236,10 +236,12 @@ inquirer }; // Add ESlint config - console.log(` Adding ${cyan('ESLint')} configuration`); - appPackage.eslintConfig = { - extends: 'react-app', - }; + if (!appPackage.eslintConfig) { + console.log(` Adding ${cyan('ESLint')} configuration`); + appPackage.eslintConfig = { + extends: 'react-app', + }; + } fs.writeFileSync( path.join(appPath, 'package.json'),