[](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.
**NOTE! the README on the `master` branch might not match that of the [latest stable release](https://github.com/zeit/next.js/releases/latest)! **
## How to use
Install it:
```bash
npm install next --save
```
and add a script to your package.json like this:
```json
{
"scripts": {
"dev": "next"
}
}
```
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 () => (
)
```
### Populating ``
We expose a built-in component for appending elements to the `` of the page.
```jsx
import Head from 'next/head'
export default () => (
Hello world!
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.
`getInitialProps` receives a context object with the following properties:
- `pathname` - path section of URL
- `query` - query string section of URL parsed as an object
- `req` - HTTP request object (server only)
- `res` - HTTP response object (server only)
- `xhr` - XMLHttpRequest object (client only)
- `err` - Error object if any error is encountered during the rendering
### Routing
#### With ``
Client-side transitions between routes can be enabled via a `` component. Consider these two pages:
```jsx
// pages/index.js
import Link from 'next/link'
export default () => (
Click here to read more
)
```
```jsx
// pages/about.js
export default () => (
Welcome to About!
) ``` 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 `{}` - `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. #### 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` withing a component_
### Prefetching Pages
Next.js exposes a module that configures a `ServiceWorker` automatically to prefetch pages: `next/prefetch`.
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 ``
You can substitute your usage of `` with the default export of `next/prefetch`. For example:
```jsx
import Link from 'next/prefetch'
// example header component
export default () => (
)
```
When this higher-level `` component is first used, the `ServiceWorker` gets installed. To turn off prefetching on a per-`` basis, you can use the `prefetch` attribute:
```jsx
Home
```
#### Imperatively
Most needs are addressed by ``, but we also expose an imperative API for advanced usage:
```jsx
import { prefetch } from 'next/prefetch'
export default ({ url }) => (
setTimeout(() => url.pushTo('/dynamic'), 100) }>
A route transition will happen after 100ms
{
// but we can prefetch it!
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 app = next({ dev: true })
const handle = app.getRequestHandler()
app.prepare().then(() => {
createServer((req, res) => {
const { pathname, query } = parse(req.url, true)
if (pathname === '/a') {
app.render(req, res, '/b', query)
} else if (pathname === '/b') {
app.render(req, res, '/a', query)
} else {
handle(req, res)
}
})
.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
- `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`) Display error messages with server information - default `false`
### Custom `{ 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 */ } ``` ### Customizing webpack config In order to extend our usage of `webpack`, you can define a function that extends its config via `next.config.js`. The following example shows how you can use [`react-svg-loader`](https://github.com/boopathi/react-svg-loader) to easily import any `.svg` file as a React component, without modification. ```js module.exports = { webpack: (cfg, { dev }) => { cfg.module.rules.push({ test: /\.svg$/, loader: 'babel!react-svg' }) return cfg } } ``` ## Production deployment To deploy, instead of running `next`, you probably want to build 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! Note: we recommend putting `.next` in `.npmignore` or `.gitignore`. Otherwise, use `files` or `now.files` to opt-into a whitelist of files you want to deploy (and obviously exclude `.next`) ## FAQ