From 665b92ed83bc2b4d2e7b59ff14e88c9981863c39 Mon Sep 17 00:00:00 2001 From: Robert Banagale Date: Mon, 19 Oct 2020 18:10:46 -0700 Subject: [PATCH 01/14] Initial work on improving configurastion overview section --- packages/craco/README.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/packages/craco/README.md b/packages/craco/README.md index 71b1b39c..46b1f6cb 100644 --- a/packages/craco/README.md +++ b/packages/craco/README.md @@ -157,9 +157,23 @@ You can also change the location of the `craco.config.js` file by specifying the ## Configuration Overview +CRACO is configured with the `craco.config.js` file. The file is divided into sections representing the major parts of +what makes up the default create react app settings. + +For example, create react app uses webpack + +using a is configured with Here is a starter template to begin configuration of your CRA-based project. Each section contains +`loaderOptions` or `configure` which allow you make detailed changes to how your CRA is run. + When the property **mode** is available there are 2 possible values: - `extends`: the provided configuration will extends the CRA settings (**default mode**) -- `file`: the CRA settings will be reseted and you will provide an official configuration file for the plugin ([postcss](https://github.com/michael-ciniawsky/postcss-load-config#postcssrc), [eslint](https://eslint.org/docs/user-guide/configuring#configuration-file-formats)) that will supersede any settings. +- `file`: the CRA settings will be reset and you will provide an official configuration file for the plugin ([postcss](https://github.com/michael-ciniawsky/postcss-load-config#postcssrc), [eslint](https://eslint.org/docs/user-guide/configuring#configuration-file-formats)) that will supersede any settings. + + + + +You only want + ```javascript const { when, whenDev, whenProd, whenTest, ESLINT_MODES, POSTCSS_MODES } = require("@craco/craco"); From 2d075a1d05af9c1d586c38944ce0ed91f525ad61 Mon Sep 17 00:00:00 2001 From: Robert Banagale Date: Mon, 19 Oct 2020 18:10:46 -0700 Subject: [PATCH 02/14] Improve documentation how to get started using CRACO --- packages/craco/README.md | 89 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 85 insertions(+), 4 deletions(-) diff --git a/packages/craco/README.md b/packages/craco/README.md index 71b1b39c..dda26323 100644 --- a/packages/craco/README.md +++ b/packages/craco/README.md @@ -18,7 +18,14 @@ All you have to do is create your app using [create-react-app](https://github.co **Guide** - [Custom location for craco.config.js](#custom-location-for-cracoconfigjs) - Customize the location of your craco.config.js file. -- [Configuration Overview](#configuration-overview) - Quickly see how you can configure your CRA installation with this plugin. +- Configuring CRACO + - [CRACO Configuration Overview](#craco-configuration-overview) + - [Notes on CRA Configurations and Problem Solving](#notes-on-cra-configurations-and-problem-solving) + - [A Final Note on Ejecting CRA](#a-final-note-on-ejecting-cra) + - [The CRACO Configuration File](#the-craco-configuration-file) + - [Direct Versus Functional Config Definitions](#direct-versus-functional-config-definitions) + - [The Mode Property](#the-mode-property) + - [The CRACO Configuration File Template](#the-craco-configuration-file-template) - [API](#api) - Have a look at CRACO APIs for Jest and Webpack. - [Recipes](https://github.com/sharegate/craco/tree/master/recipes) – Short recipes for common use cases. - [Available Plugins](https://github.com/sharegate/craco#community-maintained-plugins) - Plugins maintained by the community. @@ -155,11 +162,85 @@ You can also change the location of the `craco.config.js` file by specifying the } ``` -## Configuration Overview +## CRACO Configuration Overview -When the property **mode** is available there are 2 possible values: +Create React App (CRA) is intended to allow people to get started with writing React apps quickly. It does this by +packaging several key components with a solid default configuration. + +However, many people find the default CRA is not quite the right fit. And yet, configuring all of the components CRA +offers is overwhelming. + +CRACO allows you to enjoy the recognizable project structure of CRA while changing detailed configuration settings of +each component. + +>_Read on for more useful introduction to CRACO, or jump directly to [the CRACO configuration file template](#the-craco-configuration-file-template)_ + +### Notes on CRA Configurations and Problem Solving +Keep in mind that there are _some_ configuration settings available to CRA without CRACO. + +Getting exactly what you want may involve a combination of changes to both your CRACO configuration and by using some +of the more limited _but still important_ settings available in CRA. + +Before jumping into customizing your CRACO configuration, step back and think about each part of the problem you're +trying to solve. Be sure to review these resources on the CRA configuration, as it may save you time: + + - [Important Environment Variables that Configure CRA](https://create-react-app.dev/docs/advanced-configuration) + - [Learn about using `postbuild` commands in `package.json`](https://stackoverflow.com/a/51818028/4028977) + - [Proxying API or other Requests](https://create-react-app.dev/docs/proxying-api-requests-in-development/), or "how to integrate CRA's dev server with a second backend": [problem statement](https://github.com/facebook/create-react-app/issues/147) + - [Search open and closed CRACO issues, for gotchas, hints and examples](https://github.com/gsoft-inc/craco/issues?q=is%3Aissue+sort%3Aupdated-desc) + +### A Final Note on Ejecting CRA +Avoiding ejecting is a major goal for many CRACO users. However, if you're still learning toolchains and modern +frontend workflows, it may be helpful to create a sample ejected CRA project to see how the default CRA app configures +each of the components. + +While CRACO's sample configuration file inherits directly from these default settings, seeing the default CRA config in +the ejected CRA file structure may give you useful perspective. + +You may even want to try testing a change in the ejected app to better understand how it would be done with the CRACO +configuration file. Okay! On with the CRACO Config! + +### The CRACO Configuration File + +CRACO is configured with the `craco.config.js` file. This file is divided into sections representing the major parts of +what makes up the default create react app. + +The sample file below is a starter template you can use to begin configuring your CRA-based project. Each section contains +a primary configuration area, `loaderOptions` or `configure`. These config areas are where you will make most of your +detailed changes. + +### Direct Versus Functional Config Definitions +You, (or perhaps your IDE) may have noticed that the sections have duplicate keys, i.e. loaderOptions is listed twice. + +The reason for this is to allow you to choose between direct or functionally defined configuration choices. There are a +few reasons for this: + +1. Sometimes it may be faster to test a minor change using keys. +1. Other times a functional definition is necessary to get the right configuration. +1. While not common, a setting may **only** work if you use one or the other! See, [devServer port example](https://github.com/gsoft-inc/craco/issues/172#issuecomment-651505730) + +#### A simple example of equivalent direct and functionally defined configuration settings: +##### Direct configuration +``` + devServer: { + writeToDisk: true, + }, +``` + +##### Functionally defined configuration +``` +devServer: (devServerConfig, { env, paths, proxy, allowedHost }) => { + devServerConfig.writeToDisk = true; + return devServerConfig; + }, +``` + +### The Mode Property +Some components have a property **mode**. When this is available there are 2 possible values: - `extends`: the provided configuration will extends the CRA settings (**default mode**) -- `file`: the CRA settings will be reseted and you will provide an official configuration file for the plugin ([postcss](https://github.com/michael-ciniawsky/postcss-load-config#postcssrc), [eslint](https://eslint.org/docs/user-guide/configuring#configuration-file-formats)) that will supersede any settings. +- `file`: the CRA settings will be reset and you will provide an official configuration file for the plugin ([postcss](https://github.com/michael-ciniawsky/postcss-load-config#postcssrc), [eslint](https://eslint.org/docs/user-guide/configuring#configuration-file-formats)) that will supersede any settings. + +## The CRACO Configuration File Template ```javascript const { when, whenDev, whenProd, whenTest, ESLINT_MODES, POSTCSS_MODES } = require("@craco/craco"); From e67634846bb93b869523b6b2cb8a307aca7e2905 Mon Sep 17 00:00:00 2001 From: Robert Banagale Date: Mon, 19 Oct 2020 23:39:26 -0700 Subject: [PATCH 03/14] Reorganize and use terminology patterns --- packages/craco/README.md | 70 +++++++++++++++++++++------------------- 1 file changed, 36 insertions(+), 34 deletions(-) diff --git a/packages/craco/README.md b/packages/craco/README.md index dda26323..e816c9c4 100644 --- a/packages/craco/README.md +++ b/packages/craco/README.md @@ -17,7 +17,6 @@ All you have to do is create your app using [create-react-app](https://github.co **Guide** -- [Custom location for craco.config.js](#custom-location-for-cracoconfigjs) - Customize the location of your craco.config.js file. - Configuring CRACO - [CRACO Configuration Overview](#craco-configuration-overview) - [Notes on CRA Configurations and Problem Solving](#notes-on-cra-configurations-and-problem-solving) @@ -25,6 +24,7 @@ All you have to do is create your app using [create-react-app](https://github.co - [The CRACO Configuration File](#the-craco-configuration-file) - [Direct Versus Functional Config Definitions](#direct-versus-functional-config-definitions) - [The Mode Property](#the-mode-property) + - [Setting a custom location for `craco.config.js`](#setting-a-custom-location-for-cracoconfigjs) - [The CRACO Configuration File Template](#the-craco-configuration-file-template) - [API](#api) - Have a look at CRACO APIs for Jest and Webpack. - [Recipes](https://github.com/sharegate/craco/tree/master/recipes) – Short recipes for common use cases. @@ -69,6 +69,8 @@ my-app └── package.json ``` +Choose one of the following ways to export your configuration, or use [the sample `craco.config.js`](#the-craco-configuration-file-template) + Export your configuration as an **object literal**: ```javascript @@ -132,36 +134,6 @@ Or build your app: $ npm run build ``` -## Custom location for craco.config.js - -Both options support a **relative** or an **absolute** path. - -**1- package.json** _(Recommended)_ - -You can change the location of the `craco.config.js` file by specifying a value for `cracoConfig` in your `package.json` file. - -```javascript -/* package.json */ - -{ - "cracoConfig": "config/craco-config-with-custom-name.js" -} -``` - -**2- CLI** _(For backward compatibility)_ - -You can also change the location of the `craco.config.js` file by specifying the `--config` CLI option. _This option doesn't support Babel with Jest_ - -```javascript -/* package.json */ - -{ - "scripts": { - "start": "craco start --config config/craco-config-with-custom-name.js" - } -} -``` - ## CRACO Configuration Overview Create React App (CRA) is intended to allow people to get started with writing React apps quickly. It does this by @@ -209,10 +181,10 @@ The sample file below is a starter template you can use to begin configuring you a primary configuration area, `loaderOptions` or `configure`. These config areas are where you will make most of your detailed changes. -### Direct Versus Functional Config Definitions +### Direct (object literal) Versus Functional Config Definitions You, (or perhaps your IDE) may have noticed that the sections have duplicate keys, i.e. loaderOptions is listed twice. -The reason for this is to allow you to choose between direct or functionally defined configuration choices. There are a +The reason for this is to allow you to choose between object literal or functionally defined configuration choices. There are a few reasons for this: 1. Sometimes it may be faster to test a minor change using keys. @@ -220,7 +192,7 @@ few reasons for this: 1. While not common, a setting may **only** work if you use one or the other! See, [devServer port example](https://github.com/gsoft-inc/craco/issues/172#issuecomment-651505730) #### A simple example of equivalent direct and functionally defined configuration settings: -##### Direct configuration +##### Direct configuration (object literal) ``` devServer: { writeToDisk: true, @@ -240,6 +212,36 @@ Some components have a property **mode**. When this is available there are 2 pos - `extends`: the provided configuration will extends the CRA settings (**default mode**) - `file`: the CRA settings will be reset and you will provide an official configuration file for the plugin ([postcss](https://github.com/michael-ciniawsky/postcss-load-config#postcssrc), [eslint](https://eslint.org/docs/user-guide/configuring#configuration-file-formats)) that will supersede any settings. +### Setting a custom location for craco.config.js + +Both options support a **relative** or an **absolute** path. + +**1- package.json** _(Recommended)_ + +You can change the location of the `craco.config.js` file by specifying a value for `cracoConfig` in your `package.json` file. + +```javascript +/* package.json */ + +{ + "cracoConfig": "config/craco-config-with-custom-name.js" +} +``` + +**2- CLI** _(For backward compatibility)_ + +You can also change the location of the `craco.config.js` file by specifying the `--config` CLI option. _This option doesn't support Babel with Jest_ + +```javascript +/* package.json */ + +{ + "scripts": { + "start": "craco start --config config/craco-config-with-custom-name.js" + } +} +``` + ## The CRACO Configuration File Template ```javascript From 9a26a30733cf1b9954715a76d4cd95692562e087 Mon Sep 17 00:00:00 2001 From: Robert Banagale Date: Mon, 19 Oct 2020 23:46:14 -0700 Subject: [PATCH 04/14] Minor formatting and tweaks, update copyright year --- packages/craco/README.md | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/packages/craco/README.md b/packages/craco/README.md index e816c9c4..6cb299a0 100644 --- a/packages/craco/README.md +++ b/packages/craco/README.md @@ -17,12 +17,12 @@ All you have to do is create your app using [create-react-app](https://github.co **Guide** -- Configuring CRACO +- **Configuring CRACO** - [CRACO Configuration Overview](#craco-configuration-overview) - [Notes on CRA Configurations and Problem Solving](#notes-on-cra-configurations-and-problem-solving) - [A Final Note on Ejecting CRA](#a-final-note-on-ejecting-cra) - [The CRACO Configuration File](#the-craco-configuration-file) - - [Direct Versus Functional Config Definitions](#direct-versus-functional-config-definitions) + - [Direct Versus Functional Config Definitions](#direct-object-literal-versus-functional-config-definitions) - [The Mode Property](#the-mode-property) - [Setting a custom location for `craco.config.js`](#setting-a-custom-location-for-cracoconfigjs) - [The CRACO Configuration File Template](#the-craco-configuration-file-template) @@ -42,14 +42,12 @@ Also, please note that the configuration style of this plugin has been greatly i By doing this you're breaking the ["guarantees"](https://github.com/facebookincubator/create-react-app/issues/99#issuecomment-234657710) that CRA provides. That is to say you now "own" the configs. **No support** will be provided. Proceed with caution. -## You updated craco and everything falls apart - +## You updated CRACO and everything fell apart Before logging an issue, please consult the [changelog](https://github.com/sharegate/craco/tree/master/changelog). If you can't find a solution to your problem in the changelog, log an issue and someone should help you quickly! ## Installation - Install the plugin from **npm**: ```bash @@ -134,8 +132,8 @@ Or build your app: $ npm run build ``` +# Configuring CRACO ## CRACO Configuration Overview - Create React App (CRA) is intended to allow people to get started with writing React apps quickly. It does this by packaging several key components with a solid default configuration. @@ -147,7 +145,7 @@ each component. >_Read on for more useful introduction to CRACO, or jump directly to [the CRACO configuration file template](#the-craco-configuration-file-template)_ -### Notes on CRA Configurations and Problem Solving +## Notes on CRA Configurations and Problem Solving Keep in mind that there are _some_ configuration settings available to CRA without CRACO. Getting exactly what you want may involve a combination of changes to both your CRACO configuration and by using some @@ -161,7 +159,7 @@ trying to solve. Be sure to review these resources on the CRA configuration, as - [Proxying API or other Requests](https://create-react-app.dev/docs/proxying-api-requests-in-development/), or "how to integrate CRA's dev server with a second backend": [problem statement](https://github.com/facebook/create-react-app/issues/147) - [Search open and closed CRACO issues, for gotchas, hints and examples](https://github.com/gsoft-inc/craco/issues?q=is%3Aissue+sort%3Aupdated-desc) -### A Final Note on Ejecting CRA +## A Final Note on Ejecting CRA Avoiding ejecting is a major goal for many CRACO users. However, if you're still learning toolchains and modern frontend workflows, it may be helpful to create a sample ejected CRA project to see how the default CRA app configures each of the components. @@ -172,7 +170,7 @@ the ejected CRA file structure may give you useful perspective. You may even want to try testing a change in the ejected app to better understand how it would be done with the CRACO configuration file. Okay! On with the CRACO Config! -### The CRACO Configuration File +## The CRACO Configuration File CRACO is configured with the `craco.config.js` file. This file is divided into sections representing the major parts of what makes up the default create react app. @@ -191,15 +189,15 @@ few reasons for this: 1. Other times a functional definition is necessary to get the right configuration. 1. While not common, a setting may **only** work if you use one or the other! See, [devServer port example](https://github.com/gsoft-inc/craco/issues/172#issuecomment-651505730) -#### A simple example of equivalent direct and functionally defined configuration settings: -##### Direct configuration (object literal) +### A simple example of equivalent direct and functionally defined configuration settings: +#### Direct configuration (object literal) ``` devServer: { writeToDisk: true, }, ``` -##### Functionally defined configuration +#### Functionally defined configuration ``` devServer: (devServerConfig, { env, paths, proxy, allowedHost }) => { devServerConfig.writeToDisk = true; @@ -349,7 +347,7 @@ module.exports = { ## API -To integrate with other tools, it's usefull to have access to the configs generated by CRACO. +To integrate with other tools, it's useful to have access to the configs generated by CRACO. That's what CRACO APIs are for. The current API support Jest and Webpack configs. @@ -915,4 +913,4 @@ To activate **verbose** logging specify the CLI option `--verbose` ## License -Copyright © 2019, Groupe Sharegate inc. This code is licensed under the Apache License, Version 2.0. You may obtain a copy of this license at https://github.com/gsoft-inc/gsoft-license/blob/master/LICENSE. +Copyright © 2020, Groupe Sharegate inc. This code is licensed under the Apache License, Version 2.0. You may obtain a copy of this license at https://github.com/gsoft-inc/gsoft-license/blob/master/LICENSE. From 4330dc9834ba5f9486b20b7eb9cc5c648ebe06f8 Mon Sep 17 00:00:00 2001 From: Robert Banagale Date: Mon, 19 Oct 2020 23:47:39 -0700 Subject: [PATCH 05/14] Copy edits --- packages/craco/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/craco/README.md b/packages/craco/README.md index 6cb299a0..d46c7bde 100644 --- a/packages/craco/README.md +++ b/packages/craco/README.md @@ -20,11 +20,11 @@ All you have to do is create your app using [create-react-app](https://github.co - **Configuring CRACO** - [CRACO Configuration Overview](#craco-configuration-overview) - [Notes on CRA Configurations and Problem Solving](#notes-on-cra-configurations-and-problem-solving) - - [A Final Note on Ejecting CRA](#a-final-note-on-ejecting-cra) + - [A Note on Ejecting CRA](#a-note-on-ejecting-cra) - [The CRACO Configuration File](#the-craco-configuration-file) - [Direct Versus Functional Config Definitions](#direct-object-literal-versus-functional-config-definitions) - [The Mode Property](#the-mode-property) - - [Setting a custom location for `craco.config.js`](#setting-a-custom-location-for-cracoconfigjs) + - [Setting a Custom Location for `craco.config.js`](#setting-a-custom-location-for-cracoconfigjs) - [The CRACO Configuration File Template](#the-craco-configuration-file-template) - [API](#api) - Have a look at CRACO APIs for Jest and Webpack. - [Recipes](https://github.com/sharegate/craco/tree/master/recipes) – Short recipes for common use cases. @@ -159,7 +159,7 @@ trying to solve. Be sure to review these resources on the CRA configuration, as - [Proxying API or other Requests](https://create-react-app.dev/docs/proxying-api-requests-in-development/), or "how to integrate CRA's dev server with a second backend": [problem statement](https://github.com/facebook/create-react-app/issues/147) - [Search open and closed CRACO issues, for gotchas, hints and examples](https://github.com/gsoft-inc/craco/issues?q=is%3Aissue+sort%3Aupdated-desc) -## A Final Note on Ejecting CRA +## A Note on Ejecting CRA Avoiding ejecting is a major goal for many CRACO users. However, if you're still learning toolchains and modern frontend workflows, it may be helpful to create a sample ejected CRA project to see how the default CRA app configures each of the components. From 8105198d525560b2ded61287f39723b47df99c26 Mon Sep 17 00:00:00 2001 From: Robert Banagale Date: Tue, 20 Oct 2020 08:28:37 -0700 Subject: [PATCH 06/14] Additional copy edits and formatting --- packages/craco/README.md | 85 ++++++++++++++++++++++++---------------- 1 file changed, 51 insertions(+), 34 deletions(-) diff --git a/packages/craco/README.md b/packages/craco/README.md index d46c7bde..969ece96 100644 --- a/packages/craco/README.md +++ b/packages/craco/README.md @@ -134,60 +134,63 @@ $ npm run build # Configuring CRACO ## CRACO Configuration Overview -Create React App (CRA) is intended to allow people to get started with writing React apps quickly. It does this by -packaging several key components with a solid default configuration. +Create React App ([CRA](https://github.com/facebook/create-react-app)) is intended to allow people to get started with +writing React apps quickly. It does this by packaging several key components with a solid default configuration. -However, many people find the default CRA is not quite the right fit. And yet, configuring all of the components CRA -offers is overwhelming. +After some initial experimentation, many people find the default CRA is not quite the right fit. Yet, selecting and a +configuring a toolchain featuring all of the components CRA already offers is overwhelming. CRACO allows you to enjoy the recognizable project structure of CRA while changing detailed configuration settings of each component. ->_Read on for more useful introduction to CRACO, or jump directly to [the CRACO configuration file template](#the-craco-configuration-file-template)_ +>_Read on for more useful introduction to CRACO, or jump directly to +>[the CRACO configuration file template](#the-craco-configuration-file-template)_ ## Notes on CRA Configurations and Problem Solving Keep in mind that there are _some_ configuration settings available to CRA without CRACO. -Getting exactly what you want may involve a combination of changes to both your CRACO configuration and by using some -of the more limited _but still important_ settings available in CRA. +Getting exactly what you want may involve a combination of making changes your CRACO configuration file and by using +some of the more limited _but still important_ settings available in Create React App. -Before jumping into customizing your CRACO configuration, step back and think about each part of the problem you're +Before jumping into customizing your _CRACO_ configuration, step back and think about each part of the problem you're trying to solve. Be sure to review these resources on the CRA configuration, as it may save you time: - [Important Environment Variables that Configure CRA](https://create-react-app.dev/docs/advanced-configuration) - [Learn about using `postbuild` commands in `package.json`](https://stackoverflow.com/a/51818028/4028977) - - [Proxying API or other Requests](https://create-react-app.dev/docs/proxying-api-requests-in-development/), or "how to integrate CRA's dev server with a second backend": [problem statement](https://github.com/facebook/create-react-app/issues/147) - - [Search open and closed CRACO issues, for gotchas, hints and examples](https://github.com/gsoft-inc/craco/issues?q=is%3Aissue+sort%3Aupdated-desc) + - [Proxying API or other Requests](https://create-react-app.dev/docs/proxying-api-requests-in-development/), or "how + to integrate CRA's dev server with a second backend": + [problem statement](https://github.com/facebook/create-react-app/issues/147) + - [Search CRACO issues, for gotchas, hints and examples](https://github.com/gsoft-inc/craco/issues?q=is%3Aissue+sort%3Aupdated-desc) ## A Note on Ejecting CRA Avoiding ejecting is a major goal for many CRACO users. However, if you're still learning toolchains and modern frontend workflows, it may be helpful to create a sample ejected CRA project to see how the default CRA app configures each of the components. -While CRACO's sample configuration file inherits directly from these default settings, seeing the default CRA config in +While CRACO's sample configuration file inherits directly from CRA's default settings, seeing the default CRA config in the ejected CRA file structure may give you useful perspective. -You may even want to try testing a change in the ejected app to better understand how it would be done with the CRACO -configuration file. Okay! On with the CRACO Config! +You may even want to try testing a change in the ejected app to better understand how it would be done with your CRACO +config-based project. Okay! On with the CRACO Config! ## The CRACO Configuration File +CRACO is configured with a single `craco.config.js` file. This file is divided into sections representing the major +parts of what makes up the default create react app. -CRACO is configured with the `craco.config.js` file. This file is divided into sections representing the major parts of -what makes up the default create react app. - -The sample file below is a starter template you can use to begin configuring your CRA-based project. Each section contains -a primary configuration area, `loaderOptions` or `configure`. These config areas are where you will make most of your -detailed changes. +The sample file below is a starter template you can use to begin configuring your CRA-based project. Each section +contains a primary configuration area, `loaderOptions` or `configure`. These config areas are where you will make most +of your detailed changes. ### Direct (object literal) Versus Functional Config Definitions You, (or perhaps your IDE) may have noticed that the sections have duplicate keys, i.e. loaderOptions is listed twice. -The reason for this is to allow you to choose between object literal or functionally defined configuration choices. There are a -few reasons for this: +The reason for this is to allow you to choose between object literal or functionally defined configuration choices. +There are a few reasons for this: 1. Sometimes it may be faster to test a minor change using keys. 1. Other times a functional definition is necessary to get the right configuration. -1. While not common, a setting may **only** work if you use one or the other! See, [devServer port example](https://github.com/gsoft-inc/craco/issues/172#issuecomment-651505730) +1. While not common, a setting may **only** work if you use one or the other! See, +[devServer port example](https://github.com/gsoft-inc/craco/issues/172#issuecomment-651505730) ### A simple example of equivalent direct and functionally defined configuration settings: #### Direct configuration (object literal) @@ -208,7 +211,9 @@ devServer: (devServerConfig, { env, paths, proxy, allowedHost }) => { ### The Mode Property Some components have a property **mode**. When this is available there are 2 possible values: - `extends`: the provided configuration will extends the CRA settings (**default mode**) -- `file`: the CRA settings will be reset and you will provide an official configuration file for the plugin ([postcss](https://github.com/michael-ciniawsky/postcss-load-config#postcssrc), [eslint](https://eslint.org/docs/user-guide/configuring#configuration-file-formats)) that will supersede any settings. +- `file`: the CRA settings will be reset and you will provide an official configuration file for the plugin +([postcss](https://github.com/michael-ciniawsky/postcss-load-config#postcssrc), +[eslint](https://eslint.org/docs/user-guide/configuring#configuration-file-formats)) that will supersede any settings. ### Setting a custom location for craco.config.js @@ -216,7 +221,8 @@ Both options support a **relative** or an **absolute** path. **1- package.json** _(Recommended)_ -You can change the location of the `craco.config.js` file by specifying a value for `cracoConfig` in your `package.json` file. +You can change the location of the `craco.config.js` file by specifying a value for `cracoConfig` in your `package.json` +file. ```javascript /* package.json */ @@ -228,7 +234,8 @@ You can change the location of the `craco.config.js` file by specifying a value **2- CLI** _(For backward compatibility)_ -You can also change the location of the `craco.config.js` file by specifying the `--config` CLI option. _This option doesn't support Babel with Jest_ +You can also change the location of the `craco.config.js` file by specifying the `--config` CLI option. _This option +doesn't support Babel with Jest_ ```javascript /* package.json */ @@ -355,7 +362,8 @@ That's what CRACO APIs are for. The current API support Jest and Webpack configs Accept a `cracoConfig`, a `context` object and `options`. The generated Jest config object is returned. -**Warning:** `createJestConfig` does NOT accept `cracoConfig` as a function. If your `craco.config.js` exposes a config function, you have to call it yourself before passing it to `createJestConfig`. +**Warning:** `createJestConfig` does NOT accept `cracoConfig` as a function. If your `craco.config.js` exposes a config +function, you have to call it yourself before passing it to `createJestConfig`. `createJestConfig(cracoConfig, context = {}, options = { verbose: false, config: null })` @@ -376,7 +384,8 @@ module.exports = jestConfig; Accept a `cracoConfig`, a `context` object and `options`. The generated Webpack config object is returned. -**Warning:** Similar to `createJestConfig`, these functions do NOT accept `cracoConfig` as a function. If your `craco.config.js` exposes a config function, you have to call it yourself before passing it further. +**Warning:** Similar to `createJestConfig`, these functions do NOT accept `cracoConfig` as a function. If your +`craco.config.js` exposes a config function, you have to call it yourself before passing it further. `createWebpackDevConfig(cracoConfig, context = {}, options = { verbose: false, config: null })` `createWebpackProdConfig(cracoConfig, context = {}, options = { verbose: false, config: null })` @@ -414,7 +423,8 @@ Every functions must return the updated config object. The function `overrideCracoConfig` let a plugin override the config object **before** it's process by `craco`. -If a plugin define the function, it will be called with the config object read from the `craco.config.js` file provided by the consumer. +If a plugin define the function, it will be called with the config object read from the `craco.config.js` file provided +by the consumer. *The function must return a valid config object, otherwise `craco` will throw an error.* @@ -467,7 +477,8 @@ module.exports = { ### overrideWebpackConfig -The function `overrideWebpackConfig` let a plugin override the `webpack` config object **after** it's been customized by `craco`. +The function `overrideWebpackConfig` let a plugin override the `webpack` config object **after** it's been customized +by `craco`. *The function must return a valid config object, otherwise `craco` will throw an error.* @@ -521,7 +532,8 @@ module.exports = { ### overrideDevServerConfig -The function `overrideDevServerConfig` let a plugin override the dev server config object **after** it's been customized by `craco`. +The function `overrideDevServerConfig` let a plugin override the dev server config object **after** it's been customized +by `craco`. *The function must return a valid config object, otherwise `craco` will throw an error.* @@ -576,7 +588,8 @@ module.exports = { ### overrideJestConfig -The function `overrideJestConfig` let a plugin override the `Jest` config object **after** it's been customized by `craco`. +The function `overrideJestConfig` let a plugin override the `Jest` config object **after** it's been customized by +`craco`. *The function must return a valid config object, otherwise `craco` will throw an error.* @@ -821,7 +834,9 @@ addAfterLoaders(webpackConfig, loaderByName("eslint-loader"), myNewWebpackLoader #### throwUnexpectedConfigError -Throw an error if the webpack configuration changes and does not match your expectations. (For example, `getLoader` cannot find a loader and `isFound` is `false`.) `create-react-app` might update the structure of their webpack config, so it is very important to show a helpful error message when something breaks. +Throw an error if the webpack configuration changes and does not match your expectations. (For example, `getLoader` +cannot find a loader and `isFound` is `false`.) `create-react-app` might update the structure of their webpack config, +so it is very important to show a helpful error message when something breaks. Raises an error and crashes Node.js: @@ -909,8 +924,10 @@ To activate **verbose** logging specify the CLI option `--verbose` ## Acknowledgements -[@timarney](https://github.com/timarney) for having created [react-app-rewired](https://github.com/timarney/react-app-rewired). +[@timarney](https://github.com/timarney) for having created +[react-app-rewired](https://github.com/timarney/react-app-rewired). ## License -Copyright © 2020, Groupe Sharegate inc. This code is licensed under the Apache License, Version 2.0. You may obtain a copy of this license at https://github.com/gsoft-inc/gsoft-license/blob/master/LICENSE. +Copyright © 2020, Groupe Sharegate inc. This code is licensed under the Apache License, Version 2.0. You may obtain a +copy of this license at https://github.com/gsoft-inc/gsoft-license/blob/master/LICENSE. From 5bb9490b2ee6778b46da3133504e93eb291b1653 Mon Sep 17 00:00:00 2001 From: Robert Banagale Date: Tue, 20 Oct 2020 08:31:14 -0700 Subject: [PATCH 07/14] Additional formatting --- packages/craco/README.md | 28 +++++++++++++--------------- 1 file changed, 13 insertions(+), 15 deletions(-) diff --git a/packages/craco/README.md b/packages/craco/README.md index 969ece96..607d67a3 100644 --- a/packages/craco/README.md +++ b/packages/craco/README.md @@ -6,7 +6,7 @@ Get all the benefits of create-react-app **and** customization without using 'ej All you have to do is create your app using [create-react-app](https://github.com/facebook/create-react-app/) and customize the configuration with a `craco.config.js` file. -**Support** +## Support - CRA 3.* - Yarn @@ -15,17 +15,17 @@ All you have to do is create your app using [create-react-app](https://github.co - Lerna (with or without hoisting) - Custom `react-scripts` version -**Guide** - -- **Configuring CRACO** - - [CRACO Configuration Overview](#craco-configuration-overview) - - [Notes on CRA Configurations and Problem Solving](#notes-on-cra-configurations-and-problem-solving) - - [A Note on Ejecting CRA](#a-note-on-ejecting-cra) - - [The CRACO Configuration File](#the-craco-configuration-file) - - [Direct Versus Functional Config Definitions](#direct-object-literal-versus-functional-config-definitions) - - [The Mode Property](#the-mode-property) - - [Setting a Custom Location for `craco.config.js`](#setting-a-custom-location-for-cracoconfigjs) - - [The CRACO Configuration File Template](#the-craco-configuration-file-template) +# Documentation Index + +**Configuring CRACO** +- [CRACO Configuration Overview](#craco-configuration-overview) +- [Notes on CRA Configurations and Problem Solving](#notes-on-cra-configurations-and-problem-solving) +- [A Note on Ejecting CRA](#a-note-on-ejecting-cra) +- [The CRACO Configuration File](#the-craco-configuration-file) + - [Direct Versus Functional Config Definitions](#direct-object-literal-versus-functional-config-definitions) + - [The Mode Property](#the-mode-property) + - [Setting a Custom Location for `craco.config.js`](#setting-a-custom-location-for-cracoconfigjs) + - [The CRACO Configuration File Template](#the-craco-configuration-file-template) - [API](#api) - Have a look at CRACO APIs for Jest and Webpack. - [Recipes](https://github.com/sharegate/craco/tree/master/recipes) – Short recipes for common use cases. - [Available Plugins](https://github.com/sharegate/craco#community-maintained-plugins) - Plugins maintained by the community. @@ -33,13 +33,11 @@ All you have to do is create your app using [create-react-app](https://github.co - [Changelog](https://github.com/sharegate/craco/tree/master/changelog) - List of major changes **Acknowledgements** - We are grateful to [@timarney](https://github.com/timarney) the creator of [react-app-rewired](https://github.com/timarney/react-app-rewired) for his original idea. -Also, please note that the configuration style of this plugin has been greatly influenced by the way [Vue CLI](https://cli.vuejs.org/guide/) does it. +The configuration style of this plugin has been greatly influenced by [Vue CLI](https://cli.vuejs.org/guide/). **Please Note** - By doing this you're breaking the ["guarantees"](https://github.com/facebookincubator/create-react-app/issues/99#issuecomment-234657710) that CRA provides. That is to say you now "own" the configs. **No support** will be provided. Proceed with caution. ## You updated CRACO and everything fell apart From 3e686f2bb971a94524841048c53e32995eab90a9 Mon Sep 17 00:00:00 2001 From: Robert Banagale Date: Tue, 20 Oct 2020 08:34:38 -0700 Subject: [PATCH 08/14] Additional formatting --- packages/craco/README.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/packages/craco/README.md b/packages/craco/README.md index 607d67a3..87458fe0 100644 --- a/packages/craco/README.md +++ b/packages/craco/README.md @@ -15,9 +15,8 @@ All you have to do is create your app using [create-react-app](https://github.co - Lerna (with or without hoisting) - Custom `react-scripts` version -# Documentation Index +## Documentation Index -**Configuring CRACO** - [CRACO Configuration Overview](#craco-configuration-overview) - [Notes on CRA Configurations and Problem Solving](#notes-on-cra-configurations-and-problem-solving) - [A Note on Ejecting CRA](#a-note-on-ejecting-cra) @@ -32,12 +31,12 @@ All you have to do is create your app using [create-react-app](https://github.co - [Develop a Plugin](#develop-a-plugin) - How to develop a plugin for `craco`. - [Changelog](https://github.com/sharegate/craco/tree/master/changelog) - List of major changes -**Acknowledgements** +### Acknowledgements We are grateful to [@timarney](https://github.com/timarney) the creator of [react-app-rewired](https://github.com/timarney/react-app-rewired) for his original idea. The configuration style of this plugin has been greatly influenced by [Vue CLI](https://cli.vuejs.org/guide/). -**Please Note** +### Please Note By doing this you're breaking the ["guarantees"](https://github.com/facebookincubator/create-react-app/issues/99#issuecomment-234657710) that CRA provides. That is to say you now "own" the configs. **No support** will be provided. Proceed with caution. ## You updated CRACO and everything fell apart From 5159000dd1cd42df8a550e77ac23f2f2ebc0b09a Mon Sep 17 00:00:00 2001 From: Robert Banagale Date: Mon, 26 Oct 2020 11:13:02 -0700 Subject: [PATCH 09/14] Refactor beginner stuff into its own section, clarify language around sample config file, minor copy edits and formatting --- packages/craco/README.md | 256 +++++++++++++++++++-------------------- 1 file changed, 128 insertions(+), 128 deletions(-) diff --git a/packages/craco/README.md b/packages/craco/README.md index 87458fe0..b2a62ee4 100644 --- a/packages/craco/README.md +++ b/packages/craco/README.md @@ -8,27 +8,28 @@ All you have to do is create your app using [create-react-app](https://github.co ## Support -- CRA 3.* +- Create React App (CRA) 3.* - Yarn - Yarn Workspace - NPM - Lerna (with or without hoisting) - Custom `react-scripts` version -## Documentation Index - -- [CRACO Configuration Overview](#craco-configuration-overview) -- [Notes on CRA Configurations and Problem Solving](#notes-on-cra-configurations-and-problem-solving) -- [A Note on Ejecting CRA](#a-note-on-ejecting-cra) -- [The CRACO Configuration File](#the-craco-configuration-file) - - [Direct Versus Functional Config Definitions](#direct-object-literal-versus-functional-config-definitions) +## Documentation +- [Installation](#installation) +- [CRACO Configuration](#craco-configuration) + - [Sample CRACO Configuration File](#sample-craco-configuration-file) - [The Mode Property](#the-mode-property) - [Setting a Custom Location for `craco.config.js`](#setting-a-custom-location-for-cracoconfigjs) - - [The CRACO Configuration File Template](#the-craco-configuration-file-template) +- [Extra Help for React and Webpack Toolchain Beginners](#extra-help-for-react-and-webpack-toolchain-beginners) + - [Ejecting CRA to Learn](#ejecting-cra-to-learn) + - [Notes on CRA Configurations and Problem Solving](#notes-on-cra-configurations-and-problem-solving) + - [Direct Versus Functional Config Definitions](#direct-object-literal-versus-functional-config-definitions) - [API](#api) - Have a look at CRACO APIs for Jest and Webpack. -- [Recipes](https://github.com/sharegate/craco/tree/master/recipes) – Short recipes for common use cases. -- [Available Plugins](https://github.com/sharegate/craco#community-maintained-plugins) - Plugins maintained by the community. -- [Develop a Plugin](#develop-a-plugin) - How to develop a plugin for `craco`. +- [Recipes and Plugins](#recipes-and-plugins) + - [Recipes](https://github.com/sharegate/craco/tree/master/recipes) – Short recipes for common use cases. + - [Available Plugins](https://github.com/sharegate/craco#community-maintained-plugins) - Plugins maintained by the community. + - [Developing a Plugin](#develop-a-plugin) - How to develop a plugin for `craco`. - [Changelog](https://github.com/sharegate/craco/tree/master/changelog) - List of major changes ### Acknowledgements @@ -36,12 +37,11 @@ We are grateful to [@timarney](https://github.com/timarney) the creator of [reac The configuration style of this plugin has been greatly influenced by [Vue CLI](https://cli.vuejs.org/guide/). -### Please Note +### Fair Warning By doing this you're breaking the ["guarantees"](https://github.com/facebookincubator/create-react-app/issues/99#issuecomment-234657710) that CRA provides. That is to say you now "own" the configs. **No support** will be provided. Proceed with caution. -## You updated CRACO and everything fell apart +### Problems after updating CRACO Before logging an issue, please consult the [changelog](https://github.com/sharegate/craco/tree/master/changelog). - If you can't find a solution to your problem in the changelog, log an issue and someone should help you quickly! ## Installation @@ -129,122 +129,15 @@ Or build your app: $ npm run build ``` -# Configuring CRACO -## CRACO Configuration Overview -Create React App ([CRA](https://github.com/facebook/create-react-app)) is intended to allow people to get started with -writing React apps quickly. It does this by packaging several key components with a solid default configuration. - -After some initial experimentation, many people find the default CRA is not quite the right fit. Yet, selecting and a -configuring a toolchain featuring all of the components CRA already offers is overwhelming. - -CRACO allows you to enjoy the recognizable project structure of CRA while changing detailed configuration settings of -each component. - ->_Read on for more useful introduction to CRACO, or jump directly to ->[the CRACO configuration file template](#the-craco-configuration-file-template)_ - -## Notes on CRA Configurations and Problem Solving -Keep in mind that there are _some_ configuration settings available to CRA without CRACO. - -Getting exactly what you want may involve a combination of making changes your CRACO configuration file and by using -some of the more limited _but still important_ settings available in Create React App. - -Before jumping into customizing your _CRACO_ configuration, step back and think about each part of the problem you're -trying to solve. Be sure to review these resources on the CRA configuration, as it may save you time: - - - [Important Environment Variables that Configure CRA](https://create-react-app.dev/docs/advanced-configuration) - - [Learn about using `postbuild` commands in `package.json`](https://stackoverflow.com/a/51818028/4028977) - - [Proxying API or other Requests](https://create-react-app.dev/docs/proxying-api-requests-in-development/), or "how - to integrate CRA's dev server with a second backend": - [problem statement](https://github.com/facebook/create-react-app/issues/147) - - [Search CRACO issues, for gotchas, hints and examples](https://github.com/gsoft-inc/craco/issues?q=is%3Aissue+sort%3Aupdated-desc) - -## A Note on Ejecting CRA -Avoiding ejecting is a major goal for many CRACO users. However, if you're still learning toolchains and modern -frontend workflows, it may be helpful to create a sample ejected CRA project to see how the default CRA app configures -each of the components. - -While CRACO's sample configuration file inherits directly from CRA's default settings, seeing the default CRA config in -the ejected CRA file structure may give you useful perspective. - -You may even want to try testing a change in the ejected app to better understand how it would be done with your CRACO -config-based project. Okay! On with the CRACO Config! - -## The CRACO Configuration File -CRACO is configured with a single `craco.config.js` file. This file is divided into sections representing the major +## CRACO Configuration +CRACO is configured with the `craco.config.js` file. This file is divided into sections representing the major parts of what makes up the default create react app. -The sample file below is a starter template you can use to begin configuring your CRA-based project. Each section +The sample file below is meant to show possibilities for configuring your CRA-based project. Each section contains a primary configuration area, `loaderOptions` or `configure`. These config areas are where you will make most of your detailed changes. -### Direct (object literal) Versus Functional Config Definitions -You, (or perhaps your IDE) may have noticed that the sections have duplicate keys, i.e. loaderOptions is listed twice. - -The reason for this is to allow you to choose between object literal or functionally defined configuration choices. -There are a few reasons for this: - -1. Sometimes it may be faster to test a minor change using keys. -1. Other times a functional definition is necessary to get the right configuration. -1. While not common, a setting may **only** work if you use one or the other! See, -[devServer port example](https://github.com/gsoft-inc/craco/issues/172#issuecomment-651505730) - -### A simple example of equivalent direct and functionally defined configuration settings: -#### Direct configuration (object literal) -``` - devServer: { - writeToDisk: true, - }, -``` - -#### Functionally defined configuration -``` -devServer: (devServerConfig, { env, paths, proxy, allowedHost }) => { - devServerConfig.writeToDisk = true; - return devServerConfig; - }, -``` - -### The Mode Property -Some components have a property **mode**. When this is available there are 2 possible values: -- `extends`: the provided configuration will extends the CRA settings (**default mode**) -- `file`: the CRA settings will be reset and you will provide an official configuration file for the plugin -([postcss](https://github.com/michael-ciniawsky/postcss-load-config#postcssrc), -[eslint](https://eslint.org/docs/user-guide/configuring#configuration-file-formats)) that will supersede any settings. - -### Setting a custom location for craco.config.js - -Both options support a **relative** or an **absolute** path. - -**1- package.json** _(Recommended)_ - -You can change the location of the `craco.config.js` file by specifying a value for `cracoConfig` in your `package.json` -file. - -```javascript -/* package.json */ - -{ - "cracoConfig": "config/craco-config-with-custom-name.js" -} -``` - -**2- CLI** _(For backward compatibility)_ - -You can also change the location of the `craco.config.js` file by specifying the `--config` CLI option. _This option -doesn't support Babel with Jest_ - -```javascript -/* package.json */ - -{ - "scripts": { - "start": "craco start --config config/craco-config-with-custom-name.js" - } -} -``` - -## The CRACO Configuration File Template +## Sample CRACO Configuration File ```javascript const { when, whenDev, whenProd, whenTest, ESLINT_MODES, POSTCSS_MODES } = require("@craco/craco"); @@ -322,6 +215,45 @@ module.exports = { }; ``` +### The Mode Property +Some components have a property **mode**. When this is available there are 2 possible values: +- `extends`: the provided configuration will extends the CRA settings (**default mode**) +- `file`: the CRA settings will be reset and you will provide an official configuration file for the plugin +([postcss](https://github.com/michael-ciniawsky/postcss-load-config#postcssrc), +[eslint](https://eslint.org/docs/user-guide/configuring#configuration-file-formats)) that will supersede any settings. + +### Setting a custom location for craco.config.js + +Both options support a **relative** or an **absolute** path. + +**1- package.json** _(Recommended)_ + +You can change the location of the `craco.config.js` file by specifying a value for `cracoConfig` in your `package.json` +file. + +```javascript +/* package.json */ + +{ + "cracoConfig": "config/craco-config-with-custom-name.js" +} +``` + +**2- CLI** _(For backward compatibility)_ + +You can also change the location of the `craco.config.js` file by specifying the `--config` CLI option. _This option +doesn't support Babel with Jest_ + +```javascript +/* package.json */ + +{ + "scripts": { + "start": "craco start --config config/craco-config-with-custom-name.js" + } +} +``` + ### when, whenDev, whenProd, whenTest Usage for all those functions is the same, `whenDev, whenProd, whenTest` are shortcuts for `when`. @@ -349,6 +281,71 @@ module.exports = { }; ``` +## Extra Help for React and Webpack Toolchain Beginners +### Introduction to CRACO +Create React App ([CRA](https://github.com/facebook/create-react-app)) is intended to allow people to get started with +writing React apps quickly. It does this by packaging several key components with a solid default configuration. + +After some initial experimentation, many people find the default CRA is not quite the right fit. Yet, selecting and a +configuring a toolchain featuring all of the components CRA already offers is overwhelming. + +CRACO allows you to enjoy the recognizable project structure of CRA while changing detailed configuration settings of +each component. + +### Notes on CRA Configurations and Problem Solving +Keep in mind that there are _some_ configuration settings available to CRA without CRACO. + +Getting exactly what you want may involve a combination of making changes your CRACO configuration file and by using +some of the more limited _but still important_ settings available in Create React App. + +Before jumping into customizing your _CRACO_ configuration, step back and think about each part of the problem you're +trying to solve. Be sure to review these resources on the CRA configuration, as it may save you time: + + - [Important Environment Variables that Configure CRA](https://create-react-app.dev/docs/advanced-configuration) + - [Learn about using `postbuild` commands in `package.json`](https://stackoverflow.com/a/51818028/4028977) + - [Proxying API or other Requests](https://create-react-app.dev/docs/proxying-api-requests-in-development/), or "how + to integrate CRA's dev server with a second backend": + [problem statement](https://github.com/facebook/create-react-app/issues/147) + - [Search CRACO issues, for gotchas, hints and examples](https://github.com/gsoft-inc/craco/issues?q=is%3Aissue+sort%3Aupdated-desc) + +### Ejecting CRA to Learn +Avoiding ejecting is a major goal for many CRACO users. However, if you're still learning toolchains and modern +frontend workflows, it may be helpful to create a sample ejected CRA project to see how the default CRA app configures +each of the components. + +While CRACO's sample configuration file inherits directly from CRA's default settings, seeing the default CRA config in +the ejected CRA file structure may give you useful perspective. + +You may even want to try testing a change in the ejected app to better understand how it would be done with your CRACO +config-based project. + +### Direct (object literal) Versus Functional Config Definitions +You, (or perhaps your IDE) may have noticed that the sections have duplicate keys, i.e. loaderOptions is listed twice. + +The reason for this is to allow you to choose between object literal or functionally defined configuration choices. +There are a few reasons for this: + +1. Sometimes it may be faster to test a minor change using keys. +1. Other times a functional definition is necessary to get the right configuration. +1. While not common, a setting may **only** work if you use one or the other! See, +[devServer port example](https://github.com/gsoft-inc/craco/issues/172#issuecomment-651505730) + +### A simple example of equivalent direct and functionally defined configuration settings: +#### Direct configuration (object literal) +``` + devServer: { + writeToDisk: true, + }, +``` + +#### Functionally defined configuration +``` +devServer: (devServerConfig, { env, paths, proxy, allowedHost }) => { + devServerConfig.writeToDisk = true; + return devServerConfig; + }, +``` + ## API To integrate with other tools, it's useful to have access to the configs generated by CRACO. @@ -400,11 +397,14 @@ const webpackConfig = createWebpackDevConfig(cracoConfig); module.exports = webpackConfig; ``` -### Popular integrations +## Recipes and Plugins +### Recipes - [vscode-jest](https://github.com/sharegate/craco/tree/master/recipes/use-a-jest-config-file) -## Develop a plugin +### Available Plugins +See this list of [Available Plugins](https://github.com/sharegate/craco#community-maintained-plugins) maintained by the community. +### Develop a plugin There are 4 functions available to a plugin: - `overrideCracoConfig`: Let a plugin customize the config object before it's process by `craco`. From 018bfbed47daa522c52992c2ad5d4521f4a48b5d Mon Sep 17 00:00:00 2001 From: Robert Banagale Date: Mon, 26 Oct 2020 11:16:10 -0700 Subject: [PATCH 10/14] Use consistent section headers, remove duplicate acknowledgement section --- packages/craco/README.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/packages/craco/README.md b/packages/craco/README.md index b2a62ee4..bb82a430 100644 --- a/packages/craco/README.md +++ b/packages/craco/README.md @@ -16,6 +16,7 @@ All you have to do is create your app using [create-react-app](https://github.co - Custom `react-scripts` version ## Documentation +- [Preface](#preface) - [Installation](#installation) - [CRACO Configuration](#craco-configuration) - [Sample CRACO Configuration File](#sample-craco-configuration-file) @@ -32,6 +33,7 @@ All you have to do is create your app using [create-react-app](https://github.co - [Developing a Plugin](#develop-a-plugin) - How to develop a plugin for `craco`. - [Changelog](https://github.com/sharegate/craco/tree/master/changelog) - List of major changes +## Preface ### Acknowledgements We are grateful to [@timarney](https://github.com/timarney) the creator of [react-app-rewired](https://github.com/timarney/react-app-rewired) for his original idea. @@ -40,7 +42,7 @@ The configuration style of this plugin has been greatly influenced by [Vue CLI]( ### Fair Warning By doing this you're breaking the ["guarantees"](https://github.com/facebookincubator/create-react-app/issues/99#issuecomment-234657710) that CRA provides. That is to say you now "own" the configs. **No support** will be provided. Proceed with caution. -### Problems after updating CRACO +### Problems after updating CRACO? Before logging an issue, please consult the [changelog](https://github.com/sharegate/craco/tree/master/changelog). If you can't find a solution to your problem in the changelog, log an issue and someone should help you quickly! @@ -919,11 +921,6 @@ To activate **verbose** logging specify the CLI option `--verbose` } ``` -## Acknowledgements - -[@timarney](https://github.com/timarney) for having created -[react-app-rewired](https://github.com/timarney/react-app-rewired). - ## License Copyright © 2020, Groupe Sharegate inc. This code is licensed under the Apache License, Version 2.0. You may obtain a From 8130f92da813498c7776115a1dc2866fb91794e0 Mon Sep 17 00:00:00 2001 From: Robert Banagale Date: Mon, 26 Oct 2020 11:18:33 -0700 Subject: [PATCH 11/14] Update main readme's documentation index --- README.md | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 4d54f3b6..38d4eb8d 100644 --- a/README.md +++ b/README.md @@ -13,21 +13,30 @@ All you have to do is create your app using [create-react-app](https://github.co ## Support -- CRA 3.* +- Create React App (CRA) 3.* - Yarn - Yarn Workspace - NPM - Lerna (with or without hoisting) - Custom `react-scripts` version -## Guide - -- [Installation](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#installation) - How to install and setup `craco`. -- [Custom location for craco.config.js](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#custom-location-for-cracoconfigjs) - Customize the location of your craco.config.js file. -- [Configuration Overview](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#configuration-overview) - Quickly see how you can configure your CRA installation with this plugin. -- [API](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#api) - Have a look at CRACO API for Jest and Webpack. -- [Recipes](https://github.com/sharegate/craco/tree/master/recipes) – Short recipes for common use cases. -- [Develop a Plugin](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#develop-a-plugin) - How to develop a plugin for `craco`. +## Documentation +- [Preface](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#preface) +- [Installation](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#installation) +- [CRACO Configuration](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#craco-configuration) + - [Sample CRACO Configuration File](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#sample-craco-configuration-file) + - [The Mode Property](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#the-mode-property) + - [Setting a Custom Location for `craco.config.js`](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#setting-a-custom-location-for-cracoconfigjs) +- [Extra Help for React and Webpack Toolchain Beginners](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#extra-help-for-react-and-webpack-toolchain-beginners) + - [Ejecting CRA to Learn](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#ejecting-cra-to-learn) + - [Notes on CRA Configurations and Problem Solving](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#notes-on-cra-configurations-and-problem-solving) + - [Direct Versus Functional Config Definitions](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#direct-object-literal-versus-functional-config-definitions) +- [API](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#api) - Have a look at CRACO APIs for Jest and Webpack. +- [Recipes and Plugins](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#recipes-and-plugins) + - [Recipes](https://github.com/sharegate/craco/tree/master/recipes) – Short recipes for common use cases. + - [Available Plugins](https://github.com/sharegate/craco#community-maintained-plugins) - Plugins maintained by the community. + - [Developing a Plugin](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#develop-a-plugin) - How to develop a plugin for `craco`. +- [Changelog](https://github.com/sharegate/craco/tree/master/changelog) - List of major changes ## Changelog From 8ce3ad3eb1d47558f9a0113a41e7b4627310be97 Mon Sep 17 00:00:00 2001 From: Robert Banagale Date: Mon, 26 Oct 2020 11:26:57 -0700 Subject: [PATCH 12/14] Move more sample file copy to beginner details section, add link from main config intro --- packages/craco/README.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/packages/craco/README.md b/packages/craco/README.md index bb82a430..cca35412 100644 --- a/packages/craco/README.md +++ b/packages/craco/README.md @@ -135,10 +135,7 @@ $ npm run build CRACO is configured with the `craco.config.js` file. This file is divided into sections representing the major parts of what makes up the default create react app. -The sample file below is meant to show possibilities for configuring your CRA-based project. Each section -contains a primary configuration area, `loaderOptions` or `configure`. These config areas are where you will make most -of your detailed changes. - +For more details about this sample file, see [Direct Versus Functional Config Definitions](#direct-object-literal-versus-functional-config-definitions) ## Sample CRACO Configuration File ```javascript @@ -322,7 +319,12 @@ You may even want to try testing a change in the ejected app to better understan config-based project. ### Direct (object literal) Versus Functional Config Definitions -You, (or perhaps your IDE) may have noticed that the sections have duplicate keys, i.e. loaderOptions is listed twice. +The [sample CRACO config file]((#sample-craco-configuration-file)) is meant to show possibilities for configuring your CRA-based project. Each section +contains a primary configuration area, `loaderOptions` or `configure`. These config areas are where you will make most +of your detailed changes. + +You, (or perhaps your IDE) may have noticed that the sections have duplicate keys, i.e. loaderOptions is listed twice +in the sample config file. The reason for this is to allow you to choose between object literal or functionally defined configuration choices. There are a few reasons for this: From 17bcc6355be28da9a5acce285cbacd9affcb314f Mon Sep 17 00:00:00 2001 From: Robert Banagale Date: Fri, 30 Oct 2020 08:32:05 -0700 Subject: [PATCH 13/14] Refactor Plugin, API and Recipe sections for clarity and organization --- README.md | 26 +++---- packages/craco/README.md | 164 ++++++++++++++++++++++----------------- 2 files changed, 104 insertions(+), 86 deletions(-) diff --git a/README.md b/README.md index 38d4eb8d..fe3d7db4 100644 --- a/README.md +++ b/README.md @@ -24,23 +24,23 @@ All you have to do is create your app using [create-react-app](https://github.co - [Preface](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#preface) - [Installation](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#installation) - [CRACO Configuration](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#craco-configuration) - - [Sample CRACO Configuration File](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#sample-craco-configuration-file) - [The Mode Property](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#the-mode-property) + - [Sample CRACO Configuration File](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#sample-craco-configuration-file) - [Setting a Custom Location for `craco.config.js`](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#setting-a-custom-location-for-cracoconfigjs) + - [`when` Shortcuts](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#when-shortcuts) - [Extra Help for React and Webpack Toolchain Beginners](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#extra-help-for-react-and-webpack-toolchain-beginners) - - [Ejecting CRA to Learn](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#ejecting-cra-to-learn) - [Notes on CRA Configurations and Problem Solving](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#notes-on-cra-configurations-and-problem-solving) + - [Ejecting CRA to Learn](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#ejecting-cra-to-learn) - [Direct Versus Functional Config Definitions](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#direct-object-literal-versus-functional-config-definitions) -- [API](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#api) - Have a look at CRACO APIs for Jest and Webpack. -- [Recipes and Plugins](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#recipes-and-plugins) - - [Recipes](https://github.com/sharegate/craco/tree/master/recipes) – Short recipes for common use cases. - - [Available Plugins](https://github.com/sharegate/craco#community-maintained-plugins) - Plugins maintained by the community. - - [Developing a Plugin](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#develop-a-plugin) - How to develop a plugin for `craco`. -- [Changelog](https://github.com/sharegate/craco/tree/master/changelog) - List of major changes - -## Changelog - -Major changes are available in the [changelog folder](https://github.com/sharegate/craco/tree/master/changelog). +- [CRACO API](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#craco-api) - Access CRACO-generated configurations for Jest and Webpack + - [Jest Config Generation](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#jest-config-generation) + - [Webpack DevServer and Production Config Generation](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#webpack-devserver-and-production-config-generation) +- [Recipes](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#recipes) +- [Plugins](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#plugins) + - [Available Plugins](#community-maintained-plugins) + - [Developing a New Plugin](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#developing-a-new-plugin) - How to develop a plugin for CRACO. + - [Plugin Functions](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#plugin-functions) + - [Utility Functions for Development](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#utility-functions-for-development) ## Community Maintained Plugins @@ -71,4 +71,4 @@ Major changes are available in the [changelog folder](https://github.com/sharega ## License -Copyright © 2019, GSoft inc. This code is licensed under the Apache License, Version 2.0. You may obtain a copy of this license at https://github.com/gsoft-inc/gsoft-license/blob/master/LICENSE. +Copyright © 2020, GSoft inc. This code is licensed under the Apache License, Version 2.0. You may obtain a copy of this license at https://github.com/gsoft-inc/gsoft-license/blob/master/LICENSE. diff --git a/packages/craco/README.md b/packages/craco/README.md index cca35412..b4830b93 100644 --- a/packages/craco/README.md +++ b/packages/craco/README.md @@ -19,19 +19,23 @@ All you have to do is create your app using [create-react-app](https://github.co - [Preface](#preface) - [Installation](#installation) - [CRACO Configuration](#craco-configuration) - - [Sample CRACO Configuration File](#sample-craco-configuration-file) - [The Mode Property](#the-mode-property) + - [Sample CRACO Configuration File](#sample-craco-configuration-file) - [Setting a Custom Location for `craco.config.js`](#setting-a-custom-location-for-cracoconfigjs) + - [`when` Shortcuts](#when-shortcuts) - [Extra Help for React and Webpack Toolchain Beginners](#extra-help-for-react-and-webpack-toolchain-beginners) - - [Ejecting CRA to Learn](#ejecting-cra-to-learn) - [Notes on CRA Configurations and Problem Solving](#notes-on-cra-configurations-and-problem-solving) + - [Ejecting CRA to Learn](#ejecting-cra-to-learn) - [Direct Versus Functional Config Definitions](#direct-object-literal-versus-functional-config-definitions) -- [API](#api) - Have a look at CRACO APIs for Jest and Webpack. -- [Recipes and Plugins](#recipes-and-plugins) - - [Recipes](https://github.com/sharegate/craco/tree/master/recipes) – Short recipes for common use cases. +- [CRACO API](#craco-api) - Access CRACO-generated configurations for Jest and Webpack + - [Jest Config Generation](#jest-config-generation) + - [Webpack DevServer and Production Config Generation](#webpack-devserver-and-production-config-generation) +- [Recipes](#recipes) +- [Plugins](#plugins) - [Available Plugins](https://github.com/sharegate/craco#community-maintained-plugins) - Plugins maintained by the community. - - [Developing a Plugin](#develop-a-plugin) - How to develop a plugin for `craco`. -- [Changelog](https://github.com/sharegate/craco/tree/master/changelog) - List of major changes + - [Developing a New Plugin](#developing-a-new-plugin) - How to develop a plugin for CRACO. + - [Plugin Functions](#plugin-functions) + - [Utility Functions for Development](#utility-functions-for-development) ## Preface ### Acknowledgements @@ -43,10 +47,10 @@ The configuration style of this plugin has been greatly influenced by [Vue CLI]( By doing this you're breaking the ["guarantees"](https://github.com/facebookincubator/create-react-app/issues/99#issuecomment-234657710) that CRA provides. That is to say you now "own" the configs. **No support** will be provided. Proceed with caution. ### Problems after updating CRACO? -Before logging an issue, please consult the [changelog](https://github.com/sharegate/craco/tree/master/changelog). If you can't find a solution to your problem in the changelog, log an issue and someone should help you quickly! ## Installation +### Overview Install the plugin from **npm**: ```bash @@ -131,12 +135,35 @@ Or build your app: $ npm run build ``` +### Verbose logging + +To activate **verbose** logging specify the CLI option `--verbose` + +```javascript +/* package.json */ + +{ + "scripts": { + "start": "craco start --verbose" + } +} +``` + ## CRACO Configuration CRACO is configured with the `craco.config.js` file. This file is divided into sections representing the major parts of what makes up the default create react app. -For more details about this sample file, see [Direct Versus Functional Config Definitions](#direct-object-literal-versus-functional-config-definitions) -## Sample CRACO Configuration File +### The Mode Property +Some components have a property **mode**. When this is available there are 2 possible values: +- `extends`: the provided configuration will extends the CRA settings (**default mode**) +- `file`: the CRA settings will be reset and you will provide an official configuration file for the plugin +([postcss](https://github.com/michael-ciniawsky/postcss-load-config#postcssrc), +[eslint](https://eslint.org/docs/user-guide/configuring#configuration-file-formats)) that will supersede any settings. + +### Sample CRACO Configuration File +Below is a sample CRACO configuration file. For more details about this sample file, see [Direct Versus Functional Config Definitions](#direct-object-literal-versus-functional-config-definitions) + +> Note: Your final config file may be much shorter than this sample. See example CRACO configurations in [Recipes](https://github.com/sharegate/craco/tree/master/recipes). ```javascript const { when, whenDev, whenProd, whenTest, ESLINT_MODES, POSTCSS_MODES } = require("@craco/craco"); @@ -214,13 +241,6 @@ module.exports = { }; ``` -### The Mode Property -Some components have a property **mode**. When this is available there are 2 possible values: -- `extends`: the provided configuration will extends the CRA settings (**default mode**) -- `file`: the CRA settings will be reset and you will provide an official configuration file for the plugin -([postcss](https://github.com/michael-ciniawsky/postcss-load-config#postcssrc), -[eslint](https://eslint.org/docs/user-guide/configuring#configuration-file-formats)) that will supersede any settings. - ### Setting a custom location for craco.config.js Both options support a **relative** or an **absolute** path. @@ -253,9 +273,8 @@ doesn't support Babel with Jest_ } ``` -### when, whenDev, whenProd, whenTest - -Usage for all those functions is the same, `whenDev, whenProd, whenTest` are shortcuts for `when`. +### `when` Shortcuts +Usage for all when functions is the same, `whenDev, whenProd, whenTest` are shortcuts for `when`. `when(condition, fct, [unmetValue])` @@ -334,15 +353,15 @@ There are a few reasons for this: 1. While not common, a setting may **only** work if you use one or the other! See, [devServer port example](https://github.com/gsoft-inc/craco/issues/172#issuecomment-651505730) -### A simple example of equivalent direct and functionally defined configuration settings: -#### Direct configuration (object literal) +#### A simple example of equivalent direct and functionally defined configuration settings: +##### Direct configuration (object literal) ``` devServer: { writeToDisk: true, }, ``` -#### Functionally defined configuration +##### Functionally defined configuration ``` devServer: (devServerConfig, { env, paths, proxy, allowedHost }) => { devServerConfig.writeToDisk = true; @@ -350,17 +369,18 @@ devServer: (devServerConfig, { env, paths, proxy, allowedHost }) => { }, ``` -## API +## CRACO API +### Overview +If you would like to integrate with other tools, you may want access to configurations generated by CRACO. -To integrate with other tools, it's useful to have access to the configs generated by CRACO. +Currently, CRACO's API can generate configs for Jest and WebPack. -That's what CRACO APIs are for. The current API support Jest and Webpack configs. - -### createJestConfig +### Jest Config Generation +You can create a Jest configuration with `createJestConfig`. Accept a `cracoConfig`, a `context` object and `options`. The generated Jest config object is returned. -**Warning:** `createJestConfig` does NOT accept `cracoConfig` as a function. If your `craco.config.js` exposes a config +> **Warning:** `createJestConfig` does NOT accept `cracoConfig` as a function. If your `craco.config.js` exposes a config function, you have to call it yourself before passing it to `createJestConfig`. `createJestConfig(cracoConfig, context = {}, options = { verbose: false, config: null })` @@ -377,12 +397,15 @@ const jestConfig = createJestConfig(cracoConfig); module.exports = jestConfig; ``` +#### Example Integration: Jest config for Vscode +- [vscode-jest](https://github.com/sharegate/craco/tree/master/recipes/use-a-jest-config-file) -### createWebpackDevConfig & createWebpackProdConfig +### Webpack DevServer and Production Config Generation +You can create Webpack DevServer and Production configurations using `createWebpackDevConfig` and `createWebpackProdConfig`. Accept a `cracoConfig`, a `context` object and `options`. The generated Webpack config object is returned. -**Warning:** Similar to `createJestConfig`, these functions do NOT accept `cracoConfig` as a function. If your +> **Warning:** Similar to `createJestConfig`, these functions do NOT accept `cracoConfig` as a function. If your `craco.config.js` exposes a config function, you have to call it yourself before passing it further. `createWebpackDevConfig(cracoConfig, context = {}, options = { verbose: false, config: null })` @@ -401,16 +424,18 @@ const webpackConfig = createWebpackDevConfig(cracoConfig); module.exports = webpackConfig; ``` +## Recipes +[CRACO Recipes](https://github.com/sharegate/craco/tree/master/recipes) are a curated set of example craco config files +already built for common use cases -## Recipes and Plugins -### Recipes -- [vscode-jest](https://github.com/sharegate/craco/tree/master/recipes/use-a-jest-config-file) - +## Plugins ### Available Plugins -See this list of [Available Plugins](https://github.com/sharegate/craco#community-maintained-plugins) maintained by the community. -### Develop a plugin +See this list of [Available Plugins](https://github.com/sharegate/craco#community-maintained-plugins) maintained by the +community. -There are 4 functions available to a plugin: +### Developing a new plugin +#### Plugin Functions +There are four functions available to a plugin: - `overrideCracoConfig`: Let a plugin customize the config object before it's process by `craco`. - `overrideWebpackConfig`: Let a plugin customize the `webpack` config that will be used by CRA. - `overrideDevServerConfig`: Let a plugin customize the dev server config that will be used by CRA. @@ -418,9 +443,9 @@ There are 4 functions available to a plugin: **Important:** -Every functions must return the updated config object. +Every function must return the updated config object. -### overrideCracoConfig +##### overrideCracoConfig The function `overrideCracoConfig` let a plugin override the config object **before** it's process by `craco`. @@ -442,7 +467,7 @@ The function will be called with a single object argument having the following s } ``` -#### Example +###### Example Plugin: @@ -476,7 +501,7 @@ module.exports = { }; ``` -### overrideWebpackConfig +##### overrideWebpackConfig The function `overrideWebpackConfig` let a plugin override the `webpack` config object **after** it's been customized by `craco`. @@ -497,7 +522,7 @@ The function will be called with a single object argument having the following s } ``` -#### Example +###### Example Plugin: @@ -531,7 +556,7 @@ module.exports = { }; ``` -### overrideDevServerConfig +##### overrideDevServerConfig The function `overrideDevServerConfig` let a plugin override the dev server config object **after** it's been customized by `craco`. @@ -553,7 +578,7 @@ The function will be called with a single object argument having the following s } ``` -#### Example +###### Example Plugin: @@ -587,7 +612,7 @@ module.exports = { }; ``` -### overrideJestConfig +##### overrideJestConfig The function `overrideJestConfig` let a plugin override the `Jest` config object **after** it's been customized by `craco`. @@ -610,7 +635,7 @@ The function will be called with a single object argument having the following s } ``` -#### Example +###### Example Plugin: @@ -644,15 +669,22 @@ module.exports = { }; ``` -### Utility functions - -A few utility functions are provided by `craco` to develop a plugin: - +#### Utility Functions for Development +A few utility functions are provided by CRACO to help you develop a plugin: + - `getLoader` + - `getLoaders` + - `removeLoaders` + - `addBeforeLoader` + - `addBeforeLoaders` + - `addAfterLoader` + - `addAfterLoaders` + - `throwUnexpectedConfigError` + ```javascript const { getLoader, getLoaders, removeLoader, loaderByName, throwUnexpectedConfigError } = require("@craco/craco"); ``` -#### getLoader +##### getLoader Retrieve the **first** loader that match the specified criteria from the webpack config. @@ -681,7 +713,7 @@ if (isFound) { } ``` -#### getLoaders +##### getLoaders Retrieve **all** the loaders that match the specified criteria from the webpack config. @@ -714,7 +746,7 @@ if (hasFoundAny) { } ``` -#### removeLoaders +##### removeLoaders Remove **all** the loaders that match the specified criteria from the webpack config. @@ -735,7 +767,7 @@ const { removeLoaders, loaderByName } = require("@craco/craco"); removeLoaders(webpackConfig, loaderByName("eslint-loader")); ``` -#### addBeforeLoader +##### addBeforeLoader Add a new *loader* **before** the loader that match specified criteria to the webpack config. @@ -759,7 +791,7 @@ const myNewWebpackLoader = { addBeforeLoader(webpackConfig, loaderByName("eslint-loader"), myNewWebpackLoader); ``` -#### addBeforeLoaders +##### addBeforeLoaders Add a new *loader* **before** all the loaders that match specified criteria to the webpack config. @@ -784,7 +816,7 @@ const myNewWebpackLoader = { addBeforeLoaders(webpackConfig, loaderByName("eslint-loader"), myNewWebpackLoader); ``` -#### addAfterLoader +##### addAfterLoader Add a new *loader* **after** the loader that match specified criteria to the webpack config. @@ -808,7 +840,7 @@ const myNewWebpackLoader = { addAfterLoader(webpackConfig, loaderByName("eslint-loader"), myNewWebpackLoader); ``` -#### addAfterLoaders +##### addAfterLoaders Add a new *loader* **after** all the loaders that match specified criteria to the webpack config. @@ -833,7 +865,7 @@ const myNewWebpackLoader = { addAfterLoaders(webpackConfig, loaderByName("eslint-loader"), myNewWebpackLoader); ``` -#### throwUnexpectedConfigError +##### throwUnexpectedConfigError Throw an error if the webpack configuration changes and does not match your expectations. (For example, `getLoader` cannot find a loader and `isFound` is `false`.) `create-react-app` might update the structure of their webpack config, @@ -909,20 +941,6 @@ Options: > Only `message` is required. -## Verbose logging - -To activate **verbose** logging specify the CLI option `--verbose` - -```javascript -/* package.json */ - -{ - "scripts": { - "start": "craco start --verbose" - } -} -``` - ## License Copyright © 2020, Groupe Sharegate inc. This code is licensed under the Apache License, Version 2.0. You may obtain a From 1912be6b8ba3e04941a1ef4c93720fa17f71043d Mon Sep 17 00:00:00 2001 From: Robert Banagale Date: Tue, 3 Nov 2020 15:30:36 -0800 Subject: [PATCH 14/14] Update section titles, move verbosity to new Debugging section, format and copy tweaks --- README.md | 16 +++++----- packages/craco/README.md | 65 +++++++++++++++------------------------- 2 files changed, 32 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index fe3d7db4..5df2e220 100644 --- a/README.md +++ b/README.md @@ -21,9 +21,8 @@ All you have to do is create your app using [create-react-app](https://github.co - Custom `react-scripts` version ## Documentation -- [Preface](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#preface) - [Installation](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#installation) -- [CRACO Configuration](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#craco-configuration) +- [Configuration](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#configuration) - [The Mode Property](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#the-mode-property) - [Sample CRACO Configuration File](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#sample-craco-configuration-file) - [Setting a Custom Location for `craco.config.js`](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#setting-a-custom-location-for-cracoconfigjs) @@ -32,18 +31,20 @@ All you have to do is create your app using [create-react-app](https://github.co - [Notes on CRA Configurations and Problem Solving](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#notes-on-cra-configurations-and-problem-solving) - [Ejecting CRA to Learn](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#ejecting-cra-to-learn) - [Direct Versus Functional Config Definitions](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#direct-object-literal-versus-functional-config-definitions) -- [CRACO API](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#craco-api) - Access CRACO-generated configurations for Jest and Webpack +- [API](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#api) - Access CRACO-generated configurations for Jest and Webpack - [Jest Config Generation](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#jest-config-generation) - [Webpack DevServer and Production Config Generation](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#webpack-devserver-and-production-config-generation) - [Recipes](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#recipes) - [Plugins](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#plugins) - - [Available Plugins](#community-maintained-plugins) + - [Available Plugins](#community-maintained-plugins) - Plugins maintained by the community. - [Developing a New Plugin](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#developing-a-new-plugin) - How to develop a plugin for CRACO. - [Plugin Functions](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#plugin-functions) - [Utility Functions for Development](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#utility-functions-for-development) +- [Debugging](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#debugging) + - [Verbose Logging](https://github.com/sharegate/craco/blob/master/packages/craco/README.md#verbose-logging) +- [License](#license) ## Community Maintained Plugins - * [craco-preact](https://github.com/FormAPI/craco-preact) by [@FormAPI](https://github.com/FormAPI) * [craco-less](https://github.com/FormAPI/craco-less) by [@FormAPI](https://github.com/FormAPI) * [craco-antd](https://github.com/FormAPI/craco-antd) by [@FormAPI](https://github.com/FormAPI) @@ -66,9 +67,8 @@ All you have to do is create your app using [create-react-app](https://github.co * [craco-fast-refresh](https://github.com/vimcaw/craco-fast-refresh) by [@vimcaw](https://github.com/vimcaw) ## Acknowledgements - [@timarney](https://github.com/timarney) for having created [react-app-rewired](https://github.com/timarney/react-app-rewired). ## License - -Copyright © 2020, GSoft inc. This code is licensed under the Apache License, Version 2.0. You may obtain a copy of this license at https://github.com/gsoft-inc/gsoft-license/blob/master/LICENSE. +Copyright © 2020, Groupe Sharegate inc. This code is licensed under the Apache License, Version 2.0. You may obtain a +copy of this license at https://github.com/gsoft-inc/gsoft-license/blob/master/LICENSE. diff --git a/packages/craco/README.md b/packages/craco/README.md index b4830b93..2b8b7e11 100644 --- a/packages/craco/README.md +++ b/packages/craco/README.md @@ -7,7 +7,6 @@ Get all the benefits of create-react-app **and** customization without using 'ej All you have to do is create your app using [create-react-app](https://github.com/facebook/create-react-app/) and customize the configuration with a `craco.config.js` file. ## Support - - Create React App (CRA) 3.* - Yarn - Yarn Workspace @@ -16,9 +15,8 @@ All you have to do is create your app using [create-react-app](https://github.co - Custom `react-scripts` version ## Documentation -- [Preface](#preface) - [Installation](#installation) -- [CRACO Configuration](#craco-configuration) +- [Configuration](#configuration) - [The Mode Property](#the-mode-property) - [Sample CRACO Configuration File](#sample-craco-configuration-file) - [Setting a Custom Location for `craco.config.js`](#setting-a-custom-location-for-cracoconfigjs) @@ -27,15 +25,18 @@ All you have to do is create your app using [create-react-app](https://github.co - [Notes on CRA Configurations and Problem Solving](#notes-on-cra-configurations-and-problem-solving) - [Ejecting CRA to Learn](#ejecting-cra-to-learn) - [Direct Versus Functional Config Definitions](#direct-object-literal-versus-functional-config-definitions) -- [CRACO API](#craco-api) - Access CRACO-generated configurations for Jest and Webpack +- [API](#api) - Access CRACO-generated configurations for Jest and Webpack - [Jest Config Generation](#jest-config-generation) - [Webpack DevServer and Production Config Generation](#webpack-devserver-and-production-config-generation) - [Recipes](#recipes) - [Plugins](#plugins) - - [Available Plugins](https://github.com/sharegate/craco#community-maintained-plugins) - Plugins maintained by the community. - - [Developing a New Plugin](#developing-a-new-plugin) - How to develop a plugin for CRACO. + - [Available Plugins](https://github.com/sharegate/craco#community-maintained-plugins) - Plugins maintained by the community + - [Developing a New Plugin](#developing-a-new-plugin) - How to develop a plugin for CRACO - [Plugin Functions](#plugin-functions) - [Utility Functions for Development](#utility-functions-for-development) +- [Debugging](#debugging) + - [Verbose Logging](#verbose-logging) +- [License](#license) ## Preface ### Acknowledgements @@ -135,21 +136,7 @@ Or build your app: $ npm run build ``` -### Verbose logging - -To activate **verbose** logging specify the CLI option `--verbose` - -```javascript -/* package.json */ - -{ - "scripts": { - "start": "craco start --verbose" - } -} -``` - -## CRACO Configuration +## Configuration CRACO is configured with the `craco.config.js` file. This file is divided into sections representing the major parts of what makes up the default create react app. @@ -242,7 +229,6 @@ module.exports = { ``` ### Setting a custom location for craco.config.js - Both options support a **relative** or an **absolute** path. **1- package.json** _(Recommended)_ @@ -369,7 +355,7 @@ devServer: (devServerConfig, { env, paths, proxy, allowedHost }) => { }, ``` -## CRACO API +## API ### Overview If you would like to integrate with other tools, you may want access to configurations generated by CRACO. @@ -433,7 +419,7 @@ already built for common use cases See this list of [Available Plugins](https://github.com/sharegate/craco#community-maintained-plugins) maintained by the community. -### Developing a new plugin +### Developing a New Plugin #### Plugin Functions There are four functions available to a plugin: - `overrideCracoConfig`: Let a plugin customize the config object before it's process by `craco`. @@ -446,7 +432,6 @@ There are four functions available to a plugin: Every function must return the updated config object. ##### overrideCracoConfig - The function `overrideCracoConfig` let a plugin override the config object **before** it's process by `craco`. If a plugin define the function, it will be called with the config object read from the `craco.config.js` file provided @@ -468,7 +453,6 @@ The function will be called with a single object argument having the following s ``` ###### Example - Plugin: ```javascript @@ -502,7 +486,6 @@ module.exports = { ``` ##### overrideWebpackConfig - The function `overrideWebpackConfig` let a plugin override the `webpack` config object **after** it's been customized by `craco`. @@ -523,7 +506,6 @@ The function will be called with a single object argument having the following s ``` ###### Example - Plugin: ```javascript @@ -557,7 +539,6 @@ module.exports = { ``` ##### overrideDevServerConfig - The function `overrideDevServerConfig` let a plugin override the dev server config object **after** it's been customized by `craco`. @@ -579,7 +560,6 @@ The function will be called with a single object argument having the following s ``` ###### Example - Plugin: ```javascript @@ -613,7 +593,6 @@ module.exports = { ``` ##### overrideJestConfig - The function `overrideJestConfig` let a plugin override the `Jest` config object **after** it's been customized by `craco`. @@ -636,7 +615,6 @@ The function will be called with a single object argument having the following s ``` ###### Example - Plugin: ```javascript @@ -685,7 +663,6 @@ const { getLoader, getLoaders, removeLoader, loaderByName, throwUnexpectedConfig ``` ##### getLoader - Retrieve the **first** loader that match the specified criteria from the webpack config. Returns: @@ -714,7 +691,6 @@ if (isFound) { ``` ##### getLoaders - Retrieve **all** the loaders that match the specified criteria from the webpack config. Returns: @@ -747,7 +723,6 @@ if (hasFoundAny) { ``` ##### removeLoaders - Remove **all** the loaders that match the specified criteria from the webpack config. Returns: @@ -768,7 +743,6 @@ removeLoaders(webpackConfig, loaderByName("eslint-loader")); ``` ##### addBeforeLoader - Add a new *loader* **before** the loader that match specified criteria to the webpack config. Returns: @@ -792,7 +766,6 @@ addBeforeLoader(webpackConfig, loaderByName("eslint-loader"), myNewWebpackLoader ``` ##### addBeforeLoaders - Add a new *loader* **before** all the loaders that match specified criteria to the webpack config. Returns: @@ -817,7 +790,6 @@ addBeforeLoaders(webpackConfig, loaderByName("eslint-loader"), myNewWebpackLoade ``` ##### addAfterLoader - Add a new *loader* **after** the loader that match specified criteria to the webpack config. Returns: @@ -841,7 +813,6 @@ addAfterLoader(webpackConfig, loaderByName("eslint-loader"), myNewWebpackLoader) ``` ##### addAfterLoaders - Add a new *loader* **after** all the loaders that match specified criteria to the webpack config. Returns: @@ -866,7 +837,6 @@ addAfterLoaders(webpackConfig, loaderByName("eslint-loader"), myNewWebpackLoader ``` ##### throwUnexpectedConfigError - Throw an error if the webpack configuration changes and does not match your expectations. (For example, `getLoader` cannot find a loader and `isFound` is `false`.) `create-react-app` might update the structure of their webpack config, so it is very important to show a helpful error message when something breaks. @@ -941,7 +911,20 @@ Options: > Only `message` is required. -## License +## Debugging +### Verbose Logging +To activate **verbose** logging specify the CLI option `--verbose` +```javascript +/* package.json */ + +{ + "scripts": { + "start": "craco start --verbose" + } +} +``` + +## License Copyright © 2020, Groupe Sharegate inc. This code is licensed under the Apache License, Version 2.0. You may obtain a copy of this license at https://github.com/gsoft-inc/gsoft-license/blob/master/LICENSE.