Running npx create-react-app
is probably the most popular way of starting a new React project - however don't you wish if the bootstrapped project uses the folder structure you prefer? or comes with more strict eslint
rules (or custom ones your team use all the time)? or includes more popular stuff like prettier
auto-formatting, some UI component library you prefer? With the release of create-react-app@3.3.0
it's now possible to use a custom template to create new projects:
npx create-react-app PROJECT_NAME --template my-awesome-template
So how do we create & publish our own templates?
Project Structure
There are some limited documentation on the official site - however the official templates repo offers more clues.
When we look at the official template repo, we can see there are three major components to a template:
-
package.json
- this has nothing to do with thepackage.json
file we see in a typical react project. This file here defines the template package - Acra
template is just anothernpm
package - once it's published - anyone can use thecreate-react-app
cli just by referencing the name of the package. -
template.json
- interesting, it seems it's an extension topackage.json
- if we want to include any extra dependencies, we can put them here. -
template
- it's the main project folder, this should include all the files we would like to include in the newly bootstrapped project. Notice that there are nopackage.json
orpackage-lock.json
files here - we should letcreate-react-app
handle them.
Seems pretty straight forward, let's create our own template!
Setting Up
I would like to start with the template
folder - the easiest way is to create an empty project with create-react-app
npx create-react-app my-awesome-template
Now, let's go to the project folder and add some extra dependencies with yarn
.
cd my-awesome-template
yarn add node-sass @material-ui/core prettier
We can edit & re-organize the files in this project, add a .prettierrc
or .eslintrc
, change the components, add your own logos, fonts, etc. Go crazy, make it look like the ideal project you want it to be! Don't forget to edit the README
file as well.
Publishing to npm
Now we've got the templates, let's make a new folder which will be the home to our template project:
mkdir cra-template-my-awesome-template
Usually we should use something like npm init
to create a new package.json
file for our package, but here let's just copy the one from the official template
Open the file in your favorite editor, and make sure to change the following fields:
-
name
: name of the template package. By convention the name of the package should be prefixed withcra-template-
, however it's not required. The benefit of having that prefix is that the users won't have to type the full name of the package to use it. If you need to publish the package under an organization, your users will have to use the fullname of the template, instead of just the part after the prefix. e.g. if the name here is@acme-inc/cra-template-acme
, the user will have to speicify--template @acme-inc/cra-template-acme
in the command line. -
version
: your own version - by default cra will always use the latest version found on npm. -
description
,author
,keywords
: introduce yourself and your template to the world -
repository
: if you don't have a repo for this, just delete this for now, however we should always check our templates into source control.
Now, create a template.json
file, and copy the dependencies we installed earlier to this file. If you have some custom scripts, you can add a scripts
field here as well. Remember not to include anything that usually comes with create-react-app
.
{
"dependencies": {
"@material-ui/core": "^4.8.0",
"node-sass": "^4.12.0",
"prettier": "^1.19.1"
},
"scripts": {
"fix-formatting": "prettier --write src/**/*.{js,jsx}"
}
}
At the time of writing, only dependencies
and scripts
are supported, everything else will be ignored. Also, if you have npm run
in your scripts, they will be replaced automatically with yarn
if your user uses yarn
to bootstrap their apps. Nice!
Next, let's copy the project we setup previously to the template
folder. A few notes:
- don't copy
package.json
oryarn.lock
orpackage-lock.json
- we wantcreate-react-app
cli to manage them - don't copy
node_modules
orbuild
- or anything that you don't want to check into source control. - rename
.gitignore
togitignore
(cra will rename it back)
And it's ready to be shipped to the world! 🚀
npm publish
Don't forget to share your awesome template repo with the world as well - keeping the dependencies up-to-date and fixing bugs ASAP are as important as sharing your awesome ideas with the community.
And we are done! Congrats and happy coding!
Top comments (2)
Thank you for the guide!
Pretty awesome feature