My page title

) } } ``` All of ``, `

` and `` are required for page to be properly rendered. __Note: React-components outside of `

` will not be initialised by the browser. Do _not_ add application logic here. If you need shared components in all your pages (like a menu or a toolbar), take a look at the `App` component instead.__ 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) #### Customizing `renderPage` 🚧 It should be noted that the only reason you should be customizing `renderPage` is for usage with css-in-js libraries that need to wrap the application to properly work with server-rendering. 🚧 - It takes as argument an options object for further customization ```js import Document from 'next/document' export default class MyDocument extends Document { static async getInitialProps(ctx) { const originalRenderPage = ctx.renderPage ctx.renderPage = () => originalRenderPage({ // useful for wrapping the whole react tree enhanceApp: App => App, // userful for wrapping in a per-page basis enhanceComponent: Component => Component }) // Run the parent `getInitialProps` using `ctx` that now includes our custom `renderPage` const initialProps = await Document.getInitialProps(ctx) return initialProps } } ``` ### 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` in the pages folder: ⚠️ The default `error.js` component is only used in production ⚠️ ```jsx import React from 'react' export default class Error extends React.Component { static getInitialProps({ res, err }) { const statusCode = res ? res.statusCode : err ? err.statusCode : null; return { statusCode } } 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 errorCode = res.statusCode > 200 ? res.statusCode : false const json = await res.json() return { errorCode, stars: json.stargazers_count } } render() { if (this.props.errorCode) { return } return (

Next stars: {this.props.stars}

) } } ``` > If you have created a custom error page you have to import your own `_error` component from `./_error` 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}) => { return { /* config options here */ } } ``` `phase` is the current context in which the configuration is loaded. You can see all phases here: [constants](/packages/next-server/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, // optionally configure a port for the onDemandEntries WebSocket, not needed by default websocketPort: 3001, }, } ``` 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' } } ``` To fall back to the default of generating a unique id return `null` from the function: ```js module.exports = { generateBuildId: async () => { // When process.env.YOUR_BUILD_ID is undefined we fall back to the default if(process.env.YOUR_BUILD_ID) { return process.env.YOUR_BUILD_ID } return null } } ``` #### Configuring next process script You can pass any node arguments to `next` CLI command. ```bash NODE_OPTIONS="--throw-deprecation" next NODE_OPTIONS="-r esm" next ``` `--inspect` is a special case since it binds to a port and can't double-bind to the child process the `next` CLI creates. ``` next start --inspect ``` ### Customizing webpack config

Examples

Custom webpack bundle analyzer

Some commonly asked for features are available as modules: - [@zeit/next-css](https://github.com/zeit/next-plugins/tree/master/packages/next-css) - [@zeit/next-sass](https://github.com/zeit/next-plugins/tree/master/packages/next-sass) - [@zeit/next-less](https://github.com/zeit/next-plugins/tree/master/packages/next-less) - [@zeit/next-preact](https://github.com/zeit/next-plugins/tree/master/packages/next-preact) - [@zeit/next-typescript](https://github.com/zeit/next-plugins/tree/master/packages/next-typescript) *Warning: The `webpack` function is executed twice, once for the server and once for the client. This allows you to distinguish between client and server configuration using the `isServer` property* Multiple configurations can be combined together with function composition. For example: ```js const withTypescript = require('@zeit/next-typescript') const withSass = require('@zeit/next-sass') module.exports = withTypescript(withSass({ webpack(config, options) { // Further custom configuration here return config } })) ``` In order to extend our usage of `webpack`, you can define a function that extends its config via `next.config.js`. ```js // next.config.js is not transformed by Babel. So you can only use javascript features supported by your version of Node.js. module.exports = { webpack: (config, { buildId, dev, isServer, defaultLoaders }) => { // Perform customizations to webpack config // Important: return the modified config return config }, webpackDevMiddleware: config => { // Perform customizations to webpack dev middleware config // Important: return the modified config return config } } ``` The second argument to `webpack` is an object containing properties useful when customizing its configuration: - `buildId` - `String` the build id used as a unique identifier between builds - `dev` - `Boolean` shows if the compilation is done in development mode - `isServer` - `Boolean` shows if the resulting configuration will be used for server side (`true`), or client size compilation (`false`). - `defaultLoaders` - `Object` Holds loader objects Next.js uses internally, so that you can use them in custom configuration - `babel` - `Object` the `babel-loader` configuration for Next.js. - `hotSelfAccept` - `Object` the `hot-self-accept-loader` configuration. This loader should only be used for advanced use cases. For example [`@zeit/next-typescript`](https://github.com/zeit/next-plugins/tree/master/packages/next-typescript) adds it for top-level typescript pages. Example usage of `defaultLoaders.babel`: ```js // Example next.config.js for adding a loader that depends on babel-loader // This source was taken from the @zeit/next-mdx plugin source: // https://github.com/zeit/next-plugins/blob/master/packages/next-mdx module.exports = { webpack: (config, {}) => { config.module.rules.push({ test: /\.mdx/, use: [ options.defaultLoaders.babel, { loader: '@mdx-js/loader', options: pluginOptions.options } ] }) return config } } ``` ### Customizing babel config

Examples

Custom babel configuration

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: ```json { "presets": ["next/babel"], "plugins": [] } ``` The `next/babel` preset includes everything needed to transpile React applications. This includes: - preset-env - preset-react - plugin-proposal-class-properties - plugin-proposal-object-rest-spread - plugin-transform-runtime - styled-jsx These presets / plugins **should not** be added to your custom `.babelrc`. Instead, you can configure them on the `next/babel` preset: ```json { "presets": [ ["next/babel", { "preset-env": {}, "transform-runtime": {}, "styled-jsx": {}, "class-properties": {} }] ], "plugins": [] } ``` The `modules` option on `"preset-env"` should be kept to `false` otherwise webpack code splitting is disabled. ### Exposing configuration to the server / client side The `next/config` module gives your app access to runtime configuration stored in your `next.config.js`. Place any server-only runtime config under a `serverRuntimeConfig` property and anything accessible to both client and server-side code under `publicRuntimeConfig`. ```js // next.config.js module.exports = { serverRuntimeConfig: { // Will only be available on the server side mySecret: 'secret', secondSecret: process.env.SECOND_SECRET // Pass through env variables }, publicRuntimeConfig: { // Will be available on both server and client staticFolder: '/static', } } ``` ```js // pages/index.js import getConfig from 'next/config' // Only holds serverRuntimeConfig and publicRuntimeConfig from next.config.js nothing else. const {serverRuntimeConfig, publicRuntimeConfig} = getConfig() console.log(serverRuntimeConfig.mySecret) // Will only be available on the server side console.log(publicRuntimeConfig.staticFolder) // Will be available on both server and client export default () =>

``` ### Starting the server on alternative hostname To start the development server using a different default hostname you can use `--hostname hostname_here` or `-H hostname_here` option with next dev. This will start a TCP server listening for connections on the provided host. ### CDN support with Asset Prefix To set up a CDN, you can set up the `assetPrefix` setting and configure your CDN's origin to resolve to the domain that Next.js is hosted on. ```js const isProd = process.env.NODE_ENV === 'production' module.exports = { // You may only need to add assetPrefix in the production. assetPrefix: isProd ? 'https://cdn.mydomain.com' : '' } ``` Note: Next.js will automatically use that prefix in the scripts it loads, but this has no effect whatsoever on `/static`. If you want to serve those assets over the CDN, you'll have to introduce the prefix yourself. One way of introducing a prefix that works inside your components and varies by environment is documented [in this example](https://github.com/zeit/next.js/tree/master/examples/with-universal-configuration). If your CDN is on a separate domain and you would like assets to be requested using a [CORS aware request](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_settings_attributes) you can set a config option for that. ```js // next.config.js module.exports = { crossOrigin: 'anonymous' } ``` ## Production deployment To deploy, instead of running `next`, you want to build for production usage 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! Next.js can be deployed to other hosting solutions too. Please have a look at the ['Deployment'](https://github.com/zeit/next.js/wiki/Deployment) section of the wiki. Note: `NODE_ENV` is properly configured by the `next` subcommands, if absent, to maximize performance. if you’re using Next.js [programmatically](#custom-server-and-routing), it’s your responsibility to set `NODE_ENV=production` manually! Note: we recommend putting `.next`, or your [custom dist folder](https://github.com/zeit/next.js#custom-configuration), in `.gitignore` or `.npmignore`. Otherwise, use `files` or `now.files` to opt-into a whitelist of files you want to deploy, excluding `.next` or your custom dist folder. ## Browser support Next.js supports IE11 and all modern browsers out of the box using [`@babel/preset-env`](https://new.babeljs.io/docs/en/next/babel-preset-env.html). In order to support IE11 Next.js adds a global `Promise` polyfill. In cases where your own code or any external NPM dependencies you are using requires features not supported by your target browsers you will need to implement polyfills. The [polyfills](https://github.com/zeit/next.js/tree/canary/examples/with-polyfills) example demonstrates the recommended approach to implement polyfills. ## Static HTML export

Examples

Static export

`next export` is a way to run your Next.js app as a standalone static app without the need for a Node.js server. The exported app supports almost every feature of Next.js, including dynamic urls, prefetching, preloading and dynamic imports. The way `next export` works is by pre-rendering all pages possible to HTML. It does so based on a mapping of `pathname` key to page object. This mapping is called the `exportPathMap`. The page object has 2 values: - `page` - `String` the page inside the `pages` directory to render - `query` - `Object` the `query` object passed to `getInitialProps` when pre-rendering. Defaults to `{}` ### Usage Simply develop your app as you normally do with Next.js. Then run: ``` next build next export ``` By default `next export` doesn't require any configuration. It will generate a default `exportPathMap` containing the routes to pages inside the `pages` directory. This default mapping is available as `defaultPathMap` in the example below. If your application has dynamic routes you can add a dynamic `exportPathMap` in `next.config.js`. This function is asynchronous and gets the default `exportPathMap` as a parameter. ```js // next.config.js module.exports = { exportPathMap: async function (defaultPathMap) { return { '/': { page: '/' }, '/about': { page: '/about' }, '/readme.md': { page: '/readme' }, '/p/hello-nextjs': { page: '/post', query: { title: 'hello-nextjs' } }, '/p/learn-nextjs': { page: '/post', query: { title: 'learn-nextjs' } }, '/p/deploy-nextjs': { page: '/post', query: { title: 'deploy-nextjs' } } } } } ``` > Note that if the path ends with a directory, it will be exported as `/dir-name/index.html`, but if it ends with an extension, it will be exported as the specified filename, e.g. `/readme.md` above. If you use a file extension other than `.html`, you may need to set the `Content-Type` header to `text/html` when serving this content. Then simply run these commands: ```bash next build next export ``` For that you may need to add a NPM script to `package.json` like this: ```json { "scripts": { "build": "next build", "export": "npm run build && next export" } } ``` And run it at once with: ```bash npm run export ``` Then you have a static version of your app in the `out` directory. > You can also customize the output directory. For that run `next export -h` for the help. Now you can deploy the `out` directory to any static hosting service. Note that there is an additional step for deploying to GitHub Pages, [documented here](https://github.com/zeit/next.js/wiki/Deploying-a-Next.js-app-into-GitHub-Pages). For an example, simply visit the `out` directory and run following command to deploy your app to [ZEIT Now](https://zeit.co/now). ```bash now ``` ### Copying custom files In case you have to copy custom files like a robots.txt or generate a sitemap.xml you can do this inside of `exportPathMap`. `exportPathMap` gets a few contextual parameter to aid you with creating/copying files: - `dev` - `true` when `exportPathMap` is being called in development. `false` when running `next export`. In development `exportPathMap` is used to define routes and behavior like copying files is not required. - `dir` - Absolute path to the project directory - `outDir` - Absolute path to the `out` directory (configurable with `-o` or `--outdir`). When `dev` is `true` the value of `outDir` will be `null`. - `distDir` - Absolute path to the `.next` directory (configurable using the `distDir` config key) - `buildId` - The buildId the export is running for ```js // next.config.js const fs = require('fs') const { join } = require('path') const { promisify } = require('util') const copyFile = promisify(fs.copyFile) module.exports = { exportPathMap: async function (defaultPathMap, {dev, dir, outDir, distDir, buildId}) { if (dev) { return defaultPathMap } // This will copy robots.txt from your project root into the out directory await copyFile(join(dir, 'robots.txt'), join(outDir, 'robots.txt')) return defaultPathMap } } ``` ### Limitation With `next export`, we build a HTML version of your app. At export time we will run `getInitialProps` of your pages. The `req` and `res` fields of the `context` object passed to `getInitialProps` are not available as there is no server running. > You won't be able to render HTML dynamically when static exporting, as we pre-build the HTML files. If you want to do dynamic rendering use `next start` or the custom server API ## Multi Zones

Examples

With Zones

A zone is a single deployment of a Next.js app. Just like that, you can have multiple zones. Then you can merge them as a single app. For an example, you can have two zones like this: * https://docs.my-app.com for serving `/docs/**` * https://ui.my-app.com for serving all other pages With multi zones support, you can merge both these apps into a single one. Which allows your customers to browse it using a single URL. But you can develop and deploy both apps independently. > This is exactly the same concept as microservices, but for frontend apps. ### How to define a zone There are no special zones related APIs. You only need to do following things: * Make sure to keep only the pages you need in your app. (For an example, https://ui.my-app.com should not contain pages for `/docs/**`) * Make sure your app has an [assetPrefix](https://github.com/zeit/next.js#cdn-support-with-asset-prefix). (You can also define the assetPrefix [dynamically](https://github.com/zeit/next.js#dynamic-assetprefix).) ### How to merge them You can merge zones using any HTTP proxy. You can use [micro proxy](https://github.com/zeit/micro-proxy) as your local proxy server. It allows you to easily define routing rules like below: ```json { "rules": [ {"pathname": "/docs**", "method":["GET", "POST", "OPTIONS"], "dest": "https://docs.my-app.com"}, {"pathname": "/**", "dest": "https://ui.my-app.com"} ] } ``` For the production deployment, you can use the [path alias](https://zeit.co/docs/features/path-aliases) feature if you are using [ZEIT now](https://zeit.co/now). Otherwise, you can configure your existing proxy server to route HTML pages using a set of rules as shown above. ## Recipes - [Setting up 301 redirects](https://www.raygesualdo.com/posts/301-redirects-with-nextjs/) - [Dealing with SSR and server only modules](https://arunoda.me/blog/ssr-and-server-only-modules) - [Building with React-Material-UI-Next-Express-Mongoose-Mongodb](https://github.com/builderbook/builderbook) - [Build a SaaS Product with React-Material-UI-Next-MobX-Express-Mongoose-MongoDB-TypeScript](https://github.com/async-labs/saas) ## 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 any 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 the documentation about [customizing the babel config](#customizing-babel-config) and [next/preset](/packages/next/build/babel/preset.js) for more information.

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)

Can I use Next with my favorite Javascript library or toolkit?

Since our first release we've had **many** example contributions, you can check them out in the [examples](/examples) directory

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.

## Contributing Please see our [contributing.md](/contributing.md) ## Authors - Arunoda Susiripala ([@arunoda](https://twitter.com/arunoda)) – [ZEIT](https://zeit.co) - Tim Neutkens ([@timneutkens](https://twitter.com/timneutkens)) – [ZEIT](https://zeit.co) - Naoyuki Kanezawa ([@nkzawa](https://twitter.com/nkzawa)) – [ZEIT](https://zeit.co) - Tony Kovanen ([@tonykovanen](https://twitter.com/tonykovanen)) – [ZEIT](https://zeit.co) - Guillermo Rauch ([@rauchg](https://twitter.com/rauchg)) – [ZEIT](https://zeit.co) - Dan Zajdband ([@impronunciable](https://twitter.com/impronunciable)) – Knight-Mozilla / Coral Project

{props.title}