From bf4413f7dc5ee93fb2ebe59c80bf2de4ca2e18a2 Mon Sep 17 00:00:00 2001 From: Brody McKee Date: Fri, 29 Nov 2019 16:58:27 +0200 Subject: [PATCH 1/3] Update template docs --- CHANGELOG.md | 14 +++++- docusaurus/docs/custom-templates.md | 75 +++++++++++++++++++++++++++++ docusaurus/docs/getting-started.md | 4 +- 3 files changed, 91 insertions(+), 2 deletions(-) create mode 100644 docusaurus/docs/custom-templates.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 96dac9fb423..cc55c9e36d8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,19 @@ v3.3.0 is a minor release that adds new features, including custom templates and ### Custom Templates -DRAFT +You can now create a new app using custom templates. + +We've published our existing templates as [`cra-template`](https://github.com/facebook/create-react-app/tree/master/packages/cra-template) and [`cra-template-typescript`](https://github.com/facebook/create-react-app/tree/master/packages/cra-template-typescript), but we expect to see many great templates from the community over the coming weeks. + +The below command shows how you can create a new app with `cra-template-typescript`. + +```sh +npx create-react-app my-app --template typescript +``` + +Note that you can omit the prefix `cra-template-` when specifying which template you would like. For TypeScript users, we're deprecating `--typescript` in favour of `--template typescript`. + +If you don't set a template, we'll create your new app with `cra-template` - which is just a new name for our base template. ### Optional Chaining and Nullish Coalescing Operators diff --git a/docusaurus/docs/custom-templates.md b/docusaurus/docs/custom-templates.md new file mode 100644 index 00000000000..33ae0c1f455 --- /dev/null +++ b/docusaurus/docs/custom-templates.md @@ -0,0 +1,75 @@ +--- +id: custom-templates +title: Custom Templates +--- + +> Note: this feature is available with `react-scripts@3.3.0` and higher. + +Custom Templates enable you to select a template to create your project from, while still retaining all of the features of Create React App. + +You'll notice that Custom Templates are always named in the format `cra-template-[template-name]`, however you only need to provide the `[template-name]` to the creation command. + +### npm + +```sh +npm init react-app my-app --template [template-name] +``` + +### Yarn + +```sh +yarn create react-app my-app --template [template-name] +``` + +## Finding custom templates + +We ship two templates by default: + +- [`cra-template`](https://github.com/facebook/create-react-app/tree/master/packages/cra-template) +- [`cra-template-typescript`](https://github.com/facebook/create-react-app/tree/master/packages/cra-template-typescript) + +However, you can find many great community templates by searching for ["cra-template-\*"](https://www.npmjs.com/search?q=cra-template-*) on npm. + +## Building a template + +If you're interested in building a custom template, first take a look at how we've built [`cra-template`](https://github.com/facebook/create-react-app/tree/master/packages/cra-template). + +A template must have the following structure: + +``` +my-app/ + README.md (for npm) + template.json + package.json + template/ + README.md (for projects created from this template) + gitignore + public/ + index.html + src/ + index.js (or index.tsx) +``` + +### The `template` folder + +This folder is copied to the user's app directory as Create React App installs. During this process, the file `gitignore` is renamed to `.gitignore`. + +You can add whatever files you want in here, but you must have at least the files specified above. + +### The `template.json` file + +This is where you can define dependencies (only dependencies are supported for now), as well as any custom scripts that your template relies on. + +```json +{ + "dependencies": { + "serve": "^11.2.0" + }, + "scripts": { + "serve": "serve -s build", + "build-and-serve": "npm run build && npm run serve" + } +} +``` + +For convenience, we always replace `npm run` with `yarn` in your custom `"scripts"`, as well as in your `README`. diff --git a/docusaurus/docs/getting-started.md b/docusaurus/docs/getting-started.md index 7651ad9dc5b..98484f9ac6d 100644 --- a/docusaurus/docs/getting-started.md +++ b/docusaurus/docs/getting-started.md @@ -74,7 +74,9 @@ Templates are always named in the format `cra-template-[template-name]`, however npx create-react-app my-app --template [template-name] ``` -> You can find a a list of available templates by searching for ["cra-template-\*"](https://www.npmjs.com/search?q=cra-template-*) on npm. +> You can find a list of available templates by searching for ["cra-template-\*"](https://www.npmjs.com/search?q=cra-template-*) on npm. + +Our [Custom Templates](custom-templates.md) documentation describes how you can build your own template. #### Creating a TypeScript app From 388bcb5783af1bf147f7d4bc3effc93ae2894574 Mon Sep 17 00:00:00 2001 From: Ian Sutherland Date: Fri, 29 Nov 2019 10:37:55 -0700 Subject: [PATCH 2/3] Update custom-templates.md --- docusaurus/docs/custom-templates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/custom-templates.md b/docusaurus/docs/custom-templates.md index 33ae0c1f455..2849fcd33cf 100644 --- a/docusaurus/docs/custom-templates.md +++ b/docusaurus/docs/custom-templates.md @@ -72,4 +72,4 @@ This is where you can define dependencies (only dependencies are supported for n } ``` -For convenience, we always replace `npm run` with `yarn` in your custom `"scripts"`, as well as in your `README`. +For convenience, we always replace `npm run` with `yarn` in your custom `"scripts"`, as well as in your `README` when apps are initialized with yarn. From 19654ad902c16ace19b21891b63c883c49ca4537 Mon Sep 17 00:00:00 2001 From: Ian Sutherland Date: Fri, 29 Nov 2019 10:38:18 -0700 Subject: [PATCH 3/3] Update custom-templates.md --- docusaurus/docs/custom-templates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus/docs/custom-templates.md b/docusaurus/docs/custom-templates.md index 2849fcd33cf..98acb9b1a75 100644 --- a/docusaurus/docs/custom-templates.md +++ b/docusaurus/docs/custom-templates.md @@ -72,4 +72,4 @@ This is where you can define dependencies (only dependencies are supported for n } ``` -For convenience, we always replace `npm run` with `yarn` in your custom `"scripts"`, as well as in your `README` when apps are initialized with yarn. +For convenience, we always replace `npm run` with `yarn` in your custom `"scripts"`, as well as in your `README` when projects are initialized with yarn.