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.

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
<!-- https://github.com/thlorenz/doctoc -->

- [How to use](#how-to-use)
  - [Setup](#setup)
  - [Automatic code splitting](#automatic-code-splitting)
  - [CSS](#css)
    - [Built-in CSS support](#built-in-css-support)
    - [CSS-in-JS](#css-in-js)
  - [Static file serving (e.g.: images)](#static-file-serving-eg-images)
  - [Populating `<head>`](#populating-head)
  - [Fetching data and component lifecycle](#fetching-data-and-component-lifecycle)
  - [Routing](#routing)
    - [With `<Link>`](#with-link)
    - [Imperatively](#imperatively)
      - [Router Events](#router-events)
      - [Shallow Routing](#shallow-routing)
  - [Prefetching Pages](#prefetching-pages)
    - [With `<Link>`](#with-link-1)
    - [Imperatively](#imperatively-1)
  - [Custom server and routing](#custom-server-and-routing)
  - [Custom `<Document>`](#custom-document)
  - [Custom error handling](#custom-error-handling)
  - [Custom configuration](#custom-configuration)
  - [Customizing webpack config](#customizing-webpack-config)
  - [Customizing babel config](#customizing-babel-config)
- [Production deployment](#production-deployment)
- [FAQ](#faq)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [Authors](#authors)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## How to use

### Setup

Install it:

```bash
npm install next react react-dom --save
```

and add a script to your package.json like this:

```json
{
  "scripts": {
    "dev": "next",
    "build": "next build",
    "start": "next start"
  }
}
```

After that, the file-system is the main API. Every `.js` file becomes a route that gets automatically processed and rendered.

Populate `./pages/index.js` inside your project:

```jsx
export default () => (
  <div>Welcome to next.js!</div>
)
```

and then just run `npm run dev` and go to `http://localhost:3000`. To use another port, you can run `npm run dev -- -p <your port here>`.

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

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

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

<p><details>
  <summary>
    <b>Examples</b>
    </summary>
  <ul><li><a href="./examples/with-styled-components">Styled components</a></li><li><a href="./examples/with-styletron">Styletron</a></li><li><a href="./examples/with-glamor">Glamor</a></li><li><a href="./examples/with-cxs">Cxs</a></li><li><a href="./examples/with-aphrodite">Aphrodite</a></li><li><a href="./examples/with-fela">Fela</a></li></ul>
</details></p>

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

<p><details>
  <summary><b>Examples</b></summary>
  <ul>
    <li><a href="./examples/head-elements">Head elements</a></li>
    <li><a href="./examples/layout-component">Layout component</a></li>
  </ul>
</details></p>

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

<p><details>
  <summary><b>Examples</b></summary>
  <ul><li><a href="./examples/data-fetch">Data fetch</a></li></ul>
</details></p>

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.

_Note: `getInitialProps` can **not** be used in children components. Only in `pages`._

You can also define the `getInitialProps` lifecycle method for stateless components:

```jsx
const Page = ({ stars }) => <div>Next stars: {stars}</div>

Page.getInitialProps = async ({ req }) => {
  const res = await fetch('https://api.github.com/repos/zeit/next.js')
  const json = await res.json()
  return { stars: json.stargazers_count }
}

export default Page
```

`getInitialProps` receives a context object with the following properties:

- `pathname` - path section of URL
- `query` - query string section of URL parsed as an object
- `req` - HTTP request object (server only)
- `res` - HTTP response object (server only)
- `jsonPageRes` - [Fetch Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) object (client only)
- `err` - Error object if any error is encountered during the rendering

### Routing

#### With `<Link>`

<p><details>
  <summary><b>Examples</b></summary>
  <ul>
    <li><a href="./examples/hello-world">Hello World</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>
)
```

__Note: use [`<Link prefetch>`](#prefetching-pages) for maximum performance, to link and prefetch in the background at the same time__

Client-side routing behaves exactly like the browser:

1. The component is fetched
2. If it defines `getInitialProps`, data is fetched. If an error occurs, `_error.js` is rendered
3. After 1 and 2 complete, `pushState` is performed and the new component rendered

Each top-level component receives a `url` property with the following API:

- `pathname` - `String` of the current path excluding the query string
- `query` - `Object` with the parsed query string. Defaults to `{}`
- `push(url, as=url)` - performs a `pushState` call with the given url
- `replace(url, as=url)` - performs a `replaceState` call with the given url

The second `as` parameter for `push` and `replace` is an optional _decoration_ of the URL. Useful if you configured custom routes on the server.

##### With URL object

<p><details>
  <summary><b>Examples</b></summary>
  <ul>
    <li><a href="./examples/with-url-object-routing">With URL Object Routing</a></li>
  </ul>
</details></p>

The component `<Link>` can also receive an URL object and it will automatically format it to create the URL string.

```jsx
// pages/index.js
import Link from 'next/link'
export default () => (
  <div>Click <Link href={{ pathname: 'about', query: { name: 'Zeit' }}}<a>here</a></Link> to read more</div>
)
```

That will generate the URL string `/about?name=Zeit`, you can use every property as defined in the [Node.js URL module documentation](https://nodejs.org/api/url.html#url_url_strings_and_url_objects).

The default behaviour for the `<Link>` component is to `push` a new url into the stack. You can use the `replace` prop to prevent adding a new entry.

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

#### Imperatively

<p><details>
  <summary><b>Examples</b></summary>
  <ul>
    <li><a href="./examples/using-router">Basic routing</a></li>
    <li><a href="./examples/with-loading">With a page loading indicator</a></li>
  </ul>
</details></p>

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_

##### With URL object
You can use an URL object the same way you use it in a `<Link>` component to `push` and `replace` an url.

```jsx
import Router from 'next/router'

const handler = () => Router.push({
  pathname: 'about',
  query: { name: 'Zeit' }
})

export default () => (
  <div>Click <span onClick={handler}>here</span> to read more</div>
)
```

This uses of the same exact parameters as in the `<Link>` component.

##### Router Events

You can also listen to different events happening inside the Router.
Here's a list of supported events:

- `routeChangeStart(url)` - Fires when a route starts to change
- `routeChangeComplete(url)` - Fires when a route changed completely
- `routeChangeError(err, url)` - Fires when there's an error when changing routes
- `beforeHistoryChange(url)` - Fires just before changing the browser's history
- `appUpdated(nextRoute)` - Fires when switching pages and there's a new version of the app

> Here `url` is the URL shown in the browser. If you call `Router.push(url, as)` (or similar), then the value of `url` will be `as`.

Here's how to properly listen to the router event `routeChangeStart`:

```js
Router.onRouteChangeStart = (url) => {
  console.log('App is changing to: ', url)
}
```

If you are no longer want to listen to that event, you can simply unset the event listener like this:

```js
Router.onRouteChangeStart = null
```

If a route load is cancelled (for example by clicking two links rapidly in succession), `routeChangeError` will fire. The passed `err` will contained a `cancelled` property set to `true`.

```js
Router.onRouteChangeError = (err, url) => {
  if (err.cancelled) {
    console.log(`Route to ${url} was cancelled!`)
  }
}
```

If you change a route while in between a new deployment, we can't navigate the app via client side. We need to do a full browser navigation. We do it automatically for you.

But you can customize that via `Route.onAppUpdated` event like this:

```js
Router.onAppUpdated = (nextUrl) => {
  // persist the local state
  location.href = nextUrl
}
```

##### Shallow Routing

<p><details>
  <summary><b>Examples</b></summary>
  <ul>
    <li><a href="./examples/with-shallow-routing">Shallow Routing</a></li>
  </ul>
</details></p>

Shallow routing allows you to change the URL without running `getInitialProps`. You'll receive the updated `pathname` and the `query` via the `url` prop of the same page that's loaded, without losing state.

You can do this by invoking the eith `Router.push` or `Router.replace` with `shallow: true` option. Here's an example:

```jsx
// Current URL is "/"
const href = '/?counter=10'
const as = href
Router.push(href, as, { shallow: true })
```

Now, the URL is updated to `/?counter=10`. You can see the updated URL with `this.props.url` inside the `Component`.

You can watch for URL changes via [`componentWillReceiveProps`](https://facebook.github.io/react/docs/react-component.html#componentwillreceiveprops) hook as shown below:

```jsx
componentWillReceiveProps(nextProps) {
  const { pathname, query } = nextProps.url
  // fetch data based on the new query
}
```

> NOTES:
>
> Shallow routing works **only** for same page URL changes. For an example, let's assume we've another page called `about`, and you run this:
> ```js
> Router.push('/about?counter=10', '/about?counter=10', { shallow: true })
> ```
> Since that's a new page, it'll unload the current page, load the new one and call `getInitialProps` even we asked to do shallow routing.

### Prefetching Pages

(This is a production only feature)

<p><details>
  <summary><b>Examples</b></summary>
  <ul><li><a href="./examples/with-prefetching">Prefetching</a></li></ul>
</details></p>

Next.js has an API which allows you to prefetch pages.

Since Next.js server-renders your pages, this allows all the future interaction paths of your app to be instant. Effectively Next.js gives you the great initial download performance of a _website_, with the ahead-of-time download capabilities of an _app_. [Read more](https://zeit.co/blog/next#anticipation-is-the-key-to-performance).

> With prefetching Next.js only download JS code. When the page is getting rendered, you may need to wait for the data.

#### With `<Link>`

You can add `prefetch` prop to any `<Link>` and Next.js will prefetch those pages in the background.

```jsx
import Link from 'next/link'

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

#### Imperatively

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

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

### Custom server and routing

<p><details>
  <summary><b>Examples</b></summary>
  <ul>
    <li><a href="./examples/custom-server">Basic custom server</a></li>
    <li><a href="./examples/custom-server-express">Express integration</a></li>
    <li><a href="./examples/custom-server-hapi">Hapi integration</a></li>
    <li><a href="./examples/custom-server-koa">Koa integration</a></li>
    <li><a href="./examples/parameterized-routing">Parameterized routing</a></li>
    <li><a href="./examples/ssr-caching">SSR caching</a></li>
  </ul>
</details></p>

Typically you start your next server with `next start`. It's possible, however, to start a server 100% programmatically in order to customize routes, use route patterns, etc

This example makes `/a` resolve to `./pages/b`, and `/b` resolve to `./pages/a`:

```js
const { createServer } = require('http')
const { parse } = require('url')
const next = require('next')

const dev = process.env.NODE_ENV !== 'production'
const app = next({ dev })
const handle = app.getRequestHandler()

app.prepare().then(() => {
  createServer((req, res) => {
    // Be sure to pass `true` as the second argument to `url.parse`.
    // This tells it to parse the query portion of the URL.
    const parsedUrl = parse(req.url, true)
    const { pathname, query } = parsedUrl

    if (pathname === '/a') {
      app.render(req, res, '/b', query)
    } else if (pathname === '/b') {
      app.render(req, res, '/a', query)
    } else {
      handle(req, res, parsedUrl)
    }
  })
  .listen(3000, (err) => {
    if (err) throw err
    console.log('> Ready on http://localhost:3000')
  })
})
```

The `next` API is as follows:
- `next(path: string, opts: object)` - `path` is where the Next project is located
- `next(opts: object)`

Supported options:
- `dev` (`bool`) whether to launch Next.js in dev mode - default `false`
- `dir` (`string`) where the Next project is located - default `'.'`
- `quiet` (`bool`) Hide error messages containing server information - default `false`

Then, change your `start` script to `NODE_ENV=production node server.js`.

### Custom `<Document>`

<p><details>
  <summary><b>Examples</b></summary>
  <ul><li><a href="./examples/with-styled-components">Styled components custom document</a></li></ul>
  <ul><li><a href="./examples/with-amp">Google AMP</a></li></ul>
</details></p>

Pages in `Next.js` skip the definition of the surrounding document's markup. For example, you never include `<html>`, `<body>`, etc. To override that default behavior, you must create a file at `./pages/_document.js`, where you can extend the `Document` class:

```jsx
// ./pages/_document.js
import Document, { Head, Main, NextScript } from 'next/document'
import flush from 'styled-jsx/server'

export default class MyDocument extends Document {
  static getInitialProps ({ renderPage }) {
    const {html, head} = renderPage()
    const styles = flush()
    return { html, head, styles }
  }

  render () {
    return (
     <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, jsonPageRes }) {
    const statusCode = res ? res.statusCode : (jsonPageRes ? jsonPageRes.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

For custom advanced behavior of Next.js, you can create a `next.config.js` in the root of your project directory (next to `pages/` and `package.json`).

Note: `next.config.js` is a regular Node.js module, not a JSON file. It gets used by the Next server and build phases, and not included in the browser build.

```javascript
// next.config.js
module.exports = {
  /* config options here */
}
```

### Customizing webpack config

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

```js
// This file is not going through babel transformation.
// So, we write it in vanilla JS
// (But you could use ES2015 features supported by your Node.js version)

module.exports = {
  webpack: (config, { dev }) => {
    // Perform customizations to config
    
    // Important: return the modified config
    return config
  }
}
```

*Warning: Adding loaders to support new file types (css, less, svg, etc.) is __not__ recommended because only the client code gets bundled via webpack and thus it won't work on the initial server rendering. Babel plugins are a good alternative because they're applied consistently between server/client rendering (e.g. [babel-plugin-inline-react-svg](https://github.com/kesne/babel-plugin-inline-react-svg)).*

### Customizing babel config

<p><details>
  <summary><b>Examples</b></summary>
  <ul><li><a href="./examples/with-custom-babel-config">Custom babel configuration</a></li></ul>
</details></p>

In order to extend our usage of `babel`, you can simply define a `.babelrc` file at the root of your app. This file is optional.

If found, we're going to consider it the *source of truth*, therefore it needs to define what next needs as well, which is the `next/babel` preset.

This is designed so that you are not surprised by modifications we could make to the babel configurations.

Here's an example `.babelrc` file:

```js
{
  "presets": [
    "next/babel",
    "stage-0"
  ],
}
```

## Production deployment

To deploy, instead of running `next`, you 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: 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: `<Link>` (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 GraphQL?</summary>

Yes! Here's an example with [Apollo](./examples/with-apollo).

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

## Contributing

Please see our [contributing.md](./contributing.md)

## Authors

- Naoyuki Kanezawa ([@nkzawa](https://twitter.com/nkzawa)) – ▲ZEIT
- Tony Kovanen ([@tonykovanen](https://twitter.com/tonykovanen)) – ▲ZEIT
- Guillermo Rauch ([@rauchg](https://twitter.com/rauchg)) – ▲ZEIT
- Dan Zajdband ([@impronunciable](https://twitter.com/impronunciable)) – Knight-Mozilla / Coral Project
- Tim Neutkens ([@timneutkens](https://github.com/timneutkens))
-												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
-												Add table of contents to README (#735)

* Fix example README formatting

* Add table of contents to README

											
										
										
											2017-02-09 11:47:20 +00:00
+								<!-- START doctoc generated TOC please keep comment here to allow auto update -->
 								<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 								<!-- https://github.com/thlorenz/doctoc -->
 								- [How to use](#how-to-use)
 								  - [Setup](#setup)
 								  - [Automatic code splitting](#automatic-code-splitting)
 								  - [CSS](#css)
 								    - [Built-in CSS support](#built-in-css-support)
 								    - [CSS-in-JS](#css-in-js)
 								  - [Static file serving (e.g.: images)](#static-file-serving-eg-images)
 								  - [Populating `<head>`](#populating-head)
 								  - [Fetching data and component lifecycle](#fetching-data-and-component-lifecycle)
 								  - [Routing](#routing)
 								    - [With `<Link>`](#with-link)
 								    - [Imperatively](#imperatively)
 								      - [Router Events](#router-events)
-												Introducing Shallow Routing (#1357)

* Simplify route info handling.

* Add basic resolve=false support.

* Make sure to render getInitialProps always if it's the first render.

* Change resolve=false to shallow routing.

* Add test cases for shallow routing.

* Update README for shallow routing docs.

* Update docs.

* Update docs.

* Update docs.

											
										
										
											2017-03-06 16:48:35 +00:00
+								      - [Shallow Routing](#shallow-routing)
-												Add table of contents to README (#735)

* Fix example README formatting

* Add table of contents to README

											
										
										
											2017-02-09 11:47:20 +00:00
+								  - [Prefetching Pages](#prefetching-pages)
 								    - [With `<Link>`](#with-link-1)
 								    - [Imperatively](#imperatively-1)
 								  - [Custom server and routing](#custom-server-and-routing)
 								  - [Custom `<Document>`](#custom-document)
 								  - [Custom error handling](#custom-error-handling)
 								  - [Custom configuration](#custom-configuration)
 								  - [Customizing webpack config](#customizing-webpack-config)
 								  - [Customizing babel config](#customizing-babel-config)
 								- [Production deployment](#production-deployment)
 								- [FAQ](#faq)
 								- [Roadmap](#roadmap)
-												Update table of contents (#1051)


											
										
										
											2017-02-09 11:52:14 +00:00
+								- [Contributing](#contributing)
-												Add table of contents to README (#735)

* Fix example README formatting

* Add table of contents to README

											
										
										
											2017-02-09 11:47:20 +00:00
+								- [Authors](#authors)
 								<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-												warn about master README
											
										
										
											2016-12-16 20:22:55 +00:00
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
+								## How to use
-												Add table of contents to README (#735)

* Fix example README formatting

* Add table of contents to README

											
										
										
											2017-02-09 11:47:20 +00:00
+								### Setup
-												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
-												Install peerDependencies in readme (#1116)


											
										
										
											2017-02-14 01:52:31 +00:00
+								npm install next react react-dom --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": {
-												Add `next build` and `next start` to the first How to use sample (#894)


											
										
										
											2017-01-26 17:00:55 +00:00
+								    "dev": "next",
 								    "build": "next build",
 								    "start": "next start"
-												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: show how to `npm run dev` on another port. (#1544)


											
										
										
											2017-03-28 20:27:21 +00:00
+								and then just run `npm run dev` and go to `http://localhost:3000`. To use another port, you can run `npm run dev -- -p <your port here>`.
-												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
-												Update README.md (#499)


											
										
										
											2016-12-24 01:36:34 +00:00
+								<p><details>
-												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
+								  <summary><b>Examples</b></summary>
-												Update README.md (#499)


											
										
										
											2016-12-24 01:36:34 +00:00
+								  <ul><li><a href="./examples/basic-css">Basic css</a></li></ul>
 								</details></p>
-												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
-												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
-												Add styletron example (#486)

* add styletron example

* example: fix link

* example: improve README

* Added styletron example reference to readme and merge with master

											
										
										
											2016-12-23 13:01:24 +00:00
+								<p><details>
-												Added Fela Example to the CSS-in-JS <details> in README (#878)


											
										
										
											2017-01-25 12:13:34 +00:00
+								  <summary>
 								    <b>Examples</b>
 								    </summary>
 								  <ul><li><a href="./examples/with-styled-components">Styled components</a></li><li><a href="./examples/with-styletron">Styletron</a></li><li><a href="./examples/with-glamor">Glamor</a></li><li><a href="./examples/with-cxs">Cxs</a></li><li><a href="./examples/with-aphrodite">Aphrodite</a></li><li><a href="./examples/with-fela">Fela</a></li></ul>
-												Add styletron example (#486)

* add styletron example

* example: fix link

* example: improve README

* Added styletron example reference to readme and merge with master

											
										
										
											2016-12-23 13:01:24 +00:00
+								</details></p>
-												Update README.md
											
										
										
											2016-12-19 19:20:18 +00:00
+								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
-												Update README.md (#499)


											
										
										
											2016-12-24 01:36:34 +00:00
+								<p><details>
-												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
+								  <summary><b>Examples</b></summary>
-												Added layout component example (#560)

* added layout component example

* coding style fixes

* trailing spaces removed

* updated README file

* added layout example in docs

* moved .babelrc so that it handles all projects from the examples folder

											
										
										
											2017-01-05 21:03:36 +00:00
+								  <ul>
 								    <li><a href="./examples/head-elements">Head elements</a></li>
 								    <li><a href="./examples/layout-component">Layout component</a></li>
 								  </ul>
-												Update README.md (#499)


											
										
										
											2016-12-24 01:36:34 +00:00
+								</details></p>
-												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
-												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
-												Add/data fetch example (#485)

* Added data fetch example

* Finished updating examples install instructions and added data-fetch example to main readme

											
										
										
											2016-12-22 23:05:49 +00:00
+								<p><details>
 								  <summary><b>Examples</b></summary>
 								  <ul><li><a href="./examples/data-fetch">Data fetch</a></li></ul>
 								</details></p>
-												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
-												Add notice about getInitialProps (#1140)

* Add notice about getInitialProps

* Remove extra whitespace

											
										
										
											2017-02-15 02:58:13 +00:00
+								_Note: `getInitialProps` can **not** be used in children components. Only in `pages`._
-												Add/readme example stateless lifecycle (#1558)

* Using developit/unfetch as the Fetch API polyfill

* Added a stateless component with getInitialProps in the readme.

* Fixed typo

											
										
										
											2017-03-29 22:11:18 +00:00
+								You can also define the `getInitialProps` lifecycle method for stateless components:
 								```jsx
 								const Page = ({ stars }) => <div>Next stars: {stars}</div>
 								Page.getInitialProps = async ({ req }) => {
 								  const res = await fetch('https://api.github.com/repos/zeit/next.js')
 								  const json = await res.json()
 								  return { stars: json.stargazers_count }
 								}
 								export default Page
 								```
-												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)
-												Use jsonPageRes instead of xhr (#1424)


											
										
										
											2017-03-15 02:37:29 +00:00
+								- `jsonPageRes` - [Fetch Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) object (client only)
-												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
+								- `err` - Error object if any error is encountered during the rendering
-												Update README.md
											
										
										
											2016-12-19 15:16:44 +00:00
+								### Routing
-												Implement Router Events (#511)

* Move route loading logic to a common place.

* Add router events.

* Add EventEmitter's core API methods.

* Add example app for loading events and docs.

* Fix some typos.

* Get rid of Router.ready()

* Remove events package.
It's already shipping with webpack.

* Handling aborting properly.

* Expose simple attribute based events listener API.
Removed the proposed event listener API from the public API.

* Remove error logged when there's an abort error.
There are many other ways to capture this error.
So, it doesn't look nice to print this always.

* Change router events to pass only the current URL as arguments.

* Add a section about Cancelled Routes to README.

											
										
										
											2016-12-31 01:15:22 +00:00
+								#### With `<Link>`
-												Update README.md
											
										
										
											2016-12-22 21:08:58 +00:00
+								<p><details>
 								  <summary><b>Examples</b></summary>
-												Implement Router Events (#511)

* Move route loading logic to a common place.

* Add router events.

* Add EventEmitter's core API methods.

* Add example app for loading events and docs.

* Fix some typos.

* Get rid of Router.ready()

* Remove events package.
It's already shipping with webpack.

* Handling aborting properly.

* Expose simple attribute based events listener API.
Removed the proposed event listener API from the public API.

* Remove error logged when there's an abort error.
There are many other ways to capture this error.
So, it doesn't look nice to print this always.

* Change router events to pass only the current URL as arguments.

* Add a section about Cancelled Routes to README.

											
										
										
											2016-12-31 01:15:22 +00:00
+								  <ul>
 								    <li><a href="./examples/hello-world">Hello World</a></li>
 								  </ul>
-												Update README.md
											
										
										
											2016-12-22 21:08:58 +00:00
+								</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>
 								)
 								```
-												Rename next/prefetch to <Next prefetch> in docs (#1206)


											
										
										
											2017-02-19 14:56:33 +00:00
+								__Note: use [`<Link prefetch>`](#prefetching-pages) for maximum performance, to link and prefetch in the background at the same time__
-												Update README.md
											
										
										
											2016-12-26 23:14:27 +00:00
-												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.
-												Add support for URL objects in Link and Router (#1345)

* Add support for URL objects in Link and Router

* Fix typo in comment

* Fix possible bug if the `href` prop is `null`

* Document the usage of URL objects in Link and Router

* Update readme.md

* Parse URL to get the host & hostname in `isLocal`

This should check if the current location and the checked URL have the same `host` or `hostname`.

* Format `as` parameter from object to string if required

* Format `href` and `as` inside the construct and componentWillReceiveProps

* Use `JSON.stringify` to compare objects

* Add usage example

* chore(package): update chromedriver to version 2.28.0 (#1386)

https://greenkeeper.io/

* Refactor the codebase a bit.

* Change the example name.

* Add a few test cases.

* Add the example to the README.

											
										
										
											2017-03-12 03:57:51 +00:00
+								##### With URL object
 								<p><details>
 								  <summary><b>Examples</b></summary>
 								  <ul>
 								    <li><a href="./examples/with-url-object-routing">With URL Object Routing</a></li>
 								  </ul>
 								</details></p>
 								The component `<Link>` can also receive an URL object and it will automatically format it to create the URL string.
 								```jsx
 								// pages/index.js
 								import Link from 'next/link'
 								export default () => (
 								  <div>Click <Link href={{ pathname: 'about', query: { name: 'Zeit' }}}<a>here</a></Link> to read more</div>
 								)
 								```
 								That will generate the URL string `/about?name=Zeit`, you can use every property as defined in the [Node.js URL module documentation](https://nodejs.org/api/url.html#url_url_strings_and_url_objects).
-												Add/link replace (#1419)

* Using developit/unfetch as the Fetch API polyfill

* Added the replace prop into the Link component

* Added integration test for replace prop on Link component

											
										
										
											2017-03-14 23:06:34 +00:00
+								The default behaviour for the `<Link>` component is to `push` a new url into the stack. You can use the `replace` prop to prevent adding a new entry.
 								```jsx
 								// pages/index.js
 								import Link from 'next/link'
 								export default () => (
 								  <div>Click <Link href='/about' replace><a>here</a></Link> to read more</div>
 								)
 								```
-												Add deprecate messages for url.replaceTo and url.pushTo (#433)


											
										
										
											2016-12-19 18:49:15 +00:00
+								#### 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
-												Implement Router Events (#511)

* Move route loading logic to a common place.

* Add router events.

* Add EventEmitter's core API methods.

* Add example app for loading events and docs.

* Fix some typos.

* Get rid of Router.ready()

* Remove events package.
It's already shipping with webpack.

* Handling aborting properly.

* Expose simple attribute based events listener API.
Removed the proposed event listener API from the public API.

* Remove error logged when there's an abort error.
There are many other ways to capture this error.
So, it doesn't look nice to print this always.

* Change router events to pass only the current URL as arguments.

* Add a section about Cancelled Routes to README.

											
										
										
											2016-12-31 01:15:22 +00:00
+								<p><details>
 								  <summary><b>Examples</b></summary>
 								  <ul>
 								    <li><a href="./examples/using-router">Basic routing</a></li>
 								    <li><a href="./examples/with-loading">With a page loading indicator</a></li>
 								  </ul>
 								</details></p>
-												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
-												Add support for URL objects in Link and Router (#1345)

* Add support for URL objects in Link and Router

* Fix typo in comment

* Fix possible bug if the `href` prop is `null`

* Document the usage of URL objects in Link and Router

* Update readme.md

* Parse URL to get the host & hostname in `isLocal`

This should check if the current location and the checked URL have the same `host` or `hostname`.

* Format `as` parameter from object to string if required

* Format `href` and `as` inside the construct and componentWillReceiveProps

* Use `JSON.stringify` to compare objects

* Add usage example

* chore(package): update chromedriver to version 2.28.0 (#1386)

https://greenkeeper.io/

* Refactor the codebase a bit.

* Change the example name.

* Add a few test cases.

* Add the example to the README.

											
										
										
											2017-03-12 03:57:51 +00:00
+								##### With URL object
 								You can use an URL object the same way you use it in a `<Link>` component to `push` and `replace` an url.
 								```jsx
 								import Router from 'next/router'
 								const handler = () => Router.push({
 								  pathname: 'about',
 								  query: { name: 'Zeit' }
 								})
 								export default () => (
 								  <div>Click <span onClick={handler}>here</span> to read more</div>
 								)
 								```
 								This uses of the same exact parameters as in the `<Link>` component.
-												Implement Router Events (#511)

* Move route loading logic to a common place.

* Add router events.

* Add EventEmitter's core API methods.

* Add example app for loading events and docs.

* Fix some typos.

* Get rid of Router.ready()

* Remove events package.
It's already shipping with webpack.

* Handling aborting properly.

* Expose simple attribute based events listener API.
Removed the proposed event listener API from the public API.

* Remove error logged when there's an abort error.
There are many other ways to capture this error.
So, it doesn't look nice to print this always.

* Change router events to pass only the current URL as arguments.

* Add a section about Cancelled Routes to README.

											
										
										
											2016-12-31 01:15:22 +00:00
+								##### Router Events
 								You can also listen to different events happening inside the Router.
 								Here's a list of supported events:
 								- `routeChangeStart(url)` - Fires when a route starts to change
 								- `routeChangeComplete(url)` - Fires when a route changed completely
 								- `routeChangeError(err, url)` - Fires when there's an error when changing routes
-												Add beforeHistoryChange router event. (#1360)


											
										
										
											2017-03-08 16:30:47 +00:00
+								- `beforeHistoryChange(url)` - Fires just before changing the browser's history
-												Handle BUILD_ID mismatch error (#1224)

* Reload the page if the buildIds are mismatch.

* Reload the browser with main.js and commons.js buildId mismatch.

* Implement proper reloading with an API to persist the state.

* Add some tests for force reload.

* Change _reload to _forceReload.

* Add a section about reload hooks to the README.

* Allow to add a hook to handle BUILD_ID mismatch.

* Remove readme docs.

* Do not show a custom error to the user.

* Cancel the routing when there's a BUILD_ID mismatch.

* Fix a typo.

* Passing route to SingletonRouter.onBuildIdMismatch

* Handle buildId mismatch automatically.

											
										
										
											2017-02-20 23:48:17 +00:00
+								- `appUpdated(nextRoute)` - Fires when switching pages and there's a new version of the app
-												Implement Router Events (#511)

* Move route loading logic to a common place.

* Add router events.

* Add EventEmitter's core API methods.

* Add example app for loading events and docs.

* Fix some typos.

* Get rid of Router.ready()

* Remove events package.
It's already shipping with webpack.

* Handling aborting properly.

* Expose simple attribute based events listener API.
Removed the proposed event listener API from the public API.

* Remove error logged when there's an abort error.
There are many other ways to capture this error.
So, it doesn't look nice to print this always.

* Change router events to pass only the current URL as arguments.

* Add a section about Cancelled Routes to README.

											
										
										
											2016-12-31 01:15:22 +00:00
 								> Here `url` is the URL shown in the browser. If you call `Router.push(url, as)` (or similar), then the value of `url` will be `as`.
-												Fix typo in README (#787)


											
										
										
											2017-01-16 10:41:46 +00:00
+								Here's how to properly listen to the router event `routeChangeStart`:
-												Implement Router Events (#511)

* Move route loading logic to a common place.

* Add router events.

* Add EventEmitter's core API methods.

* Add example app for loading events and docs.

* Fix some typos.

* Get rid of Router.ready()

* Remove events package.
It's already shipping with webpack.

* Handling aborting properly.

* Expose simple attribute based events listener API.
Removed the proposed event listener API from the public API.

* Remove error logged when there's an abort error.
There are many other ways to capture this error.
So, it doesn't look nice to print this always.

* Change router events to pass only the current URL as arguments.

* Add a section about Cancelled Routes to README.

											
										
										
											2016-12-31 01:15:22 +00:00
 								```js
 								Router.onRouteChangeStart = (url) => {
 								  console.log('App is changing to: ', url)
 								}
 								```
 								If you are no longer want to listen to that event, you can simply unset the event listener like this:
 								```js
 								Router.onRouteChangeStart = null
 								```
-												Update README.md
											
										
										
											2016-12-31 01:37:06 +00:00
+								If a route load is cancelled (for example by clicking two links rapidly in succession), `routeChangeError` will fire. The passed `err` will contained a `cancelled` property set to `true`.
-												Implement Router Events (#511)

* Move route loading logic to a common place.

* Add router events.

* Add EventEmitter's core API methods.

* Add example app for loading events and docs.

* Fix some typos.

* Get rid of Router.ready()

* Remove events package.
It's already shipping with webpack.

* Handling aborting properly.

* Expose simple attribute based events listener API.
Removed the proposed event listener API from the public API.

* Remove error logged when there's an abort error.
There are many other ways to capture this error.
So, it doesn't look nice to print this always.

* Change router events to pass only the current URL as arguments.

* Add a section about Cancelled Routes to README.

											
										
										
											2016-12-31 01:15:22 +00:00
 								```js
 								Router.onRouteChangeError = (err, url) => {
 								  if (err.cancelled) {
-												Update README.md
											
										
										
											2016-12-31 01:37:06 +00:00
+								    console.log(`Route to ${url} was cancelled!`)
-												Implement Router Events (#511)

* Move route loading logic to a common place.

* Add router events.

* Add EventEmitter's core API methods.

* Add example app for loading events and docs.

* Fix some typos.

* Get rid of Router.ready()

* Remove events package.
It's already shipping with webpack.

* Handling aborting properly.

* Expose simple attribute based events listener API.
Removed the proposed event listener API from the public API.

* Remove error logged when there's an abort error.
There are many other ways to capture this error.
So, it doesn't look nice to print this always.

* Change router events to pass only the current URL as arguments.

* Add a section about Cancelled Routes to README.

											
										
										
											2016-12-31 01:15:22 +00:00
+								  }
 								}
 								```
-												Handle BUILD_ID mismatch error (#1224)

* Reload the page if the buildIds are mismatch.

* Reload the browser with main.js and commons.js buildId mismatch.

* Implement proper reloading with an API to persist the state.

* Add some tests for force reload.

* Change _reload to _forceReload.

* Add a section about reload hooks to the README.

* Allow to add a hook to handle BUILD_ID mismatch.

* Remove readme docs.

* Do not show a custom error to the user.

* Cancel the routing when there's a BUILD_ID mismatch.

* Fix a typo.

* Passing route to SingletonRouter.onBuildIdMismatch

* Handle buildId mismatch automatically.

											
										
										
											2017-02-20 23:48:17 +00:00
+								If you change a route while in between a new deployment, we can't navigate the app via client side. We need to do a full browser navigation. We do it automatically for you.
 								But you can customize that via `Route.onAppUpdated` event like this:
 								```js
 								Router.onAppUpdated = (nextUrl) => {
 								  // persist the local state
 								  location.href = nextUrl
 								}
 								```
-												Introducing Shallow Routing (#1357)

* Simplify route info handling.

* Add basic resolve=false support.

* Make sure to render getInitialProps always if it's the first render.

* Change resolve=false to shallow routing.

* Add test cases for shallow routing.

* Update README for shallow routing docs.

* Update docs.

* Update docs.

* Update docs.

											
										
										
											2017-03-06 16:48:35 +00:00
+								##### Shallow Routing
 								<p><details>
 								  <summary><b>Examples</b></summary>
 								  <ul>
 								    <li><a href="./examples/with-shallow-routing">Shallow Routing</a></li>
 								  </ul>
 								</details></p>
-												Fix typo in README (#1427)

`routing`not `routig`
											
										
										
											2017-03-15 12:24:34 +00:00
+								Shallow routing allows you to change the URL without running `getInitialProps`. You'll receive the updated `pathname` and the `query` via the `url` prop of the same page that's loaded, without losing state.
-												Introducing Shallow Routing (#1357)

* Simplify route info handling.

* Add basic resolve=false support.

* Make sure to render getInitialProps always if it's the first render.

* Change resolve=false to shallow routing.

* Add test cases for shallow routing.

* Update README for shallow routing docs.

* Update docs.

* Update docs.

* Update docs.

											
										
										
											2017-03-06 16:48:35 +00:00
 								You can do this by invoking the eith `Router.push` or `Router.replace` with `shallow: true` option. Here's an example:
-												Update readme.md
											
										
										
											2017-03-06 16:51:19 +00:00
+								```jsx
-												Introducing Shallow Routing (#1357)

* Simplify route info handling.

* Add basic resolve=false support.

* Make sure to render getInitialProps always if it's the first render.

* Change resolve=false to shallow routing.

* Add test cases for shallow routing.

* Update README for shallow routing docs.

* Update docs.

* Update docs.

* Update docs.

											
										
										
											2017-03-06 16:48:35 +00:00
+								// Current URL is "/"
 								const href = '/?counter=10'
 								const as = href
 								Router.push(href, as, { shallow: true })
 								```
-												Update readme.md
											
										
										
											2017-03-06 16:51:19 +00:00
+								Now, the URL is updated to `/?counter=10`. You can see the updated URL with `this.props.url` inside the `Component`.
-												Introducing Shallow Routing (#1357)

* Simplify route info handling.

* Add basic resolve=false support.

* Make sure to render getInitialProps always if it's the first render.

* Change resolve=false to shallow routing.

* Add test cases for shallow routing.

* Update README for shallow routing docs.

* Update docs.

* Update docs.

* Update docs.

											
										
										
											2017-03-06 16:48:35 +00:00
-												Update readme.md
											
										
										
											2017-03-06 16:51:19 +00:00
+								You can watch for URL changes via [`componentWillReceiveProps`](https://facebook.github.io/react/docs/react-component.html#componentwillreceiveprops) hook as shown below:
-												Introducing Shallow Routing (#1357)

* Simplify route info handling.

* Add basic resolve=false support.

* Make sure to render getInitialProps always if it's the first render.

* Change resolve=false to shallow routing.

* Add test cases for shallow routing.

* Update README for shallow routing docs.

* Update docs.

* Update docs.

* Update docs.

											
										
										
											2017-03-06 16:48:35 +00:00
-												Update readme.md
											
										
										
											2017-03-06 16:51:19 +00:00
+								```jsx
-												Introducing Shallow Routing (#1357)

* Simplify route info handling.

* Add basic resolve=false support.

* Make sure to render getInitialProps always if it's the first render.

* Change resolve=false to shallow routing.

* Add test cases for shallow routing.

* Update README for shallow routing docs.

* Update docs.

* Update docs.

* Update docs.

											
										
										
											2017-03-06 16:48:35 +00:00
+								componentWillReceiveProps(nextProps) {
 								  const { pathname, query } = nextProps.url
 								  // fetch data based on the new query
 								}
 								```
 								> NOTES:
-												Add reference to deployment wiki page (#1423)


											
										
										
											2017-03-15 02:38:00 +00:00
+								>
-												Update readme.md
											
										
										
											2017-03-06 16:51:19 +00:00
+								> Shallow routing works **only** for same page URL changes. For an example, let's assume we've another page called `about`, and you run this:
-												Introducing Shallow Routing (#1357)

* Simplify route info handling.

* Add basic resolve=false support.

* Make sure to render getInitialProps always if it's the first render.

* Change resolve=false to shallow routing.

* Add test cases for shallow routing.

* Update README for shallow routing docs.

* Update docs.

* Update docs.

* Update docs.

											
										
										
											2017-03-06 16:48:35 +00:00
+								> ```js
 								> Router.push('/about?counter=10', '/about?counter=10', { shallow: true })
 								> ```
-												Update readme.md
											
										
										
											2017-03-06 16:51:19 +00:00
+								> Since that's a new page, it'll unload the current page, load the new one and call `getInitialProps` even we asked to do shallow routing.
-												Introducing Shallow Routing (#1357)

* Simplify route info handling.

* Add basic resolve=false support.

* Make sure to render getInitialProps always if it's the first render.

* Change resolve=false to shallow routing.

* Add test cases for shallow routing.

* Update README for shallow routing docs.

* Update docs.

* Update docs.

* Update docs.

											
										
										
											2017-03-06 16:48:35 +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
-												Update prefetch docs and mention it's production only. (#1324)


											
										
										
											2017-03-01 16:54:41 +00:00
+								(This is a production only feature)
-												Add/data fetch example (#485)

* Added data fetch example

* Finished updating examples install instructions and added data-fetch example to main readme

											
										
										
											2016-12-22 23:05:49 +00:00
+								<p><details>
-												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
+								  <summary><b>Examples</b></summary>
-												Add/data fetch example (#485)

* Added data fetch example

* Finished updating examples install instructions and added data-fetch example to main readme

											
										
										
											2016-12-22 23:05:49 +00:00
+								  <ul><li><a href="./examples/with-prefetching">Prefetching</a></li></ul>
 								</details></p>
-												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
-												Introduce a simple prefetching solution (#957)

* Implement a very simple prefetching solution.

* Remove next-prefetcher.

* Require 'whatwg-fetch' only in the client.

* Use xhr in the code.

* Use a simple fetching solution.

* Fix 404 and xhr status issue.

* Move the prefetching implementation to next/router.

* Add deprecated warnning for next/prefetch

* Run only 2 parellel prefetching request at a time.

* Change xhr to jsonPageRes.

* Improve the prefetching logic.

* Add unit tests covering the Router.prefetch()

* Update examples to use the new syntax.

* Update docs.

* Use execOnce() to manage warn printing.

* Remove prefetcher building from the flyfile.js
Because, we no longer use it.

											
										
										
											2017-02-15 08:52:22 +00:00
+								Next.js has an API which allows you to prefetch pages.
-												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
-												Introduce a simple prefetching solution (#957)

* Implement a very simple prefetching solution.

* Remove next-prefetcher.

* Require 'whatwg-fetch' only in the client.

* Use xhr in the code.

* Use a simple fetching solution.

* Fix 404 and xhr status issue.

* Move the prefetching implementation to next/router.

* Add deprecated warnning for next/prefetch

* Run only 2 parellel prefetching request at a time.

* Change xhr to jsonPageRes.

* Improve the prefetching logic.

* Add unit tests covering the Router.prefetch()

* Update examples to use the new syntax.

* Update docs.

* Use execOnce() to manage warn printing.

* Remove prefetcher building from the flyfile.js
Because, we no longer use it.

											
										
										
											2017-02-15 08:52:22 +00:00
+								> With prefetching Next.js only download JS code. When the page is getting rendered, you may need to wait for the data.
-												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
-												Introduce a simple prefetching solution (#957)

* Implement a very simple prefetching solution.

* Remove next-prefetcher.

* Require 'whatwg-fetch' only in the client.

* Use xhr in the code.

* Use a simple fetching solution.

* Fix 404 and xhr status issue.

* Move the prefetching implementation to next/router.

* Add deprecated warnning for next/prefetch

* Run only 2 parellel prefetching request at a time.

* Change xhr to jsonPageRes.

* Improve the prefetching logic.

* Add unit tests covering the Router.prefetch()

* Update examples to use the new syntax.

* Update docs.

* Use execOnce() to manage warn printing.

* Remove prefetcher building from the flyfile.js
Because, we no longer use it.

											
										
										
											2017-02-15 08:52:22 +00:00
+								You can add `prefetch` prop to any `<Link>` and Next.js will prefetch those pages in the background.
-												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
-												Introduce a simple prefetching solution (#957)

* Implement a very simple prefetching solution.

* Remove next-prefetcher.

* Require 'whatwg-fetch' only in the client.

* Use xhr in the code.

* Use a simple fetching solution.

* Fix 404 and xhr status issue.

* Move the prefetching implementation to next/router.

* Add deprecated warnning for next/prefetch

* Run only 2 parellel prefetching request at a time.

* Change xhr to jsonPageRes.

* Improve the prefetching logic.

* Add unit tests covering the Router.prefetch()

* Update examples to use the new syntax.

* Update docs.

* Use execOnce() to manage warn printing.

* Remove prefetcher building from the flyfile.js
Because, we no longer use it.

											
										
										
											2017-02-15 08:52:22 +00:00
+								import Link from 'next/link'
-												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>
-												Fix typo in a href example (#1168)


											
										
										
											2017-02-16 00:35:25 +00:00
+								      <li><Link prefetch href='/'><a>Home</a></Link></li>
-												Introduce a simple prefetching solution (#957)

* Implement a very simple prefetching solution.

* Remove next-prefetcher.

* Require 'whatwg-fetch' only in the client.

* Use xhr in the code.

* Use a simple fetching solution.

* Fix 404 and xhr status issue.

* Move the prefetching implementation to next/router.

* Add deprecated warnning for next/prefetch

* Run only 2 parellel prefetching request at a time.

* Change xhr to jsonPageRes.

* Improve the prefetching logic.

* Add unit tests covering the Router.prefetch()

* Update examples to use the new syntax.

* Update docs.

* Use execOnce() to manage warn printing.

* Remove prefetcher building from the flyfile.js
Because, we no longer use it.

											
										
										
											2017-02-15 08:52:22 +00:00
+								      <li><Link prefetch href='/about'><a>About</a></Link></li>
 								      <li><Link prefetch href='/contact'><a>Contact</a></Link></li>
-												Update README.md
											
										
										
											2016-12-17 19:16:22 +00:00
+								    </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-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
-												Introduce a simple prefetching solution (#957)

* Implement a very simple prefetching solution.

* Remove next-prefetcher.

* Require 'whatwg-fetch' only in the client.

* Use xhr in the code.

* Use a simple fetching solution.

* Fix 404 and xhr status issue.

* Move the prefetching implementation to next/router.

* Add deprecated warnning for next/prefetch

* Run only 2 parellel prefetching request at a time.

* Change xhr to jsonPageRes.

* Improve the prefetching logic.

* Add unit tests covering the Router.prefetch()

* Update examples to use the new syntax.

* Update docs.

* Use execOnce() to manage warn printing.

* Remove prefetcher building from the flyfile.js
Because, we no longer use it.

											
										
										
											2017-02-15 08:52:22 +00:00
+								Most prefetching 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
-												Introduce a simple prefetching solution (#957)

* Implement a very simple prefetching solution.

* Remove next-prefetcher.

* Require 'whatwg-fetch' only in the client.

* Use xhr in the code.

* Use a simple fetching solution.

* Fix 404 and xhr status issue.

* Move the prefetching implementation to next/router.

* Add deprecated warnning for next/prefetch

* Run only 2 parellel prefetching request at a time.

* Change xhr to jsonPageRes.

* Improve the prefetching logic.

* Add unit tests covering the Router.prefetch()

* Update examples to use the new syntax.

* Update docs.

* Use execOnce() to manage warn printing.

* Remove prefetcher building from the flyfile.js
Because, we no longer use it.

											
										
										
											2017-02-15 08:52:22 +00:00
+								import Router from 'next/router'
-												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!
-												Introduce a simple prefetching solution (#957)

* Implement a very simple prefetching solution.

* Remove next-prefetcher.

* Require 'whatwg-fetch' only in the client.

* Use xhr in the code.

* Use a simple fetching solution.

* Fix 404 and xhr status issue.

* Move the prefetching implementation to next/router.

* Add deprecated warnning for next/prefetch

* Run only 2 parellel prefetching request at a time.

* Change xhr to jsonPageRes.

* Improve the prefetching logic.

* Add unit tests covering the Router.prefetch()

* Update examples to use the new syntax.

* Update docs.

* Use execOnce() to manage warn printing.

* Remove prefetcher building from the flyfile.js
Because, we no longer use it.

											
										
										
											2017-02-15 08:52:22 +00:00
+								      Router.prefetch('/dynamic')
-												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>
-												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
-												Add/data fetch example (#485)

* Added data fetch example

* Finished updating examples install instructions and added data-fetch example to main readme

											
										
										
											2016-12-22 23:05:49 +00:00
+								<p><details>
-												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
+								  <summary><b>Examples</b></summary>
-												Add/data fetch example (#485)

* Added data fetch example

* Finished updating examples install instructions and added data-fetch example to main readme

											
										
										
											2016-12-22 23:05:49 +00:00
+								  <ul>
 								    <li><a href="./examples/custom-server">Basic custom server</a></li>
 								    <li><a href="./examples/custom-server-express">Express integration</a></li>
-												Custom server example with Hapi in README (#825)


											
										
										
											2017-01-19 13:22:21 +00:00
+								    <li><a href="./examples/custom-server-hapi">Hapi integration</a></li>
-												Added Koa example (#800)

* Added Koa example

* Linted koa example

											
										
										
											2017-01-17 07:23:06 +00:00
+								    <li><a href="./examples/custom-server-koa">Koa integration</a></li>
-												Add/data fetch example (#485)

* Added data fetch example

* Finished updating examples install instructions and added data-fetch example to main readme

											
										
										
											2016-12-22 23:05:49 +00:00
+								    <li><a href="./examples/parameterized-routing">Parameterized routing</a></li>
-												Add SSR caching example to the README. (#503)


											
										
										
											2016-12-24 01:30:06 +00:00
+								    <li><a href="./examples/ssr-caching">SSR caching</a></li>
-												Add/data fetch example (#485)

* Added data fetch example

* Finished updating examples install instructions and added data-fetch example to main readme

											
										
										
											2016-12-22 23:05:49 +00:00
+								  </ul>
 								</details></p>
-												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
-												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')
-												Set dev variable consistent with examples (#939)


											
										
										
											2017-01-31 14:18:10 +00:00
+								const dev = process.env.NODE_ENV !== 'production'
 								const app = next({ dev })
-												Update README.md
											
										
										
											2016-12-20 19:19:03 +00:00
+								const handle = app.getRequestHandler()
 								app.prepare().then(() => {
 								  createServer((req, res) => {
-												Add better documentation around url.parse (#1281)


											
										
										
											2017-02-25 18:35:10 +00:00
+								    // Be sure to pass `true` as the second argument to `url.parse`.
 								    // This tells it to parse the query portion of the URL.
-												Allow parsed url to be passed down (#950)

* Allow parsed url to be passed down

* Update example to reflect url passing

* Check if passed url.query is empty

* Rename url to parsedUrl

											
										
										
											2017-02-02 06:51:08 +00:00
+								    const parsedUrl = parse(req.url, true)
 								    const { pathname, query } = parsedUrl
-												Update README.md
											
										
										
											2016-12-20 19:19:03 +00:00
 								    if (pathname === '/a') {
 								      app.render(req, res, '/b', query)
 								    } else if (pathname === '/b') {
 								      app.render(req, res, '/a', query)
 								    } else {
-												Allow parsed url to be passed down (#950)

* Allow parsed url to be passed down

* Update example to reflect url passing

* Check if passed url.query is empty

* Rename url to parsedUrl

											
										
										
											2017-02-02 06:51:08 +00:00
+								      handle(req, res, parsedUrl)
-												Update README.md
											
										
										
											2016-12-20 19:19:03 +00:00
+								    }
 								  })
 								  .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:
-												Revive truncated text in readme (#1538)


											
										
										
											2017-03-28 16:22:25 +00:00
+								- `next(path: string, opts: object)` - `path` is where the Next project is located
-												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 `'.'`
-												Improve quiet documentation (#1085)


											
										
										
											2017-02-12 16:26:51 +00:00
+								- `quiet` (`bool`) Hide error messages containing server information - default `false`
-												Update README.md
											
										
										
											2016-12-20 19:26:59 +00:00
-												Ensure NODE_ENV is production when deploying on Now (#1106)

* Ensure NODE_ENV is production when deploying on Now

* Fix custom server example instead of default one

* Fix typo

											
										
										
											2017-02-13 15:09:11 +00:00
+								Then, change your `start` script to `NODE_ENV=production node server.js`.
-												Update README.md
											
										
										
											2016-12-19 21:34:19 +00:00
+								### Custom `<Document>`
-												Add/data fetch example (#485)

* Added data fetch example

* Finished updating examples install instructions and added data-fetch example to main readme

											
										
										
											2016-12-22 23:05:49 +00:00
+								<p><details>
-												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
+								  <summary><b>Examples</b></summary>
-												Add/data fetch example (#485)

* Added data fetch example

* Finished updating examples install instructions and added data-fetch example to main readme

											
										
										
											2016-12-22 23:05:49 +00:00
+								  <ul><li><a href="./examples/with-styled-components">Styled components custom document</a></li></ul>
-												Added Google AMP example (#793)

* Added Google AMP example

* Added styles and a second page

* Using regular anchor since there is no client-side routing

* Added comment on react config for amp

											
										
										
											2017-01-24 13:20:56 +00:00
+								  <ul><li><a href="./examples/with-amp">Google AMP</a></li></ul>
-												Add/data fetch example (#485)

* Added data fetch example

* Finished updating examples install instructions and added data-fetch example to main readme

											
										
										
											2016-12-22 23:05:49 +00:00
+								</details></p>
-												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
-												Update styled-component docs (#841)

* Add details to custom Document documentation

Custom document must be created at ./Pages/_document.js, which is not
noted in the README… so I updated it.

* Add note to styled-components example about existing issue

* Made phrasing a bit more clear

* Another phrasing update.

* from P to p

											
										
										
											2017-01-21 21:24:17 +00:00
+								Pages in `Next.js` skip the definition of the surrounding document's markup. For example, you never include `<html>`, `<body>`, etc. To override that default behavior, you must create a file at `./pages/_document.js`, where you can extend the `Document` class:
-												Update README.md
											
										
										
											2016-12-19 21:34:19 +00:00
 								```jsx
-												Update styled-component docs (#841)

* Add details to custom Document documentation

Custom document must be created at ./Pages/_document.js, which is not
noted in the README… so I updated it.

* Add note to styled-components example about existing issue

* Made phrasing a bit more clear

* Another phrasing update.

* from P to p

											
										
										
											2017-01-21 21:24:17 +00:00
+								// ./pages/_document.js
-												Update README.md (#802)

fix quotation mark
											
										
										
											2017-01-17 04:26:23 +00:00
+								import Document, { Head, Main, NextScript } from 'next/document'
-												Render styled-jsx in _document example (#1287)


											
										
										
											2017-02-27 23:45:49 +00:00
+								import flush from 'styled-jsx/server'
-												Update README.md
											
										
										
											2016-12-19 21:34:19 +00:00
 								export default class MyDocument extends Document {
-												Render styled-jsx in _document example (#1287)


											
										
										
											2017-02-27 23:45:49 +00:00
+								  static getInitialProps ({ renderPage }) {
 								    const {html, head} = renderPage()
 								    const styles = flush()
 								    return { html, head, styles }
-												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 {
-												Use jsonPageRes instead of xhr (#1424)


											
										
										
											2017-03-15 02:37:29 +00:00
+								  static getInitialProps ({ res, jsonPageRes }) {
 								    const statusCode = res ? res.statusCode : (jsonPageRes ? jsonPageRes.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
-												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
 								```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 }) => {
-												Warn about webpack loaders (#638)


											
										
										
											2017-01-03 18:06:55 +00:00
+								    // Perform customizations to config
 								    // Important: return the modified config
-												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
+								    return config
 								  }
 								}
 								```
-												Warn about webpack loaders (#638)


											
										
										
											2017-01-03 18:06:55 +00:00
+								*Warning: Adding loaders to support new file types (css, less, svg, etc.) is __not__ recommended because only the client code gets bundled via webpack and thus it won't work on the initial server rendering. Babel plugins are a good alternative because they're applied consistently between server/client rendering (e.g. [babel-plugin-inline-react-svg](https://github.com/kesne/babel-plugin-inline-react-svg)).*
-												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
+								### Customizing babel config
-												wrong position of babel config example (#1057)


											
										
										
											2017-02-09 17:57:17 +00:00
+								<p><details>
 								  <summary><b>Examples</b></summary>
 								  <ul><li><a href="./examples/with-custom-babel-config">Custom babel configuration</a></li></ul>
 								</details></p>
-												Clean up docs about next/babel (#557)

* Clean up docs about next/babel

* Add suggestions from #553

											
										
										
											2016-12-29 13:58:28 +00:00
+								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:
-												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
 								```js
-												Add support for using .babelrc in the app root. (#493)

* Add support for using .babelrc in the app root.

* Update the README about the .babelrc usage.

* Fix a typo.

* Remove additional example usage.

											
										
										
											2016-12-26 18:13:45 +00:00
+								{
 								  "presets": [
 								    "next/babel",
 								    "stage-0"
 								  ],
-												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
-												Add reference to deployment wiki page (#1423)


											
										
										
											2017-03-15 02:38:00 +00:00
+								To deploy, instead of running `next`, you want to build for production usage 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 deployment wiki link.
											
										
										
											2017-03-15 02:40:10 +00:00
+								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.
-												Add reference to deployment wiki page (#1423)


											
										
										
											2017-03-15 02:38:00 +00:00
-												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>
-												fixed zeit.co link in readme (#1497)


											
										
										
											2017-03-24 19:50:56 +00:00
+								  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:
-												README: fix "Routing with lazy component loading" blob (#915)

Looks like `<Link>` was replaced with `\n` on accident
											
										
										
											2017-01-29 00:59:29 +00:00
+								- Routing with lazy component loading: `<Link>` (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>
-												Add Apollo example (#780)

* Add minimal apollo example

* Update apollo example README

* Update apollo example demo link in README

* Fix button styles

* Fix show more button

* Alias demo url

* Include the data field on the Apollo store when hydrating

* Revert

* Include the data field on the Apollo store when hydrating per tpreusse's suggestion.

* Add example to faq section in README

* Sort by newest; Add active state to buttons

* Make optimization suggestions

* Use process.browser; inline props

											
										
										
											2017-01-22 12:27:06 +00:00
+								<details>
 								  <summary>Can I use it with GraphQL?</summary>
 								Yes! Here's an example with [Apollo](./examples/with-apollo).
 								</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
-												Add contributing.md (#1009)

* Add contributing.md

* Only reload example app on server changes

											
										
										
											2017-02-06 13:19:34 +00:00
+								## Contributing
-												Lowercase file name (#1190)


											
										
										
											2017-02-17 13:36:47 +00:00
+								Please see our [contributing.md](./contributing.md)
-												Add contributing.md (#1009)

* Add contributing.md

* Only reload example app on server changes

											
										
										
											2017-02-06 13:19:34 +00:00
-												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
-												adding @timneutkens
											
										
										
											2017-01-10 20:55:48 +00:00
+								- Tim Neutkens ([@timneutkens](https://github.com/timneutkens))