[](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://zeit.chat)
Next.js is a minimalistic framework for server-rendered React applications.
**Visit [learnnextjs.com](https://learnnextjs.com) 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)
- [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)
- [Imperatively](#imperatively)
- [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)
- [Dynamic Import](#dynamic-import)
- [Custom `> We had to drop React 15 support due to the way React 16 works and how we use it. 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 () =>
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 `
```
### 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`.
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 rendered 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 - `push(url, as=url)` - performs a `pushState` call with the given url - `replace(url, as=url)` - performs a `replaceState` call with the given url 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
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 support `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.
```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
```
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
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 of 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
- `appUpdated(nextRoute)` - Fires when switching pages and there's a new version of the app
> 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
Router.onRouteChangeStart = url => {
console.log('App is changing to: ', url)
}
```
If you no longer want to listen to that event, you can simply unset the event listener like this:
```js
Router.onRouteChangeStart = null
```
If a route load is cancelled (for example by clicking two links rapidly in succession), `routeChangeError` will fire. The passed `err` will contained a `cancelled` property set to `true`.
```js
Router.onRouteChangeError = (err, url) => {
if (err.cancelled) {
console.log(`Route to ${url} was cancelled!`)
}
}
```
If you change a route while in between a new deployment, we can't navigate the app via client side. We need to do a full browser navigation. We do it automatically for you.
But you can customize that via `Route.onAppUpdated` event like this:
```js
Router.onAppUpdated = nextUrl => {
// persist the local state
location.href = nextUrl
}
```
##### 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')}
```
### 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 This example makes `/a` resolve to `./pages/b`, and `/b` resolve to `./pages/a`: ```js // This file doesn't not 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(path: string, opts: object)` - `path` is where the Next project is located - `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`. ### Dynamic Import
Examples
HOME PAGE is here!
...
} ) export default () =>HOME PAGE is here!
HOME PAGE is here!
{props.title}
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 // ./pages/_document.js import Document, { Head, Main, NextScript } from 'next/document' import flush from 'styled-jsx/server' export default class MyDocument extends Document { static getInitialProps({ renderPage }) { const { html, head, errorHtml, chunks } = renderPage() const styles = flush() return { html, head, errorHtml, chunks, styles } } render() { return ( {this.props.customValue}
{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 */
}
```
#### 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'
}
```
#### 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,
}
}
```
### Customizing webpack config
Examples
Examples
Examples