next.js/README.md

<img width="112" alt="screen shot 2016-10-25 at 2 37 27 pm" src="https://cloud.githubusercontent.com/assets/13041/19686250/971bf7f8-9ac0-11e6-975c-188defd82df1.png">

[![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

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 () => (
  <div>Welcome to next.js!</div>
)
```

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 () => (
  <pre>{ cowsay.say({ text: 'hi there!' }) }</pre>
)
```

### CSS

#### Built-in CSS support

<details>
  <summary><b>Examples</b></summary>
  - [Basic css](./examples/basic-css)
</details>

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 () => (
  <div>
    Hello world
    <p>scoped!</p>
    <style jsx>{`
      p {
        color: blue;
      }
      div {
        background: red;
      }
      @media (max-width: 600px) {
        div {
          background: blue;
        }
      }
    `}</style>
  </div>
)
```

#### CSS-in-JS

It's possible to use any existing CSS-in-JS solution. The simplest one is inline styles:

```jsx
export default () => (
  <p style={{ color: 'red' }}>hi there</p>
)
```

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 `<Document>`](#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 () => (
  <img src="/static/my-image.png" />
)
```

### Populating `<head>`

<details>
  <summary><b>Examples</b></summary>
  - [Head elements](./examples/head-elements)
</details>

We expose a built-in component for appending elements to the `<head>` of the page.

```jsx
import Head from 'next/head'
export default () => (
  <div>
    <Head>
      <title>My page title</title>
      <meta name="viewport" content="initial-scale=1.0, width=device-width" />
    </Head>
    <p>Hello world!</p>
  </div>
)
```

_Note: The contents of `<head>` get cleared upon unmounting the component, so make sure each page completely defines what it needs in `<head>`, without making assumptions about what other pages added_

### Fetching data and component lifecycle

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 <div>
      Hello World {this.props.userAgent}
    </div>
  }
}
```

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

<p><details>
  <summary><b>Examples</b></summary>
  <ul><li><a href="./examples/using-routing">Basic routing</a></li></ul>
</details></p>

Client-side transitions between routes can be enabled via a `<Link>` component. Consider these two pages:

```jsx
// pages/index.js
import Link from 'next/link'
export default () => (
  <div>Click <Link href="/about"><a>here</a></Link> to read more</div>
)
```

```jsx
// pages/about.js
export default () => (
  <p>Welcome to About!</p>
)
```

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 () => (
  <div>Click <span onClick={() => Router.push('/about')}>here</span> to read more</div>
)
```

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_

### Prefetching Pages

<details>
  <summary><b>Examples</b></summary>
  - [Prefetching](./examples/with-prefetching)
</details>

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

You can substitute your usage of `<Link>` with the default export of `next/prefetch`. For example:

```jsx
import Link from 'next/prefetch'
// example header component
export default () => (
  <nav>
    <ul>
      <li><Link href='/'><a>Home</a></Link></li>
      <li><Link href='/about'><a>About</a></Link></li>
      <li><Link href='/contact'><a>Contact</a></Link></li>
    </ul>
  </nav>
)
```

When this higher-level `<Link>` component is first used, the `ServiceWorker` gets installed. To turn off prefetching on a per-`<Link>` basis, you can use the `prefetch` attribute:

```jsx
<Link href='/contact' prefetch={false}>Home</Link>
```

#### Imperatively

Most needs are addressed by `<Link />`, but we also expose an imperative API for advanced usage:

```jsx
import { prefetch } from 'next/prefetch'
export default ({ url }) => (
  <div>
    <a onClick={ () => setTimeout(() => url.pushTo('/dynamic'), 100) }>
      A route transition will happen after 100ms
    </a>
    {
      // but we can prefetch it!
      prefetch('/dynamic')
    }
  </div>
)
```

### Custom server and routing

<details>
  <summary><b>Examples</b></summary>
  - [Basic custom server](./examples/custom-server)
  - [Express integration](./examples/custom-server-express)
  - [Parameterized routing](./examples/parameterized-routing)
</details>

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

<details>
  <summary><b>Examples</b></summary>
  - [Styled components custom document](./examples/with-styled-components)
</details>

Pages in `Next.js` skip the definition of the surrounding document's markup. For example, you never include `<html>`, `<body>`, etc. But we still make it possible to override that:

```jsx
import Document, { Head, Main, NextScript } from `next/document`

export default class MyDocument extends Document {
  static async getInitialProps (ctx) {
    const props = await Document.getInitialProps(ctx)
    return { ...props, customValue: 'hi there!' }
  }

  render () {
    return (
     <html>
       <Head>
         <style>{`body { margin: 0 } /* custom! */`}</style>
       </Head>
       <body className="custom_class">
         {this.props.customValue}
         <Main />
         <NextScript />
       </body>
     </html>
    )
  }
}
```

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 (
      <p>{
        this.props.statusCode
        ? `An error ${this.props.statusCode} occurred on server`
        : 'An error occurred on client'
      }</p>
    )
  }
}
```

### Custom configuration

<details>
  <summary><b>Examples</b></summary>
  - [Custom babel configuration](./examples/with-custom-babel-config)
</details>

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
// 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 }) => {
    config.module.rules.push({ test: /\.svg$/, loader: 'babel!react-svg' })

    // Important: return the modified config
    return config
  }
}
```

### Customizing babel config

In order to extend our usage of `babel`, you can define a function that extends its config via `next.config.js`.

The following example config shows you how to use `babel-preset-stage-0` with your app.

```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 = {
  // config is the set of options we pass to our babel-loaders's query option
  babel: function (config, { dev }) {
    // Add the stage-0 preset.
    // Make sure to use 'require.resolve' otherwise we won't be able to find it.
    config.presets.push(require.resolve('babel-preset-stage-0'))

    // Important: return the modified config
    return config
  }
}
```

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

<details>
  <summary>Is this production ready?</summary>
  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.
</details>

<details>
  <summary>How big is it?</summary>

The client side bundle size should be measured in a per-app basis.
A small Next main bundle is around 65kb gzipped.

</details>

<details>
  <summary>Is this like `create-react-app`?</summary>

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 `<head>`: `<Head>` (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!

</details>

<details>
  <summary>How do I use CSS-in-JS solutions?</summary>

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.
</details>

<details>
  <summary>What syntactic features are transpiled? How do I change them?</summary>

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)

</details>

<details>
  <summary>Why a new Router?</summary>

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 `<Link />` component is used to wrap elements like anchors (`<a/>`) 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).

</details>

<details>
<summary>How do I define a custom fancy route?</summary>

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 `<Link>` that _decorates_ the URL differently from the URL it _fetches_.
</details>

<details>
<summary>How do I fetch data?</summary>

