mirror of
https://github.com/terribleplan/next.js.git
synced 2024-01-19 02:48:18 +00:00
401594ed36
Since glamorous is [no longer maintained](https://github.com/paypal/glamorous#status-unmaintained) removing it from readme.
1867 lines
61 KiB
Markdown
1867 lines
61 KiB
Markdown
[](https://nextjs.org)
|
||
|
||
[](https://www.npmjs.com/package/next)
|
||
[](https://travis-ci.org/zeit/next.js)
|
||
[](https://dev.azure.com/nextjs/next.js/_build/latest?definitionId=3)
|
||
[](https://coveralls.io/r/zeit/next.js?branch=master)
|
||
[](https://spectrum.chat/next-js)
|
||
|
||
**Visit [nextjs.org/learn](https://nextjs.org/learn) to get started with Next.js.**
|
||
|
||
---
|
||
|
||
**The below readme is the documentation for the `canary` (prerelease) branch. To view the documentation for the latest stable Next.js version visit [nextjs.org/docs](https://nextjs.org/docs)**
|
||
|
||
---
|
||
|
||
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
||
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
||
<!-- https://github.com/thlorenz/doctoc -->
|
||
|
||
- [How to use](#how-to-use)
|
||
- [Setup](#setup)
|
||
- [Automatic code splitting](#automatic-code-splitting)
|
||
- [CSS](#css)
|
||
- [Built-in CSS support](#built-in-css-support)
|
||
- [CSS-in-JS](#css-in-js)
|
||
- [Importing CSS / Sass / Less / Stylus files](#importing-css--sass--less--stylus-files)
|
||
- [Static file serving (e.g.: images)](#static-file-serving-eg-images)
|
||
- [Populating `<head>`](#populating-head)
|
||
- [Fetching data and component lifecycle](#fetching-data-and-component-lifecycle)
|
||
- [Routing](#routing)
|
||
- [With `<Link>`](#with-link)
|
||
- [With URL object](#with-url-object)
|
||
- [Replace instead of push url](#replace-instead-of-push-url)
|
||
- [Using a component that supports `onClick`](#using-a-component-that-supports-onclick)
|
||
- [Forcing the Link to expose `href` to its child](#forcing-the-link-to-expose-href-to-its-child)
|
||
- [Disabling the scroll changes to top on page](#disabling-the-scroll-changes-to-top-on-page)
|
||
- [Imperatively](#imperatively)
|
||
- [Intercepting `popstate`](#intercepting-popstate)
|
||
- [With URL object](#with-url-object-1)
|
||
- [Router Events](#router-events)
|
||
- [Shallow Routing](#shallow-routing)
|
||
- [Using a Higher Order Component](#using-a-higher-order-component)
|
||
- [Prefetching Pages](#prefetching-pages)
|
||
- [With `<Link>`](#with-link-1)
|
||
- [Imperatively](#imperatively-1)
|
||
- [Custom server and routing](#custom-server-and-routing)
|
||
- [Disabling file-system routing](#disabling-file-system-routing)
|
||
- [Dynamic assetPrefix](#dynamic-assetprefix)
|
||
- [Dynamic Import](#dynamic-import)
|
||
- [1. Basic Usage (Also does SSR)](#1-basic-usage-also-does-ssr)
|
||
- [2. With Custom Loading Component](#2-with-custom-loading-component)
|
||
- [3. With No SSR](#3-with-no-ssr)
|
||
- [4. With Multiple Modules At Once](#4-with-multiple-modules-at-once)
|
||
- [Custom `<App>`](#custom-app)
|
||
- [Custom `<Document>`](#custom-document)
|
||
- [Custom error handling](#custom-error-handling)
|
||
- [Reusing the built-in error page](#reusing-the-built-in-error-page)
|
||
- [Custom configuration](#custom-configuration)
|
||
- [Setting a custom build directory](#setting-a-custom-build-directory)
|
||
- [Disabling etag generation](#disabling-etag-generation)
|
||
- [Configuring the onDemandEntries](#configuring-the-ondemandentries)
|
||
- [Configuring extensions looked for when resolving pages in `pages`](#configuring-extensions-looked-for-when-resolving-pages-in-pages)
|
||
- [Configuring the build ID](#configuring-the-build-id)
|
||
- [Customizing webpack config](#customizing-webpack-config)
|
||
- [Customizing babel config](#customizing-babel-config)
|
||
- [Exposing configuration to the server / client side](#exposing-configuration-to-the-server--client-side)
|
||
- [Starting the server on alternative hostname](#starting-the-server-on-alternative-hostname)
|
||
- [CDN support with Asset Prefix](#cdn-support-with-asset-prefix)
|
||
- [Production deployment](#production-deployment)
|
||
- [Static HTML export](#static-html-export)
|
||
- [Usage](#usage)
|
||
- [Limitation](#limitation)
|
||
- [Multi Zones](#multi-zones)
|
||
- [How to define a zone](#how-to-define-a-zone)
|
||
- [How to merge them](#how-to-merge-them)
|
||
- [Recipes](#recipes)
|
||
- [FAQ](#faq)
|
||
- [Contributing](#contributing)
|
||
- [Authors](#authors)
|
||
|
||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||
|
||
## How to use
|
||
|
||
### Setup
|
||
|
||
Install it:
|
||
|
||
```bash
|
||
npm install --save next react react-dom
|
||
```
|
||
|
||
and add a script to your package.json like this:
|
||
|
||
```json
|
||
{
|
||
"scripts": {
|
||
"dev": "next",
|
||
"build": "next build",
|
||
"start": "next start"
|
||
}
|
||
}
|
||
```
|
||
|
||
After that, the file-system is the main API. Every `.js` file becomes a route that gets automatically processed and rendered.
|
||
|
||
Populate `./pages/index.js` inside your project:
|
||
|
||
```jsx
|
||
export default () => <div>Welcome to next.js!</div>
|
||
```
|
||
|
||
and then just run `npm run dev` and go to `http://localhost:3000`. To use another port, you can run `npm run dev -- -p <your port here>`.
|
||
|
||
So far, we get:
|
||
|
||
- Automatic transpilation and bundling (with webpack and babel)
|
||
- Hot code reloading
|
||
- Server rendering and indexing of `./pages`
|
||
- Static file serving. `./static/` is mapped to `/static/` (given you [create a `./static/` directory](#static-file-serving-eg-images) inside your project)
|
||
|
||
To see how simple this is, check out the [sample app - nextgram](https://github.com/zeit/nextgram)
|
||
|
||
### Automatic code splitting
|
||
|
||
Every `import` you declare gets bundled and served with each page. That means pages never load unnecessary code!
|
||
|
||
```jsx
|
||
import cowsay from 'cowsay-browser'
|
||
|
||
export default () => (
|
||
<pre>
|
||
{cowsay.say({ text: 'hi there!' })}
|
||
</pre>
|
||
)
|
||
```
|
||
|
||
### CSS
|
||
|
||
#### Built-in CSS support
|
||
|
||
<details>
|
||
<summary><b>Examples</b></summary>
|
||
<ul>
|
||
<li><a href="/examples/basic-css">Basic css</a></li>
|
||
</ul>
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
We bundle [styled-jsx](https://github.com/zeit/styled-jsx) to provide support for isolated scoped CSS. The aim is to support "shadow CSS" similar to Web Components, which unfortunately [do not support server-rendering and are JS-only](https://github.com/w3c/webcomponents/issues/71).
|
||
|
||
```jsx
|
||
export default () => (
|
||
<div>
|
||
Hello world
|
||
<p>scoped!</p>
|
||
<style jsx>{`
|
||
p {
|
||
color: blue;
|
||
}
|
||
div {
|
||
background: red;
|
||
}
|
||
@media (max-width: 600px) {
|
||
div {
|
||
background: blue;
|
||
}
|
||
}
|
||
`}</style>
|
||
<style global jsx>{`
|
||
body {
|
||
background: black;
|
||
}
|
||
`}</style>
|
||
</div>
|
||
)
|
||
```
|
||
|
||
Please see the [styled-jsx documentation](https://www.npmjs.com/package/styled-jsx) for more examples.
|
||
|
||
#### CSS-in-JS
|
||
|
||
<details>
|
||
<summary>
|
||
<b>Examples</b>
|
||
</summary>
|
||
<ul>
|
||
<li><a href="/examples/with-styled-components">Styled components</a></li>
|
||
<li><a href="/examples/with-styletron">Styletron</a></li>
|
||
<li><a href="/examples/with-glamor">Glamor</a></li>
|
||
<li><a href="/examples/with-cxs">Cxs</a></li>
|
||
<li><a href="/examples/with-aphrodite">Aphrodite</a></li>
|
||
<li><a href="/examples/with-fela">Fela</a></li>
|
||
</ul>
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
It's possible to use any existing CSS-in-JS solution. The simplest one is inline styles:
|
||
|
||
```jsx
|
||
export default () => <p style={{ color: 'red' }}>hi there</p>
|
||
```
|
||
|
||
To use more sophisticated CSS-in-JS solutions, you typically have to implement style flushing for server-side rendering. We enable this by allowing you to define your own [custom `<Document>`](#user-content-custom-document) component that wraps each page.
|
||
|
||
#### Importing CSS / Sass / Less / Stylus files
|
||
|
||
To support importing `.css`, `.scss`, `.less` or `.styl` files you can use these modules, which configure sensible defaults for server rendered applications.
|
||
|
||
- [@zeit/next-css](https://github.com/zeit/next-plugins/tree/master/packages/next-css)
|
||
- [@zeit/next-sass](https://github.com/zeit/next-plugins/tree/master/packages/next-sass)
|
||
- [@zeit/next-less](https://github.com/zeit/next-plugins/tree/master/packages/next-less)
|
||
- [@zeit/next-stylus](https://github.com/zeit/next-plugins/tree/master/packages/next-stylus)
|
||
|
||
### Static file serving (e.g.: images)
|
||
|
||
Create a folder called `static` in your project root directory. From your code you can then reference those files with `/static/` URLs:
|
||
|
||
```jsx
|
||
export default () => <img src="/static/my-image.png" alt="my image" />
|
||
```
|
||
|
||
_Note: Don't name the `static` directory anything else. The name is required and is the only directory that Next.js uses for serving static assets._
|
||
|
||
### Populating `<head>`
|
||
|
||
<details>
|
||
<summary><b>Examples</b></summary>
|
||
<ul>
|
||
<li><a href="/examples/head-elements">Head elements</a></li>
|
||
<li><a href="/examples/layout-component">Layout component</a></li>
|
||
</ul>
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
We expose a built-in component for appending elements to the `<head>` of the page.
|
||
|
||
```jsx
|
||
import Head from 'next/head'
|
||
|
||
export default () => (
|
||
<div>
|
||
<Head>
|
||
<title>My page title</title>
|
||
<meta name="viewport" content="initial-scale=1.0, width=device-width" />
|
||
</Head>
|
||
<p>Hello world!</p>
|
||
</div>
|
||
)
|
||
```
|
||
|
||
To avoid duplicate tags in your `<head>` you can use the `key` property, which will make sure the tag is only rendered once:
|
||
|
||
```jsx
|
||
import Head from 'next/head'
|
||
|
||
export default () => (
|
||
<div>
|
||
<Head>
|
||
<title>My page title</title>
|
||
<meta name="viewport" content="initial-scale=1.0, width=device-width" key="viewport" />
|
||
</Head>
|
||
<Head>
|
||
<meta name="viewport" content="initial-scale=1.2, width=device-width" key="viewport" />
|
||
</Head>
|
||
<p>Hello world!</p>
|
||
</div>
|
||
)
|
||
```
|
||
|
||
In this case only the second `<meta name="viewport" />` is rendered.
|
||
|
||
_Note: The contents of `<head>` get cleared upon unmounting the component, so make sure each page completely defines what it needs in `<head>`, without making assumptions about what other pages added_
|
||
|
||
### Fetching data and component lifecycle
|
||
|
||
<details>
|
||
<summary><b>Examples</b></summary>
|
||
<ul>
|
||
<li><a href="/examples/data-fetch">Data fetch</a></li>
|
||
</ul>
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
When you need state, lifecycle hooks or **initial data population** you can export a `React.Component` (instead of a stateless function, like shown above):
|
||
|
||
```jsx
|
||
import React from 'react'
|
||
|
||
export default class extends React.Component {
|
||
static async getInitialProps({ req }) {
|
||
const userAgent = req ? req.headers['user-agent'] : navigator.userAgent
|
||
return { userAgent }
|
||
}
|
||
|
||
render() {
|
||
return (
|
||
<div>
|
||
Hello World {this.props.userAgent}
|
||
</div>
|
||
)
|
||
}
|
||
}
|
||
```
|
||
|
||
Notice that to load data when the page loads, we use `getInitialProps` which is an [`async`](https://zeit.co/blog/async-and-await) static method. It can asynchronously fetch anything that resolves to a JavaScript plain `Object`, which populates `props`.
|
||
|
||
Data returned from `getInitialProps` is serialized when server rendering, similar to a `JSON.stringify`. Make sure the returned object from `getInitialProps` is a plain `Object` and not using `Date`, `Map` or `Set`.
|
||
|
||
For the initial page load, `getInitialProps` will execute on the server only. `getInitialProps` will only be executed on the client when navigating to a different route via the `Link` component or using the routing APIs.
|
||
|
||
_Note: `getInitialProps` can **not** be used in children components. Only in `pages`._
|
||
|
||
<br/>
|
||
|
||
> If you are using some server only modules inside `getInitialProps`, make sure to [import them properly](https://arunoda.me/blog/ssr-and-server-only-modules).
|
||
> Otherwise, it'll slow down your app.
|
||
|
||
<br/>
|
||
|
||
You can also define the `getInitialProps` lifecycle method for stateless components:
|
||
|
||
```jsx
|
||
const Page = ({ stars }) =>
|
||
<div>
|
||
Next stars: {stars}
|
||
</div>
|
||
|
||
Page.getInitialProps = async ({ req }) => {
|
||
const res = await fetch('https://api.github.com/repos/zeit/next.js')
|
||
const json = await res.json()
|
||
return { stars: json.stargazers_count }
|
||
}
|
||
|
||
export default Page
|
||
```
|
||
|
||
`getInitialProps` receives a context object with the following properties:
|
||
|
||
- `pathname` - path section of URL
|
||
- `query` - query string section of URL parsed as an object
|
||
- `asPath` - `String` of the actual path (including the query) shows in the browser
|
||
- `req` - HTTP request object (server only)
|
||
- `res` - HTTP response object (server only)
|
||
- `jsonPageRes` - [Fetch Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) object (client only)
|
||
- `err` - Error object if any error is encountered during the rendering
|
||
|
||
### Routing
|
||
|
||
#### With `<Link>`
|
||
|
||
<details>
|
||
<summary><b>Examples</b></summary>
|
||
<ul>
|
||
<li><a href="/examples/hello-world">Hello World</a></li>
|
||
</ul>
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
Client-side transitions between routes can be enabled via a `<Link>` component. Consider these two pages:
|
||
|
||
```jsx
|
||
// pages/index.js
|
||
import Link from 'next/link'
|
||
|
||
export default () => (
|
||
<div>
|
||
Click{' '}
|
||
<Link href="/about">
|
||
<a>here</a>
|
||
</Link>{' '}
|
||
to read more
|
||
</div>
|
||
)
|
||
```
|
||
|
||
```jsx
|
||
// pages/about.js
|
||
export default () => <p>Welcome to About!</p>
|
||
```
|
||
|
||
__Note: use [`<Link prefetch>`](#prefetching-pages) for maximum performance, to link and prefetch in the background at the same time__
|
||
|
||
Client-side routing behaves exactly like the browser:
|
||
|
||
1. The component is fetched
|
||
2. If it defines `getInitialProps`, data is fetched. If an error occurs, `_error.js` is rendered
|
||
3. After 1 and 2 complete, `pushState` is performed and the new component is rendered
|
||
|
||
To inject the `pathname`, `query` or `asPath` in your component, you can use [withRouter](#using-a-higher-order-component).
|
||
|
||
##### With URL object
|
||
|
||
<details>
|
||
<summary><b>Examples</b></summary>
|
||
<ul>
|
||
<li><a href="/examples/with-url-object-routing">With URL Object Routing</a></li>
|
||
</ul>
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
The component `<Link>` can also receive an URL object and it will automatically format it to create the URL string.
|
||
|
||
```jsx
|
||
// pages/index.js
|
||
import Link from 'next/link'
|
||
|
||
export default () => (
|
||
<div>
|
||
Click{' '}
|
||
<Link href={{ pathname: '/about', query: { name: 'Zeit' } }}>
|
||
<a>here</a>
|
||
</Link>{' '}
|
||
to read more
|
||
</div>
|
||
)
|
||
```
|
||
|
||
That will generate the URL string `/about?name=Zeit`, you can use every property as defined in the [Node.js URL module documentation](https://nodejs.org/api/url.html#url_url_strings_and_url_objects).
|
||
|
||
##### Replace instead of push url
|
||
|
||
The default behaviour for the `<Link>` component is to `push` a new url into the stack. You can use the `replace` prop to prevent adding a new entry.
|
||
|
||
```jsx
|
||
// pages/index.js
|
||
import Link from 'next/link'
|
||
|
||
export default () => (
|
||
<div>
|
||
Click{' '}
|
||
<Link href="/about" replace>
|
||
<a>here</a>
|
||
</Link>{' '}
|
||
to read more
|
||
</div>
|
||
)
|
||
```
|
||
|
||
##### Using a component that supports `onClick`
|
||
|
||
`<Link>` supports any component that supports the `onClick` event. In case you don't provide an `<a>` tag, it will only add the `onClick` event handler and won't pass the `href` property.
|
||
|
||
```jsx
|
||
// pages/index.js
|
||
import Link from 'next/link'
|
||
|
||
export default () => (
|
||
<div>
|
||
Click{' '}
|
||
<Link href="/about">
|
||
<img src="/static/image.png" alt="image" />
|
||
</Link>
|
||
</div>
|
||
)
|
||
```
|
||
|
||
##### Forcing the Link to expose `href` to its child
|
||
|
||
If child is an `<a>` tag and doesn't have a href attribute we specify it so that the repetition is not needed by the user. However, sometimes, you’ll want to pass an `<a>` tag inside of a wrapper and the `Link` won’t recognize it as a *hyperlink*, and, consequently, won’t transfer its `href` to the child. In cases like that, you should define a boolean `passHref` property to the `Link`, forcing it to expose its `href` property to the child.
|
||
|
||
**Please note**: using a tag other than `a` and failing to pass `passHref` may result in links that appear to navigate correctly, but, when being crawled by search engines, will not be recognized as links (owing to the lack of `href` attribute). This may result in negative effects on your sites SEO.
|
||
|
||
```jsx
|
||
import Link from 'next/link'
|
||
import Unexpected_A from 'third-library'
|
||
|
||
export default ({ href, name }) => (
|
||
<Link href={href} passHref>
|
||
<Unexpected_A>
|
||
{name}
|
||
</Unexpected_A>
|
||
</Link>
|
||
)
|
||
```
|
||
|
||
##### Disabling the scroll changes to top on page
|
||
|
||
The default behaviour of `<Link>` is to scroll to the top of the page. When there is a hash defined it will scroll to the specific id, just like a normal `<a>` tag. To prevent scrolling to the top / hash `scroll={false}` can be added to `<Link>`:
|
||
|
||
```jsx
|
||
<Link scroll={false} href="/?counter=10"><a>Disables scrolling</a></Link>
|
||
<Link href="/?counter=10"><a>Changes with scrolling to top</a></Link>
|
||
```
|
||
|
||
#### Imperatively
|
||
|
||
<details>
|
||
<summary><b>Examples</b></summary>
|
||
<ul>
|
||
<li><a href="/examples/using-router">Basic routing</a></li>
|
||
<li><a href="/examples/with-loading">With a page loading indicator</a></li>
|
||
</ul>
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
You can also do client-side page transitions using the `next/router`
|
||
|
||
```jsx
|
||
import Router from 'next/router'
|
||
|
||
export default () => (
|
||
<div>
|
||
Click <span onClick={() => Router.push('/about')}>here</span> to read more
|
||
</div>
|
||
)
|
||
```
|
||
|
||
#### Intercepting `popstate`
|
||
|
||
In some cases (for example, if using a [custom router](#custom-server-and-routing)), you may wish
|
||
to listen to [`popstate`](https://developer.mozilla.org/en-US/docs/Web/Events/popstate) and react before the router acts on it.
|
||
For example, you could use this to manipulate the request, or force an SSR refresh.
|
||
|
||
```jsx
|
||
import Router from 'next/router'
|
||
|
||
Router.beforePopState(({ url, as, options }) => {
|
||
// I only want to allow these two routes!
|
||
if (as !== "/" || as !== "/other") {
|
||
// Have SSR render bad routes as a 404.
|
||
window.location.href = as
|
||
return false
|
||
}
|
||
|
||
return true
|
||
});
|
||
```
|
||
|
||
If the function you pass into `beforePopState` returns `false`, `Router` will not handle `popstate`;
|
||
you'll be responsible for handling it, in that case.
|
||
See [Disabling File-System Routing](#disabling-file-system-routing).
|
||
|
||
Above `Router` object comes with the following API:
|
||
|
||
- `route` - `String` of the current route
|
||
- `pathname` - `String` of the current path excluding the query string
|
||
- `query` - `Object` with the parsed query string. Defaults to `{}`
|
||
- `asPath` - `String` of the actual path (including the query) shows in the browser
|
||
- `push(url, as=url)` - performs a `pushState` call with the given url
|
||
- `replace(url, as=url)` - performs a `replaceState` call with the given url
|
||
- `beforePopState(cb=function)` - intercept popstate before router processes the event.
|
||
|
||
The second `as` parameter for `push` and `replace` is an optional _decoration_ of the URL. Useful if you configured custom routes on the server.
|
||
|
||
##### With URL object
|
||
You can use an URL object the same way you use it in a `<Link>` component to `push` and `replace` an URL.
|
||
|
||
```jsx
|
||
import Router from 'next/router'
|
||
|
||
const handler = () => {
|
||
Router.push({
|
||
pathname: '/about',
|
||
query: { name: 'Zeit' }
|
||
})
|
||
}
|
||
|
||
export default () => (
|
||
<div>
|
||
Click <span onClick={handler}>here</span> to read more
|
||
</div>
|
||
)
|
||
```
|
||
|
||
This uses the same exact parameters as in the `<Link>` component.
|
||
|
||
##### Router Events
|
||
|
||
You can also listen to different events happening inside the Router.
|
||
Here's a list of supported events:
|
||
|
||
- `routeChangeStart(url)` - Fires when a route starts to change
|
||
- `routeChangeComplete(url)` - Fires when a route changed completely
|
||
- `routeChangeError(err, url)` - Fires when there's an error when changing routes
|
||
- `beforeHistoryChange(url)` - Fires just before changing the browser's history
|
||
- `hashChangeStart(url)` - Fires when the hash will change but not the page
|
||
- `hashChangeComplete(url)` - Fires when the hash has changed but not the page
|
||
|
||
> Here `url` is the URL shown in the browser. If you call `Router.push(url, as)` (or similar), then the value of `url` will be `as`.
|
||
|
||
Here's how to properly listen to the router event `routeChangeStart`:
|
||
|
||
```js
|
||
const handleRouteChange = url => {
|
||
console.log('App is changing to: ', url)
|
||
}
|
||
|
||
Router.events.on('routeChangeStart', handleRouteChange)
|
||
```
|
||
|
||
If you no longer want to listen to that event, you can unsubscribe with the `off` method:
|
||
|
||
```js
|
||
Router.events.off('routeChangeStart', handleRouteChange)
|
||
```
|
||
|
||
If a route load is cancelled (for example by clicking two links rapidly in succession), `routeChangeError` will fire. The passed `err` will contain a `cancelled` property set to `true`.
|
||
|
||
```js
|
||
Router.events.on('routeChangeError', (err, url) => {
|
||
if (err.cancelled) {
|
||
console.log(`Route to ${url} was cancelled!`)
|
||
}
|
||
})
|
||
```
|
||
|
||
##### Shallow Routing
|
||
|
||
<details>
|
||
<summary><b>Examples</b></summary>
|
||
<ul>
|
||
<li><a href="/examples/with-shallow-routing">Shallow Routing</a></li>
|
||
</ul>
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
Shallow routing allows you to change the URL without running `getInitialProps`. You'll receive the updated `pathname` and the `query` via the `url` prop of the same page that's loaded, without losing state.
|
||
|
||
You can do this by invoking either `Router.push` or `Router.replace` with the `shallow: true` option. Here's an example:
|
||
|
||
```js
|
||
// Current URL is "/"
|
||
const href = '/?counter=10'
|
||
const as = href
|
||
Router.push(href, as, { shallow: true })
|
||
```
|
||
|
||
Now, the URL is updated to `/?counter=10`. You can see the updated URL with `this.props.router.query` inside the `Component` (make sure you are using [`withRouter`](#using-a-higher-order-component) around your `Component` to inject the `router` prop).
|
||
|
||
You can watch for URL changes via [`componentDidUpdate`](https://reactjs.org/docs/react-component.html#componentdidupdate) hook as shown below:
|
||
|
||
```js
|
||
componentDidUpdate(prevProps) {
|
||
const { pathname, query } = this.props.router
|
||
// verify props have changed to avoid an infinite loop
|
||
if (query.id !== prevProps.router.query.id) {
|
||
// fetch data based on the new query
|
||
}
|
||
}
|
||
```
|
||
|
||
> NOTES:
|
||
>
|
||
> Shallow routing works **only** for same page URL changes. For an example, let's assume we have another page called `about`, and you run this:
|
||
> ```js
|
||
> Router.push('/?counter=10', '/about?counter=10', { shallow: true })
|
||
> ```
|
||
> Since that's a new page, it'll unload the current page, load the new one and call `getInitialProps` even though we asked to do shallow routing.
|
||
|
||
#### Using a Higher Order Component
|
||
|
||
<details>
|
||
<summary><b>Examples</b></summary>
|
||
<ul>
|
||
<li><a href="/examples/using-with-router">Using the `withRouter` utility</a></li>
|
||
</ul>
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
If you want to access the `router` object inside any component in your app, you can use the `withRouter` Higher-Order Component. Here's how to use it:
|
||
|
||
```jsx
|
||
import { withRouter } from 'next/router'
|
||
|
||
const ActiveLink = ({ children, router, href }) => {
|
||
const style = {
|
||
marginRight: 10,
|
||
color: router.pathname === href ? 'red' : 'black'
|
||
}
|
||
|
||
const handleClick = (e) => {
|
||
e.preventDefault()
|
||
router.push(href)
|
||
}
|
||
|
||
return (
|
||
<a href={href} onClick={handleClick} style={style}>
|
||
{children}
|
||
</a>
|
||
)
|
||
}
|
||
|
||
export default withRouter(ActiveLink)
|
||
```
|
||
|
||
The above `router` object comes with an API similar to [`next/router`](#imperatively).
|
||
|
||
### Prefetching Pages
|
||
|
||
⚠️ This is a production only feature ⚠️
|
||
|
||
<details>
|
||
<summary><b>Examples</b></summary>
|
||
<ul>
|
||
<li><a href="/examples/with-prefetching">Prefetching</a></li>
|
||
</ul>
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
Next.js has an API which allows you to prefetch pages.
|
||
|
||
Since Next.js server-renders your pages, this allows all the future interaction paths of your app to be instant. Effectively Next.js gives you the great initial download performance of a _website_, with the ahead-of-time download capabilities of an _app_. [Read more](https://zeit.co/blog/next#anticipation-is-the-key-to-performance).
|
||
|
||
> With prefetching Next.js only downloads JS code. When the page is getting rendered, you may need to wait for the data.
|
||
|
||
#### With `<Link>`
|
||
|
||
You can add `prefetch` prop to any `<Link>` and Next.js will prefetch those pages in the background.
|
||
|
||
```jsx
|
||
import Link from 'next/link'
|
||
|
||
// example header component
|
||
export default () => (
|
||
<nav>
|
||
<ul>
|
||
<li>
|
||
<Link prefetch href="/">
|
||
<a>Home</a>
|
||
</Link>
|
||
</li>
|
||
<li>
|
||
<Link prefetch href="/about">
|
||
<a>About</a>
|
||
</Link>
|
||
</li>
|
||
<li>
|
||
<Link prefetch href="/contact">
|
||
<a>Contact</a>
|
||
</Link>
|
||
</li>
|
||
</ul>
|
||
</nav>
|
||
)
|
||
```
|
||
|
||
#### Imperatively
|
||
|
||
Most prefetching needs are addressed by `<Link />`, but we also expose an imperative API for advanced usage:
|
||
|
||
```jsx
|
||
import { withRouter } from 'next/router'
|
||
|
||
export default withRouter(({ router }) => (
|
||
<div>
|
||
<a onClick={() => setTimeout(() => router.push('/dynamic'), 100)}>
|
||
A route transition will happen after 100ms
|
||
</a>
|
||
{// but we can prefetch it!
|
||
router.prefetch('/dynamic')}
|
||
</div>
|
||
)
|
||
```
|
||
|
||
The router instance should be only used inside the client side of your app though. In order to prevent any error regarding this subject, when rendering the Router on the server side, use the imperatively prefetch method in the `componentDidMount()` lifecycle method.
|
||
|
||
```jsx
|
||
import React from 'react'
|
||
import { withRouter } from 'next/router'
|
||
|
||
class MyLink extends React.Component {
|
||
componentDidMount() {
|
||
const { router } = this.props
|
||
router.prefetch('/dynamic')
|
||
}
|
||
|
||
render() {
|
||
const { router } = this.props
|
||
|
||
return (
|
||
<div>
|
||
<a onClick={() => setTimeout(() => router.push('/dynamic'), 100)}>
|
||
A route transition will happen after 100ms
|
||
</a>
|
||
</div>
|
||
)
|
||
}
|
||
}
|
||
|
||
export default withRouter(MyLink)
|
||
```
|
||
|
||
### Custom server and routing
|
||
|
||
<details>
|
||
<summary><b>Examples</b></summary>
|
||
<ul>
|
||
<li><a href="/examples/custom-server">Basic custom server</a></li>
|
||
<li><a href="/examples/custom-server-express">Express integration</a></li>
|
||
<li><a href="/examples/custom-server-hapi">Hapi integration</a></li>
|
||
<li><a href="/examples/custom-server-koa">Koa integration</a></li>
|
||
<li><a href="/examples/parameterized-routing">Parameterized routing</a></li>
|
||
<li><a href="/examples/ssr-caching">SSR caching</a></li>
|
||
</ul>
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
Typically you start your next server with `next start`. It's possible, however, to start a server 100% programmatically in order to customize routes, use route patterns, etc.
|
||
|
||
When using a custom server with a server file, for example called `server.js`, make sure you update the scripts key in `package.json` to:
|
||
|
||
```json
|
||
{
|
||
"scripts": {
|
||
"dev": "node server.js",
|
||
"build": "next build",
|
||
"start": "NODE_ENV=production node server.js"
|
||
}
|
||
}
|
||
```
|
||
|
||
This example makes `/a` resolve to `./pages/b`, and `/b` resolve to `./pages/a`:
|
||
|
||
```js
|
||
// This file doesn't go through babel or webpack transformation.
|
||
// Make sure the syntax and sources this file requires are compatible with the current node version you are running
|
||
// See https://github.com/zeit/next.js/issues/1245 for discussions on Universal Webpack or universal Babel
|
||
const { createServer } = require('http')
|
||
const { parse } = require('url')
|
||
const next = require('next')
|
||
|
||
const dev = process.env.NODE_ENV !== 'production'
|
||
const app = next({ dev })
|
||
const handle = app.getRequestHandler()
|
||
|
||
app.prepare().then(() => {
|
||
createServer((req, res) => {
|
||
// Be sure to pass `true` as the second argument to `url.parse`.
|
||
// This tells it to parse the query portion of the URL.
|
||
const parsedUrl = parse(req.url, true)
|
||
const { pathname, query } = parsedUrl
|
||
|
||
if (pathname === '/a') {
|
||
app.render(req, res, '/b', query)
|
||
} else if (pathname === '/b') {
|
||
app.render(req, res, '/a', query)
|
||
} else {
|
||
handle(req, res, parsedUrl)
|
||
}
|
||
}).listen(3000, err => {
|
||
if (err) throw err
|
||
console.log('> Ready on http://localhost:3000')
|
||
})
|
||
})
|
||
```
|
||
|
||
The `next` API is as follows:
|
||
- `next(opts: object)`
|
||
|
||
Supported options:
|
||
- `dev` (`bool`) whether to launch Next.js in dev mode - default `false`
|
||
- `dir` (`string`) where the Next project is located - default `'.'`
|
||
- `quiet` (`bool`) Hide error messages containing server information - default `false`
|
||
- `conf` (`object`) the same object you would use in `next.config.js` - default `{}`
|
||
|
||
Then, change your `start` script to `NODE_ENV=production node server.js`.
|
||
|
||
#### Disabling file-system routing
|
||
By default, `Next` will serve each file in `/pages` under a pathname matching the filename (eg, `/pages/some-file.js` is served at `site.com/some-file`.
|
||
|
||
If your project uses custom routing, this behavior may result in the same content being served from multiple paths, which can present problems with SEO and UX.
|
||
|
||
To disable this behavior & prevent routing based on files in `/pages`, simply set the following option in your `next.config.js`:
|
||
|
||
```js
|
||
// next.config.js
|
||
module.exports = {
|
||
useFileSystemPublicRoutes: false
|
||
}
|
||
```
|
||
|
||
Note that `useFileSystemPublicRoutes` simply disables filename routes from SSR; client-side routing
|
||
may still access those paths. If using this option, you should guard against navigation to routes
|
||
you do not want programmatically.
|
||
|
||
You may also wish to configure the client-side Router to disallow client-side redirects to filename
|
||
routes; please refer to [Intercepting `popstate`](#intercepting-popstate).
|
||
|
||
#### Dynamic assetPrefix
|
||
|
||
Sometimes we need to set the `assetPrefix` dynamically. This is useful when changing the `assetPrefix` based on incoming requests.
|
||
For that, we can use `app.setAssetPrefix`.
|
||
|
||
Here's an example usage of it:
|
||
|
||
```js
|
||
const next = require('next')
|
||
const http = require('http')
|
||
|
||
const dev = process.env.NODE_ENV !== 'production'
|
||
const app = next({ dev })
|
||
const handleNextRequests = app.getRequestHandler()
|
||
|
||
app.prepare().then(() => {
|
||
const server = new http.Server((req, res) => {
|
||
// Add assetPrefix support based on the hostname
|
||
if (req.headers.host === 'my-app.com') {
|
||
app.setAssetPrefix('http://cdn.com/myapp')
|
||
} else {
|
||
app.setAssetPrefix('')
|
||
}
|
||
|
||
handleNextRequests(req, res)
|
||
})
|
||
|
||
server.listen(port, (err) => {
|
||
if (err) {
|
||
throw err
|
||
}
|
||
|
||
console.log(`> Ready on http://localhost:${port}`)
|
||
})
|
||
})
|
||
|
||
```
|
||
|
||
### Dynamic Import
|
||
|
||
<details>
|
||
<summary><b>Examples</b></summary>
|
||
<ul>
|
||
<li><a href="/examples/with-dynamic-import">With Dynamic Import</a></li>
|
||
</ul>
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
Next.js supports TC39 [dynamic import proposal](https://github.com/tc39/proposal-dynamic-import) for JavaScript.
|
||
With that, you could import JavaScript modules (inc. React Components) dynamically and work with them.
|
||
|
||
You can think dynamic imports as another way to split your code into manageable chunks.
|
||
Since Next.js supports dynamic imports with SSR, you could do amazing things with it.
|
||
|
||
Here are a few ways to use dynamic imports.
|
||
|
||
#### 1. Basic Usage (Also does SSR)
|
||
|
||
```jsx
|
||
import dynamic from 'next/dynamic'
|
||
|
||
const DynamicComponent = dynamic(() => import('../components/hello'))
|
||
|
||
export default () => (
|
||
<div>
|
||
<Header />
|
||
<DynamicComponent />
|
||
<p>HOME PAGE is here!</p>
|
||
</div>
|
||
)
|
||
```
|
||
|
||
#### 2. With Custom Loading Component
|
||
|
||
```jsx
|
||
import dynamic from 'next/dynamic'
|
||
|
||
const DynamicComponentWithCustomLoading = dynamic(() => import('../components/hello2'), {
|
||
loading: () => <p>...</p>
|
||
})
|
||
|
||
export default () => (
|
||
<div>
|
||
<Header />
|
||
<DynamicComponentWithCustomLoading />
|
||
<p>HOME PAGE is here!</p>
|
||
</div>
|
||
)
|
||
```
|
||
|
||
#### 3. With No SSR
|
||
|
||
```jsx
|
||
import dynamic from 'next/dynamic'
|
||
|
||
const DynamicComponentWithNoSSR = dynamic(() => import('../components/hello3'), {
|
||
ssr: false
|
||
})
|
||
|
||
export default () => (
|
||
<div>
|
||
<Header />
|
||
<DynamicComponentWithNoSSR />
|
||
<p>HOME PAGE is here!</p>
|
||
</div>
|
||
)
|
||
```
|
||
|
||
#### 4. With Multiple Modules At Once
|
||
|
||
```jsx
|
||
import dynamic from 'next/dynamic'
|
||
|
||
const HelloBundle = dynamic({
|
||
modules: () => {
|
||
const components = {
|
||
Hello1: () => import('../components/hello1'),
|
||
Hello2: () => import('../components/hello2')
|
||
}
|
||
|
||
return components
|
||
},
|
||
render: (props, { Hello1, Hello2 }) =>
|
||
<div>
|
||
<h1>
|
||
{props.title}
|
||
</h1>
|
||
<Hello1 />
|
||
<Hello2 />
|
||
</div>
|
||
})
|
||
|
||
export default () => <HelloBundle title="Dynamic Bundle" />
|
||
```
|
||
|
||
### Custom `<App>`
|
||
|
||
<details>
|
||
<summary><b>Examples</b></summary>
|
||
<ul>
|
||
<li><a href="/examples/with-app-layout">Using `_app.js` for layout</a></li>
|
||
<li><a href="/examples/with-componentdidcatch">Using `_app.js` to override `componentDidCatch`</a></li>
|
||
</ul>
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
Next.js uses the `App` component to initialize pages. You can override it and control the page initialization. Which allows you to do amazing things like:
|
||
|
||
- Persisting layout between page changes
|
||
- Keeping state when navigating pages
|
||
- Custom error handling using `componentDidCatch`
|
||
- Inject additional data into pages (for example by processing GraphQL queries)
|
||
|
||
To override, create the `./pages/_app.js` file and override the App class as shown below:
|
||
|
||
```js
|
||
import React from 'react'
|
||
import App, { Container } from 'next/app'
|
||
|
||
export default class MyApp extends App {
|
||
static async getInitialProps({ Component, router, ctx }) {
|
||
let pageProps = {}
|
||
|
||
if (Component.getInitialProps) {
|
||
pageProps = await Component.getInitialProps(ctx)
|
||
}
|
||
|
||
return { pageProps }
|
||
}
|
||
|
||
render () {
|
||
const { Component, pageProps } = this.props
|
||
|
||
return (
|
||
<Container>
|
||
<Component {...pageProps} />
|
||
</Container>
|
||
)
|
||
}
|
||
}
|
||
```
|
||
|
||
### Custom `<Document>`
|
||
|
||
<details>
|
||
<summary><b>Examples</b></summary>
|
||
<ul>
|
||
<li><a href="/examples/with-styled-components">Styled components custom document</a></li>
|
||
<li><a href="/examples/with-amp">Google AMP</a></li>
|
||
</ul>
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
- Is rendered on the server side
|
||
- Is used to change the initial server side rendered document markup
|
||
- Commonly used to implement server side rendering for css-in-js libraries like [styled-components](/examples/with-styled-components) or [emotion](/examples/with-emotion). [styled-jsx](https://github.com/zeit/styled-jsx) is included with Next.js by default.
|
||
|
||
Pages in `Next.js` skip the definition of the surrounding document's markup. For example, you never include `<html>`, `<body>`, etc. To override that default behavior, you must create a file at `./pages/_document.js`, where you can extend the `Document` class:
|
||
|
||
```jsx
|
||
// _document is only rendered on the server side and not on the client side
|
||
// Event handlers like onClick can't be added to this file
|
||
|
||
// ./pages/_document.js
|
||
import Document, { Head, Main, NextScript } from 'next/document'
|
||
|
||
export default class MyDocument extends Document {
|
||
static async getInitialProps(ctx) {
|
||
const initialProps = await Document.getInitialProps(ctx)
|
||
return { ...initialProps }
|
||
}
|
||
|
||
render() {
|
||
return (
|
||
<html>
|
||
<Head>
|
||
<style>{`body { margin: 0 } /* custom! */`}</style>
|
||
</Head>
|
||
<body className="custom_class">
|
||
<Main />
|
||
<NextScript />
|
||
</body>
|
||
</html>
|
||
)
|
||
}
|
||
}
|
||
```
|
||
|
||
All of `<Head />`, `<Main />` and `<NextScript />` are required for page to be properly rendered.
|
||
|
||
The `ctx` object is equivalent to the one received in all [`getInitialProps`](#fetching-data-and-component-lifecycle) hooks, with one addition:
|
||
|
||
- `renderPage` (`Function`) a callback that executes the actual React rendering logic (synchronously). It's useful to decorate this function in order to support server-rendering wrappers like Aphrodite's [`renderStatic`](https://github.com/Khan/aphrodite#server-side-rendering)
|
||
|
||
__Note: React-components outside of `<Main />` will not be initialised by the browser. Do _not_ add application logic here. If you need shared components in all your pages (like a menu or a toolbar), take a look at the `App` component instead.__
|
||
|
||
### Custom error handling
|
||
|
||
404 or 500 errors are handled both client and server side by a default component `error.js`. If you wish to override it, define a `_error.js` in the pages folder:
|
||
|
||
⚠️ The default `error.js` component is only used in production ⚠️
|
||
|
||
```jsx
|
||
import React from 'react'
|
||
|
||
export default class Error extends React.Component {
|
||
static getInitialProps({ res, err }) {
|
||
const statusCode = res ? res.statusCode : err ? err.statusCode : null;
|
||
return { statusCode }
|
||
}
|
||
|
||
render() {
|
||
return (
|
||
<p>
|
||
{this.props.statusCode
|
||
? `An error ${this.props.statusCode} occurred on server`
|
||
: 'An error occurred on client'}
|
||
</p>
|
||
)
|
||
}
|
||
}
|
||
```
|
||
|
||
### Reusing the built-in error page
|
||
|
||
If you want to render the built-in error page you can by using `next/error`:
|
||
|
||
```jsx
|
||
import React from 'react'
|
||
import Error from 'next/error'
|
||
import fetch from 'isomorphic-unfetch'
|
||
|
||
export default class Page extends React.Component {
|
||
static async getInitialProps() {
|
||
const res = await fetch('https://api.github.com/repos/zeit/next.js')
|
||
const statusCode = res.statusCode > 200 ? res.statusCode : false
|
||
const json = await res.json()
|
||
|
||
return { statusCode, stars: json.stargazers_count }
|
||
}
|
||
|
||
render() {
|
||
if (this.props.statusCode) {
|
||
return <Error statusCode={this.props.statusCode} />
|
||
}
|
||
|
||
return (
|
||
<div>
|
||
Next stars: {this.props.stars}
|
||
</div>
|
||
)
|
||
}
|
||
}
|
||
```
|
||
|
||
> If you have created a custom error page you have to import your own `_error` component from `./_error` instead of `next/error`
|
||
|
||
### Custom configuration
|
||
|
||
For custom advanced behavior of Next.js, you can create a `next.config.js` in the root of your project directory (next to `pages/` and `package.json`).
|
||
|
||
Note: `next.config.js` is a regular Node.js module, not a JSON file. It gets used by the Next server and build phases, and not included in the browser build.
|
||
|
||
```js
|
||
// next.config.js
|
||
module.exports = {
|
||
/* config options here */
|
||
}
|
||
```
|
||
|
||
Or use a function:
|
||
|
||
```js
|
||
module.exports = (phase, {defaultConfig}) => {
|
||
//
|
||
// https://github.com/zeit/
|
||
return {
|
||
/* config options here */
|
||
}
|
||
}
|
||
```
|
||
|
||
`phase` is the current context in which the configuration is loaded. You can see all phases here: [constants](/packages/next-server/lib/constants.js)
|
||
Phases can be imported from `next/constants`:
|
||
|
||
```js
|
||
const {PHASE_DEVELOPMENT_SERVER} = require('next/constants')
|
||
module.exports = (phase, {defaultConfig}) => {
|
||
if(phase === PHASE_DEVELOPMENT_SERVER) {
|
||
return {
|
||
/* development only config options here */
|
||
}
|
||
}
|
||
|
||
return {
|
||
/* config options for all phases except development here */
|
||
}
|
||
}
|
||
```
|
||
|
||
#### Setting a custom build directory
|
||
|
||
You can specify a name to use for a custom build directory. For example, the following config will create a `build` folder instead of a `.next` folder. If no configuration is specified then next will create a `.next` folder.
|
||
|
||
```js
|
||
// next.config.js
|
||
module.exports = {
|
||
distDir: 'build'
|
||
}
|
||
```
|
||
|
||
#### Disabling etag generation
|
||
|
||
You can disable etag generation for HTML pages depending on your cache strategy. If no configuration is specified then Next will generate etags for every page.
|
||
|
||
```js
|
||
// next.config.js
|
||
module.exports = {
|
||
generateEtags: false
|
||
}
|
||
```
|
||
|
||
#### Configuring the onDemandEntries
|
||
|
||
Next exposes some options that give you some control over how the server will dispose or keep in memories pages built:
|
||
|
||
```js
|
||
module.exports = {
|
||
onDemandEntries: {
|
||
// period (in ms) where the server will keep pages in the buffer
|
||
maxInactiveAge: 25 * 1000,
|
||
// number of pages that should be kept simultaneously without being disposed
|
||
pagesBufferLength: 2,
|
||
}
|
||
}
|
||
```
|
||
|
||
This is development-only feature. If you want to cache SSR pages in production, please see [SSR-caching](https://github.com/zeit/next.js/tree/canary/examples/ssr-caching) example.
|
||
|
||
#### Configuring extensions looked for when resolving pages in `pages`
|
||
|
||
Aimed at modules like [`@zeit/next-typescript`](https://github.com/zeit/next-plugins/tree/master/packages/next-typescript), that add support for pages ending in `.ts`. `pageExtensions` allows you to configure the extensions looked for in the `pages` directory when resolving pages.
|
||
|
||
```js
|
||
// next.config.js
|
||
module.exports = {
|
||
pageExtensions: ['jsx', 'js']
|
||
}
|
||
```
|
||
|
||
#### Configuring the build ID
|
||
|
||
Next.js uses a constant generated at build time to identify which version of your application is being served. This can cause problems in multi-server deployments when `next build` is ran on every server. In order to keep a static build id between builds you can provide the `generateBuildId` function:
|
||
|
||
```js
|
||
// next.config.js
|
||
module.exports = {
|
||
generateBuildId: async () => {
|
||
// For example get the latest git commit hash here
|
||
return 'my-build-id'
|
||
}
|
||
}
|
||
```
|
||
|
||
### Customizing webpack config
|
||
|
||
<details>
|
||
<summary><b>Examples</b></summary>
|
||
<ul>
|
||
<li><a href="/examples/with-webpack-bundle-analyzer">Custom webpack bundle analyzer</a></li>
|
||
</ul>
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
Some commonly asked for features are available as modules:
|
||
|
||
- [@zeit/next-css](https://github.com/zeit/next-plugins/tree/master/packages/next-css)
|
||
- [@zeit/next-sass](https://github.com/zeit/next-plugins/tree/master/packages/next-sass)
|
||
- [@zeit/next-less](https://github.com/zeit/next-plugins/tree/master/packages/next-less)
|
||
- [@zeit/next-preact](https://github.com/zeit/next-plugins/tree/master/packages/next-preact)
|
||
- [@zeit/next-typescript](https://github.com/zeit/next-plugins/tree/master/packages/next-typescript)
|
||
|
||
*Warning: The `webpack` function is executed twice, once for the server and once for the client. This allows you to distinguish between client and server configuration using the `isServer` property*
|
||
|
||
Multiple configurations can be combined together with function composition. For example:
|
||
|
||
```js
|
||
const withTypescript = require('@zeit/next-typescript')
|
||
const withSass = require('@zeit/next-sass')
|
||
|
||
module.exports = withTypescript(withSass({
|
||
webpack(config, options) {
|
||
// Further custom configuration here
|
||
return config
|
||
}
|
||
}))
|
||
```
|
||
|
||
In order to extend our usage of `webpack`, you can define a function that extends its config via `next.config.js`.
|
||
|
||
```js
|
||
// next.config.js is not transformed by Babel. So you can only use javascript features supported by your version of Node.js.
|
||
|
||
module.exports = {
|
||
webpack: (config, { buildId, dev, isServer, defaultLoaders }) => {
|
||
// Perform customizations to webpack config
|
||
// Important: return the modified config
|
||
return config
|
||
},
|
||
webpackDevMiddleware: config => {
|
||
// Perform customizations to webpack dev middleware config
|
||
// Important: return the modified config
|
||
return config
|
||
}
|
||
}
|
||
```
|
||
|
||
The second argument to `webpack` is an object containing properties useful when customizing its configuration:
|
||
|
||
- `buildId` - `String` the build id used as a unique identifier between builds
|
||
- `dev` - `Boolean` shows if the compilation is done in development mode
|
||
- `isServer` - `Boolean` shows if the resulting configuration will be used for server side (`true`), or client size compilation (`false`).
|
||
- `defaultLoaders` - `Object` Holds loader objects Next.js uses internally, so that you can use them in custom configuration
|
||
- `babel` - `Object` the `babel-loader` configuration for Next.js.
|
||
- `hotSelfAccept` - `Object` the `hot-self-accept-loader` configuration. This loader should only be used for advanced use cases. For example [`@zeit/next-typescript`](https://github.com/zeit/next-plugins/tree/master/packages/next-typescript) adds it for top-level typescript pages.
|
||
|
||
Example usage of `defaultLoaders.babel`:
|
||
|
||
```js
|
||
// Example next.config.js for adding a loader that depends on babel-loader
|
||
// This source was taken from the @zeit/next-mdx plugin source:
|
||
// https://github.com/zeit/next-plugins/blob/master/packages/next-mdx
|
||
module.exports = {
|
||
webpack: (config, {}) => {
|
||
config.module.rules.push({
|
||
test: /\.mdx/,
|
||
use: [
|
||
options.defaultLoaders.babel,
|
||
{
|
||
loader: '@mdx-js/loader',
|
||
options: pluginOptions.options
|
||
}
|
||
]
|
||
})
|
||
|
||
return config
|
||
}
|
||
}
|
||
```
|
||
|
||
### Customizing babel config
|
||
|
||
<details>
|
||
<summary><b>Examples</b></summary>
|
||
<ul>
|
||
<li><a href="/examples/with-custom-babel-config">Custom babel configuration</a></li>
|
||
</ul>
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
In order to extend our usage of `babel`, you can simply define a `.babelrc` file at the root of your app. This file is optional.
|
||
|
||
If found, we're going to consider it the *source of truth*, therefore it needs to define what next needs as well, which is the `next/babel` preset.
|
||
|
||
This is designed so that you are not surprised by modifications we could make to the babel configurations.
|
||
|
||
Here's an example `.babelrc` file:
|
||
|
||
```json
|
||
{
|
||
"presets": ["next/babel"],
|
||
"plugins": []
|
||
}
|
||
```
|
||
|
||
The `next/babel` preset includes everything needed to transpile React applications. This includes:
|
||
|
||
- preset-env
|
||
- preset-react
|
||
- plugin-proposal-class-properties
|
||
- plugin-proposal-object-rest-spread
|
||
- plugin-transform-runtime
|
||
- styled-jsx
|
||
|
||
These presets / plugins **should not** be added to your custom `.babelrc`. Instead, you can configure them on the `next/babel` preset:
|
||
|
||
```json
|
||
{
|
||
"presets": [
|
||
["next/babel", {
|
||
"preset-env": {},
|
||
"transform-runtime": {},
|
||
"styled-jsx": {},
|
||
"class-properties": {}
|
||
}]
|
||
],
|
||
"plugins": []
|
||
}
|
||
```
|
||
|
||
The `modules` option on `"preset-env"` should be kept to `false` otherwise webpack code splitting is disabled.
|
||
|
||
### Exposing configuration to the server / client side
|
||
|
||
The `next/config` module gives your app access to runtime configuration stored in your `next.config.js`. Place any server-only runtime config under a `serverRuntimeConfig` property and anything accessible to both client and server-side code under `publicRuntimeConfig`.
|
||
|
||
```js
|
||
// next.config.js
|
||
module.exports = {
|
||
serverRuntimeConfig: { // Will only be available on the server side
|
||
mySecret: 'secret'
|
||
},
|
||
publicRuntimeConfig: { // Will be available on both server and client
|
||
staticFolder: '/static',
|
||
mySecret: process.env.MY_SECRET // Pass through env variables
|
||
}
|
||
}
|
||
```
|
||
|
||
```js
|
||
// pages/index.js
|
||
import getConfig from 'next/config'
|
||
// Only holds serverRuntimeConfig and publicRuntimeConfig from next.config.js nothing else.
|
||
const {serverRuntimeConfig, publicRuntimeConfig} = getConfig()
|
||
|
||
console.log(serverRuntimeConfig.mySecret) // Will only be available on the server side
|
||
console.log(publicRuntimeConfig.staticFolder) // Will be available on both server and client
|
||
|
||
export default () => <div>
|
||
<img src={`${publicRuntimeConfig.staticFolder}/logo.png`} alt="logo" />
|
||
</div>
|
||
```
|
||
|
||
### Starting the server on alternative hostname
|
||
|
||
To start the development server using a different default hostname you can use `--hostname hostname_here` or `-H hostname_here` option with next dev. This will start a TCP server listening for connections on the provided host.
|
||
|
||
### CDN support with Asset Prefix
|
||
|
||
To set up a CDN, you can set up the `assetPrefix` setting and configure your CDN's origin to resolve to the domain that Next.js is hosted on.
|
||
|
||
```js
|
||
const isProd = process.env.NODE_ENV === 'production'
|
||
module.exports = {
|
||
// You may only need to add assetPrefix in the production.
|
||
assetPrefix: isProd ? 'https://cdn.mydomain.com' : ''
|
||
}
|
||
```
|
||
|
||
Note: Next.js will automatically use that prefix in the scripts it loads, but this has no effect whatsoever on `/static`. If you want to serve those assets over the CDN, you'll have to introduce the prefix yourself. One way of introducing a prefix that works inside your components and varies by environment is documented [in this example](https://github.com/zeit/next.js/tree/master/examples/with-universal-configuration).
|
||
|
||
If your CDN is on a separate domain and you would like assets to be requested using a [CORS aware request](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_settings_attributes) you can extend _document.js and specify the `crossOrigin` attribute on Head and NextScripts which is then used for all Next.js asset tags.
|
||
```js
|
||
<Head crossOrigin="anonymous">...</Head>
|
||
<body>
|
||
<Main/>
|
||
<NextScript crossOrigin="anonymous"/>
|
||
</body>
|
||
```
|
||
## Production deployment
|
||
|
||
To deploy, instead of running `next`, you want to build for production usage ahead of time. Therefore, building and starting are separate commands:
|
||
|
||
```bash
|
||
next build
|
||
next start
|
||
```
|
||
|
||
For example, to deploy with [`now`](https://zeit.co/now) a `package.json` like follows is recommended:
|
||
|
||
```json
|
||
{
|
||
"name": "my-app",
|
||
"dependencies": {
|
||
"next": "latest"
|
||
},
|
||
"scripts": {
|
||
"dev": "next",
|
||
"build": "next build",
|
||
"start": "next start"
|
||
}
|
||
}
|
||
```
|
||
|
||
Then run `now` and enjoy!
|
||
|
||
Next.js can be deployed to other hosting solutions too. Please have a look at the ['Deployment'](https://github.com/zeit/next.js/wiki/Deployment) section of the wiki.
|
||
|
||
Note: `NODE_ENV` is properly configured by the `next` subcommands, if absent, to maximize performance. if you’re using Next.js [programmatically](#custom-server-and-routing), it’s your responsibility to set `NODE_ENV=production` manually!
|
||
|
||
Note: we recommend putting `.next`, or your [custom dist folder](https://github.com/zeit/next.js#custom-configuration), in `.gitignore` or `.npmignore`. Otherwise, use `files` or `now.files` to opt-into a whitelist of files you want to deploy, excluding `.next` or your custom dist folder.
|
||
|
||
## Browser support
|
||
|
||
Next.js supports IE11 and all modern browsers out of the box using [`@babel/preset-env`](https://new.babeljs.io/docs/en/next/babel-preset-env.html). In order to support IE11 Next.js adds a global `Promise` polyfill. In cases where your own code or any external NPM dependencies you are using requires features not supported by your target browsers you will need to implement polyfills.
|
||
|
||
The [polyfills](https://github.com/zeit/next.js/tree/canary/examples/with-polyfills) example demonstrates the recommended approach to implement polyfills.
|
||
|
||
## Static HTML export
|
||
|
||
<details>
|
||
<summary><b>Examples</b></summary>
|
||
<ul>
|
||
<li><a href="/examples/with-static-export">Static export</a></li>
|
||
</ul>
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
`next export` is a way to run your Next.js app as a standalone static app without the need for a Node.js server.
|
||
The exported app supports almost every feature of Next.js, including dynamic urls, prefetching, preloading and dynamic imports.
|
||
|
||
The way `next export` works is by pre-rendering all pages possible to HTML. It does so based on a mapping of `pathname` key to page object. This mapping is called the `exportPathMap`.
|
||
|
||
The page object has 2 values:
|
||
|
||
- `page` - `String` the page inside the `pages` directory to render
|
||
- `query` - `Object` the `query` object passed to `getInitialProps` when pre-rendering. Defaults to `{}`
|
||
|
||
|
||
### Usage
|
||
|
||
Simply develop your app as you normally do with Next.js. Then run:
|
||
|
||
```
|
||
next build
|
||
next export
|
||
```
|
||
|
||
By default `next export` doesn't require any configuration. It will generate a default `exportPathMap` containing the routes to pages inside the `pages` directory. This default mapping is available as `defaultPathMap` in the example below.
|
||
|
||
If your application has dynamic routes you can add a dynamic `exportPathMap` in `next.config.js`.
|
||
This function is asynchronous and gets the default `exportPathMap` as a parameter.
|
||
|
||
```js
|
||
// next.config.js
|
||
module.exports = {
|
||
exportPathMap: async function (defaultPathMap) {
|
||
return {
|
||
'/': { page: '/' },
|
||
'/about': { page: '/about' },
|
||
'/readme.md': { page: '/readme' },
|
||
'/p/hello-nextjs': { page: '/post', query: { title: 'hello-nextjs' } },
|
||
'/p/learn-nextjs': { page: '/post', query: { title: 'learn-nextjs' } },
|
||
'/p/deploy-nextjs': { page: '/post', query: { title: 'deploy-nextjs' } }
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
> Note that if the path ends with a directory, it will be exported as `/dir-name/index.html`, but if it ends with an extension, it will be exported as the specified filename, e.g. `/readme.md` above. If you use a file extension other than `.html`, you may need to set the `Content-Type` header to `text/html` when serving this content.
|
||
|
||
Then simply run these commands:
|
||
|
||
```bash
|
||
next build
|
||
next export
|
||
```
|
||
|
||
For that you may need to add a NPM script to `package.json` like this:
|
||
|
||
```json
|
||
{
|
||
"scripts": {
|
||
"build": "next build",
|
||
"export": "npm run build && next export"
|
||
}
|
||
}
|
||
```
|
||
|
||
And run it at once with:
|
||
|
||
```bash
|
||
npm run export
|
||
```
|
||
|
||
Then you have a static version of your app in the `out` directory.
|
||
|
||
> You can also customize the output directory. For that run `next export -h` for the help.
|
||
|
||
Now you can deploy the `out` directory to any static hosting service. Note that there is an additional step for deploying to GitHub Pages, [documented here](https://github.com/zeit/next.js/wiki/Deploying-a-Next.js-app-into-GitHub-Pages).
|
||
|
||
For an example, simply visit the `out` directory and run following command to deploy your app to [ZEIT Now](https://zeit.co/now).
|
||
|
||
```bash
|
||
now
|
||
```
|
||
|
||
### Copying custom files
|
||
|
||
In case you have to copy custom files like a robots.txt or generate a sitemap.xml you can do this inside of `exportPathMap`.
|
||
`exportPathMap` gets a few contextual parameter to aid you with creating/copying files:
|
||
|
||
- `dev` - `true` when `exportPathMap` is being called in development. `false` when running `next export`. In development `exportPathMap` is used to define routes and behavior like copying files is not required.
|
||
- `dir` - Absolute path to the project directory
|
||
- `outDir` - Absolute path to the `out` directory (configurable with `-o` or `--outdir`). When `dev` is `true` the value of `outDir` will be `null`.
|
||
- `distDir` - Absolute path to the `.next` directory (configurable using the `distDir` config key)
|
||
- `buildId` - The buildId the export is running for
|
||
|
||
```js
|
||
// next.config.js
|
||
const fs = require('fs')
|
||
const { join } = require('path')
|
||
const { promisify } = require('util')
|
||
const copyFile = promisify(fs.copyFile)
|
||
|
||
module.exports = {
|
||
exportPathMap: async function (defaultPathMap, {dev, dir, outDir, distDir, buildId}) {
|
||
if (dev) {
|
||
return defaultPathMap
|
||
}
|
||
// This will copy robots.txt from your project root into the out directory
|
||
await copyFile(join(dir, 'robots.txt'), join(outDir, 'robots.txt'))
|
||
return defaultPathMap
|
||
}
|
||
}
|
||
```
|
||
|
||
### Limitation
|
||
|
||
With `next export`, we build a HTML version of your app. At export time we will run `getInitialProps` of your pages.
|
||
|
||
The `req` and `res` fields of the `context` object passed to `getInitialProps` are not available as there is no server running.
|
||
|
||
> You won't be able to render HTML dynamically when static exporting, as we pre-build the HTML files. If you want to do dynamic rendering use `next start` or the custom server API
|
||
|
||
## Multi Zones
|
||
|
||
<details>
|
||
<summary><b>Examples</b></summary>
|
||
<ul>
|
||
<li><a href="/examples/with-zones">With Zones</a></li>
|
||
</ul>
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
A zone is a single deployment of a Next.js app. Just like that, you can have multiple zones. Then you can merge them as a single app.
|
||
|
||
For an example, you can have two zones like this:
|
||
|
||
* https://docs.my-app.com for serving `/docs/**`
|
||
* https://ui.my-app.com for serving all other pages
|
||
|
||
With multi zones support, you can merge both these apps into a single one. Which allows your customers to browse it using a single URL. But you can develop and deploy both apps independently.
|
||
|
||
> This is exactly the same concept as microservices, but for frontend apps.
|
||
|
||
### How to define a zone
|
||
|
||
There are no special zones related APIs. You only need to do following things:
|
||
|
||
* Make sure to keep only the pages you need in your app. (For an example, https://ui.my-app.com should not contain pages for `/docs/**`)
|
||
* Make sure your app has an [assetPrefix](https://github.com/zeit/next.js#cdn-support-with-asset-prefix). (You can also define the assetPrefix [dynamically](https://github.com/zeit/next.js#dynamic-assetprefix).)
|
||
|
||
### How to merge them
|
||
|
||
You can merge zones using any HTTP proxy.
|
||
|
||
You can use [micro proxy](https://github.com/zeit/micro-proxy) as your local proxy server. It allows you to easily define routing rules like below:
|
||
|
||
```json
|
||
{
|
||
"rules": [
|
||
{"pathname": "/docs**", "method":["GET", "POST", "OPTIONS"], "dest": "https://docs.my-app.com"},
|
||
{"pathname": "/**", "dest": "https://ui.my-app.com"}
|
||
]
|
||
}
|
||
```
|
||
|
||
For the production deployment, you can use the [path alias](https://zeit.co/docs/features/path-aliases) feature if you are using [ZEIT now](https://zeit.co/now). Otherwise, you can configure your existing proxy server to route HTML pages using a set of rules as shown above.
|
||
|
||
## Recipes
|
||
|
||
- [Setting up 301 redirects](https://www.raygesualdo.com/posts/301-redirects-with-nextjs/)
|
||
- [Dealing with SSR and server only modules](https://arunoda.me/blog/ssr-and-server-only-modules)
|
||
- [Building with React-Material-UI-Next-Express-Mongoose-Mongodb](https://github.com/builderbook/builderbook)
|
||
- [Build a SaaS Product with React-Material-UI-Next-MobX-Express-Mongoose-MongoDB-TypeScript](https://github.com/async-labs/saas)
|
||
|
||
## FAQ
|
||
|
||
<details>
|
||
<summary>Is this production ready?</summary>
|
||
Next.js has been powering https://zeit.co since its inception.
|
||
|
||
We’re ecstatic about both the developer experience and end-user performance, so we decided to share it with the community.
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
<details>
|
||
<summary>How big is it?</summary>
|
||
|
||
The client side bundle size should be measured in a per-app basis.
|
||
A small Next main bundle is around 65kb gzipped.
|
||
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
<details>
|
||
<summary>Is this like `create-react-app`?</summary>
|
||
|
||
Yes and No.
|
||
|
||
Yes in that both make your life easier.
|
||
|
||
No in that it enforces a _structure_ so that we can do more advanced things like:
|
||
- Server side rendering
|
||
- Automatic code splitting
|
||
|
||
In addition, Next.js provides two built-in features that are critical for every single website:
|
||
- Routing with lazy component loading: `<Link>` (by importing `next/link`)
|
||
- A way for components to alter `<head>`: `<Head>` (by importing `next/head`)
|
||
|
||
If you want to create re-usable React components that you can embed in your Next.js app or other React applications, using `create-react-app` is a great idea. You can later `import` it and keep your codebase clean!
|
||
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
<details>
|
||
<summary>How do I use CSS-in-JS solutions?</summary>
|
||
|
||
Next.js bundles [styled-jsx](https://github.com/zeit/styled-jsx) supporting scoped css. However you can use any CSS-in-JS solution in your Next app by just including your favorite library [as mentioned before](#css-in-js) in the document.
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
<details>
|
||
<summary>What syntactic features are transpiled? How do I change them?</summary>
|
||
|
||
We track V8. Since V8 has wide support for ES6 and `async` and `await`, we transpile those. Since V8 doesn’t support class decorators, we don’t transpile those.
|
||
|
||
See the documentation about [customizing the babel config](#customizing-babel-config) and [next/preset](/packages/next/build/babel/preset.js) for more information.
|
||
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
<details>
|
||
<summary>Why a new Router?</summary>
|
||
|
||
Next.js is special in that:
|
||
|
||
- Routes don’t need to be known ahead of time
|
||
- Routes are always lazy-loadable
|
||
- Top-level components can define `getInitialProps` that should _block_ the loading of the route (either when server-rendering or lazy-loading)
|
||
|
||
As a result, we were able to introduce a very simple approach to routing that consists of two pieces:
|
||
|
||
- Every top level component receives a `url` object to inspect the url or perform modifications to the history
|
||
- A `<Link />` component is used to wrap elements like anchors (`<a/>`) to perform client-side transitions
|
||
|
||
We tested the flexibility of the routing with some interesting scenarios. For an example, check out [nextgram](https://github.com/zeit/nextgram).
|
||
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
<details>
|
||
<summary>How do I define a custom fancy route?</summary>
|
||
|
||
We [added](#custom-server-and-routing) the ability to map between an arbitrary URL and any component by supplying a request handler.
|
||
|
||
On the client side, we have a parameter call `as` on `<Link>` that _decorates_ the URL differently from the URL it _fetches_.
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
<details>
|
||
<summary>How do I fetch data?</summary>
|
||
|
||
It’s up to you. `getInitialProps` is an `async` function (or a regular function that returns a `Promise`). It can retrieve data from anywhere.
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
<details>
|
||
<summary>Can I use it with GraphQL?</summary>
|
||
|
||
Yes! Here's an example with [Apollo](/examples/with-apollo).
|
||
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
<details>
|
||
<summary>Can I use it with Redux?</summary>
|
||
|
||
Yes! Here's an [example](/examples/with-redux)
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
<details>
|
||
<summary>Can I use Next with my favorite Javascript library or toolkit?</summary>
|
||
|
||
Since our first release we've had **many** example contributions, you can check them out in the [examples](/examples) directory
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
<details>
|
||
<summary>What is this inspired by?</summary>
|
||
|
||
Many of the goals we set out to accomplish were the ones listed in [The 7 principles of Rich Web Applications](http://rauchg.com/2014/7-principles-of-rich-web-applications/) by Guillermo Rauch.
|
||
|
||
The ease-of-use of PHP is a great inspiration. We feel Next.js is a suitable replacement for many scenarios where you otherwise would use PHP to output HTML.
|
||
|
||
Unlike PHP, we benefit from the ES6 module system and every file exports a **component or function** that can be easily imported for lazy evaluation or testing.
|
||
|
||
As we were researching options for server-rendering React that didn’t involve a large number of steps, we came across [react-page](https://github.com/facebookarchive/react-page) (now deprecated), a similar approach to Next.js by the creator of React Jordan Walke.
|
||
|
||
</details>
|
||
|
||
<p></p>
|
||
|
||
## Contributing
|
||
|
||
Please see our [contributing.md](/contributing.md)
|
||
|
||
## Authors
|
||
|
||
- Arunoda Susiripala ([@arunoda](https://twitter.com/arunoda)) – [ZEIT](https://zeit.co)
|
||
- Tim Neutkens ([@timneutkens](https://twitter.com/timneutkens)) – [ZEIT](https://zeit.co)
|
||
- Naoyuki Kanezawa ([@nkzawa](https://twitter.com/nkzawa)) – [ZEIT](https://zeit.co)
|
||
- Tony Kovanen ([@tonykovanen](https://twitter.com/tonykovanen)) – [ZEIT](https://zeit.co)
|
||
- Guillermo Rauch ([@rauchg](https://twitter.com/rauchg)) – [ZEIT](https://zeit.co)
|
||
- Dan Zajdband ([@impronunciable](https://twitter.com/impronunciable)) – Knight-Mozilla / Coral Project
|