[](https://www.npmjs.com/package/next)
[](https://travis-ci.org/zeit/next.js)
[](https://ci.appveyor.com/project/arunoda/next-js/branch/master)
[](https://coveralls.io/r/zeit/next.js?branch=master)
[](https://spectrum.chat/next-js)
Next.js is a minimalistic framework for server-rendered React applications.
**Visit [nextjs.org/learn](https://nextjs.org/learn) to get started with Next.js.**
---
- [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 ``](#populating-head)
- [Fetching data and component lifecycle](#fetching-data-and-component-lifecycle)
- [Routing](#routing)
- [With ``](#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 ``](#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 `Welcome to next.js!
```
and then just run `npm run dev` and go to `http://localhost:3000`. To use another port, you can run `npm run dev -- -p
{cowsay.say({ text: 'hi there!' })}
```
### CSS
#### Built-in CSS support
Examples
Hello world
```
Please see the [styled-jsx documentation](https://www.npmjs.com/package/styled-jsx) for more examples.
#### CSS-in-JS
scoped!
It's possible to use any existing CSS-in-JS solution. The simplest one is inline styles: ```jsx export default () =>
hi there
``` 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 `
```
_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 ``
Examples
Hello world!
Hello world!
Examples
Hello World {this.props.userAgent}
)
}
}
```
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`._
> 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.
You can also define the `getInitialProps` lifecycle method for stateless components: ```jsx const Page = ({ stars }) =>
Next stars: {stars}
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 ``
Examples
Click{' '}
here
{' '}
to read more
```
```jsx
// pages/about.js
export default () => Welcome to About!
``` __Note: use [``](#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 **Deprecated, use [withRouter](https://github.com/zeit/next.js#using-a-higher-order-component) instead** - Each top-level component receives a `url` property with the following API: - `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 ##### With URL object
Examples
Click{' '}
here
{' '}
to read more
```
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 `` 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 () =>
Click{' '}
here
{' '}
to read more
```
##### Using a component that supports `onClick`
`` supports any component that supports the `onClick` event. In case you don't provide an `` 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 () =>
Click{' '}
```
##### Forcing the Link to expose `href` to its child
If child is an `` 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 `` 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 }) =>
You can also do client-side page transitions using the `next/router` ```jsx import Router from 'next/router' export default () =>
Click Router.push('/about')}>here to read more
```
#### 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 you return a falsy value from `beforePopState`, `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.
_Note: in order to programmatically change the route without triggering navigation and component-fetching, use `props.url.push` and `props.url.replace` within a component_
##### With URL object
You can use an URL object the same way you use it in a `` component to `push` and `replace` an URL.
```jsx
import Router from 'next/router'
const handler = () =>
Router.push({
pathname: '/about',
query: { name: 'Zeit' }
})
export default () =>
Click here to read more
```
This uses the same exact parameters as in the `` 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
Examples
Examples
Examples
setTimeout(() => url.pushTo('/dynamic'), 100)}>
A route transition will happen after 100ms
{// but we can prefetch it!
Router.prefetch('/dynamic')}
```
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 Router from 'next/router'
export default class MyLink extends React.Component {
componentDidMount() {
Router.prefetch('/dynamic')
}
render() {
return (
)
}
}
```
### Custom server and routing
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 micro = require('micro') const dev = process.env.NODE_ENV !== 'production' const app = next({ dev }) const handle = app.getRequestHandler() app.prepare().then(() => { const server = micro((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
Examples
HOME PAGE is here!
...
} ) export default () =>HOME PAGE is here!
HOME PAGE is here!
{props.title}
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 App, {Container} from 'next/app' import React from 'react' 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
- 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), [glamorous](./examples/with-glamorous) or [emotion](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 ``, ``, 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 (
{this.props.statusCode ? `An error ${this.props.statusCode} occurred on server` : 'An error occurred on client'}
) } } ``` ### 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
Next stars: {this.props.stars}
)
}
}
```
> If you have created a custom error page you have to import your own `_error` component 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](./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
Examples
Examples
Examples
Examples