It’s up to you. `getInitialProps` is an `async` function (or a regular function that returns a `Promise`). It can retrieve data from anywhere.
</details>

<details>
<summary>Can I use it with Redux?</summary>

Yes! Here's an [example](./examples/with-redux)
</details>

<details>
<summary>What is this inspired by?</summary>

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.

</details>

## Roadmap

Our Roadmap towards 2.0.0 [is public](https://github.com/zeit/next.js/wiki/Roadmap#nextjs-200).

## 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
-												Update Readme.md
											
										
										
											2016-10-25 12:37:55 +00:00
+								<img width="112" alt="screen shot 2016-10-25 at 2 37 27 pm" src="https://cloud.githubusercontent.com/assets/13041/19686250/971bf7f8-9ac0-11e6-975c-188defd82df1.png">
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
-												README: add travis badge

											
										
										
											2016-11-05 18:21:32 +00:00
+								[![Build Status](https://travis-ci.org/zeit/next.js.svg?branch=master)](https://travis-ci.org/zeit/next.js)
-												chore: add test coverage

											
										
										
											2016-11-15 08:24:20 +00:00
+								[![Coverage Status](https://coveralls.io/repos/zeit/next.js/badge.svg?branch=master)](https://coveralls.io/r/zeit/next.js?branch=master)
-												Slack badge (#176)


											
										
										
											2016-11-02 19:02:56 +00:00
+								[![Slack Channel](https://zeit-slackin.now.sh/badge.svg)](https://zeit.chat)
-												Update Readme.md
											
										
										
											2016-10-25 06:09:45 +00:00
+								Next.js is a minimalistic framework for server-rendered React applications.
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
-												warn about master README
											
										
										
											2016-12-16 20:22:55 +00:00
+								**NOTE! the README on the `master` branch might not match that of the [latest stable release](https://github.com/zeit/next.js/releases/latest)! **
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
+								## How to use
-												Update Readme.md
											
										
										
											2016-10-25 06:09:45 +00:00
+								Install it:
-												Update README.md
											
										
										
											2016-12-20 19:19:03 +00:00
+								```bash
 								npm install next --save
-												Update Readme.md
											
										
										
											2016-10-25 06:09:45 +00:00
+								```
-												readme: fix the instruction of running next

											
										
										
											2016-10-26 01:46:58 +00:00
+								and add a script to your package.json like this:
 								```json
 								{
 								  "scripts": {
-												README: fix instruction

											
										
										
											2016-10-26 23:07:33 +00:00
+								    "dev": "next"
-												Implement the Singleton Router API (#429)

* Immplement the initial singleton Router.

* Use the new SingletonRouter for HMR error handling.

* Use SingletonRouter inside the Link.

* Create an example app using the Router.

* Make the url parameter optional in Router.push and Router.replace

* Add a section about next/router in the README.

											
										
										
											2016-12-19 14:40:26 +00:00
+								  }
-												readme: fix the instruction of running next

											
										
										
											2016-10-26 01:46:58 +00:00
+								}
 								```
-												Update Readme.md
											
										
										
											2016-10-25 06:09:45 +00:00
+								After that, the file-system is the main API. Every `.js` file becomes a route that gets automatically processed and rendered.
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
-												Update Readme.md
											
										
										
											2016-10-05 23:36:18 +00:00
+								Populate `./pages/index.js` inside your project:
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
-												Update Readme.md
											
										
										
											2016-10-05 23:58:36 +00:00
+								```jsx
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
+								export default () => (
 								  <div>Welcome to next.js!</div>
 								)
 								```
-												README: fix instruction

											
										
										
											2016-10-26 23:07:33 +00:00
+								and then just run `npm run dev` and go to `http://localhost:3000`
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
 								So far, we get:
 								- Automatic transpilation and bundling (with webpack and babel)
 								- Hot code reloading
-												Update Readme.md
											
										
										
											2016-10-05 23:36:18 +00:00
+								- Server rendering and indexing of `./pages`
 								- Static file serving. `./static/` is mapped to `/static/`
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
-												Fix minor typo in README
											
										
										
											2016-10-25 16:26:27 +00:00
+								To see how simple this is, check out the [sample app - nextgram](https://github.com/zeit/nextgram)
-												Added sample app link to README
											
										
										
											2016-10-25 16:18:57 +00:00
-												Update README.md
											
										
										
											2016-12-19 21:34:19 +00:00
+								### Automatic code splitting
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
-												Update README.md
											
										
										
											2016-12-19 21:34:19 +00:00
+								Every `import` you declare gets bundled and served with each page. That means pages never load unnecessary code!
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
-												Update Readme.md
											
										
										
											2016-10-05 23:58:36 +00:00
+								```jsx
-												Fixed examples.

											
										
										
											2016-10-14 21:13:46 +00:00
+								import cowsay from 'cowsay-browser'
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
+								export default () => (
-												Fix cowsay example so that it compiles
											
										
										
											2016-10-25 17:03:20 +00:00
+								  <pre>{ cowsay.say({ text: 'hi there!' }) }</pre>
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
+								)
 								```
 								### CSS
-												Update README.md
											
										
										
											2016-12-19 19:20:18 +00:00
+								#### Built-in CSS support
-												README: add more help on using Glamor (#165)


											
										
										
											2016-10-31 07:32:51 +00:00
-												Added missing readme and references in main readme. (#483)

* Added missing readme and references in main readme.

* Fixed wrong links

* Updated examples format

											
										
										
											2016-12-22 21:04:32 +00:00
+								<details>
 								  <summary><b>Examples</b></summary>
 								  - [Basic css](./examples/basic-css)
 								</details>
-												Update README.md
											
										
										
											2016-12-19 19:20:18 +00:00
+								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).
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
-												Update Readme.md
											
										
										
											2016-10-05 23:58:36 +00:00
+								```jsx
-												Fixed examples.

											
										
										
											2016-10-14 21:13:46 +00:00
+								export default () => (
-												Update README.md
											
										
										
											2016-12-19 19:20:18 +00:00
+								  <div>
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
+								    Hello world
-												Update README.md
											
										
										
											2016-12-19 19:20:18 +00:00
+								    <p>scoped!</p>
 								    <style jsx>{`
 								      p {
 								        color: blue;
 								      }
 								      div {
 								        background: red;
 								      }
 								      @media (max-width: 600px) {
 								        div {
 								          background: blue;
 								        }
 								      }
 								    `}</style>
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
+								  </div>
-												Fixed examples.

											
										
										
											2016-10-14 21:13:46 +00:00
+								)
-												Update README.md
											
										
										
											2016-12-19 19:20:18 +00:00
+								```
 								#### CSS-in-JS
 								It's possible to use any existing CSS-in-JS solution. The simplest one is inline styles:
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
-												Update README.md
											
										
										
											2016-12-19 21:34:19 +00:00
+								```jsx
-												Update README.md
											
										
										
											2016-12-19 19:20:18 +00:00
+								export default () => (
-												Updated README with new features and code fixes (#444)

* Updated README with new features and code fixes

* Removed staticMarkup option from docs.

* Fixed quiet parameter info.

											
										
										
											2016-12-20 22:57:11 +00:00
+								  <p style={{ color: 'red' }}>hi there</p>
-												Update README.md
											
										
										
											2016-12-19 19:20:18 +00:00
+								)
 								```
-												Update README.md
											
										
										
											2016-12-19 21:34:19 +00:00
+								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 `<Document>`](#user-content-custom-document) component that wraps each page
-												Update README.md
											
										
										
											2016-12-19 19:20:18 +00:00
-												Update README.md
											
										
										
											2016-12-19 21:34:19 +00:00
+								### Static file serving (e.g.: images)
-												Instructions for images and static assets (#235)

* Instructions for images and static assets

Helpful pointer in the README about `/static` directory

* Update README.md

* remove reference to components directory

* Update README.md

											
										
										
											2016-11-17 16:03:04 +00:00
-												Update README.md
											
										
										
											2016-12-19 21:34:19 +00:00
+								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 () => (
 								  <img src="/static/my-image.png" />
 								)
 								```
-												Instructions for images and static assets (#235)

* Instructions for images and static assets

Helpful pointer in the README about `/static` directory

* Update README.md

* remove reference to components directory

* Update README.md

											
										
										
											2016-11-17 16:03:04 +00:00
-												Update README.md
											
										
										
											2016-12-17 19:16:22 +00:00
+								### Populating `<head>`
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
-												Added missing readme and references in main readme. (#483)

* Added missing readme and references in main readme.

* Fixed wrong links

* Updated examples format

											
										
										
											2016-12-22 21:04:32 +00:00
+								<details>
 								  <summary><b>Examples</b></summary>
 								  - [Head elements](./examples/head-elements)
 								</details>
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
+								We expose a built-in component for appending elements to the `<head>` of the page.
-												Update Readme.md
											
										
										
											2016-10-05 23:58:36 +00:00
+								```jsx
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
+								import Head from 'next/head'
 								export default () => (
-												Fixed examples.

											
										
										
											2016-10-14 21:13:46 +00:00
+								  <div>
 								    <Head>
 								      <title>My page title</title>
 								      <meta name="viewport" content="initial-scale=1.0, width=device-width" />
 								    </Head>
 								    <p>Hello world!</p>
 								  </div>
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
+								)
 								```
-												Update README.md
											
										
										
											2016-12-17 19:16:22 +00:00
+								_Note: The contents of `<head>` get cleared upon unmounting the component, so make sure each page completely defines what it needs in `<head>`, without making assumptions about what other pages added_
 								### Fetching data and component lifecycle
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
-												Update README.md
											
										
										
											2016-12-19 21:34:19 +00:00
+								When you need state, lifecycle hooks or **initial data population** you can export a `React.Component` (instead of a stateless function, like shown above):
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
-												Update Readme.md
											
										
										
											2016-10-05 23:58:36 +00:00
+								```jsx
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
+								import React from 'react'
 								export default class extends React.Component {
-												Update Readme.md
											
										
										
											2016-10-09 00:50:09 +00:00
+								  static async getInitialProps ({ req }) {
 								    return req
-												Fix userAgent reference in getInitialProps example (#81)

The getInitialProps example references `req.header.userAgent`, which does not exist. `req.headers['user-agent']` does.
											
										
										
											2016-10-26 10:19:28 +00:00
+								      ? { userAgent: req.headers['user-agent'] }
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
+								      : { userAgent: navigator.userAgent }
 								  }
 								  render () {
 								    return <div>
 								      Hello World {this.props.userAgent}
 								    </div>
 								  }
 								}
 								```
-												Update README.md
											
										
										
											2016-11-01 01:13:42 +00:00
+								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`.
-												Update README.md
											
										
										
											2016-12-19 15:16:44 +00:00
+								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.
-												Merge branch 'patch-3' of https://github.com/timoxley/next.js into timoxley-patch-3

											
										
										
											2016-11-04 11:37:36 +00:00
-												Update README.md
											
										
										
											2016-12-19 22:36:33 +00:00
+								`getInitialProps` receives a context object with the following properties:
-												Add pathname and query to the argument of getInitialProps (#194)

* pass pathname and query to getInitialProps on both server and client

* README: describe about the contet object of getInitialProps

											
										
										
											2016-11-04 08:05:03 +00:00
 								- `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
-												Update README.md
											
										
										
											2016-12-19 15:16:44 +00:00
+								### Routing
 								#### With `<Link>`
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
-												Update README.md
											
										
										
											2016-12-22 21:08:58 +00:00
+								<p><details>
 								  <summary><b>Examples</b></summary>
 								  <ul><li><a href="./examples/using-routing">Basic routing</a></li></ul>
 								</details></p>
-												Update README.md
											
										
										
											2016-12-19 15:04:53 +00:00
+								Client-side transitions between routes can be enabled via a `<Link>` component. Consider these two pages:
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
-												Update Readme.md
											
										
										
											2016-10-05 23:58:36 +00:00
+								```jsx
-												Update README.md
											
										
										
											2016-12-19 15:04:53 +00:00
+								// pages/index.js
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
+								import Link from 'next/link'
 								export default () => (
 								  <div>Click <Link href="/about"><a>here</a></Link> to read more</div>
 								)
 								```
-												Update Readme.md
											
										
										
											2016-10-05 23:58:36 +00:00
+								```jsx
-												Update README.md
											
										
										
											2016-12-19 15:04:53 +00:00
+								// pages/about.js
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
+								export default () => (
 								  <p>Welcome to About!</p>
 								)
 								```
-												Update README.md
											
										
										
											2016-12-19 15:04:53 +00:00
+								Client-side routing behaves exactly like the browser:
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
 . The component is fetched
 . If it defines `getInitialProps`, data is fetched. If an error occurs, `_error.js` is rendered
 . 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:
-												Updated readme to reflect proper name of url.pathname property (#66)


											
										
										
											2016-10-26 09:49:05 +00:00
+								- `pathname` - `String` of the current path excluding the query string
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
+								- `query` - `Object` with the parsed query string. Defaults to `{}`
-												Add deprecate messages for url.replaceTo and url.pushTo (#433)


											
										
										
											2016-12-19 18:49:15 +00:00
+								- `push(url, as=url)` - performs a `pushState` call with the given url
 								- `replace(url, as=url)` - performs a `replaceState` call with the given url
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
-												Add deprecate messages for url.replaceTo and url.pushTo (#433)


											
										
										
											2016-12-19 18:49:15 +00:00
+								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
-												Implement the Singleton Router API (#429)

* Immplement the initial singleton Router.

* Use the new SingletonRouter for HMR error handling.

* Use SingletonRouter inside the Link.

* Create an example app using the Router.

* Make the url parameter optional in Router.push and Router.replace

* Add a section about next/router in the README.

											
										
										
											2016-12-19 14:40:26 +00:00
-												Update README.md
											
										
										
											2016-12-19 15:16:44 +00:00
+								You can also do client-side page transitions using the `next/router`
-												Implement the Singleton Router API (#429)

* Immplement the initial singleton Router.

* Use the new SingletonRouter for HMR error handling.

* Use SingletonRouter inside the Link.

* Create an example app using the Router.

* Make the url parameter optional in Router.push and Router.replace

* Add a section about next/router in the README.

											
										
										
											2016-12-19 14:40:26 +00:00
 								```jsx
 								import Router from 'next/router'
 								export default () => (
-												Update README.md
											
										
										
											2016-12-19 15:17:33 +00:00
+								  <div>Click <span onClick={() => Router.push('/about')}>here</span> to read more</div>
-												Implement the Singleton Router API (#429)

* Immplement the initial singleton Router.

* Use the new SingletonRouter for HMR error handling.

* Use SingletonRouter inside the Link.

* Create an example app using the Router.

* Make the url parameter optional in Router.push and Router.replace

* Add a section about next/router in the README.

											
										
										
											2016-12-19 14:40:26 +00:00
+								)
 								```
 								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 `{}`
-												Add deprecate messages for url.replaceTo and url.pushTo (#433)


											
										
										
											2016-12-19 18:49:15 +00:00
+								- `push(url, as=url)` - performs a `pushState` call with the given url
 								- `replace(url, as=url)` - performs a `replaceState` call with the given url
-												Implement the Singleton Router API (#429)

* Immplement the initial singleton Router.

* Use the new SingletonRouter for HMR error handling.

* Use SingletonRouter inside the Link.

* Create an example app using the Router.

* Make the url parameter optional in Router.push and Router.replace

* Add a section about next/router in the README.

											
										
										
											2016-12-19 14:40:26 +00:00
-												Update README.md
											
										
										
											2016-12-19 15:04:53 +00:00
+								The second `as` parameter for `push` and `replace` is an optional _decoration_ of the URL. Useful if you configured custom routes on the server.
-												Implement the Singleton Router API (#429)

* Immplement the initial singleton Router.

* Use the new SingletonRouter for HMR error handling.

* Use SingletonRouter inside the Link.

* Create an example app using the Router.

* Make the url parameter optional in Router.push and Router.replace

* Add a section about next/router in the README.

											
										
										
											2016-12-19 14:40:26 +00:00
-												Fix typo (#471)


											
										
										
											2016-12-22 03:52:43 +00:00
+								_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_
-												Update README.md
											
										
										
											2016-12-19 15:16:44 +00:00
-												Prefetch pages with Service Workers (#375)

* Register the service worker.

* Update prefetcher code to do prefetching.

* Implement the core prefetching API.
support "import <Link>, { prefetch } from 'next/prefetch'"

* Implement a better communication system with the service worker.

* Add a separate example for prefetching

* Fix some typos.

* Initiate service worker support even prefetching is not used.
This is pretty important since initiating will reset the cache.
If we don't do this, it's possible to have old cached resources
after the user decided to remove all of the prefetching logic.
In this case, even the page didn't prefetch it'll use the
previously cached pages. That because of there might be a already running
service worker.

* Use url module to get pathname.

* Move prefetcher code to the client from pages
Now we also do a webpack build for the prefetcher code.

* Add prefetching docs to the README.md

* Fix some typo.

* Register service worker only if asked to prefetch
We also clean the cache always, even we initialize
the service worker or not.

											
										
										
											2016-12-15 19:13:40 +00:00
+								### Prefetching Pages
-												Added missing readme and references in main readme. (#483)

* Added missing readme and references in main readme.

* Fixed wrong links

* Updated examples format

											
										
										
											2016-12-22 21:04:32 +00:00
+								<details>
 								  <summary><b>Examples</b></summary>
 								  - [Prefetching](./examples/with-prefetching)
 								</details>
-												Implement the Singleton Router API (#429)

* Immplement the initial singleton Router.

* Use the new SingletonRouter for HMR error handling.

* Use SingletonRouter inside the Link.

* Create an example app using the Router.

* Make the url parameter optional in Router.push and Router.replace

* Add a section about next/router in the README.

											
										
										
											2016-12-19 14:40:26 +00:00
+								Next.js exposes a module that configures a `ServiceWorker` automatically to prefetch pages: `next/prefetch`.
-												Prefetch pages with Service Workers (#375)

* Register the service worker.

* Update prefetcher code to do prefetching.

* Implement the core prefetching API.
support "import <Link>, { prefetch } from 'next/prefetch'"

* Implement a better communication system with the service worker.

* Add a separate example for prefetching

* Fix some typos.

* Initiate service worker support even prefetching is not used.
This is pretty important since initiating will reset the cache.
If we don't do this, it's possible to have old cached resources
after the user decided to remove all of the prefetching logic.
In this case, even the page didn't prefetch it'll use the
previously cached pages. That because of there might be a already running
service worker.

* Use url module to get pathname.

* Move prefetcher code to the client from pages
Now we also do a webpack build for the prefetcher code.

* Add prefetching docs to the README.md

* Fix some typo.

* Register service worker only if asked to prefetch
We also clean the cache always, even we initialize
the service worker or not.

											
										
										
											2016-12-15 19:13:40 +00:00
-												Implement the Singleton Router API (#429)

* Immplement the initial singleton Router.

* Use the new SingletonRouter for HMR error handling.

* Use SingletonRouter inside the Link.

* Create an example app using the Router.

* Make the url parameter optional in Router.push and Router.replace

* Add a section about next/router in the README.

											
										
										
											2016-12-19 14:40:26 +00:00
+								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).
-												Prefetch pages with Service Workers (#375)

* Register the service worker.

* Update prefetcher code to do prefetching.

* Implement the core prefetching API.
support "import <Link>, { prefetch } from 'next/prefetch'"

* Implement a better communication system with the service worker.

* Add a separate example for prefetching

* Fix some typos.

* Initiate service worker support even prefetching is not used.
This is pretty important since initiating will reset the cache.
If we don't do this, it's possible to have old cached resources
after the user decided to remove all of the prefetching logic.
In this case, even the page didn't prefetch it'll use the
previously cached pages. That because of there might be a already running
service worker.

* Use url module to get pathname.

* Move prefetcher code to the client from pages
Now we also do a webpack build for the prefetcher code.

* Add prefetching docs to the README.md

* Fix some typo.

* Register service worker only if asked to prefetch
We also clean the cache always, even we initialize
the service worker or not.

											
										
										
											2016-12-15 19:13:40 +00:00
-												Update README.md
											
										
										
											2016-12-19 15:16:44 +00:00
+								#### With `<Link>`
-												Prefetch pages with Service Workers (#375)

* Register the service worker.

* Update prefetcher code to do prefetching.

* Implement the core prefetching API.
support "import <Link>, { prefetch } from 'next/prefetch'"

* Implement a better communication system with the service worker.

* Add a separate example for prefetching

* Fix some typos.

* Initiate service worker support even prefetching is not used.
This is pretty important since initiating will reset the cache.
If we don't do this, it's possible to have old cached resources
after the user decided to remove all of the prefetching logic.
In this case, even the page didn't prefetch it'll use the
previously cached pages. That because of there might be a already running
service worker.

* Use url module to get pathname.

* Move prefetcher code to the client from pages
Now we also do a webpack build for the prefetcher code.

* Add prefetching docs to the README.md

* Fix some typo.

* Register service worker only if asked to prefetch
We also clean the cache always, even we initialize
the service worker or not.

											
										
										
											2016-12-15 19:13:40 +00:00
-												Update README.md
											
										
										
											2016-12-17 19:33:07 +00:00
+								You can substitute your usage of `<Link>` with the default export of `next/prefetch`. For example:
-												Prefetch pages with Service Workers (#375)

* Register the service worker.

* Update prefetcher code to do prefetching.

* Implement the core prefetching API.
support "import <Link>, { prefetch } from 'next/prefetch'"

* Implement a better communication system with the service worker.

* Add a separate example for prefetching

* Fix some typos.

* Initiate service worker support even prefetching is not used.
This is pretty important since initiating will reset the cache.
If we don't do this, it's possible to have old cached resources
after the user decided to remove all of the prefetching logic.
In this case, even the page didn't prefetch it'll use the
previously cached pages. That because of there might be a already running
service worker.

* Use url module to get pathname.

* Move prefetcher code to the client from pages
Now we also do a webpack build for the prefetcher code.

* Add prefetching docs to the README.md

* Fix some typo.

* Register service worker only if asked to prefetch
We also clean the cache always, even we initialize
the service worker or not.

											
										
										
											2016-12-15 19:13:40 +00:00
 								```jsx
 								import Link from 'next/prefetch'
-												Update README.md
											
										
										
											2016-12-17 19:16:22 +00:00
+								// example header component
-												Prefetch pages with Service Workers (#375)

* Register the service worker.

* Update prefetcher code to do prefetching.

* Implement the core prefetching API.
support "import <Link>, { prefetch } from 'next/prefetch'"

* Implement a better communication system with the service worker.

* Add a separate example for prefetching

* Fix some typos.

* Initiate service worker support even prefetching is not used.
This is pretty important since initiating will reset the cache.
If we don't do this, it's possible to have old cached resources
after the user decided to remove all of the prefetching logic.
In this case, even the page didn't prefetch it'll use the
previously cached pages. That because of there might be a already running
service worker.

* Use url module to get pathname.

* Move prefetcher code to the client from pages
Now we also do a webpack build for the prefetcher code.

* Add prefetching docs to the README.md

* Fix some typo.

* Register service worker only if asked to prefetch
We also clean the cache always, even we initialize
the service worker or not.

											
										
										
											2016-12-15 19:13:40 +00:00
+								export default () => (
-												Update README.md
											
										
										
											2016-12-17 19:16:22 +00:00
+								  <nav>
 								    <ul>
 								      <li><Link href='/'><a>Home</a></Link></li>
 								      <li><Link href='/about'><a>About</a></Link></li>
 								      <li><Link href='/contact'><a>Contact</a></Link></li>
 								    </ul>
 								  </nav>
-												Prefetch pages with Service Workers (#375)

* Register the service worker.

* Update prefetcher code to do prefetching.

* Implement the core prefetching API.
support "import <Link>, { prefetch } from 'next/prefetch'"

* Implement a better communication system with the service worker.

* Add a separate example for prefetching

* Fix some typos.

* Initiate service worker support even prefetching is not used.
This is pretty important since initiating will reset the cache.
If we don't do this, it's possible to have old cached resources
after the user decided to remove all of the prefetching logic.
In this case, even the page didn't prefetch it'll use the
previously cached pages. That because of there might be a already running
service worker.

* Use url module to get pathname.

* Move prefetcher code to the client from pages
Now we also do a webpack build for the prefetcher code.

* Add prefetching docs to the README.md

* Fix some typo.

* Register service worker only if asked to prefetch
We also clean the cache always, even we initialize
the service worker or not.

											
										
										
											2016-12-15 19:13:40 +00:00
+								)
 								```
-												Update README.md
											
										
										
											2016-12-17 19:16:22 +00:00
+								When this higher-level `<Link>` component is first used, the `ServiceWorker` gets installed. To turn off prefetching on a per-`<Link>` basis, you can use the `prefetch` attribute:
-												Prefetch pages with Service Workers (#375)

* Register the service worker.

* Update prefetcher code to do prefetching.

* Implement the core prefetching API.
support "import <Link>, { prefetch } from 'next/prefetch'"

* Implement a better communication system with the service worker.

* Add a separate example for prefetching

* Fix some typos.

* Initiate service worker support even prefetching is not used.
This is pretty important since initiating will reset the cache.
If we don't do this, it's possible to have old cached resources
after the user decided to remove all of the prefetching logic.
In this case, even the page didn't prefetch it'll use the
previously cached pages. That because of there might be a already running
service worker.

* Use url module to get pathname.

* Move prefetcher code to the client from pages
Now we also do a webpack build for the prefetcher code.

* Add prefetching docs to the README.md

* Fix some typo.

* Register service worker only if asked to prefetch
We also clean the cache always, even we initialize
the service worker or not.

											
										
										
											2016-12-15 19:13:40 +00:00
 								```jsx
 								<Link href='/contact' prefetch={false}>Home</Link>
 								```
-												Update README.md
											
										
										
											2016-12-19 15:16:44 +00:00
+								#### Imperatively
-												Prefetch pages with Service Workers (#375)

* Register the service worker.

* Update prefetcher code to do prefetching.

* Implement the core prefetching API.
support "import <Link>, { prefetch } from 'next/prefetch'"

* Implement a better communication system with the service worker.

* Add a separate example for prefetching

* Fix some typos.

* Initiate service worker support even prefetching is not used.
This is pretty important since initiating will reset the cache.
If we don't do this, it's possible to have old cached resources
after the user decided to remove all of the prefetching logic.
In this case, even the page didn't prefetch it'll use the
previously cached pages. That because of there might be a already running
service worker.

* Use url module to get pathname.

* Move prefetcher code to the client from pages
Now we also do a webpack build for the prefetcher code.

* Add prefetching docs to the README.md

* Fix some typo.

* Register service worker only if asked to prefetch
We also clean the cache always, even we initialize
the service worker or not.

											
										
										
											2016-12-15 19:13:40 +00:00
-												Update README.md
											
										
										
											2016-12-17 19:16:22 +00:00
+								Most needs are addressed by `<Link />`, but we also expose an imperative API for advanced usage:
-												Prefetch pages with Service Workers (#375)

* Register the service worker.

* Update prefetcher code to do prefetching.

* Implement the core prefetching API.
support "import <Link>, { prefetch } from 'next/prefetch'"

* Implement a better communication system with the service worker.

* Add a separate example for prefetching

* Fix some typos.

* Initiate service worker support even prefetching is not used.
This is pretty important since initiating will reset the cache.
If we don't do this, it's possible to have old cached resources
after the user decided to remove all of the prefetching logic.
In this case, even the page didn't prefetch it'll use the
previously cached pages. That because of there might be a already running
service worker.

* Use url module to get pathname.

* Move prefetcher code to the client from pages
Now we also do a webpack build for the prefetcher code.

* Add prefetching docs to the README.md

* Fix some typo.

* Register service worker only if asked to prefetch
We also clean the cache always, even we initialize
the service worker or not.

											
										
										
											2016-12-15 19:13:40 +00:00
 								```jsx
 								import { prefetch } from 'next/prefetch'
-												Update README.md
											
										
										
											2016-12-17 19:48:52 +00:00
+								export default ({ url }) => (
-												Updated README with new features and code fixes (#444)

* Updated README with new features and code fixes

* Removed staticMarkup option from docs.

* Fixed quiet parameter info.

											
										
										
											2016-12-20 22:57:11 +00:00
+								  <div>
 								    <a onClick={ () => setTimeout(() => url.pushTo('/dynamic'), 100) }>
 								      A route transition will happen after 100ms
 								    </a>
 								    {
 								      // but we can prefetch it!
 								      prefetch('/dynamic')
 								    }
 								  </div>
-												Update README.md
											
										
										
											2016-12-17 19:16:22 +00:00
+								)
 								```
-												Prefetch pages with Service Workers (#375)

* Register the service worker.

* Update prefetcher code to do prefetching.

* Implement the core prefetching API.
support "import <Link>, { prefetch } from 'next/prefetch'"

* Implement a better communication system with the service worker.

* Add a separate example for prefetching

* Fix some typos.

* Initiate service worker support even prefetching is not used.
This is pretty important since initiating will reset the cache.
If we don't do this, it's possible to have old cached resources
after the user decided to remove all of the prefetching logic.
In this case, even the page didn't prefetch it'll use the
previously cached pages. That because of there might be a already running
service worker.

* Use url module to get pathname.

* Move prefetcher code to the client from pages
Now we also do a webpack build for the prefetcher code.

* Add prefetching docs to the README.md

* Fix some typo.

* Register service worker only if asked to prefetch
We also clean the cache always, even we initialize
the service worker or not.

											
										
										
											2016-12-15 19:13:40 +00:00
-												Update README.md
											
										
										
											2016-12-20 19:19:03 +00:00
+								### Custom server and routing
-												Added missing readme and references in main readme. (#483)

* Added missing readme and references in main readme.

* Fixed wrong links

* Updated examples format

											
										
										
											2016-12-22 21:04:32 +00:00
+								<details>
 								  <summary><b>Examples</b></summary>
 								  - [Basic custom server](./examples/custom-server)
 								  - [Express integration](./examples/custom-server-express)
 								  - [Parameterized routing](./examples/parameterized-routing)
 								</details>
-												Update README.md
											
										
										
											2016-12-20 19:19:03 +00:00
+								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`:
-												Update README.md
											
										
										
											2016-12-20 19:27:29 +00:00
+								```js
-												Update README.md
											
										
										
											2016-12-20 19:19:03 +00:00
+								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')
 								  })
 								})
 								```
-												Update README.md
											
										
										
											2016-12-20 19:26:59 +00:00
+								The `next` API is as follows:
-												Allow to customize our babel configuration (#466)

* Add a way to customize babel configurations.

* Add babel configuration docs to README.

											
										
										
											2016-12-22 01:36:00 +00:00
+								- `next(path: string, opts: object)` - `path` is
-												Update README.md
											
										
										
											2016-12-20 19:26:59 +00:00
+								- `next(opts: object)`
 								Supported options:
-												Updated README with new features and code fixes (#444)

* Updated README with new features and code fixes

* Removed staticMarkup option from docs.

* Fixed quiet parameter info.

											
										
										
											2016-12-20 22:57:11 +00:00
+								- `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`
-												Update README.md
											
										
										
											2016-12-20 19:26:59 +00:00
-												Update README.md
											
										
										
											2016-12-19 21:34:19 +00:00
+								### Custom `<Document>`
-												Added missing readme and references in main readme. (#483)

* Added missing readme and references in main readme.

* Fixed wrong links

* Updated examples format

											
										
										
											2016-12-22 21:04:32 +00:00
+								<details>
 								  <summary><b>Examples</b></summary>
 								  - [Styled components custom document](./examples/with-styled-components)
 								</details>
-												Update README.md
											
										
										
											2016-12-19 22:41:21 +00:00
+								Pages in `Next.js` skip the definition of the surrounding document's markup. For example, you never include `<html>`, `<body>`, etc. But we still make it possible to override that:
-												Update README.md
											
										
										
											2016-12-19 21:34:19 +00:00
 								```jsx
 								import Document, { Head, Main, NextScript } from `next/document`
 								export default class MyDocument extends Document {
 								  static async getInitialProps (ctx) {
 								    const props = await Document.getInitialProps(ctx)
-												Update README.md
											
										
										
											2016-12-19 22:25:03 +00:00
+								    return { ...props, customValue: 'hi there!' }
-												Update README.md
											
										
										
											2016-12-19 21:34:19 +00:00
+								  }
 								  render () {
 								    return (
 								     <html>
 								       <Head>
-												Update README.md
											
										
										
											2016-12-19 22:25:03 +00:00
+								         <style>{`body { margin: 0 } /* custom! */`}</style>
-												Update README.md
											
										
										
											2016-12-19 21:34:19 +00:00
+								       </Head>
-												Update README.md
											
										
										
											2016-12-19 22:25:03 +00:00
+								       <body className="custom_class">
 								         {this.props.customValue}
-												Update README.md
											
										
										
											2016-12-19 21:34:19 +00:00
+								         <Main />
 								         <NextScript />
 								       </body>
 								     </html>
 								    )
 								  }
 								}
 								```
-												Update README.md
											
										
										
											2016-12-19 22:41:21 +00:00
+								The `ctx` object is equivalent to the one received in all [`getInitialProps`](#fetching-data-and-component-lifecycle) hooks, with one addition:
-												Update README.md
											
										
										
											2016-12-19 22:35:26 +00:00
 								- `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)
-												Update README.md
											
										
										
											2016-12-17 19:33:07 +00:00
+								### Custom error handling
-												Implemented missing pieces for overriding 404 and 500 pages. (#10)


											
										
										
											2016-10-15 22:36:54 +00:00
 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'
-												Reverting default props for errors. (#12)


											
										
										
											2016-10-16 22:44:26 +00:00
+								export default class Error extends React.Component {
 								  static getInitialProps ({ res, xhr }) {
-												Handle runtime errors (#268)

* display runtime errors by error-debug

* server: fix status

* render Error component on client error

* server: render runtime errors of error template

* server: handle errors of error template on render404

* server: add a comment

* server: refactor renderJSON

* recover from runtime errors

* _error: check if xhr exists

* _error: improve client error

* _error: improve error message

											
										
										
											2016-11-24 14:03:16 +00:00
+								    const statusCode = res ? res.statusCode : (xhr ? xhr.status : null)
-												Reverting default props for errors. (#12)


											
										
										
											2016-10-16 22:44:26 +00:00
+								    return { statusCode }
 								  }
 								  render () {
 								    return (
-												Handle runtime errors (#268)

* display runtime errors by error-debug

* server: fix status

* render Error component on client error

* server: render runtime errors of error template

* server: handle errors of error template on render404

* server: add a comment

* server: refactor renderJSON

* recover from runtime errors

* _error: check if xhr exists

* _error: improve client error

* _error: improve error message

											
										
										
											2016-11-24 14:03:16 +00:00
+								      <p>{
 								        this.props.statusCode
 								        ? `An error ${this.props.statusCode} occurred on server`
 								        : 'An error occurred on client'
-												update example with correct syntax (#383)

- was using `]` instead of `}`
											
										
										
											2016-12-13 05:36:20 +00:00
+								      }</p>
-												Reverting default props for errors. (#12)


											
										
										
											2016-10-16 22:44:26 +00:00
+								    )
 								  }
 								}
-												Implemented missing pieces for overriding 404 and 500 pages. (#10)


											
										
										
											2016-10-15 22:36:54 +00:00
+								```
-												Update README.md
											
										
										
											2016-12-17 19:33:07 +00:00
+								### Custom configuration
-												Update README.md
											
										
										
											2016-12-17 19:04:44 +00:00
-												Added missing readme and references in main readme. (#483)

* Added missing readme and references in main readme.

* Fixed wrong links

* Updated examples format

											
										
										
											2016-12-22 21:04:32 +00:00
+								<details>
 								  <summary><b>Examples</b></summary>
 								  - [Custom babel configuration](./examples/with-custom-babel-config)
 								</details>
-												Implement the Singleton Router API (#429)

* Immplement the initial singleton Router.

* Use the new SingletonRouter for HMR error handling.

* Use SingletonRouter inside the Link.

* Create an example app using the Router.

* Make the url parameter optional in Router.push and Router.replace

* Add a section about next/router in the README.

											
										
										
											2016-12-19 14:40:26 +00:00
+								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`).
-												Update README.md
											
										
										
											2016-12-17 19:04:44 +00:00
 								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
-												Update README.md
											
										
										
											2016-12-19 22:37:15 +00:00
+								In order to extend our usage of `webpack`, you can define a function that extends its config via `next.config.js`.
-												Update README.md
											
										
										
											2016-12-17 19:04:44 +00:00
 								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
-												Allow to customize our babel configuration (#466)

* Add a way to customize babel configurations.

* Add babel configuration docs to README.

											
										
										
											2016-12-22 01:36:00 +00:00
+								// 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 }) => {
 								    config.module.rules.push({ test: /\.svg$/, loader: 'babel!react-svg' })
 								    // Important: return the modified config
 								    return config
 								  }
 								}
 								```
 								### Customizing babel config
 								In order to extend our usage of `babel`, you can define a function that extends its config via `next.config.js`.
 								The following example config shows you how to use `babel-preset-stage-0` with your app.
 								```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)
-												Update README.md
											
										
										
											2016-12-17 19:04:44 +00:00
+								module.exports = {
-												Allow to customize our babel configuration (#466)

* Add a way to customize babel configurations.

* Add babel configuration docs to README.

											
										
										
											2016-12-22 01:36:00 +00:00
+								  // config is the set of options we pass to our babel-loaders's query option
 								  babel: function (config, { dev }) {
 								    // Add the stage-0 preset.
 								    // Make sure to use 'require.resolve' otherwise we won't be able to find it.
 								    config.presets.push(require.resolve('babel-preset-stage-0'))
 								    // Important: return the modified config
 								    return config
-												Update README.md
											
										
										
											2016-12-17 19:04:44 +00:00
+								  }
 								}
 								```
-												Update Readme.md
											
										
										
											2016-10-20 00:58:42 +00:00
+								## Production deployment
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
-												Update Readme.md
											
										
										
											2016-10-20 00:58:42 +00:00
+								To deploy, instead of running `next`, you probably want to build ahead of time. Therefore, building and starting are separate commands:
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
-												Update Readme.md
											
										
										
											2016-10-05 23:58:36 +00:00
+								```bash
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
+								next build
 								next start
 								```
-												Update Readme.md
											
										
										
											2016-10-20 00:58:42 +00:00
+								For example, to deploy with [`now`](https://zeit.co/now) a `package.json` like follows is recommended:
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
-												Update Readme.md
											
										
										
											2016-10-05 23:58:36 +00:00
+								```json
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
+								{
 								  "name": "my-app",
 								  "dependencies": {
 								    "next": "latest"
 								  },
 								  "scripts": {
 								    "dev": "next",
 								    "build": "next build",
 								    "start": "next start"
 								  }
 								}
 								```
-												Update Readme.md
											
										
										
											2016-10-15 13:15:10 +00:00
-												Update Readme.md
											
										
										
											2016-10-20 00:58:42 +00:00
+								Then run `now` and enjoy!
-												Fix typo
											
										
										
											2016-10-25 16:58:31 +00:00
+								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`)
-												Update Readme.md
											
										
										
											2016-10-20 00:58:42 +00:00
 								## FAQ
-												Update Readme.md
											
										
										
											2016-10-15 13:15:10 +00:00
-												Update Readme.md
											
										
										
											2016-10-24 19:59:46 +00:00
+								<details>
 								  <summary>Is this production ready?</summary>
 								  Next.js has been powering `https://zeit.co` since its inception.
-												Added bundle size and % (#43)


											
										
										
											2016-10-25 10:32:03 +00:00
-												Update Readme.md
											
										
										
											2016-10-24 19:59:46 +00:00
+								  We’re ecstatic about both the developer experience and end-user performance, so we decided to share it with the community.
 								</details>
-												Update Readme.md
											
										
										
											2016-10-15 13:16:25 +00:00
-												Update Readme.md
											
										
										
											2016-10-24 19:59:46 +00:00
+								<details>
 								  <summary>How big is it?</summary>
-												Updated README with new features and code fixes (#444)

* Updated README with new features and code fixes

* Removed staticMarkup option from docs.

* Fixed quiet parameter info.

											
										
										
											2016-12-20 22:57:11 +00:00
+								The client side bundle size should be measured in a per-app basis.
 								A small Next main bundle is around 65kb gzipped.
-												Update Readme.md
											
										
										
											2016-10-24 19:59:46 +00:00
 								</details>
 								<details>
 								  <summary>Is this like `create-react-app`?</summary>
-												Added bundle size and % (#43)


											
										
										
											2016-10-25 10:32:03 +00:00
-												Update Readme.md
											
										
										
											2016-10-24 19:59:46 +00:00
+								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:
-												Update Readme.md
											
										
										
											2016-10-25 06:09:45 +00:00
+								- Server side rendering
 								- Automatic code splitting
-												Update Readme.md
											
										
										
											2016-10-24 19:59:46 +00:00
 								In addition, Next.js provides two built-in features that are critical for every single website:
-												Update README.md
											
										
										
											2016-12-17 19:33:07 +00:00
+								- Routing with lazy component loading: `
 								>` (by importing `next/link`)
-												Update Readme.md
											
										
										
											2016-10-25 06:09:45 +00:00
+								- A way for components to alter `<head>`: `<Head>` (by importing `next/head`)
-												Update Readme.md
											
										
										
											2016-10-24 19:59:46 +00:00
-												Update Readme.md
											
										
										
											2016-10-25 06:09:45 +00:00
+								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!
-												Update Readme.md
											
										
										
											2016-10-24 19:59:46 +00:00
 								</details>
 								<details>
-												Update README.md
											
										
										
											2016-12-22 05:30:06 +00:00
+								  <summary>How do I use CSS-in-JS solutions?</summary>
-												Update Readme.md
											
										
										
											2016-10-24 19:59:46 +00:00
-												Updated README with new features and code fixes (#444)

* Updated README with new features and code fixes

* Removed staticMarkup option from docs.

* Fixed quiet parameter info.

											
										
										
											2016-12-20 22:57:11 +00:00
+								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.
-												Update Readme.md
											
										
										
											2016-10-24 19:59:46 +00:00
+								</details>
 								<details>
 								  <summary>What syntactic features are transpiled? How do I change them?</summary>
 								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.
-												README: fix missing links

											
										
										
											2016-10-26 10:04:01 +00:00
+								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)
-												Update Readme.md
											
										
										
											2016-10-24 19:59:46 +00:00
 								</details>
 								<details>
 								  <summary>Why a new Router?</summary>
 								Next.js is special in that:
 								- Routes don’t need to be known ahead of time
-												README: grammer fix

											
										
										
											2016-10-26 09:47:41 +00:00
+								- Routes are always lazy-loadable
-												Update Readme.md
											
										
										
											2016-10-24 19:59:46 +00:00
+								- 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 `<Link />` component is used to wrap elements like anchors (`<a/>`) 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).
 								</details>
 								<details>
 								<summary>How do I define a custom fancy route?</summary>
-												Updated README with new features and code fixes (#444)

* Updated README with new features and code fixes

* Removed staticMarkup option from docs.

* Fixed quiet parameter info.

											
										
										
											2016-12-20 22:57:11 +00:00
+								We [added](#custom-server-and-routing) the ability to map between an arbitrary URL and any component by supplying a request handler.
-												Update Readme.md
											
										
										
											2016-10-24 19:59:46 +00:00
-												Updated README with new features and code fixes (#444)

* Updated README with new features and code fixes

* Removed staticMarkup option from docs.

* Fixed quiet parameter info.

											
										
										
											2016-12-20 22:57:11 +00:00
+								On the client side, we have a parameter call `as` on `<Link>` that _decorates_ the URL differently from the URL it _fetches_.
-												Update Readme.md
											
										
										
											2016-10-24 19:59:46 +00:00
+								</details>
 								<details>
 								<summary>How do I fetch data?</summary>
 								It’s up to you. `getInitialProps` is an `async` function (or a regular function that returns a `Promise`). It can retrieve data from anywhere.
 								</details>
-												Update Readme.md
											
										
										
											2016-10-25 10:34:14 +00:00
+								<details>
 								<summary>Can I use it with Redux?</summary>
-												Added missing readme and references in main readme. (#483)

* Added missing readme and references in main readme.

* Fixed wrong links

* Updated examples format

											
										
										
											2016-12-22 21:04:32 +00:00
+								Yes! Here's an [example](./examples/with-redux)
-												Update Readme.md
											
										
										
											2016-10-25 10:34:14 +00:00
+								</details>
-												Update Readme.md
											
										
										
											2016-10-24 19:59:46 +00:00
+								<details>
 								<summary>What is this inspired by?</summary>
 								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.
 								</details>
-												Update README.md
											
										
										
											2016-12-08 17:16:05 +00:00
+								## Roadmap
-												Update Readme.md
											
										
										
											2016-10-24 19:59:46 +00:00
-												Update README.md
											
										
										
											2016-12-08 17:16:05 +00:00
+								Our Roadmap towards 2.0.0 [is public](https://github.com/zeit/next.js/wiki/Roadmap#nextjs-200).
-												Update Readme.md
											
										
										
											2016-10-24 19:40:29 +00:00
 								## Authors
-												Added bundle size and % (#43)


											
										
										
											2016-10-25 10:32:03 +00:00
+								- Naoyuki Kanezawa ([@nkzawa](https://twitter.com/nkzawa)) – ▲ZEIT
-												Update Readme.md (#57)


											
										
										
											2016-10-25 18:42:57 +00:00
+								- Tony Kovanen ([@tonykovanen](https://twitter.com/tonykovanen)) – ▲ZEIT
-												Added bundle size and % (#43)


											
										
										
											2016-10-25 10:32:03 +00:00
+								- Guillermo Rauch ([@rauchg](https://twitter.com/rauchg)) – ▲ZEIT
-												Update Readme.md
											
										
										
											2016-10-24 19:40:29 +00:00
+								- Dan Zajdband ([@impronunciable](https://twitter.com/impronunciable)) – Knight-Mozilla / Coral Project