screen shot 2016-10-25 at 2 37 27 pm [![Build Status](https://travis-ci.org/zeit/next.js.svg?branch=master)](https://travis-ci.org/zeit/next.js) [![Coverage Status](https://coveralls.io/repos/zeit/next.js/badge.svg?branch=master)](https://coveralls.io/r/zeit/next.js?branch=master) [![Slack Channel](https://zeit-slackin.now.sh/badge.svg)](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](#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) - [Prefetching Pages](#prefetching-pages) - [With ``](#with-link-1) - [Imperatively](#imperatively-1) - [Custom server and routing](#custom-server-and-routing) - [Custom ``](#custom-document) - [Custom error handling](#custom-error-handling) - [Custom configuration](#custom-configuration) - [Customizing webpack config](#customizing-webpack-config) - [Customizing babel config](#customizing-babel-config) - [Production deployment](#production-deployment) - [FAQ](#faq) - [Roadmap](#roadmap) - [Contributing](#contributing) - [Authors](#authors) ## How to use ### Setup Install it: ```bash npm install next react react-dom --save ``` 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` 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/` 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 () => ( 
{ cowsay.say({ text: 'hi there!' }) }
) ``` ### CSS #### Built-in CSS support

Examples

We bundle [styled-jsx](https://github.com/zeit/styled-jsx) to provide support for isolated scoped CSS. The aim is to support "shadow CSS" resembling of Web Components, which unfortunately [do not support server-rendering and are JS-only](https://github.com/w3c/webcomponents/issues/71). ```jsx export default () => (
Hello world

scoped!

) ``` #### CSS-in-JS

Examples

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 ``](#user-content-custom-document) component that wraps each page ### 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 () => ( ) ``` ### Populating ``

Examples

We expose a built-in component for appending elements to the `` of the page. ```jsx import Head from 'next/head' export default () => (
My page title

Hello world!

) ``` _Note: The contents of `` get cleared upon unmounting the component, so make sure each page completely defines what it needs in ``, without making assumptions about what other pages added_ ### Fetching data and component lifecycle

Examples

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 }) { return req ? { userAgent: req.headers['user-agent'] } : { userAgent: navigator.userAgent } } render () { return
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`._ `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 ``

Examples

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!

) ``` __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 `{}` - `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

The component `` 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 () => (
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). #### Imperatively

Examples

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

Shallow routig 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 the eith `Router.push` or `Router.replace` with `shallow: true` option. Here's an example: ```jsx // 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.url` inside the `Component`. You can watch for URL changes via [`componentWillReceiveProps`](https://facebook.github.io/react/docs/react-component.html#componentwillreceiveprops) hook as shown below: ```jsx componentWillReceiveProps(nextProps) { const { pathname, query } = nextProps.url // fetch data based on the new query } ``` > NOTES: > > Shallow routing works **only** for same page URL changes. For an example, let's assume we've another page called `about`, and you run this: > ```js > Router.push('/about?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 we asked to do shallow routing. ### Prefetching Pages (This is a production only feature)

Examples

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 download JS code. When the page is getting rendered, you may need to wait for the data. #### With `` You can add `prefetch` prop to any `` and Next.js will prefetch those pages in the background. ```jsx import Link from 'next/link' // example header component export default () => ( ) ``` #### Imperatively Most prefetching needs are addressed by ``, but we also expose an imperative API for advanced usage: ```jsx import Router from 'next/router' export default ({ url }) => (
setTimeout(() => url.pushTo('/dynamic'), 100) }> A route transition will happen after 100ms { // but we can prefetch it! Router.prefetch('/dynamic') }
) ``` ### Custom server and routing

Examples

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 - `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 ``

Examples

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}
) } } ``` 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) ### 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`: ```jsx import React from 'react' export default class Error extends React.Component { static getInitialProps ({ res, xhr }) { const statusCode = res ? res.statusCode : (xhr ? xhr.status : null) return { statusCode } } render () { return (

{ 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`. ```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

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: ```js { "presets": [ "next/babel", "stage-0" ], } ``` ## 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
Is this production ready? 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.
How big is it? The client side bundle size should be measured in a per-app basis. A small Next main bundle is around 65kb gzipped.
Is this like `create-react-app`? 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: `` (by importing `next/link`) - A way for components to alter ``: `` (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!
How do I use CSS-in-JS solutions? Next.js bundles [styled-jsx](https://github.com/zeit/styled-jsx) supporting scoped css. However you can use a CSS-in-JS solution in your Next app by just including your favorite library [as mentioned before](#css-in-js) in the document.
What syntactic features are transpiled? How do I change them? 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 [this](https://github.com/zeit/next.js/blob/master/server/build/webpack.js#L79) and [this](https://github.com/zeit/next.js/issues/26)
Why a new Router? 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 `` component is used to wrap elements like anchors (``) 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).
How do I define a custom fancy route? 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 `` that _decorates_ the URL differently from the URL it _fetches_.
How do I fetch data? It’s up to you. `getInitialProps` is an `async` function (or a regular function that returns a `Promise`). It can retrieve data from anywhere.
Can I use it with GraphQL? Yes! Here's an example with [Apollo](./examples/with-apollo).
Can I use it with Redux? Yes! Here's an [example](./examples/with-redux)
What is this inspired by? 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.
## Roadmap Our Roadmap towards 2.0.0 [is public](https://github.com/zeit/next.js/wiki/Roadmap#nextjs-200). ## Contributing Please see our [contributing.md](./contributing.md) ## Authors - Naoyuki Kanezawa ([@nkzawa](https://twitter.com/nkzawa)) – ▲ZEIT - Tony Kovanen ([@tonykovanen](https://twitter.com/tonykovanen)) – ▲ZEIT - Guillermo Rauch ([@rauchg](https://twitter.com/rauchg)) – ▲ZEIT - Dan Zajdband ([@impronunciable](https://twitter.com/impronunciable)) – Knight-Mozilla / Coral Project - Tim Neutkens ([@timneutkens](https://github.com/timneutkens))