Update template docs (#8050)

* Update template docs * Update custom-templates.md * Update custom-templates.md Co-authored-by: Ian Sutherland <[email protected]>
facebook · Nov 29, 2019 · 29c5e55 · 29c5e55
1 parent f6ba862
commit 29c5e55
Show file tree

Hide file tree

Showing 3 changed files with 91 additions and 2 deletions.
diff --git 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
@@ -0,0 +1,75 @@
+---
+id: custom-templates
+title: Custom Templates
+---
+
+> Note: this feature is available with `[email protected]` 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` when projects are initialized with yarn.
diff --git 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