next-react-app-scripts v3.0.2
Create Next React App
This package includes a set of scripts that makes configuring a project easier. It is intended to be the likes of Create React App but for NextJS applications.
If you want to start a new project, see create-next-react-app.
If you want to migrate an existing project, please refer to the folder structure, or the template folder. The folder is following the one of CRA to make migrations between the 2 as painless as possible.
NextJS by default
We support all the default options that NextJS provides by using their next/babel configuration as a Babel preset and by using their build script.
Table of contents
- Folder Structure
- Getting Started
- NextJS by default
- Browsers/NodeJS support
- CSS
- Assets
- Environment variables in client side
- CDN
- Port
- Config
- Polyfills
- Tests
- Moment.js locales
Folder Structure
|_ build // Where the generated files will be added
|_ src
| |_ client
| | |_ components
| | |_ pages
| | |_ static
| |_ server
| |_ server.js
| |_ setupTests.js
|_ .babelrc // To inherit the Babel config
|_ .env
|_ .eslintrc.js // To inherit the ESLint config so you can see it in your IDE
|_ .gitignore
|_ package.jsonFor the project to build, these files must exist with exact filenames:
pagesfolder with.jsfiles that map to your routesserver.jsis the NodeJS server entry point..babelrcso when building we use our built-in configuration.
Getting started
After creating your project using Create Next React App, you will have a set of 4 commands:
start
npm start will start your development environment.
build
npm run build will create all the necessary files for your production environments.
By running your build with CI=true, it will make it fail on ESLint warnings.
prod
npm run prod will run your server in a production environment. A build needs to have been generated first.
test
npm test will run your tests in watch mode. To learn more about the test runner, refer to its documentation: jest-run
Browsers/NodeJS support
For browser/node.js compatibility we use babel-preset-env with the following options by default, but you can customize them in your package.json:
{
"targets": {
"node": "8.9.4",
"browsers": ["last 2 versions", "ie 11"]
}
}CSS
You can Next's bundled styled-jsx, but you can also import CSS files directly:
// Any page/component/...
import React from 'react';
import './style.css';
export default function() {
return <span className="my-class-name">Some text</span>;
}For the CSS to be served to your application, you will however have to create a _document.js file in your pages folder:
// src/client/pages/_document.js
import React from 'react';
import Document, { Head, Main, NextScript } from 'next/document';
export default class MyDocument extends Document {
render() {
return (
<html>
<Head>
<link rel="stylesheet" href="/_next/static/style.css" />
</Head>
<body>
<Main />
<NextScript />
</body>
</html>
);
}
}Assets
Import your assets directly from the static folder:
// Any page/component/...
import React from 'react';
import logo from '../static/logo.png';
export default function() {
return <img src={logo} alt="logo" />;
}Environment variables in client side
Your project can consume variables declared in your environment as if they were declared locally in your JS files. By default you will have NODE_ENV defined for you, and any other environment variables starting with NEXT_APP_.
// .env
NEXT_APP_TEST=abc// Any page/component/...
import React from 'react';
export default function() {
return <span>{process.env.NEXT_APP_TEST}</span>;
}Note: You must create custom environment variables beginning with
NEXT_APP_. Any other variables exceptNODE_ENVwill be ignored to avoid accidentally exposing a private key on the machine that could have the same name. Changing any environment variables will require you to restart the development server if it is running.
Leverage assets using CDN
Using a CDN is just an example, it could be that you want to host your JS/CSS/Static files on a different server or just a different domain.
It will work automatically for src/client/static files that you import directly into your code, but you will have to make a small change to your CSS.
To make that happen, you need:
- To create the
PUBLIC_URLvariable and use it as such:
// .env
PUBLIC_URL=https://cdn.net/some/path// src/client/pages/_document.js
// Change
<link rel="stylesheet" href="/_next/static/style.css" />
// To
<link rel="stylesheet" href={`${process.env.ASSET_PREFIX}/static/style.css`} />// Any page/component/...
import React from 'react';
import logo from '../static/logo.png';
export default function() {
return <img src={logo} alt="logo" />;
}Note: CSS and Static files do not work yet. We're waiting on NextJS to publish their next version for that. Once released, it will start working automatically.
After those changes are made, you just need to upload the content of build/public and serve those files from where ever you want.
Customize the port
Customize the port your application will be running on by declaring a PORT variable:
PORT=3001 guestline-scripts startUse your own config
You can use your own config or extend ours by creating a src/client/next.config.js file.
This file should follow the Next.js documentation.
Remember to use your own config in your server.js too.
Use polyfills
In case you want to add your own set of polyfills for the client, just create a polyfills.js file inside the client folder, and add the ones you want to use. create-next-react-app will automatically pick it for you and put it at the beginning of the bundle. You can use directly core-js, as Next already uses it.
Example:
// src/client/polyfills.js
import 'core-js/fn/object/assign';
import 'core-js/fn/array/fill';
import 'core-js/fn/array/from';Tests
By default the test command is using jest-run. Refer to its documentation to see how to work with it.
Moment.js locales
If you use a Moment.js, you might notice that only the English locale is available by default. This is because the locale files are large, and you probably only need a subset of all the locales provided by Moment.js.
To add a specific Moment.js locale to your bundle, you need to import it explicitly. For example:
import moment from 'moment';
import 'moment/locale/fr';If import multiple locales this way, you can later switch between them by calling moment.locale() with the locale name:
import moment from 'moment';
import 'moment/locale/fr';
import 'moment/locale/es';
// ...
moment.locale('fr');This will only work for locales that have been explicitly imported before.