[](https://travis-ci.org/zeit/next.js)
[](https://coveralls.io/r/zeit/next.js?branch=master)
[](https://zeit.chat)
Next.js is a minimalistic framework for server-rendered React applications.
- [How to use](#how-to-use)
- [Getting Started](#getting-started)
- [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)
- [Prefetching Pages](#prefetching-pages)
- [With ``](#with-link-1)
- [Imperatively](#imperatively-1)
- [Custom server and routing](#custom-server-and-routing)
- [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
)
```
#### 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!
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`._
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` - the actual url path
- `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).
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
)
```
#### Imperatively
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 `{}`
- `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 are 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
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 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` Then, change your `start` script to `NODE_ENV=production node server.js`. ### Custom `
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} = renderPage() const styles = flush() return { html, head, styles } } render () { return ( {this.props.customValue}
{ this.props.statusCode ? `An error ${this.props.statusCode} occurred on server` : 'An error occurred on client' }
) } } ``` ### 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. ```javascript // 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. ```javascript // next.config.js module.exports = { distDir: 'build' } ``` ### Customizing webpack config In order to extend our usage of `webpack`, you can define a function that extends its config via `next.config.js`. ```js // This file is not going through babel transformation. // So, we write it in vanilla JS // (But you could use ES2015 features supported by your Node.js version) module.exports = { webpack: (config, { dev }) => { // Perform customizations to config // Important: return the modified config return config } } ``` *Warning: Adding loaders to support new file types (css, less, svg, etc.) is __not__ recommended because only the client code gets bundled via webpack and thus it won't work on the initial server rendering. Babel plugins are a good alternative because they're applied consistently between server/client rendering (e.g. [babel-plugin-inline-react-svg](https://github.com/kesne/babel-plugin-inline-react-svg)).* ### Customizing babel config
Examples