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

[![NPM version](https://img.shields.io/npm/v/next.svg)](https://www.npmjs.com/package/next)
[![Build Status](https://travis-ci.org/zeit/next.js.svg?branch=master)](https://travis-ci.org/zeit/next.js)
[![Build status](https://ci.appveyor.com/api/projects/status/g2e75cnkv0k925bc?svg=true)](https://ci.appveyor.com/project/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)
[![Join the community on Spectrum](https://withspectrum.github.io/badge/badge.svg)](https://spectrum.chat/next-js)

Next.js is a minimalistic framework for server-rendered React applications.

**Visit [nextjs.org/learn](https://nextjs.org/learn) to get started with Next.js.**

---

**The below readme is the documentation for the `canary` (prerelease) branch. To view the documentation for the latest stable Next.js version visit [nextjs.org/docs](https://nextjs.org/docs)**

---

<!-- 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)
    - [Importing CSS / Sass / Less / Stylus files](#importing-css--sass--less--stylus-files)
  - [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)
      - [With URL object](#with-url-object)
      - [Replace instead of push url](#replace-instead-of-push-url)
      - [Using a component that supports `onClick`](#using-a-component-that-supports-onclick)
      - [Forcing the Link to expose `href` to its child](#forcing-the-link-to-expose-href-to-its-child)
      - [Disabling the scroll changes to top on page](#disabling-the-scroll-changes-to-top-on-page)
    - [Imperatively](#imperatively)
    - [Intercepting `popstate`](#intercepting-popstate)
      - [With URL object](#with-url-object-1)
      - [Router Events](#router-events)
      - [Shallow Routing](#shallow-routing)
    - [Using a Higher Order Component](#using-a-higher-order-component)
  - [Prefetching Pages](#prefetching-pages)
    - [With `<Link>`](#with-link-1)
    - [Imperatively](#imperatively-1)
  - [Custom server and routing](#custom-server-and-routing)
    - [Disabling file-system routing](#disabling-file-system-routing)
    - [Dynamic assetPrefix](#dynamic-assetprefix)
  - [Dynamic Import](#dynamic-import)
    - [1. Basic Usage (Also does SSR)](#1-basic-usage-also-does-ssr)
    - [2. With Custom Loading Component](#2-with-custom-loading-component)
    - [3. With No SSR](#3-with-no-ssr)
    - [4. With Multiple Modules At Once](#4-with-multiple-modules-at-once)
  - [Custom `<App>`](#custom-app)
  - [Custom `<Document>`](#custom-document)
  - [Custom error handling](#custom-error-handling)
  - [Reusing the built-in error page](#reusing-the-built-in-error-page)
  - [Custom configuration](#custom-configuration)
    - [Setting a custom build directory](#setting-a-custom-build-directory)
    - [Disabling etag generation](#disabling-etag-generation)
    - [Configuring the onDemandEntries](#configuring-the-ondemandentries)
    - [Configuring extensions looked for when resolving pages in `pages`](#configuring-extensions-looked-for-when-resolving-pages-in-pages)
    - [Configuring the build ID](#configuring-the-build-id)
  - [Customizing webpack config](#customizing-webpack-config)
  - [Customizing babel config](#customizing-babel-config)
  - [Exposing configuration to the server / client side](#exposing-configuration-to-the-server--client-side)
  - [Starting the server on alternative hostname](#starting-the-server-on-alternative-hostname)
  - [CDN support with Asset Prefix](#cdn-support-with-asset-prefix)
- [Production deployment](#production-deployment)
- [Static HTML export](#static-html-export)
  - [Usage](#usage)
  - [Limitation](#limitation)
- [Multi Zones](#multi-zones)
  - [How to define a zone](#how-to-define-a-zone)
  - [How to merge them](#how-to-merge-them)
- [Recipes](#recipes)
- [FAQ](#faq)
- [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 --save next react react-dom
```

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/` (given you [create a `./static/` directory](#static-file-serving-eg-images) inside your project)

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" similar to 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>
    <style global jsx>{`
      body {
        background: black;
      }
    `}</style>
  </div>
)
```

Please see the [styled-jsx documentation](https://www.npmjs.com/package/styled-jsx) for more examples.

#### 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-glamorous">Glamorous</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.

#### Importing CSS / Sass / Less / Stylus files

To support importing `.css`, `.scss`, `.less` or `.styl` files you can use these modules, which configure sensible defaults for server rendered applications.

- [@zeit/next-css](https://github.com/zeit/next-plugins/tree/master/packages/next-css)
- [@zeit/next-sass](https://github.com/zeit/next-plugins/tree/master/packages/next-sass)
- [@zeit/next-less](https://github.com/zeit/next-plugins/tree/master/packages/next-less)
- [@zeit/next-stylus](https://github.com/zeit/next-plugins/tree/master/packages/next-stylus)

### 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" alt="my image" />
```

_Note: Don't name the `static` directory anything else. The name is required and is the only directory that Next.js uses for serving static assets._

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

To avoid duplicate tags in your `<head>` you can use the `key` property, which will make sure the tag is only rendered once:

```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" key="viewport" />
    </Head>
    <Head>
      <meta name="viewport" content="initial-scale=1.2, width=device-width" key="viewport" />
    </Head>
    <p>Hello world!</p>
  </div>
)
```

In this case only the second `<meta name="viewport" />` is rendered.

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

Data returned from `getInitialProps` is serialized when server rendering, similar to a `JSON.stringify`. Make sure the returned object from `getInitialProps` is a plain `Object` and not using `Date`, `Map` or `Set`.

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

<br/>

> If you are using some server only modules inside `getInitialProps`, make sure to [import them properly](https://arunoda.me/blog/ssr-and-server-only-modules).
> Otherwise, it'll slow down your app.

<br/>

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
- `asPath` - `String` of the actual path (including the query) shows in the browser
- `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 is rendered

To inject the `pathname`, `query` or `asPath` in your component, you can use [withRouter](#using-a-higher-order-component).

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

##### Replace instead of push url

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

##### Using a component that supports `onClick`

`<Link>` supports any component that supports the `onClick` event. In case you don't provide an `<a>` tag, it will only add the `onClick` event handler and won't pass the `href` property.

```jsx
// pages/index.js
import Link from 'next/link'

export default () => (
  <div>
    Click{' '}
    <Link href="/about">
      <img src="/static/image.png" alt="image" />
    </Link>
  </div>
)
```

##### Forcing the Link to expose `href` to its child

If child is an `<a>` tag and doesn't have a href attribute we specify it so that the repetition is not needed by the user. However, sometimes, you’ll want to pass an `<a>` tag inside of a wrapper and the `Link` won’t recognize it as a *hyperlink*, and, consequently, won’t transfer its `href` to the child. In cases like that, you should define a boolean `passHref` property to the `Link`, forcing it to expose its `href` property to the child.

**Please note**: using a tag other than `a` and failing to pass `passHref` may result in links that appear to navigate correctly, but, when being crawled by search engines, will not be recognized as links (owing to the lack of `href` attribute). This may result in negative effects on your sites SEO.

```jsx
import Link from 'next/link'
import Unexpected_A from 'third-library'

export default ({ href, name }) => (
  <Link href={href} passHref>
    <Unexpected_A>
      {name}
    </Unexpected_A>
  </Link>
)
```

##### Disabling the scroll changes to top on page

The default behaviour of `<Link>` is to scroll to the top of the page. When there is a hash defined it will scroll to the specific id, just like a normal `<a>` tag. To prevent scrolling to the top / hash `scroll={false}` can be added to `<Link>`:

```jsx
<Link scroll={false} href="/?counter=10"><a>Disables scrolling</a></Link>
<Link href="/?counter=10"><a>Changes with scrolling to top</a></Link>
```

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

#### Intercepting `popstate`

In some cases (for example, if using a [custom router](#custom-server-and-routing)), you may wish
to listen to [`popstate`](https://developer.mozilla.org/en-US/docs/Web/Events/popstate) and react before the router acts on it.
For example, you could use this to manipulate the request, or force an SSR refresh.

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

Router.beforePopState(({ url, as, options }) => {
  // I only want to allow these two routes!
  if (as !== "/" || as !== "/other") {
    // Have SSR render bad routes as a 404.
    window.location.href = as
    return false
  }

  return true
});
```

If you return a falsy value from `beforePopState`, `Router` will not handle `popstate`;
you'll be responsible for handling it, in that case.
See [Disabling File-System Routing](#disabling-file-system-routing).

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 `{}`
- `asPath` - `String` of the actual path (including the query) shows in the browser
- `push(url, as=url)` - performs a `pushState` call with the given url
- `replace(url, as=url)` - performs a `replaceState` call with the given url
- `beforePopState(cb=function)` - intercept popstate before router processes the event.

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
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 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
- `hashChangeStart(url)` - Fires when the hash will change but not the page
- `hashChangeComplete(url)` - Fires when the hash has changed but not the page

> 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
const handleRouteChange = url => {
  console.log('App is changing to: ', url)
}

Router.events.on('routeChangeStart', handleRouteChange)
```

If you no longer want to listen to that event, you can unsubscribe with the `off` method:

```js
Router.events.off('routeChangeStart', handleRouteChange)
```

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

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

##### 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 either `Router.push` or `Router.replace` with the `shallow: true` option. Here's an example:

```js
// 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.router.query` inside the `Component` (make sure you are using [`withRouter`](#using-a-higher-order-component) around your `Component` to inject the `router` prop).

You can watch for URL changes via [`componentDidUpdate`](https://reactjs.org/docs/react-component.html#componentdidupdate) hook as shown below:

```js
componentDidUpdate(prevProps) {
  const { pathname, query } = this.props.router
  // verify props have changed to avoid an infinite loop
  if (query.id !== prevProps.router.query.id) {
    // fetch data based on the new query
  }
}
```

> NOTES:
>
> Shallow routing works **only** for same page URL changes. For an example, let's assume we have another page called `about`, and you run this:
> ```js
> Router.push('/?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 though we asked to do shallow routing.

#### Using a Higher Order Component

<p><details>
  <summary><b>Examples</b></summary>
  <ul>
    <li><a href="./examples/using-with-router">Using the `withRouter` utility</a></li>
  </ul>
</details></p>

If you want to access the `router` object inside any component in your app, you can use the `withRouter` Higher-Order Component. Here's how to use it:

```jsx
import { withRouter } from 'next/router'

const ActiveLink = ({ children, router, href }) => {
  const style = {
    marginRight: 10,
    color: router.pathname === href? 'red' : 'black'
  }

  const handleClick = (e) => {
    e.preventDefault()
    router.push(href)
  }

  return (
    <a href={href} onClick={handleClick} style={style}>
      {children}
    </a>
  )
}

export default withRouter(ActiveLink)
```

The above `router` object comes with an API similar to [`next/router`](#imperatively).

### 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 downloads 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 { withRouter } from 'next/router'

export default withRouter(({ router }) => (
  <div>
    <a onClick={() => setTimeout(() => router.push('/dynamic'), 100)}>
      A route transition will happen after 100ms
    </a>
    {// but we can prefetch it!
    router.prefetch('/dynamic')}
  </div>
)
```

The router instance should be only used inside the client side of your app though. In order to prevent any error regarding this subject, when rendering the Router on the server side, use the imperatively prefetch method in the `componentDidMount()` lifecycle method.

```jsx
import React from 'react'
import { withRouter } from 'next/router'

class MyLink extends React.Component {
  componentDidMount() {
    const { router } = this.props
    router.prefetch('/dynamic')
  }
  
  render() {
    const { router } = this.props
    
    return (
       <div>
        <a onClick={() => setTimeout(() => router.push('/dynamic'), 100)}>
          A route transition will happen after 100ms
        </a>
      </div>   
    )
  }
}

export default withRouter(MyLink)
```

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

When using a custom server with a server file, for example called `server.js`, make sure you update the scripts key in `package.json` to:

```json
{
  "scripts": {
    "dev": "node server.js",
    "build": "next build",
    "start": "NODE_ENV=production node server.js"
  }
}
```

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

```js
// This file doesn't go through babel or webpack transformation.
// Make sure the syntax and sources this file requires are compatible with the current node version you are running
// See https://github.com/zeit/next.js/issues/1245 for discussions on Universal Webpack or universal Babel
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(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`
- `conf` (`object`) the same object you would use in `next.config.js` - default `{}`

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

#### Disabling file-system routing
By default, `Next` will serve each file in `/pages` under a pathname matching the filename (eg, `/pages/some-file.js` is served at `site.com/some-file`.

If your project uses custom routing, this behavior may result in the same content being served from multiple paths, which can present problems with SEO and UX.

To disable this behavior & prevent routing based on files in `/pages`, simply set the following option in your `next.config.js`:

```js
// next.config.js
module.exports = {
  useFileSystemPublicRoutes: false
}
```

Note that `useFileSystemPublicRoutes` simply disables filename routes from SSR; client-side routing
may still access those paths. If using this option, you should guard against navigation to routes
you do not want programmatically.

You may also wish to configure the client-side Router to disallow client-side redirects to filename
routes; please refer to [Intercepting `popstate`](#intercepting-popstate).

#### Dynamic assetPrefix

Sometimes we need to set the `assetPrefix` dynamically. This is useful when changing the `assetPrefix` based on incoming requests.
For that, we can use `app.setAssetPrefix`.

Here's an example usage of it:

```js
const next = require('next')
const micro = require('micro')

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

app.prepare().then(() => {
  const server = micro((req, res) => {
    // Add assetPrefix support based on the hostname
    if (req.headers.host === 'my-app.com') {
      app.setAssetPrefix('http://cdn.com/myapp')
    } else {
      app.setAssetPrefix('')
    }

    handleNextRequests(req, res)
  })

  server.listen(port, (err) => {
    if (err) {
      throw err
    }

    console.log(`> Ready on http://localhost:${port}`)
  })
})

```

### Dynamic Import

<p><details>
  <summary><b>Examples</b></summary>
  <ul>
    <li><a href="./examples/with-dynamic-import">With Dynamic Import</a></li>
  </ul>
</details></p>

Next.js supports TC39 [dynamic import proposal](https://github.com/tc39/proposal-dynamic-import) for JavaScript.
With that, you could import JavaScript modules (inc. React Components) dynamically and work with them.

You can think dynamic imports as another way to split your code into manageable chunks.
Since Next.js supports dynamic imports with SSR, you could do amazing things with it.

Here are a few ways to use dynamic imports.

#### 1. Basic Usage (Also does SSR)

```jsx
import dynamic from 'next/dynamic'

const DynamicComponent = dynamic(() => import('../components/hello'))

export default () => (
  <div>
    <Header />
    <DynamicComponent />
    <p>HOME PAGE is here!</p>
  </div>
)
```

#### 2. With Custom Loading Component

```jsx
import dynamic from 'next/dynamic'

const DynamicComponentWithCustomLoading = dynamic(() => import('../components/hello2'), {
  loading: () => <p>...</p>
})

export default () => (
  <div>
    <Header />
    <DynamicComponentWithCustomLoading />
    <p>HOME PAGE is here!</p>
  </div>
)
```

#### 3. With No SSR

```jsx
import dynamic from 'next/dynamic'

const DynamicComponentWithNoSSR = dynamic(() => import('../components/hello3'), {
  ssr: false
})

export default () => (
  <div>
    <Header />
    <DynamicComponentWithNoSSR />
    <p>HOME PAGE is here!</p>
  </div>
)
```

#### 4. With Multiple Modules At Once

```jsx
import dynamic from 'next/dynamic'

const HelloBundle = dynamic({
  modules: () => {
    const components = {
      Hello1: () => import('../components/hello1'),
      Hello2: () => import('../components/hello2')
    }

    return components
  },
  render: (props, { Hello1, Hello2 }) =>
    <div>
      <h1>
        {props.title}
      </h1>
      <Hello1 />
      <Hello2 />
    </div>
})

export default () => <HelloBundle title="Dynamic Bundle" />
```

### Custom `<App>`

<p><details>
  <summary><b>Examples</b></summary>
  <ul><li><a href="./examples/with-app-layout">Using `_app.js` for layout</a></li></ul>
  <ul><li><a href="./examples/with-componentdidcatch">Using `_app.js` to override `componentDidCatch`</a></li></ul>
</details></p>

Next.js uses the `App` component to initialize pages. You can override it and control the page initialization. Which allows you to do amazing things like:

- Persisting layout between page changes
- Keeping state when navigating pages
- Custom error handling using `componentDidCatch`
- Inject additional data into pages (for example by processing GraphQL queries)

To override, create the `./pages/_app.js` file and override the App class as shown below:

```js
import React from 'react'
import App, { Container } from 'next/app'

export default class MyApp extends App {
  static async getInitialProps({ Component, router, ctx }) {
    let pageProps = {}

    if (Component.getInitialProps) {
      pageProps = await Component.getInitialProps(ctx)
    }

    return { pageProps }
  }

  render () {
    const { Component, pageProps } = this.props

    return (
      <Container>
        <Component {...pageProps} />
      </Container>
    )
  }
}
```

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

- Is rendered on the server side
- Is used to change the initial server side rendered document markup
- Commonly used to implement server side rendering for css-in-js libraries like [styled-components](./examples/with-styled-components), [glamorous](./examples/with-glamorous) or [emotion](with-emotion). [styled-jsx](https://github.com/zeit/styled-jsx) is included with Next.js by default.

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
// _document is only rendered on the server side and not on the client side
// Event handlers like onClick can't be added to this file

// ./pages/_document.js
import Document, { Head, Main, NextScript } from 'next/document'

export default class MyDocument extends Document {
  static async getInitialProps(ctx) {
    const initialProps = await Document.getInitialProps(ctx)
    return { ...initialProps }
  }

  render() {
    return (
      <html>
        <Head>
          <style>{`body { margin: 0 } /* custom! */`}</style>
        </Head>
        <body className="custom_class">
          <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)

__Note: React-components outside of `<Main />` will not be initialised by the browser. Do _not_ add application logic here. If you need shared components in all your pages (like a menu or a toolbar), take a look at the `App` component instead.__

### Custom error handling

404 or 500 errors are handled both client and server side by a default component `error.js`. If you wish to override it, define a `_error.js` in the pages folder:

```jsx
import React from 'react'

export default class Error extends React.Component {
  static getInitialProps({ res, err }) {
    const statusCode = res ? res.statusCode : err ? err.statusCode : null;
    return { statusCode }
  }

  render() {
    return (
      <p>
        {this.props.statusCode
          ? `An error ${this.props.statusCode} occurred on server`
          : 'An error occurred on client'}
      </p>
    )
  }
}
```

### Reusing the built-in error page

If you want to render the built-in error page you can by using `next/error`:

```jsx
import React from 'react'
import Error from 'next/error'
import fetch from 'isomorphic-unfetch'

export default class Page extends React.Component {
  static async getInitialProps() {
    const res = await fetch('https://api.github.com/repos/zeit/next.js')
    const statusCode = res.statusCode > 200 ? res.statusCode : false
    const json = await res.json()

    return { statusCode, stars: json.stargazers_count }
  }

  render() {
    if (this.props.statusCode) {
      return <Error statusCode={this.props.statusCode} />
    }

    return (
      <div>
        Next stars: {this.props.stars}
      </div>
    )
  }
}
```

> If you have created a custom error page you have to import your own `_error` component instead of `next/error`

### Custom configuration

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

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

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

Or use a function:

```js
module.exports = (phase, {defaultConfig}) => {
  //
  // https://github.com/zeit/
  return {
    /* config options here */
  }
}
```

`phase` is the current context in which the configuration is loaded. You can see all phases here: [constants](./lib/constants.js)
Phases can be imported from `next/constants`:

```js
const {PHASE_DEVELOPMENT_SERVER} = require('next/constants')
module.exports = (phase, {defaultConfig}) => {
  if(phase === PHASE_DEVELOPMENT_SERVER) {
    return {
      /* development only config options here */
    }
  }

  return {
    /* config options for all phases except development here */
  }
}
```

#### Setting a custom build directory

You can specify a name to use for a custom build directory. For example, the following config will create a `build` folder instead of a `.next` folder. If no configuration is specified then next will create a `.next` folder.

```js
// next.config.js
module.exports = {
  distDir: 'build'
}
```

#### Disabling etag generation

You can disable etag generation for HTML pages depending on your cache strategy. If no configuration is specified then Next will generate etags for every page.

```js
// next.config.js
module.exports = {
  generateEtags: false
}
```

#### Configuring the onDemandEntries

Next exposes some options that give you some control over how the server will dispose or keep in memories pages built:

```js
module.exports = {
  onDemandEntries: {
    // period (in ms) where the server will keep pages in the buffer
    maxInactiveAge: 25 * 1000,
    // number of pages that should be kept simultaneously without being disposed
    pagesBufferLength: 2,
  }
}
```

This is development-only feature. If you want to cache SSR pages in production, please see [SSR-caching](https://github.com/zeit/next.js/tree/canary/examples/ssr-caching) example.

#### Configuring extensions looked for when resolving pages in `pages`

Aimed at modules like [`@zeit/next-typescript`](https://github.com/zeit/next-plugins/tree/master/packages/next-typescript), that add support for pages ending in `.ts`. `pageExtensions` allows you to configure the extensions looked for in the `pages` directory when resolving pages.

```js
// next.config.js
module.exports = {
  pageExtensions: ['jsx', 'js']
}
```

#### Configuring the build ID

Next.js uses a constant generated at build time to identify which version of your application is being served. This can cause problems in multi-server deployments when `next build` is ran on every server. In order to keep a static build id between builds you can provide the `generateBuildId` function:

```js
// next.config.js
module.exports = {
  generateBuildId: async () => {
    // For example get the latest git commit hash here
    return 'my-build-id'
  }
}
```

### Customizing webpack config

<p><details>
  <summary><b>Examples</b></summary>
  <ul><li><a href="./examples/with-webpack-bundle-analyzer">Custom webpack bundle analyzer</a></li></ul>
</details></p>

Some commonly asked for features are available as modules:

- [@zeit/next-css](https://github.com/zeit/next-plugins/tree/master/packages/next-css)
- [@zeit/next-sass](https://github.com/zeit/next-plugins/tree/master/packages/next-sass)
- [@zeit/next-less](https://github.com/zeit/next-plugins/tree/master/packages/next-less)
- [@zeit/next-preact](https://github.com/zeit/next-plugins/tree/master/packages/next-preact)
- [@zeit/next-typescript](https://github.com/zeit/next-plugins/tree/master/packages/next-typescript)

*Warning: The `webpack` function is executed twice, once for the server and once for the client. This allows you to distinguish between client and server configuration using the `isServer` property*

Multiple configurations can be combined together with function composition. For example:

```js
const withTypescript = require('@zeit/next-typescript')
const withSass = require('@zeit/next-sass')

module.exports = withTypescript(withSass({
  webpack(config, options) {
    // Further custom configuration here
    return config
  }
}))
```

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

```js
// next.config.js is not transformed by Babel. So you can only use javascript features supported by your version of Node.js.

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

The second argument to `webpack` is an object containing properties useful when customing the WebPack configuration:

- `buildId` - `String` the build id used as a unique identifier between builds
- `dev` - `Boolean` shows if the compilation is done in development mode
- `isServer` - `Boolean` shows if the resulting configuration will be used for server side (`true`), or client size compilation (`false`).
- `defaultLoaders` - `Object` Holds loader objects Next.js uses internally, so that you can use them in custom configuration
  - `babel` - `Object` the `babel-loader` configuration for Next.js.
  - `hotSelfAccept` - `Object` the `hot-self-accept-loader` configuration. This loader should only be used for advanced use cases. For example [`@zeit/next-typescript`](https://github.com/zeit/next-plugins/tree/master/packages/next-typescript) adds it for top-level typescript pages.

Example usage of `defaultLoaders.babel`: 

```js
// Example next.config.js for adding a loader that depends on babel-loader
// This source was taken from the @zeit/next-mdx plugin source: 
// https://github.com/zeit/next-plugins/blob/master/packages/next-mdx
module.exports = {
  webpack: (config, {}) => {
    config.module.rules.push({
      test: /\.mdx/,
      use: [
        options.defaultLoaders.babel,
        {
          loader: '@mdx-js/loader',
          options: pluginOptions.options
        }
      ]
    })

    return config
  }
}
```

### Customizing babel config

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

```json
{
  "presets": ["next/babel"],
  "plugins": []
}
```

The `next/babel` preset includes everything needed to transpile React applications. This includes:

- preset-env
- preset-react
- plugin-proposal-class-properties
- plugin-proposal-object-rest-spread
- plugin-transform-runtime
- styled-jsx

These presets / plugins **should not** be added to your custom `.babelrc`. Instead, you can configure them on the `next/babel` preset:

```json
{
  "presets": [
    ["next/babel", {
      "preset-env": {},
      "transform-runtime": {},
      "styled-jsx": {},
      "class-properties": {}
    }]
  ],
  "plugins": []
}
```

The `modules` option on `"preset-env"` should be kept to `false` otherwise webpack code splitting is disabled.

### Exposing configuration to the server / client side

The `next/config` module gives your app access to runtime configuration stored in your `next.config.js`. Place any server-only runtime config under a `serverRuntimeConfig` property and anything accessible to both client and server-side code under `publicRuntimeConfig`.

```js
// next.config.js
module.exports = {
  serverRuntimeConfig: { // Will only be available on the server side
    mySecret: 'secret'
  },
  publicRuntimeConfig: { // Will be available on both server and client
    staticFolder: '/static',
    mySecret: process.env.MY_SECRET // Pass through env variables
  }
}
```

```js
// pages/index.js
import getConfig from 'next/config'
// Only holds serverRuntimeConfig and publicRuntimeConfig from next.config.js nothing else.
const {serverRuntimeConfig, publicRuntimeConfig} = getConfig()

console.log(serverRuntimeConfig.mySecret) // Will only be available on the server side
console.log(publicRuntimeConfig.staticFolder) // Will be available on both server and client

export default () => <div>
  <img src={`${publicRuntimeConfig.staticFolder}/logo.png`} alt="logo" />
</div>
```

### Starting the server on alternative hostname

To start the development server using a different default hostname you can use `--hostname hostname_here` or `-H hostname_here` option with next dev. This will start a TCP server listening for connections on the provided host.

### CDN support with Asset Prefix

To set up a CDN, you can set up the `assetPrefix` setting and configure your CDN's origin to resolve to the domain that Next.js is hosted on.

```js
const isProd = process.env.NODE_ENV === 'production'
module.exports = {
  // You may only need to add assetPrefix in the production.
  assetPrefix: isProd ? 'https://cdn.mydomain.com' : ''
}
```

Note: Next.js will automatically use that prefix in the scripts it loads, but this has no effect whatsoever on `/static`. If you want to serve those assets over the CDN, you'll have to introduce the prefix yourself. One way of introducing a prefix that works inside your components and varies by environment is documented [in this example](https://github.com/zeit/next.js/tree/master/examples/with-universal-configuration).

## Production deployment

To deploy, instead of running `next`, you want to build for production usage ahead of time. Therefore, building and starting are separate commands:

```bash
next build
next start
```

For example, to deploy with [`now`](https://zeit.co/now) a `package.json` like follows is recommended:

```json
{
  "name": "my-app",
  "dependencies": {
    "next": "latest"
  },
  "scripts": {
    "dev": "next",
    "build": "next build",
    "start": "next start"
  }
}
```

Then run `now` and enjoy!

Next.js can be deployed to other hosting solutions too. Please have a look at the ['Deployment'](https://github.com/zeit/next.js/wiki/Deployment) section of the wiki.

Note: `NODE_ENV` is properly configured by the `next` subcommands, if absent, to maximize performance. if you’re using Next.js [programmatically](#custom-server-and-routing), it’s your responsibility to set `NODE_ENV=production` manually!

Note: we recommend putting `.next`, or your [custom dist folder](https://github.com/zeit/next.js#custom-configuration), in `.gitignore` or `.npmignore`. Otherwise, use `files` or `now.files` to opt-into a whitelist of files you want to deploy, excluding `.next` or your custom dist folder.

## Browser support

Next.js supports IE11 and all modern browsers out of the box using [`@babel/preset-env`](https://new.babeljs.io/docs/en/next/babel-preset-env.html). In order to support IE11 Next.js adds a global `Promise` polyfill. In cases where your own code or any external NPM dependencies you are using requires features not supported by your target browsers you will need to implement polyfills. 

The [polyfills](https://github.com/zeit/next.js/tree/canary/examples/with-polyfills) example demonstrates the recommended approach to implement polyfills.

## Static HTML export

<p><details>
  <summary><b>Examples</b></summary>
  <ul><li><a href="./examples/with-static-export">Static export</a></li></ul>
</details></p>

`next export` is a way to run your Next.js app as a standalone static app without the need for a Node.js server.
The exported app supports almost every feature of Next.js, including dynamic urls, prefetching, preloading and dynamic imports.

The way `next export` works is by pre-rendering all pages possible to HTML. It does so based on a mapping of `pathname` key to page object. This mapping is called the `exportPathMap`.

The page object has 2 values:

- `page` - `String` the page inside the `pages` directory to render
- `query` - `Object` the `query` object passed to `getInitialProps` when pre-rendering. Defaults to `{}`


### Usage

Simply develop your app as you normally do with Next.js. Then run:

```
next build
next export
```

By default `next export` doesn't require any configuration. It will generate a default `exportPathMap` containing the routes to pages inside the `pages` directory. This default mapping is available as `defaultPathMap` in the example below. 

If your application has dynamic routes you can add a dynamic `exportPathMap` in `next.config.js`.
This function is asynchronous and gets the default `exportPathMap` as a parameter.

```js
// next.config.js
module.exports = {
  exportPathMap: async function (defaultPathMap) {
    return {
      '/': { page: '/' },
      '/about': { page: '/about' },
      '/readme.md': { page: '/readme' },
      '/p/hello-nextjs': { page: '/post', query: { title: 'hello-nextjs' } },
      '/p/learn-nextjs': { page: '/post', query: { title: 'learn-nextjs' } },
      '/p/deploy-nextjs': { page: '/post', query: { title: 'deploy-nextjs' } }
    }
  }
}
```

> Note that if the path ends with a directory, it will be exported as `/dir-name/index.html`, but if it ends with an extension, it will be exported as the specified filename, e.g. `/readme.md` above. If you use a file extension other than `.html`, you may need to set the `Content-Type` header to `text/html` when serving this content.

Then simply run these commands:

```sh
next build
next export
```

For that you may need to add a NPM script to `package.json` like this:

```json
{
  "scripts": {
    "build": "next build",
    "export": "npm run build && next export"
  }
}
```

And run it at once with:

```sh
npm run export
```

Then you have a static version of your app in the `out` directory.

> You can also customize the output directory. For that run `next export -h` for the help.

Now you can deploy the `out` directory to any static hosting service. Note that there is an additional step for deploying to GitHub Pages, [documented here](https://github.com/zeit/next.js/wiki/Deploying-a-Next.js-app-into-GitHub-Pages).

For an example, simply visit the `out` directory and run following command to deploy your app to [ZEIT Now](https://zeit.co/now).

```sh
now
```

### Copying custom files

In case you have to copy custom files like a robots.txt or generate a sitemap.xml you can do this inside of `exportPathMap`.
`exportPathMap` gets a few contextual parameter to aid you with creating/copying files: 

- `dev` - `true` when `exportPathMap` is being called in development. `false` when running `next export`. In development `exportPathMap` is used to define routes and behavior like copying files is not required.
- `dir` - Absolute path to the project directory
- `outDir` - Absolute path to the `out` directory (configurable with `-o` or `--outdir`). When `dev` is `true` the value of `outDir` will be `null`.
- `distDir` - Absolute path to the `.next` directory (configurable using the `distDir` config key)
- `buildId` - The buildId the export is running for

```js
// next.config.js
const fs = require('fs')
const { join } = require('path')
const { promisify } = require('util')
const copyFile = promisify(fs.copyFile)

module.exports = {
  exportPathMap: async function (defaultPathMap, {dev, dir, outDir, distDir, buildId}) {
    if (dev) {
      return defaultPathMap
    }
    // This will copy robots.txt from your project root into the out directory
    await copyFile(join(dir, 'robots.txt'), join(outDir, 'robots.txt'))
    return defaultPathMap
  }
}
```

### Limitation

With `next export`, we build a HTML version of your app. At export time we will run `getInitialProps` of your pages.

The `req` and `res` fields of the `context` object passed to `getInitialProps` are not available as there is no server running.

> You won't be able to render HTML dynamically when static exporting, as we pre-build the HTML files. If you want to do dynamic rendering use `next start` or the custom server API

## Multi Zones

<p><details>
  <summary><b>Examples</b></summary>
  <ul><li><a href="./examples/with-zones">With Zones</a></li></ul>
</details></p>

A zone is a single deployment of a Next.js app. Just like that, you can have multiple zones. Then you can merge them as a single app.

For an example, you can have two zones like this:

* https://docs.my-app.com for serving `/docs/**`
* https://ui.my-app.com for serving all other pages

With multi zones support, you can merge both these apps into a single one. Which allows your customers to browse it using a single URL. But you can develop and deploy both apps independently.

> This is exactly the same concept as microservices, but for frontend apps.

### How to define a zone

There are no special zones related APIs. You only need to do following things:

* Make sure to keep only the pages you need in your app. (For an example, https://ui.my-app.com should not contain pages for `/docs/**`)
* Make sure your app has an [assetPrefix](https://github.com/zeit/next.js#cdn-support-with-asset-prefix). (You can also define the assetPrefix [dynamically](https://github.com/zeit/next.js#dynamic-assetprefix).)

### How to merge them

You can merge zones using any HTTP proxy.

You can use [micro proxy](https://github.com/zeit/micro-proxy) as your local proxy server. It allows you to easily define routing rules like below:

```json
{
  "rules": [
    {"pathname": "/docs**", "method":["GET", "POST", "OPTIONS"], "dest": "https://docs.my-app.com"},
    {"pathname": "/**", "dest": "https://ui.my-app.com"}
  ]
}
```

For the production deployment, you can use the [path alias](https://zeit.co/docs/features/path-aliases) feature if you are using [ZEIT now](https://zeit.co/now). Otherwise, you can configure your existing proxy server to route HTML pages using a set of rules as show above.

## Recipes

- [Setting up 301 redirects](https://www.raygesualdo.com/posts/301-redirects-with-nextjs/)
- [Dealing with SSR and server only modules](https://arunoda.me/blog/ssr-and-server-only-modules)
- [Building with React-Material-UI-Next-Express-Mongoose-Mongodb](https://github.com/builderbook/builderbook)
- [Build a SaaS Product with React-Material-UI-Next-MobX-Express-Mongoose-MongoDB-TypeScript](https://github.com/async-labs/saas)

## FAQ

<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 any 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 the  documentation about [customizing the babel config](#customizing-babel-config) and [next/preset](./build/babel/preset.js) for more information.

</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>Can I use Next with my favorite Javascript library or toolkit?</summary>

Since our first release we've had **many** example contributions, you can check them out in the [examples](./examples) directory
</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>

## Contributing

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

## Authors

- Arunoda Susiripala ([@arunoda](https://twitter.com/arunoda)) – [ZEIT](https://zeit.co)
- Tim Neutkens ([@timneutkens](https://twitter.com/timneutkens)) – [ZEIT](https://zeit.co)
- Naoyuki Kanezawa ([@nkzawa](https://twitter.com/nkzawa)) – [ZEIT](https://zeit.co)
- Tony Kovanen ([@tonykovanen](https://twitter.com/tonykovanen)) – [ZEIT](https://zeit.co)
- Guillermo Rauch ([@rauchg](https://twitter.com/rauchg)) – [ZEIT](https://zeit.co)
- Dan Zajdband ([@impronunciable](https://twitter.com/impronunciable)) – Knight-Mozilla / Coral Project
-												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
-												Set assetPrefix dynamically (#3661)

* Introduce the setAssetPrefix API for dynamic assetPrefix.

* Remove unwanted node_modules dir in a test dir.

* Change test main description.

											
										
										
											2018-02-02 14:43:36 +00:00
+								[![NPM version](https://img.shields.io/npm/v/next.svg)](https://www.npmjs.com/package/next)
-												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)
-												Moved to ZEIT's AppVeyor (#4991)

Previously, it was mistakenly located under @arunoda's personal account.
											
										
										
											2018-08-20 09:52:00 +00:00
+								[![Build status](https://ci.appveyor.com/api/projects/status/g2e75cnkv0k925bc?svg=true)](https://ci.appveyor.com/project/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)
-												Add Spectrum badge (#3927)

:raised_hands:
											
										
										
											2018-03-03 14:51:15 +00:00
+								[![Join the community on Spectrum](https://withspectrum.github.io/badge/badge.svg)](https://spectrum.chat/next-js)
-												Slack badge (#176)


											
										
										
											2016-11-02 19:02:56 +00:00
-												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
-												Update link to new learning page (#4223)


											
										
										
											2018-04-29 17:55:19 +00:00
+								**Visit [nextjs.org/learn](https://nextjs.org/learn) to get started with Next.js.**
-												Remove the getting started section.

Just add the https://learnnextjs.com link at the top of the page.
											
										
										
											2017-05-09 23:34:43 +00:00
 								---
-												Add mention of canary vs stable (#5074)


											
										
										
											2018-09-02 22:13:22 +00:00
+								**The below readme is the documentation for the `canary` (prerelease) branch. To view the documentation for the latest stable Next.js version visit [nextjs.org/docs](https://nextjs.org/docs)**
 								---
-												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)
-												Expose app.js (#4129)

* Expose pages/_app.js

* Add tests for _app and _document

* Uncomment deprecation warnings

* Add documentation for _app, improve documentation of _document

* Update docs / test for _document

* Add _document to client compiler in development

* Add missing app.js to comment

* Only warn once

* Add url-deprecated error page

* Combine tests

* Yse same message for all methods of ‘props.url’

* Update docs around _app

* Update documentation

* Quotes

* Update table of contents

											
										
										
											2018-04-12 08:33:22 +00:00
+								    - [Importing CSS / Sass / Less / Stylus files](#importing-css--sass--less--stylus-files)
-												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
+								  - [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)
-												Expose app.js (#4129)

* Expose pages/_app.js

* Add tests for _app and _document

* Uncomment deprecation warnings

* Add documentation for _app, improve documentation of _document

* Update docs / test for _document

* Add _document to client compiler in development

* Add missing app.js to comment

* Only warn once

* Add url-deprecated error page

* Combine tests

* Yse same message for all methods of ‘props.url’

* Update docs around _app

* Update documentation

* Quotes

* Update table of contents

											
										
										
											2018-04-12 08:33:22 +00:00
+								      - [With URL object](#with-url-object)
 								      - [Replace instead of push url](#replace-instead-of-push-url)
 								      - [Using a component that supports `onClick`](#using-a-component-that-supports-onclick)
 								      - [Forcing the Link to expose `href` to its child](#forcing-the-link-to-expose-href-to-its-child)
 								      - [Disabling the scroll changes to top on page](#disabling-the-scroll-changes-to-top-on-page)
-												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
+								    - [Imperatively](#imperatively)
-												Expose app.js (#4129)

* Expose pages/_app.js

* Add tests for _app and _document

* Uncomment deprecation warnings

* Add documentation for _app, improve documentation of _document

* Update docs / test for _document

* Add _document to client compiler in development

* Add missing app.js to comment

* Only warn once

* Add url-deprecated error page

* Combine tests

* Yse same message for all methods of ‘props.url’

* Update docs around _app

* Update documentation

* Quotes

* Update table of contents

											
										
										
											2018-04-12 08:33:22 +00:00
+								    - [Intercepting `popstate`](#intercepting-popstate)
 								      - [With URL object](#with-url-object-1)
-												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
+								      - [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/with router (#2870)

* Add withRoute HOC

Rebased (squashed)
- removed routerToProps
- updated hoist-non-react-statics
- improved propTypes

* Expose the whole Router instead of the route.

* Make the example simple.

* Update examples and the readme.

* Add a test case.

											
										
										
											2017-08-30 14:07:12 +00:00
+								    - [Using a Higher Order Component](#using-a-higher-order-component)
-												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)
-												Expose app.js (#4129)

* Expose pages/_app.js

* Add tests for _app and _document

* Uncomment deprecation warnings

* Add documentation for _app, improve documentation of _document

* Update docs / test for _document

* Add _document to client compiler in development

* Add missing app.js to comment

* Only warn once

* Add url-deprecated error page

* Combine tests

* Yse same message for all methods of ‘props.url’

* Update docs around _app

* Update documentation

* Quotes

* Update table of contents

											
										
										
											2018-04-12 08:33:22 +00:00
+								    - [Disabling file-system routing](#disabling-file-system-routing)
 								    - [Dynamic assetPrefix](#dynamic-assetprefix)
-												Change dynamic imports to dynamic import (#1980)

Fix problem with anchor by changing link and changing text to section title.
											
										
										
											2017-05-16 14:29:52 +00:00
+								  - [Dynamic Import](#dynamic-import)
-												Expose app.js (#4129)

* Expose pages/_app.js

* Add tests for _app and _document

* Uncomment deprecation warnings

* Add documentation for _app, improve documentation of _document

* Update docs / test for _document

* Add _document to client compiler in development

* Add missing app.js to comment

* Only warn once

* Add url-deprecated error page

* Combine tests

* Yse same message for all methods of ‘props.url’

* Update docs around _app

* Update documentation

* Quotes

* Update table of contents

											
										
										
											2018-04-12 08:33:22 +00:00
+								    - [1. Basic Usage (Also does SSR)](#1-basic-usage-also-does-ssr)
 								    - [2. With Custom Loading Component](#2-with-custom-loading-component)
 								    - [3. With No SSR](#3-with-no-ssr)
 								    - [4. With Multiple Modules At Once](#4-with-multiple-modules-at-once)
 								  - [Custom `<App>`](#custom-app)
-												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
+								  - [Custom `<Document>`](#custom-document)
 								  - [Custom error handling](#custom-error-handling)
-												Expose app.js (#4129)

* Expose pages/_app.js

* Add tests for _app and _document

* Uncomment deprecation warnings

* Add documentation for _app, improve documentation of _document

* Update docs / test for _document

* Add _document to client compiler in development

* Add missing app.js to comment

* Only warn once

* Add url-deprecated error page

* Combine tests

* Yse same message for all methods of ‘props.url’

* Update docs around _app

* Update documentation

* Quotes

* Update table of contents

											
										
										
											2018-04-12 08:33:22 +00:00
+								  - [Reusing the built-in error page](#reusing-the-built-in-error-page)
-												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
+								  - [Custom configuration](#custom-configuration)
-												Expose app.js (#4129)

* Expose pages/_app.js

* Add tests for _app and _document

* Uncomment deprecation warnings

* Add documentation for _app, improve documentation of _document

* Update docs / test for _document

* Add _document to client compiler in development

* Add missing app.js to comment

* Only warn once

* Add url-deprecated error page

* Combine tests

* Yse same message for all methods of ‘props.url’

* Update docs around _app

* Update documentation

* Quotes

* Update table of contents

											
										
										
											2018-04-12 08:33:22 +00:00
+								    - [Setting a custom build directory](#setting-a-custom-build-directory)
 								    - [Disabling etag generation](#disabling-etag-generation)
 								    - [Configuring the onDemandEntries](#configuring-the-ondemandentries)
 								    - [Configuring extensions looked for when resolving pages in `pages`](#configuring-extensions-looked-for-when-resolving-pages-in-pages)
 								    - [Configuring the build ID](#configuring-the-build-id)
-												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
+								  - [Customizing webpack config](#customizing-webpack-config)
 								  - [Customizing babel config](#customizing-babel-config)
-												Improve documentation on runtime configuration (#4756)

* Remove nesting of runtime configuration under the babel section, since it's not related to babel.
* Clean up confusing verbiage relating to "keys."
											
										
										
											2018-07-10 21:02:45 +00:00
+								  - [Exposing configuration to the server / client side](#exposing-configuration-to-the-server--client-side)
-												Update readme with alternative hostname option (#4829)

Tackles the issue in #4025.
											
										
										
											2018-07-26 10:42:35 +00:00
+								  - [Starting the server on alternative hostname](#starting-the-server-on-alternative-hostname)
-												Add CDN support with assetPrefix (#1700)

* Introduce script tag based page loading system.

* Call ensurePage only in the dev mode.

* Implement router using the page-loader.

* Fix a typo and remove unwanted code.

* Fix some issues related to rendering.

* Fix production tests.

* Fix ondemand test cases.

* Fix unit tests.

* Get rid of eval completely.

* Remove all the inline code.

* Remove the json-pages plugin.

* Rename NEXT_PAGE_LOADER into __NEXT_PAGE_LOADER__

* Rename NEXT_LOADED_PAGES into __NEXT_LOADED_PAGES__

* Remove some unwanted code.

* Load everything async.

* Remove lib/eval-script.js
We no longer need it.

* Move webpack idle wait code to the page-loader.
Because that's the place to do it.

* Remove pageNotFound key from the error.

* Remove unused error field 'buildError'

* Add much better logic to normalize routes.

* Get rid of mitt.

* Introduce a better way to register pages.

* Came back to the mitt() based page-loader.

* Add link rel=preload support.

* Add assetPrefix support to add support for CDNs.

* Add assetPrefix support for preload links.

* Update readme.md

											
										
										
											2017-04-18 04:18:43 +00:00
+								  - [CDN support with Asset Prefix](#cdn-support-with-asset-prefix)
-												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
+								- [Production deployment](#production-deployment)
-												Add docs.

											
										
										
											2017-05-15 03:42:27 +00:00
+								- [Static HTML export](#static-html-export)
-												Expose app.js (#4129)

* Expose pages/_app.js

* Add tests for _app and _document

* Uncomment deprecation warnings

* Add documentation for _app, improve documentation of _document

* Update docs / test for _document

* Add _document to client compiler in development

* Add missing app.js to comment

* Only warn once

* Add url-deprecated error page

* Combine tests

* Yse same message for all methods of ‘props.url’

* Update docs around _app

* Update documentation

* Quotes

* Update table of contents

											
										
										
											2018-04-12 08:33:22 +00:00
+								  - [Usage](#usage)
 								  - [Limitation](#limitation)
-												Include next/dist/pages instead of exclude (patch) (#3704)

* Move security related test cases into a its own file.

* Removes the unused renderScript function

* Add a nerv example. (#3573)

* Add a nerv example.

* Fix for indentation/style

* Fix for name

* Release 5.0.0

* Add multi-zones docs. (#3688)

* Include next/dist/pages

* Fix linting

											
										
										
											2018-02-06 12:09:41 +00:00
+								- [Multi Zones](#multi-zones)
-												Expose app.js (#4129)

* Expose pages/_app.js

* Add tests for _app and _document

* Uncomment deprecation warnings

* Add documentation for _app, improve documentation of _document

* Update docs / test for _document

* Add _document to client compiler in development

* Add missing app.js to comment

* Only warn once

* Add url-deprecated error page

* Combine tests

* Yse same message for all methods of ‘props.url’

* Update docs around _app

* Update documentation

* Quotes

* Update table of contents

											
										
										
											2018-04-12 08:33:22 +00:00
+								  - [How to define a zone](#how-to-define-a-zone)
 								  - [How to merge them](#how-to-merge-them)
-												added recipes section to readme (#1928)


											
										
										
											2017-05-09 18:22:14 +00:00
+								- [Recipes](#recipes)
-												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
+								- [FAQ](#faq)
-												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:
-												Add beta installation instruction

											
										
										
											2017-09-27 21:15:46 +00:00
+								```bash
-												Update README for Next 4.

											
										
										
											2017-10-09 18:58:41 +00:00
+								npm install --save next react react-dom
-												Add beta installation instruction

											
										
										
											2017-09-27 21:15:46 +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
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								export default () => <div>Welcome to next.js!</div>
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
+								```
-												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`
-												Clarify documentation regarding the static folder (#4340)


											
										
										
											2018-05-25 11:42:19 +00:00
+								- Static file serving. `./static/` is mapped to `/static/` (given you [create a `./static/` directory](#static-file-serving-eg-images) inside your project)
-												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'
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								export default () => (
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								  <pre>
 								    {cowsay.say({ text: 'hi there!' })}
 								  </pre>
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								)
-												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
-												Minor grammatical fix: "resembling of" -> "similar to" (#2669)


											
										
										
											2017-07-28 05:10:17 +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" similar to 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
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +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>
-												Improve styled-jsx section of readme (#1932)

* Document style global jsx

* Add notice that styled-jsx docs contain more examples

											
										
										
											2017-05-10 08:25:56 +00:00
+								    <style global jsx>{`
 								      body {
 								        background: black;
 								      }
 								    `}</style>
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
+								  </div>
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								)
-												Update README.md
											
										
										
											2016-12-19 19:20:18 +00:00
+								```
-												Point to styled-jsx npm package's readme (#2085)

As we add new features and update README.md in zeit/styled-jsx people ask questions, typically why doesn't x works.
Master shouldn't be the source of truth, better link to the npm package's landing page.
											
										
										
											2017-05-27 17:46:58 +00:00
+								Please see the [styled-jsx documentation](https://www.npmjs.com/package/styled-jsx) for more examples.
-												Improve styled-jsx section of readme (#1932)

* Document style global jsx

* Add notice that styled-jsx docs contain more examples

											
										
										
											2017-05-10 08:25:56 +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>
-												Add link to the Glamorous example (#1887)


											
										
										
											2017-05-06 18:31:42 +00:00
+								  <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-glamorous">Glamorous</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
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								export default () => <p style={{ color: 'red' }}>hi there</p>
-												Update README.md
											
										
										
											2016-12-19 19:20:18 +00:00
+								```
-												docs(readme): add missing period (#3295)


											
										
										
											2017-11-16 04:35:42 +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 doc for @zeit/next-stylus (#4107)


											
										
										
											2018-04-04 11:18:28 +00:00
+								#### Importing CSS / Sass / Less / Stylus files
-												Universal Webpack (#3578)

* Speed up next build

* Document webpack config

* Speed up next build

* Remove comment

* Add comment

* Clean up rules

* Add comments

* Run in parallel

* Push plugins seperately

* Create a new chunk for react

* Don’t uglify react since it’s already uglified. Move react to commons in development

* Use the minified version directly

* Re-add globpattern

* Move loaders into a separate variable

* Add comment linking to Dan’s explanation

* Remove dot

* Add universal webpack

* Initial dev support

* Fix linting

* Add changes from Arunoda's work

* Made next dev works.
But super slow and no HMR support.

* Fix client side hot reload

* Server side hmr

* Only in dev

* Add on-demand-entries client + hot-middleware

* Add .babelrc support

* Speed up on demand entries by running in parallel

* Serve static generated files

* Add missing config in dev

* Add sass support

* Add support for .map

* Add cssloader config and fix .jsx support

* Rename

* use same defaults as css-loader. Fix linting

* Add NoEmitErrorsPlugin

* Add clientBootstrap

* Use webpackhotmiddleware on the multi compiler

* alpha.3

* Use babel 16.2.x

* Fix reloading after error

* Remove comment

* Release 5.0.0-univeral-alpha.1

* Remove check for React 16

* Release 5.0.0-universal-alpha.2

* React hot loader v4

* Use our static file rendering machanism to serve pages.
This should work well since the file path for a page is predictable.

* Release 5.0.0-universal-alpha.3

* Remove optional loaders

* Release 5.0.0-universal-alpha.4

* Remove clientBootstrap

* Remove renderScript

* Make sure pages bundles are served correctly

* Remove unused import

* Revert to using the same code as canary

* Fix hot loader

* Release 5.0.0-universal-alpha.5

* Check if externals dir exist before applying config

* Add typescript support

* Add support for transpiling certain packages in node_modules

Thanks to @giuseppeg’s work in https://github.com/zeit/next.js/pull/3319

* Add BABEL_DISABLE_CACHE support

* Make sourcemaps in production opt-in

* Revert "Add support for transpiling certain packages in node_modules"

This reverts commit d4b1d9babfb4b9ed4f4b12d56d52dee233e862da.

In favor of a better api around this.

* Support typescript through next.config.js

* Remove comments

* Bring back commons.js calculation

* Remove unused dependencies

* Move base.config.js to webpack.js

* Make sure to only invalidate webpackDevMiddleware one after other.

* Allow babel-loder caching by default.

* Add comment about preact support

* Bring back buildir replace

* Remove obsolete plugin

* Remove build replace, speed up build

* Resolve page entries like pages/day/index.js to pages/day.js

* Add componentDidCatch back

* Compile to bundles

* Use config.distDir everywhere

* Make sure the file is an array

* Remove console.log

* Apply optimization to uglifyjs

* Add comment pointing to source

* Create entries the same way in dev and production

* Remove unused and broken pagesGlobPattern

* day/index.js is automatically turned into day.js at build time

* Remove poweredByHeader option

* Load pages with the correct path.

* Release 5.0.0-universal-alpha.6

* Make sure react-dom/server can be overwritten by module-alias

* Only add react-hot-loader babel plugin in dev

* Release 5.0.0-universal-alpha.7

* Revert tests

* Release 5.0.0-universal-alpha.10

* Make sure next/head is working properly.

* Add wepack alias for 'next' back.

* Make sure overriding className in next/head works

* Alias react too

* Add missing r

* Fragment fallback has to wrap the children

* Use min.js

* Remove css.js

* Remove wallaby.js

* Release 5.0.0-universal-alpha.11

* Resolve relative to workdir instead of next

* Make sure we touch the right file

* Resolve next modules

* Remove dotjsx removal plugins since we use webpack on the server

* Revert "Resolve relative to workdir instead of next"

This reverts commit a13f3e4ab565df9e2c9a3dfc8eb4009c0c2e02ed.

* Externalize any locally loaded module lives outside of app dir.

* Remove server aliases

* Check node_modules reliably

* Add symlink to next for tests

* Make sure dynamic imports work locally.
This is why we need it: https://github.com/webpack/webpack/blob/b545b519b2024e3f8be3041385bd326bf5d24449/lib/MainTemplate.js#L68
We need to have the finally clause in the above in __webpack_require__.
webpack output option strictModuleExceptionHandling does that.

* dynmaic -> dynamic

* Remove webpack-node-externals

* Make sure dynamic imports support SSR.

* Remove css support in favor of next-css

* Make sure we load path from `/` since it’s included in the path matching

* Catch when ensurepage couldn’t be fulfilled for `.js.map`

* Register require cache flusher for both client and server

* Add comment explaining this is to facilitate hot reloading

* Only load module when needed

* Remove unused modules

* Release 5.0.0-universal-alpha.12

* Only log the `found babel` message once

* Make sure ondemand entries working correctly.
Now we are just using a single instance of OnDemandEntryHandler.

* Better sourcemaps

* Release 5.0.0-universal-alpha.13

* Lock uglify version to 1.1.6

* Release 5.0.0-universal-alpha.14

* Fix a typo.

* Introduce multi-zones support for mircofrontends

* Add section on css

											
										
										
											2018-01-30 15:40:52 +00:00
-												Update doc for @zeit/next-stylus (#4107)


											
										
										
											2018-04-04 11:18:28 +00:00
+								To support importing `.css`, `.scss`, `.less` or `.styl` files you can use these modules, which configure sensible defaults for server rendered applications.
-												Universal Webpack (#3578)

* Speed up next build

* Document webpack config

* Speed up next build

* Remove comment

* Add comment

* Clean up rules

* Add comments

* Run in parallel

* Push plugins seperately

* Create a new chunk for react

* Don’t uglify react since it’s already uglified. Move react to commons in development

* Use the minified version directly

* Re-add globpattern

* Move loaders into a separate variable

* Add comment linking to Dan’s explanation

* Remove dot

* Add universal webpack

* Initial dev support

* Fix linting

* Add changes from Arunoda's work

* Made next dev works.
But super slow and no HMR support.

* Fix client side hot reload

* Server side hmr

* Only in dev

* Add on-demand-entries client + hot-middleware

* Add .babelrc support

* Speed up on demand entries by running in parallel

* Serve static generated files

* Add missing config in dev

* Add sass support

* Add support for .map

* Add cssloader config and fix .jsx support

* Rename

* use same defaults as css-loader. Fix linting

* Add NoEmitErrorsPlugin

* Add clientBootstrap

* Use webpackhotmiddleware on the multi compiler

* alpha.3

* Use babel 16.2.x

* Fix reloading after error

* Remove comment

* Release 5.0.0-univeral-alpha.1

* Remove check for React 16

* Release 5.0.0-universal-alpha.2

* React hot loader v4

* Use our static file rendering machanism to serve pages.
This should work well since the file path for a page is predictable.

* Release 5.0.0-universal-alpha.3

* Remove optional loaders

* Release 5.0.0-universal-alpha.4

* Remove clientBootstrap

* Remove renderScript

* Make sure pages bundles are served correctly

* Remove unused import

* Revert to using the same code as canary

* Fix hot loader

* Release 5.0.0-universal-alpha.5

* Check if externals dir exist before applying config

* Add typescript support

* Add support for transpiling certain packages in node_modules

Thanks to @giuseppeg’s work in https://github.com/zeit/next.js/pull/3319

* Add BABEL_DISABLE_CACHE support

* Make sourcemaps in production opt-in

* Revert "Add support for transpiling certain packages in node_modules"

This reverts commit d4b1d9babfb4b9ed4f4b12d56d52dee233e862da.

In favor of a better api around this.

* Support typescript through next.config.js

* Remove comments

* Bring back commons.js calculation

* Remove unused dependencies

* Move base.config.js to webpack.js

* Make sure to only invalidate webpackDevMiddleware one after other.

* Allow babel-loder caching by default.

* Add comment about preact support

* Bring back buildir replace

* Remove obsolete plugin

* Remove build replace, speed up build

* Resolve page entries like pages/day/index.js to pages/day.js

* Add componentDidCatch back

* Compile to bundles

* Use config.distDir everywhere

* Make sure the file is an array

* Remove console.log

* Apply optimization to uglifyjs

* Add comment pointing to source

* Create entries the same way in dev and production

* Remove unused and broken pagesGlobPattern

* day/index.js is automatically turned into day.js at build time

* Remove poweredByHeader option

* Load pages with the correct path.

* Release 5.0.0-universal-alpha.6

* Make sure react-dom/server can be overwritten by module-alias

* Only add react-hot-loader babel plugin in dev

* Release 5.0.0-universal-alpha.7

* Revert tests

* Release 5.0.0-universal-alpha.10

* Make sure next/head is working properly.

* Add wepack alias for 'next' back.

* Make sure overriding className in next/head works

* Alias react too

* Add missing r

* Fragment fallback has to wrap the children

* Use min.js

* Remove css.js

* Remove wallaby.js

* Release 5.0.0-universal-alpha.11

* Resolve relative to workdir instead of next

* Make sure we touch the right file

* Resolve next modules

* Remove dotjsx removal plugins since we use webpack on the server

* Revert "Resolve relative to workdir instead of next"

This reverts commit a13f3e4ab565df9e2c9a3dfc8eb4009c0c2e02ed.

* Externalize any locally loaded module lives outside of app dir.

* Remove server aliases

* Check node_modules reliably

* Add symlink to next for tests

* Make sure dynamic imports work locally.
This is why we need it: https://github.com/webpack/webpack/blob/b545b519b2024e3f8be3041385bd326bf5d24449/lib/MainTemplate.js#L68
We need to have the finally clause in the above in __webpack_require__.
webpack output option strictModuleExceptionHandling does that.

* dynmaic -> dynamic

* Remove webpack-node-externals

* Make sure dynamic imports support SSR.

* Remove css support in favor of next-css

* Make sure we load path from `/` since it’s included in the path matching

* Catch when ensurepage couldn’t be fulfilled for `.js.map`

* Register require cache flusher for both client and server

* Add comment explaining this is to facilitate hot reloading

* Only load module when needed

* Remove unused modules

* Release 5.0.0-universal-alpha.12

* Only log the `found babel` message once

* Make sure ondemand entries working correctly.
Now we are just using a single instance of OnDemandEntryHandler.

* Better sourcemaps

* Release 5.0.0-universal-alpha.13

* Lock uglify version to 1.1.6

* Release 5.0.0-universal-alpha.14

* Fix a typo.

* Introduce multi-zones support for mircofrontends

* Add section on css

											
										
										
											2018-01-30 15:40:52 +00:00
-												Fix links for next css (#3820)


											
										
										
											2018-02-16 07:41:40 +00:00
+								- [@zeit/next-css](https://github.com/zeit/next-plugins/tree/master/packages/next-css)
 								- [@zeit/next-sass](https://github.com/zeit/next-plugins/tree/master/packages/next-sass)
 								- [@zeit/next-less](https://github.com/zeit/next-plugins/tree/master/packages/next-less)
-												Update doc for @zeit/next-stylus (#4107)


											
										
										
											2018-04-04 11:18:28 +00:00
+								- [@zeit/next-stylus](https://github.com/zeit/next-plugins/tree/master/packages/next-stylus)
-												Universal Webpack (#3578)

* Speed up next build

* Document webpack config

* Speed up next build

* Remove comment

* Add comment

* Clean up rules

* Add comments

* Run in parallel

* Push plugins seperately

* Create a new chunk for react

* Don’t uglify react since it’s already uglified. Move react to commons in development

* Use the minified version directly

* Re-add globpattern

* Move loaders into a separate variable

* Add comment linking to Dan’s explanation

* Remove dot

* Add universal webpack

* Initial dev support

* Fix linting

* Add changes from Arunoda's work

* Made next dev works.
But super slow and no HMR support.

* Fix client side hot reload

* Server side hmr

* Only in dev

* Add on-demand-entries client + hot-middleware

* Add .babelrc support

* Speed up on demand entries by running in parallel

* Serve static generated files

* Add missing config in dev

* Add sass support

* Add support for .map

* Add cssloader config and fix .jsx support

* Rename

* use same defaults as css-loader. Fix linting

* Add NoEmitErrorsPlugin

* Add clientBootstrap

* Use webpackhotmiddleware on the multi compiler

* alpha.3

* Use babel 16.2.x

* Fix reloading after error

* Remove comment

* Release 5.0.0-univeral-alpha.1

* Remove check for React 16

* Release 5.0.0-universal-alpha.2

* React hot loader v4

* Use our static file rendering machanism to serve pages.
This should work well since the file path for a page is predictable.

* Release 5.0.0-universal-alpha.3

* Remove optional loaders

* Release 5.0.0-universal-alpha.4

* Remove clientBootstrap

* Remove renderScript

* Make sure pages bundles are served correctly

* Remove unused import

* Revert to using the same code as canary

* Fix hot loader

* Release 5.0.0-universal-alpha.5

* Check if externals dir exist before applying config

* Add typescript support

* Add support for transpiling certain packages in node_modules

Thanks to @giuseppeg’s work in https://github.com/zeit/next.js/pull/3319

* Add BABEL_DISABLE_CACHE support

* Make sourcemaps in production opt-in

* Revert "Add support for transpiling certain packages in node_modules"

This reverts commit d4b1d9babfb4b9ed4f4b12d56d52dee233e862da.

In favor of a better api around this.

* Support typescript through next.config.js

* Remove comments

* Bring back commons.js calculation

* Remove unused dependencies

* Move base.config.js to webpack.js

* Make sure to only invalidate webpackDevMiddleware one after other.

* Allow babel-loder caching by default.

* Add comment about preact support

* Bring back buildir replace

* Remove obsolete plugin

* Remove build replace, speed up build

* Resolve page entries like pages/day/index.js to pages/day.js

* Add componentDidCatch back

* Compile to bundles

* Use config.distDir everywhere

* Make sure the file is an array

* Remove console.log

* Apply optimization to uglifyjs

* Add comment pointing to source

* Create entries the same way in dev and production

* Remove unused and broken pagesGlobPattern

* day/index.js is automatically turned into day.js at build time

* Remove poweredByHeader option

* Load pages with the correct path.

* Release 5.0.0-universal-alpha.6

* Make sure react-dom/server can be overwritten by module-alias

* Only add react-hot-loader babel plugin in dev

* Release 5.0.0-universal-alpha.7

* Revert tests

* Release 5.0.0-universal-alpha.10

* Make sure next/head is working properly.

* Add wepack alias for 'next' back.

* Make sure overriding className in next/head works

* Alias react too

* Add missing r

* Fragment fallback has to wrap the children

* Use min.js

* Remove css.js

* Remove wallaby.js

* Release 5.0.0-universal-alpha.11

* Resolve relative to workdir instead of next

* Make sure we touch the right file

* Resolve next modules

* Remove dotjsx removal plugins since we use webpack on the server

* Revert "Resolve relative to workdir instead of next"

This reverts commit a13f3e4ab565df9e2c9a3dfc8eb4009c0c2e02ed.

* Externalize any locally loaded module lives outside of app dir.

* Remove server aliases

* Check node_modules reliably

* Add symlink to next for tests

* Make sure dynamic imports work locally.
This is why we need it: https://github.com/webpack/webpack/blob/b545b519b2024e3f8be3041385bd326bf5d24449/lib/MainTemplate.js#L68
We need to have the finally clause in the above in __webpack_require__.
webpack output option strictModuleExceptionHandling does that.

* dynmaic -> dynamic

* Remove webpack-node-externals

* Make sure dynamic imports support SSR.

* Remove css support in favor of next-css

* Make sure we load path from `/` since it’s included in the path matching

* Catch when ensurepage couldn’t be fulfilled for `.js.map`

* Register require cache flusher for both client and server

* Add comment explaining this is to facilitate hot reloading

* Only load module when needed

* Remove unused modules

* Release 5.0.0-universal-alpha.12

* Only log the `found babel` message once

* Make sure ondemand entries working correctly.
Now we are just using a single instance of OnDemandEntryHandler.

* Better sourcemaps

* Release 5.0.0-universal-alpha.13

* Lock uglify version to 1.1.6

* Release 5.0.0-universal-alpha.14

* Fix a typo.

* Introduce multi-zones support for mircofrontends

* Add section on css

											
										
										
											2018-01-30 15:40:52 +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
-												Add alt attributes to examples in readme.md (#4053)


											
										
										
											2018-03-25 10:43:36 +00:00
+								export default () => <img src="/static/my-image.png" alt="my image" />
-												Update README.md
											
										
										
											2016-12-19 21:34:19 +00:00
+								```
-												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
-												Clarify documentation regarding the static folder (#4340)


											
										
										
											2018-05-25 11:42:19 +00:00
+								_Note: Don't name the `static` directory anything else. The name is required and is the only directory that Next.js uses for serving static assets._
-												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'
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								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>
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								)
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
+								```
-												Support de-deduping head tags by setting key (#3170)

* Support de-deduping head tags by setting key

* move dedupe logic to `unique` function

* fix head tag deduping logic

* remove console.log

* use `toContain` assertions

* update de-duping head tags section in README

											
										
										
											2017-10-31 21:52:51 +00:00
+								To avoid duplicate tags in your `<head>` you can use the `key` property, which will make sure the tag is only rendered once:
 								```jsx
 								import Head from 'next/head'
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
-												Support de-deduping head tags by setting key (#3170)

* Support de-deduping head tags by setting key

* move dedupe logic to `unique` function

* fix head tag deduping logic

* remove console.log

* use `toContain` assertions

* update de-duping head tags section in README

											
										
										
											2017-10-31 21:52:51 +00:00
+								export default () => (
 								  <div>
 								    <Head>
 								      <title>My page title</title>
 								      <meta name="viewport" content="initial-scale=1.0, width=device-width" key="viewport" />
 								    </Head>
 								    <Head>
 								      <meta name="viewport" content="initial-scale=1.2, width=device-width" key="viewport" />
 								    </Head>
 								    <p>Hello world!</p>
 								  </div>
 								)
 								```
 								In this case only the second `<meta name="viewport" />` is rendered.
-												Set assetPrefix dynamically (#3661)

* Introduce the setAssetPrefix API for dynamic assetPrefix.

* Remove unwanted node_modules dir in a test dir.

* Change test main description.

											
										
										
											2018-02-02 14:43:36 +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'
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
+								export default class extends React.Component {
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								  static async getInitialProps({ req }) {
 								    const userAgent = req ? req.headers['user-agent'] : navigator.userAgent
 								    return { userAgent }
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
+								  }
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
 								  render() {
 								    return (
 								      <div>
 								        Hello World {this.props.userAgent}
 								      </div>
 								    )
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
+								  }
 								}
 								```
-												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`.
-												Document serialization of data (#3516)

* Document serialization of data

* Add date

											
										
										
											2017-12-29 20:33:49 +00:00
+								Data returned from `getInitialProps` is serialized when server rendering, similar to a `JSON.stringify`. Make sure the returned object from `getInitialProps` is a plain `Object` and not using `Date`, `Map` or `Set`.
-												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 a note about importing server only modules.
											
										
										
											2017-06-29 16:51:23 +00:00
+								<br/>
-												Fix some errors in README.
											
										
										
											2017-06-29 16:57:17 +00:00
-												Add a note about importing server only modules.
											
										
										
											2017-06-29 16:51:23 +00:00
+								> If you are using some server only modules inside `getInitialProps`, make sure to [import them properly](https://arunoda.me/blog/ssr-and-server-only-modules).
 								> Otherwise, it'll slow down your app.
-												Fix some errors in README.
											
										
										
											2017-06-29 16:57:17 +00:00
-												Add a note about importing server only modules.
											
										
										
											2017-06-29 16:51:23 +00:00
+								<br/>
-												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
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								const Page = ({ stars }) =>
 								  <div>
 								    Next stars: {stars}
 								  </div>
-												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
 								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
-												Add/with router (#2870)

* Add withRoute HOC

Rebased (squashed)
- removed routerToProps
- updated hoist-non-react-statics
- improved propTypes

* Expose the whole Router instead of the route.

* Make the example simple.

* Update examples and the readme.

* Add a test case.

											
										
										
											2017-08-30 14:07:12 +00:00
+								- `asPath` - `String` of the actual path (including the query) shows in the browser
-												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
+								- `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'
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								export default () => (
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								  <div>
 								    Click{' '}
 								    <Link href="/about">
 								      <a>here</a>
 								    </Link>{' '}
 								    to read more
 								  </div>
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								)
-												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/about.js
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								export default () => <p>Welcome to About!</p>
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
+								```
-												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
-												fix grammatical error in readme file (#3443)


											
										
										
											2017-12-13 09:49:44 +00:00
+. After 1 and 2 complete, `pushState` is performed and the new component is rendered
-												initial spec

											
										
										
											2016-10-05 23:35:00 +00:00
-												Replace deprecated `props.url` in readme (#4952)

Following https://github.com/zeit/next.js/pull/4950

Fix https://github.com/zeit/next.js/issues/4716

I'm not sure to understand this part, though :
> 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

Is there a difference between :
```jsx
export default () => <a onClick={() => Router.push('/about')}>About</a>
```

and
 
```jsx
export default withRouter(
  () => <a onClick={() => props.router.push('/about')}>About</a>
)
```
?
											
										
										
											2018-08-13 21:38:02 +00:00
+								To inject the `pathname`, `query` or `asPath` in your component, you can use [withRouter](#using-a-higher-order-component).
-												Add deprecate messages for url.replaceTo and url.pushTo (#433)


											
										
										
											2016-12-19 18:49:15 +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
 								<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'
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								export default () => (
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								  <div>
 								    Click{' '}
 								    <Link href={{ pathname: '/about', query: { name: 'Zeit' } }}>
 								      <a>here</a>
 								    </Link>{' '}
 								    to read more
 								  </div>
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +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
+								```
 								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).
-												Document usage of <Link> without <a> (#2369)


											
										
										
											2017-06-27 05:02:30 +00:00
+								##### Replace instead of push url
-												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'
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								export default () => (
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								  <div>
 								    Click{' '}
 								    <Link href="/about" replace>
 								      <a>here</a>
 								    </Link>{' '}
 								    to read more
 								  </div>
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								)
-												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
+								```
-												fix grammatical error in readme file (#3443)


											
										
										
											2017-12-13 09:49:44 +00:00
+								##### Using a component that supports `onClick`
-												Document usage of <Link> without <a> (#2369)


											
										
										
											2017-06-27 05:02:30 +00:00
 								`<Link>` supports any component that supports the `onClick` event. In case you don't provide an `<a>` tag, it will only add the `onClick` event handler and won't pass the `href` property.
 								```jsx
 								// pages/index.js
 								import Link from 'next/link'
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								export default () => (
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								  <div>
 								    Click{' '}
 								    <Link href="/about">
-												Add alt attributes to examples in readme.md (#4053)


											
										
										
											2018-03-25 10:43:36 +00:00
+								      <img src="/static/image.png" alt="image" />
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								    </Link>
 								  </div>
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								)
-												Document usage of <Link> without <a> (#2369)


											
										
										
											2017-06-27 05:02:30 +00:00
+								```
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								##### Forcing the Link to expose `href` to its child
-												fix: Forces Link to expose the href to the child using passHref property. (#2503)

* Forces Link to exposes the href to the child using passHref property.

* tests for passHref prop of the Link

* passHref property Link documentation

											
										
										
											2017-07-09 05:09:02 +00:00
-												Hyperlink spelling (#2616)


											
										
										
											2017-07-21 11:19:22 +00:00
+								If child is an `<a>` tag and doesn't have a href attribute we specify it so that the repetition is not needed by the user. However, sometimes, you’ll want to pass an `<a>` tag inside of a wrapper and the `Link` won’t recognize it as a *hyperlink*, and, consequently, won’t transfer its `href` to the child. In cases like that, you should define a boolean `passHref` property to the `Link`, forcing it to expose its `href` property to the child.
-												fix: Forces Link to expose the href to the child using passHref property. (#2503)

* Forces Link to exposes the href to the child using passHref property.

* tests for passHref prop of the Link

* passHref property Link documentation

											
										
										
											2017-07-09 05:09:02 +00:00
-												doc'd fs-routing option & added note on `passHref` (#3384)

2 changes:

`passHref` - just added a cautionary note on the importance of `passHref`. We had a few days of no-href links on our site b/c we used a custom component instead of a raw `<a>` tag,  and Google bot wasn't crawling our links (confirmed in Google cache). Hurt our SEO a bit, so I thought it was worth noting.


`useFileSystemPublicRoutes` - this is mentioned in https://github.com/zeit/next.js/pull/914 , but it doesn't appear any doc was actually added. We use `next-routes`, and we were serving all the files in `/pages/` in addition to their route patterns (ie duplicate content), which can be a pain w/ SEO and duplicate content.
											
										
										
											2017-12-03 23:01:48 +00:00
+								**Please note**: using a tag other than `a` and failing to pass `passHref` may result in links that appear to navigate correctly, but, when being crawled by search engines, will not be recognized as links (owing to the lack of `href` attribute). This may result in negative effects on your sites SEO.
-												fix: Forces Link to expose the href to the child using passHref property. (#2503)

* Forces Link to exposes the href to the child using passHref property.

* tests for passHref prop of the Link

* passHref property Link documentation

											
										
										
											2017-07-09 05:09:02 +00:00
+								```jsx
 								import Link from 'next/link'
 								import Unexpected_A from 'third-library'
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								export default ({ href, name }) => (
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								  <Link href={href} passHref>
 								    <Unexpected_A>
 								      {name}
 								    </Unexpected_A>
-												fix: Forces Link to expose the href to the child using passHref property. (#2503)

* Forces Link to exposes the href to the child using passHref property.

* tests for passHref prop of the Link

* passHref property Link documentation

											
										
										
											2017-07-09 05:09:02 +00:00
+								  </Link>
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								)
-												fix: Forces Link to expose the href to the child using passHref property. (#2503)

* Forces Link to exposes the href to the child using passHref property.

* tests for passHref prop of the Link

* passHref property Link documentation

											
										
										
											2017-07-09 05:09:02 +00:00
+								```
-												Update readme.md (#3957)

Update readme for scroll props related to #3950
											
										
										
											2018-03-07 07:38:11 +00:00
+								##### Disabling the scroll changes to top on page
 								The default behaviour of `<Link>` is to scroll to the top of the page. When there is a hash defined it will scroll to the specific id, just like a normal `<a>` tag. To prevent scrolling to the top / hash `scroll={false}` can be added to `<Link>`:
 								```jsx
 								<Link scroll={false} href="/?counter=10"><a>Disables scrolling</a></Link>
 								<Link href="/?counter=10"><a>Changes with scrolling to top</a></Link>
 								```
-												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'
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								export default () => (
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								  <div>
 								    Click <span onClick={() => Router.push('/about')}>here</span> to read more
 								  </div>
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +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
+								```
-												Add Router method to execute custom logic before popstate events (#3956)

* Add router method to inject code before popstate events

* Default _beforePopState, return true

* Fix link in README

* Re-order `if` statements per feedback

											
										
										
											2018-03-31 14:21:51 +00:00
+								#### Intercepting `popstate`
 								In some cases (for example, if using a [custom router](#custom-server-and-routing)), you may wish
-												Link to popstate doc on MDN (#4150)


											
										
										
											2018-04-13 10:29:35 +00:00
+								to listen to [`popstate`](https://developer.mozilla.org/en-US/docs/Web/Events/popstate) and react before the router acts on it.
-												Add Router method to execute custom logic before popstate events (#3956)

* Add router method to inject code before popstate events

* Default _beforePopState, return true

* Fix link in README

* Re-order `if` statements per feedback

											
										
										
											2018-03-31 14:21:51 +00:00
+								For example, you could use this to manipulate the request, or force an SSR refresh.
 								```jsx
 								import Router from 'next/router'
 								Router.beforePopState(({ url, as, options }) => {
 								  // I only want to allow these two routes!
 								  if (as !== "/" || as !== "/other") {
 								    // Have SSR render bad routes as a 404.
 								    window.location.href = as
 								    return false
 								  }
 								  return true
 								});
 								```
 								If you return a falsy value from `beforePopState`, `Router` will not handle `popstate`;
 								you'll be responsible for handling it, in that case.
 								See [Disabling File-System Routing](#disabling-file-system-routing).
-												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/with router (#2870)

* Add withRoute HOC

Rebased (squashed)
- removed routerToProps
- updated hoist-non-react-statics
- improved propTypes

* Expose the whole Router instead of the route.

* Make the example simple.

* Update examples and the readme.

* Add a test case.

											
										
										
											2017-08-30 14:07:12 +00:00
+								- `asPath` - `String` of the actual path (including the query) shows in the browser
-												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
-												Add Router method to execute custom logic before popstate events (#3956)

* Add router method to inject code before popstate events

* Default _beforePopState, return true

* Fix link in README

* Re-order `if` statements per feedback

											
										
										
											2018-03-31 14:21:51 +00:00
+								- `beforePopState(cb=function)` - intercept popstate before router processes the event.
-												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
-												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
-												Fix grammatical errors in readme.md (#4199)


											
										
										
											2018-04-23 18:17:27 +00:00
+								You can use an URL object the same way you use it in a `<Link>` component to `push` and `replace` an URL.
-												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
 								```jsx
 								import Router from 'next/router'
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								const handler = () => {
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								  Router.push({
 								    pathname: '/about',
 								    query: { name: 'Zeit' }
 								  })
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +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
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								export default () => (
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								  <div>
 								    Click <span onClick={handler}>here</span> to read more
 								  </div>
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +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
+								```
-												Fix grammatical errors in readme.md (#4199)


											
										
										
											2018-04-23 18:17:27 +00:00
+								This uses the same exact parameters as in the `<Link>` component.
-												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
-												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:
-												Support `events` emitter for router (#4726)

Fixes #4679 
* Document usage of `events` router property
* Expose `events` in the `router` context object
											
										
										
											2018-07-05 12:41:18 +00:00
+								- `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
 								- `hashChangeStart(url)` - Fires when the hash will change but not the page
 								- `hashChangeComplete(url)` - Fires when the hash has changed but not the page
-												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`.
-												Support `events` emitter for router (#4726)

Fixes #4679 
* Document usage of `events` router property
* Expose `events` in the `router` context object
											
										
										
											2018-07-05 12:41:18 +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
-												Support `events` emitter for router (#4726)

Fixes #4679 
* Document usage of `events` router property
* Expose `events` in the `router` context object
											
										
										
											2018-07-05 12:41:18 +00:00
+								const handleRouteChange = url => {
-												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
+								  console.log('App is changing to: ', url)
 								}
-												Support `events` emitter for router (#4726)

Fixes #4679 
* Document usage of `events` router property
* Expose `events` in the `router` context object
											
										
										
											2018-07-05 12:41:18 +00:00
 								Router.events.on('routeChangeStart', handleRouteChange)
-												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
+								```
-												Support `events` emitter for router (#4726)

Fixes #4679 
* Document usage of `events` router property
* Expose `events` in the `router` context object
											
										
										
											2018-07-05 12:41:18 +00:00
+								If you no longer want to listen to that event, you can unsubscribe with the `off` method:
-												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
-												Support `events` emitter for router (#4726)

Fixes #4679 
* Document usage of `events` router property
* Expose `events` in the `router` context object
											
										
										
											2018-07-05 12:41:18 +00:00
+								Router.events.off('routeChangeStart', handleRouteChange)
-												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
+								```
-												fix grammatical error in readme file (#3443)


											
										
										
											2017-12-13 09:49:44 +00:00
+								If a route load is cancelled (for example by clicking two links rapidly in succession), `routeChangeError` will fire. The passed `err` will contain 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
-												Support `events` emitter for router (#4726)

Fixes #4679 
* Document usage of `events` router property
* Expose `events` in the `router` context object
											
										
										
											2018-07-05 12:41:18 +00:00
+								Router.events.on('routeChangeError', (err, url) => {
-												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
+								  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
+								  }
-												Support `events` emitter for router (#4726)

Fixes #4679 
* Document usage of `events` router property
* Expose `events` in the `router` context object
											
										
										
											2018-07-05 12:41:18 +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
+								```
-												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
-												Fix typo in Shallow Routing doc (#1593)


											
										
										
											2017-04-02 07:28:39 +00:00
+								You can do this by invoking either `Router.push` or `Router.replace` with the `shallow: true` option. Here's an example:
-												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
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								```js
-												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 })
 								```
-												Fix shallow routing examples using old React lifecycle and deprecated `props.url` (#4950)

* replace componentWillReceiveProps by componentDidUpdate

* replace props.url by withRouter HOC

* fix deprecated `props.url` in with-shallow-routing example

											
										
										
											2018-08-13 18:09:45 +00:00
+								Now, the URL is updated to `/?counter=10`. You can see the updated URL with `this.props.router.query` inside the `Component` (make sure you are using [`withRouter`](#using-a-higher-order-component) around your `Component` to inject the `router` prop).
-												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
-												Fix shallow routing examples using old React lifecycle and deprecated `props.url` (#4950)

* replace componentWillReceiveProps by componentDidUpdate

* replace props.url by withRouter HOC

* fix deprecated `props.url` in with-shallow-routing example

											
										
										
											2018-08-13 18:09:45 +00:00
+								You can watch for URL changes via [`componentDidUpdate`](https://reactjs.org/docs/react-component.html#componentdidupdate) 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
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								```js
-												Fix shallow routing examples using old React lifecycle and deprecated `props.url` (#4950)

* replace componentWillReceiveProps by componentDidUpdate

* replace props.url by withRouter HOC

* fix deprecated `props.url` in with-shallow-routing example

											
										
										
											2018-08-13 18:09:45 +00:00
+								componentDidUpdate(prevProps) {
 								  const { pathname, query } = this.props.router
 								  // verify props have changed to avoid an infinite loop
 								  if (query.id !== prevProps.router.query.id) {
 								    // fetch data based on the new query
 								  }
-												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
+								}
 								```
 								> NOTES:
-												Add reference to deployment wiki page (#1423)


											
										
										
											2017-03-15 02:38:00 +00:00
+								>
-												Small grammar mistake (#3930)

"Let's assume we've another page called..." correct way to say it is "we have". Just a small correction.
											
										
										
											2018-03-04 15:09:06 +00:00
+								> Shallow routing works **only** for same page URL changes. For an example, let's assume we have 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
-												fix mistake in docs (#4013)


											
										
										
											2018-03-15 05:00:29 +00:00
+								> Router.push('/?counter=10', '/about?counter=10', { shallow: true })
-												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
+								> ```
-												Fixed typo in README (#1784)

In Shallow Routing, the line `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.` is missing the word `though`.
											
										
										
											2017-04-26 11:24:46 +00:00
+								> Since that's a new page, it'll unload the current page, load the new one and call `getInitialProps` even though 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
-												Add/with router (#2870)

* Add withRoute HOC

Rebased (squashed)
- removed routerToProps
- updated hoist-non-react-statics
- improved propTypes

* Expose the whole Router instead of the route.

* Make the example simple.

* Update examples and the readme.

* Add a test case.

											
										
										
											2017-08-30 14:07:12 +00:00
+								#### Using a Higher Order Component
 								<p><details>
 								  <summary><b>Examples</b></summary>
 								  <ul>
 								    <li><a href="./examples/using-with-router">Using the `withRouter` utility</a></li>
 								  </ul>
 								</details></p>
 								If you want to access the `router` object inside any component in your app, you can use the `withRouter` Higher-Order Component. Here's how to use it:
 								```jsx
 								import { withRouter } from 'next/router'
 								const ActiveLink = ({ children, router, href }) => {
 								  const style = {
 								    marginRight: 10,
 								    color: router.pathname === href? 'red' : 'black'
 								  }
 								  const handleClick = (e) => {
 								    e.preventDefault()
 								    router.push(href)
 								  }
 								  return (
 								    <a href={href} onClick={handleClick} style={style}>
 								      {children}
 								    </a>
 								  )
 								}
 								export default withRouter(ActiveLink)
 								```
 								The above `router` object comes with an API similar to [`next/router`](#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
+								### Prefetching Pages
-												⚠️ prefetch is a production only feature ⚠️ (#3851)

I was wondering why I couldn't see the prefetch network request.
Turns out I wasn't forwarding the property to the next router nor I was running the application in production.
											
										
										
											2018-02-20 13:24:51 +00:00
+								⚠️ This is a production only feature ⚠️
-												Update prefetch docs and mention it's production only. (#1324)


											
										
										
											2017-03-01 16:54:41 +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>
-												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
-												"download" to "downloads" when subject is singular (#3140)


											
										
										
											2017-10-21 14:59:16 +00:00
+								> With prefetching Next.js only downloads JS code. When the page is getting rendered, you may need to wait for the data.
-												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
-												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
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								export default () => (
-												Update README.md
											
										
										
											2016-12-17 19:16:22 +00:00
+								  <nav>
 								    <ul>
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								      <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>
-												Update README.md
											
										
										
											2016-12-17 19:16:22 +00:00
+								    </ul>
 								  </nav>
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +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-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
-												Replace deprecated `props.url` in readme (#4952)

Following https://github.com/zeit/next.js/pull/4950

Fix https://github.com/zeit/next.js/issues/4716

I'm not sure to understand this part, though :
> 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

Is there a difference between :
```jsx
export default () => <a onClick={() => Router.push('/about')}>About</a>
```

and
 
```jsx
export default withRouter(
  () => <a onClick={() => props.router.push('/about')}>About</a>
)
```
?
											
										
										
											2018-08-13 21:38:02 +00:00
+								import { withRouter } from 'next/router'
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								export default withRouter(({ router }) => (
-												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>
-												Replace deprecated `props.url` in readme (#4952)

Following https://github.com/zeit/next.js/pull/4950

Fix https://github.com/zeit/next.js/issues/4716

I'm not sure to understand this part, though :
> 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

Is there a difference between :
```jsx
export default () => <a onClick={() => Router.push('/about')}>About</a>
```

and
 
```jsx
export default withRouter(
  () => <a onClick={() => props.router.push('/about')}>About</a>
)
```
?
											
										
										
											2018-08-13 21:38:02 +00:00
+								    <a onClick={() => setTimeout(() => router.push('/dynamic'), 100)}>
-												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
+								      A route transition will happen after 100ms
 								    </a>
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								    {// but we can prefetch it!
-												Replace deprecated `props.url` in readme (#4952)

Following https://github.com/zeit/next.js/pull/4950

Fix https://github.com/zeit/next.js/issues/4716

I'm not sure to understand this part, though :
> 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

Is there a difference between :
```jsx
export default () => <a onClick={() => Router.push('/about')}>About</a>
```

and
 
```jsx
export default withRouter(
  () => <a onClick={() => props.router.push('/about')}>About</a>
)
```
?
											
										
										
											2018-08-13 21:38:02 +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>
-												Replace deprecated `props.url` in readme (#4952)

Following https://github.com/zeit/next.js/pull/4950

Fix https://github.com/zeit/next.js/issues/4716

I'm not sure to understand this part, though :
> 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

Is there a difference between :
```jsx
export default () => <a onClick={() => Router.push('/about')}>About</a>
```

and
 
```jsx
export default withRouter(
  () => <a onClick={() => props.router.push('/about')}>About</a>
)
```
?
											
										
										
											2018-08-13 21:38:02 +00:00
+								)
-												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
-												Improve route prefetch docs: add client side imperative code (#4213)

I stumbled into this Issue https://github.com/zeit/next.js/issues/2868 and thought it should be mentioned properly in the documentation.
											
										
										
											2018-05-25 12:26:45 +00:00
+								The router instance should be only used inside the client side of your app though. In order to prevent any error regarding this subject, when rendering the Router on the server side, use the imperatively prefetch method in the `componentDidMount()` lifecycle method.
 								```jsx
 								import React from 'react'
-												Replace deprecated `props.url` in readme (#4952)

Following https://github.com/zeit/next.js/pull/4950

Fix https://github.com/zeit/next.js/issues/4716

I'm not sure to understand this part, though :
> 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

Is there a difference between :
```jsx
export default () => <a onClick={() => Router.push('/about')}>About</a>
```

and
 
```jsx
export default withRouter(
  () => <a onClick={() => props.router.push('/about')}>About</a>
)
```
?
											
										
										
											2018-08-13 21:38:02 +00:00
+								import { withRouter } from 'next/router'
-												Improve route prefetch docs: add client side imperative code (#4213)

I stumbled into this Issue https://github.com/zeit/next.js/issues/2868 and thought it should be mentioned properly in the documentation.
											
										
										
											2018-05-25 12:26:45 +00:00
-												Replace deprecated `props.url` in readme (#4952)

Following https://github.com/zeit/next.js/pull/4950

Fix https://github.com/zeit/next.js/issues/4716

I'm not sure to understand this part, though :
> 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

Is there a difference between :
```jsx
export default () => <a onClick={() => Router.push('/about')}>About</a>
```

and
 
```jsx
export default withRouter(
  () => <a onClick={() => props.router.push('/about')}>About</a>
)
```
?
											
										
										
											2018-08-13 21:38:02 +00:00
+								class MyLink extends React.Component {
-												Improve route prefetch docs: add client side imperative code (#4213)

I stumbled into this Issue https://github.com/zeit/next.js/issues/2868 and thought it should be mentioned properly in the documentation.
											
										
										
											2018-05-25 12:26:45 +00:00
+								  componentDidMount() {
-												Replace deprecated `props.url` in readme (#4952)

Following https://github.com/zeit/next.js/pull/4950

Fix https://github.com/zeit/next.js/issues/4716

I'm not sure to understand this part, though :
> 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

Is there a difference between :
```jsx
export default () => <a onClick={() => Router.push('/about')}>About</a>
```

and
 
```jsx
export default withRouter(
  () => <a onClick={() => props.router.push('/about')}>About</a>
)
```
?
											
										
										
											2018-08-13 21:38:02 +00:00
+								    const { router } = this.props
 								    router.prefetch('/dynamic')
-												Improve route prefetch docs: add client side imperative code (#4213)

I stumbled into this Issue https://github.com/zeit/next.js/issues/2868 and thought it should be mentioned properly in the documentation.
											
										
										
											2018-05-25 12:26:45 +00:00
+								  }
 								  render() {
-												Replace deprecated `props.url` in readme (#4952)

Following https://github.com/zeit/next.js/pull/4950

Fix https://github.com/zeit/next.js/issues/4716

I'm not sure to understand this part, though :
> 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

Is there a difference between :
```jsx
export default () => <a onClick={() => Router.push('/about')}>About</a>
```

and
 
```jsx
export default withRouter(
  () => <a onClick={() => props.router.push('/about')}>About</a>
)
```
?
											
										
										
											2018-08-13 21:38:02 +00:00
+								    const { router } = this.props
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
-												Improve route prefetch docs: add client side imperative code (#4213)

I stumbled into this Issue https://github.com/zeit/next.js/issues/2868 and thought it should be mentioned properly in the documentation.
											
										
										
											2018-05-25 12:26:45 +00:00
+								    return (
 								       <div>
-												Replace deprecated `props.url` in readme (#4952)

Following https://github.com/zeit/next.js/pull/4950

Fix https://github.com/zeit/next.js/issues/4716

I'm not sure to understand this part, though :
> 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

Is there a difference between :
```jsx
export default () => <a onClick={() => Router.push('/about')}>About</a>
```

and
 
```jsx
export default withRouter(
  () => <a onClick={() => props.router.push('/about')}>About</a>
)
```
?
											
										
										
											2018-08-13 21:38:02 +00:00
+								        <a onClick={() => setTimeout(() => router.push('/dynamic'), 100)}>
-												Improve route prefetch docs: add client side imperative code (#4213)

I stumbled into this Issue https://github.com/zeit/next.js/issues/2868 and thought it should be mentioned properly in the documentation.
											
										
										
											2018-05-25 12:26:45 +00:00
+								          A route transition will happen after 100ms
 								        </a>
 								      </div>
 								    )
 								  }
 								}
-												Replace deprecated `props.url` in readme (#4952)

Following https://github.com/zeit/next.js/pull/4950

Fix https://github.com/zeit/next.js/issues/4716

I'm not sure to understand this part, though :
> 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

Is there a difference between :
```jsx
export default () => <a onClick={() => Router.push('/about')}>About</a>
```

and
 
```jsx
export default withRouter(
  () => <a onClick={() => props.router.push('/about')}>About</a>
)
```
?
											
										
										
											2018-08-13 21:38:02 +00:00
 								export default withRouter(MyLink)
-												Improve route prefetch docs: add client side imperative code (#4213)

I stumbled into this Issue https://github.com/zeit/next.js/issues/2868 and thought it should be mentioned properly in the documentation.
											
										
										
											2018-05-25 12:26:45 +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
-												Add check for writeable directory (#3370)

* Add check for writeable directory

Followup of https://github.com/zeit/now-cli/issues/175

* Add link to docs

											
										
										
											2017-12-02 17:13:39 +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.
 								When using a custom server with a server file, for example called `server.js`, make sure you update the scripts key in `package.json` to:
 								```json
 								{
 								  "scripts": {
 								    "dev": "node server.js",
 								    "build": "next build",
 								    "start": "NODE_ENV=production node server.js"
 								  }
 								}
 								```
-												Update README.md
											
										
										
											2016-12-20 19:19:03 +00:00
 								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
-												[DOC] typo in readme: double negation is probably unintended (#3658)


											
										
										
											2018-02-02 19:12:37 +00:00
+								// This file doesn't go through babel or webpack transformation.
-												make clear that server.js doesn't go through Webpack or Babel (#3090)


											
										
										
											2017-10-14 17:08:30 +00:00
+								// Make sure the syntax and sources this file requires are compatible with the current node version you are running
 								// See https://github.com/zeit/next.js/issues/1245 for discussions on Universal Webpack or universal Babel
-												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
+								    }
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								  }).listen(3000, err => {
-												Update README.md
											
										
										
											2016-12-20 19:19:03 +00:00
+								    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:
 								- `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`
-												Add next configuration as an option for custom servers (#2058)

* Add a configuration parameter to custom server startup

* Adding related documentation

* Do not access filesystem if configuration is supplied

* Make the configuration log clearer

* Make the conf default value to `null`

											
										
										
											2017-05-31 08:06:07 +00:00
+								- `conf` (`object`) the same object you would use in `next.config.js` - default `{}`
-												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`.
-												doc'd fs-routing option & added note on `passHref` (#3384)

2 changes:

`passHref` - just added a cautionary note on the importance of `passHref`. We had a few days of no-href links on our site b/c we used a custom component instead of a raw `<a>` tag,  and Google bot wasn't crawling our links (confirmed in Google cache). Hurt our SEO a bit, so I thought it was worth noting.


`useFileSystemPublicRoutes` - this is mentioned in https://github.com/zeit/next.js/pull/914 , but it doesn't appear any doc was actually added. We use `next-routes`, and we were serving all the files in `/pages/` in addition to their route patterns (ie duplicate content), which can be a pain w/ SEO and duplicate content.
											
										
										
											2017-12-03 23:01:48 +00:00
+								#### Disabling file-system routing
-												fix typo in readme.md (#3385)


											
										
										
											2017-12-04 16:14:19 +00:00
+								By default, `Next` will serve each file in `/pages` under a pathname matching the filename (eg, `/pages/some-file.js` is served at `site.com/some-file`.
-												doc'd fs-routing option & added note on `passHref` (#3384)

2 changes:

`passHref` - just added a cautionary note on the importance of `passHref`. We had a few days of no-href links on our site b/c we used a custom component instead of a raw `<a>` tag,  and Google bot wasn't crawling our links (confirmed in Google cache). Hurt our SEO a bit, so I thought it was worth noting.


`useFileSystemPublicRoutes` - this is mentioned in https://github.com/zeit/next.js/pull/914 , but it doesn't appear any doc was actually added. We use `next-routes`, and we were serving all the files in `/pages/` in addition to their route patterns (ie duplicate content), which can be a pain w/ SEO and duplicate content.
											
										
										
											2017-12-03 23:01:48 +00:00
-												Set assetPrefix dynamically (#3661)

* Introduce the setAssetPrefix API for dynamic assetPrefix.

* Remove unwanted node_modules dir in a test dir.

* Change test main description.

											
										
										
											2018-02-02 14:43:36 +00:00
+								If your project uses custom routing, this behavior may result in the same content being served from multiple paths, which can present problems with SEO and UX.
-												doc'd fs-routing option & added note on `passHref` (#3384)

2 changes:

`passHref` - just added a cautionary note on the importance of `passHref`. We had a few days of no-href links on our site b/c we used a custom component instead of a raw `<a>` tag,  and Google bot wasn't crawling our links (confirmed in Google cache). Hurt our SEO a bit, so I thought it was worth noting.


`useFileSystemPublicRoutes` - this is mentioned in https://github.com/zeit/next.js/pull/914 , but it doesn't appear any doc was actually added. We use `next-routes`, and we were serving all the files in `/pages/` in addition to their route patterns (ie duplicate content), which can be a pain w/ SEO and duplicate content.
											
										
										
											2017-12-03 23:01:48 +00:00
-												Set assetPrefix dynamically (#3661)

* Introduce the setAssetPrefix API for dynamic assetPrefix.

* Remove unwanted node_modules dir in a test dir.

* Change test main description.

											
										
										
											2018-02-02 14:43:36 +00:00
+								To disable this behavior & prevent routing based on files in `/pages`, simply set the following option in your `next.config.js`:
-												doc'd fs-routing option & added note on `passHref` (#3384)

2 changes:

`passHref` - just added a cautionary note on the importance of `passHref`. We had a few days of no-href links on our site b/c we used a custom component instead of a raw `<a>` tag,  and Google bot wasn't crawling our links (confirmed in Google cache). Hurt our SEO a bit, so I thought it was worth noting.


`useFileSystemPublicRoutes` - this is mentioned in https://github.com/zeit/next.js/pull/914 , but it doesn't appear any doc was actually added. We use `next-routes`, and we were serving all the files in `/pages/` in addition to their route patterns (ie duplicate content), which can be a pain w/ SEO and duplicate content.
											
										
										
											2017-12-03 23:01:48 +00:00
 								```js
 								// next.config.js
 								module.exports = {
 								  useFileSystemPublicRoutes: false
 								}
 								```
-												Add Router method to execute custom logic before popstate events (#3956)

* Add router method to inject code before popstate events

* Default _beforePopState, return true

* Fix link in README

* Re-order `if` statements per feedback

											
										
										
											2018-03-31 14:21:51 +00:00
+								Note that `useFileSystemPublicRoutes` simply disables filename routes from SSR; client-side routing
 								may still access those paths. If using this option, you should guard against navigation to routes
 								you do not want programmatically.
 								You may also wish to configure the client-side Router to disallow client-side redirects to filename
 								routes; please refer to [Intercepting `popstate`](#intercepting-popstate).
-												Set assetPrefix dynamically (#3661)

* Introduce the setAssetPrefix API for dynamic assetPrefix.

* Remove unwanted node_modules dir in a test dir.

* Change test main description.

											
										
										
											2018-02-02 14:43:36 +00:00
+								#### Dynamic assetPrefix
 								Sometimes we need to set the `assetPrefix` dynamically. This is useful when changing the `assetPrefix` based on incoming requests.
 								For that, we can use `app.setAssetPrefix`.
 								Here's an example usage of it:
 								```js
 								const next = require('next')
 								const micro = require('micro')
 								const dev = process.env.NODE_ENV !== 'production'
 								const app = next({ dev })
-												Fix micro readme example (#4827)

I found mistake on readme
											
										
										
											2018-07-24 11:55:13 +00:00
+								const handleNextRequests = app.getRequestHandler()
-												Set assetPrefix dynamically (#3661)

* Introduce the setAssetPrefix API for dynamic assetPrefix.

* Remove unwanted node_modules dir in a test dir.

* Change test main description.

											
										
										
											2018-02-02 14:43:36 +00:00
 								app.prepare().then(() => {
 								  const server = micro((req, res) => {
 								    // Add assetPrefix support based on the hostname
 								    if (req.headers.host === 'my-app.com') {
 								      app.setAssetPrefix('http://cdn.com/myapp')
 								    } else {
 								      app.setAssetPrefix('')
 								    }
 								    handleNextRequests(req, res)
 								  })
 								  server.listen(port, (err) => {
 								    if (err) {
 								      throw err
 								    }
 								    console.log(`> Ready on http://localhost:${port}`)
 								  })
 								})
 								```
-												doc'd fs-routing option & added note on `passHref` (#3384)

2 changes:

`passHref` - just added a cautionary note on the importance of `passHref`. We had a few days of no-href links on our site b/c we used a custom component instead of a raw `<a>` tag,  and Google bot wasn't crawling our links (confirmed in Google cache). Hurt our SEO a bit, so I thought it was worth noting.


`useFileSystemPublicRoutes` - this is mentioned in https://github.com/zeit/next.js/pull/914 , but it doesn't appear any doc was actually added. We use `next-routes`, and we were serving all the files in `/pages/` in addition to their route patterns (ie duplicate content), which can be a pain w/ SEO and duplicate content.
											
										
										
											2017-12-03 23:01:48 +00:00
-												Add docs.

											
										
										
											2017-04-27 15:56:53 +00:00
+								### Dynamic Import
 								<p><details>
 								  <summary><b>Examples</b></summary>
 								  <ul>
 								    <li><a href="./examples/with-dynamic-import">With Dynamic Import</a></li>
 								  </ul>
 								</details></p>
 								Next.js supports TC39 [dynamic import proposal](https://github.com/tc39/proposal-dynamic-import) for JavaScript.
 								With that, you could import JavaScript modules (inc. React Components) dynamically and work with them.
 								You can think dynamic imports as another way to split your code into manageable chunks.
 								Since Next.js supports dynamic imports with SSR, you could do amazing things with it.
 								Here are a few ways to use dynamic imports.
 								#### 1. Basic Usage (Also does SSR)
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								```jsx
-												Add docs.

											
										
										
											2017-04-27 15:56:53 +00:00
+								import dynamic from 'next/dynamic'
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
-												Use new import syntax in readme examples

											
										
										
											2018-09-29 09:41:03 +00:00
+								const DynamicComponent = dynamic(() => import('../components/hello'))
-												Add docs.

											
										
										
											2017-04-27 15:56:53 +00:00
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								export default () => (
-												Add docs.

											
										
										
											2017-04-27 15:56:53 +00:00
+								  <div>
 								    <Header />
 								    <DynamicComponent />
 								    <p>HOME PAGE is here!</p>
 								  </div>
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								)
-												Add docs.

											
										
										
											2017-04-27 15:56:53 +00:00
+								```
 								#### 2. With Custom Loading Component
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								```jsx
-												Add docs.

											
										
										
											2017-04-27 15:56:53 +00:00
+								import dynamic from 'next/dynamic'
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
-												Use new import syntax in readme examples

											
										
										
											2018-09-29 09:41:03 +00:00
+								const DynamicComponentWithCustomLoading = dynamic(() => import('../components/hello2'), {
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								  loading: () => <p>...</p>
 								})
-												Add docs.

											
										
										
											2017-04-27 15:56:53 +00:00
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								export default () => (
-												Add docs.

											
										
										
											2017-04-27 15:56:53 +00:00
+								  <div>
 								    <Header />
 								    <DynamicComponentWithCustomLoading />
 								    <p>HOME PAGE is here!</p>
 								  </div>
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								)
-												Add docs.

											
										
										
											2017-04-27 15:56:53 +00:00
+								```
 								#### 3. With No SSR
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								```jsx
-												Add docs.

											
										
										
											2017-04-27 15:56:53 +00:00
+								import dynamic from 'next/dynamic'
-												Use new import syntax in readme examples

											
										
										
											2018-09-29 09:41:03 +00:00
+								const DynamicComponentWithNoSSR = dynamic(() => import('../components/hello3'), {
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								  ssr: false
 								})
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								export default () => (
-												Add docs.

											
										
										
											2017-04-27 15:56:53 +00:00
+								  <div>
 								    <Header />
 								    <DynamicComponentWithNoSSR />
 								    <p>HOME PAGE is here!</p>
 								  </div>
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								)
-												Add docs.

											
										
										
											2017-04-27 15:56:53 +00:00
+								```
-												Dynamic component support with multiple modules (#2235)

* Layout ground works for next/async

* Implement the Dynamic Bundle feature.

* Add some test cases.

* Update README.

* Implement props aware dynamic bundle API.

* Update tests and README.

* Add a test case for React Context support.

											
										
										
											2017-06-16 13:19:34 +00:00
+								#### 4. With Multiple Modules At Once
-												Add docs.

											
										
										
											2017-04-27 15:56:53 +00:00
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								```jsx
-												Dynamic component support with multiple modules (#2235)

* Layout ground works for next/async

* Implement the Dynamic Bundle feature.

* Add some test cases.

* Update README.

* Implement props aware dynamic bundle API.

* Update tests and README.

* Add a test case for React Context support.

											
										
										
											2017-06-16 13:19:34 +00:00
+								import dynamic from 'next/dynamic'
 								const HelloBundle = dynamic({
-												[WIP] Webpack 4, react-error-overlay, react-loadable (#4639)

Webpack 4, react-error-overlay, react-loadable (major)
											
										
										
											2018-07-24 09:24:40 +00:00
+								  modules: () => {
-												fix typo in dynamic import with multiple modules (#2344)


											
										
										
											2017-06-22 17:11:54 +00:00
+								    const components = {
-												Use new import syntax in readme examples

											
										
										
											2018-09-29 09:41:03 +00:00
+								      Hello1: () => import('../components/hello1'),
 								      Hello2: () => import('../components/hello2')
-												Dynamic component support with multiple modules (#2235)

* Layout ground works for next/async

* Implement the Dynamic Bundle feature.

* Add some test cases.

* Update README.

* Implement props aware dynamic bundle API.

* Update tests and README.

* Add a test case for React Context support.

											
										
										
											2017-06-16 13:19:34 +00:00
+								    }
 								    return components
 								  },
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								  render: (props, { Hello1, Hello2 }) =>
-												Dynamic component support with multiple modules (#2235)

* Layout ground works for next/async

* Implement the Dynamic Bundle feature.

* Add some test cases.

* Update README.

* Implement props aware dynamic bundle API.

* Update tests and README.

* Add a test case for React Context support.

											
										
										
											2017-06-16 13:19:34 +00:00
+								    <div>
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								      <h1>
 								        {props.title}
 								      </h1>
-												Dynamic component support with multiple modules (#2235)

* Layout ground works for next/async

* Implement the Dynamic Bundle feature.

* Add some test cases.

* Update README.

* Implement props aware dynamic bundle API.

* Update tests and README.

* Add a test case for React Context support.

											
										
										
											2017-06-16 13:19:34 +00:00
+								      <Hello1 />
 								      <Hello2 />
 								    </div>
-												Add docs.

											
										
										
											2017-04-27 15:56:53 +00:00
+								})
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								export default () => <HelloBundle title="Dynamic Bundle" />
-												Add docs.

											
										
										
											2017-04-27 15:56:53 +00:00
+								```
-												Expose app.js (#4129)

* Expose pages/_app.js

* Add tests for _app and _document

* Uncomment deprecation warnings

* Add documentation for _app, improve documentation of _document

* Update docs / test for _document

* Add _document to client compiler in development

* Add missing app.js to comment

* Only warn once

* Add url-deprecated error page

* Combine tests

* Yse same message for all methods of ‘props.url’

* Update docs around _app

* Update documentation

* Quotes

* Update table of contents

											
										
										
											2018-04-12 08:33:22 +00:00
+								### Custom `<App>`
 								<p><details>
 								  <summary><b>Examples</b></summary>
-												Add _app layout example

											
										
										
											2018-04-24 19:30:24 +00:00
+								  <ul><li><a href="./examples/with-app-layout">Using `_app.js` for layout</a></li></ul>
-												Update url for componentDidCatch

											
										
										
											2018-04-23 22:16:22 +00:00
+								  <ul><li><a href="./examples/with-componentdidcatch">Using `_app.js` to override `componentDidCatch`</a></li></ul>
-												Expose app.js (#4129)

* Expose pages/_app.js

* Add tests for _app and _document

* Uncomment deprecation warnings

* Add documentation for _app, improve documentation of _document

* Update docs / test for _document

* Add _document to client compiler in development

* Add missing app.js to comment

* Only warn once

* Add url-deprecated error page

* Combine tests

* Yse same message for all methods of ‘props.url’

* Update docs around _app

* Update documentation

* Quotes

* Update table of contents

											
										
										
											2018-04-12 08:33:22 +00:00
+								</details></p>
-												Fixed typo (#4144)

which allows you can -> which allows you to
											
										
										
											2018-04-12 08:40:32 +00:00
+								Next.js uses the `App` component to initialize pages. You can override it and control the page initialization. Which allows you to do amazing things like:
-												Expose app.js (#4129)

* Expose pages/_app.js

* Add tests for _app and _document

* Uncomment deprecation warnings

* Add documentation for _app, improve documentation of _document

* Update docs / test for _document

* Add _document to client compiler in development

* Add missing app.js to comment

* Only warn once

* Add url-deprecated error page

* Combine tests

* Yse same message for all methods of ‘props.url’

* Update docs around _app

* Update documentation

* Quotes

* Update table of contents

											
										
										
											2018-04-12 08:33:22 +00:00
 								- Persisting layout between page changes
 								- Keeping state when navigating pages
 								- Custom error handling using `componentDidCatch`
 								- Inject additional data into pages (for example by processing GraphQL queries)
 								To override, create the `./pages/_app.js` file and override the App class as shown below:
 								```js
 								import React from 'react'
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								import App, { Container } from 'next/app'
-												Expose app.js (#4129)

* Expose pages/_app.js

* Add tests for _app and _document

* Uncomment deprecation warnings

* Add documentation for _app, improve documentation of _document

* Update docs / test for _document

* Add _document to client compiler in development

* Add missing app.js to comment

* Only warn once

* Add url-deprecated error page

* Combine tests

* Yse same message for all methods of ‘props.url’

* Update docs around _app

* Update documentation

* Quotes

* Update table of contents

											
										
										
											2018-04-12 08:33:22 +00:00
 								export default class MyApp extends App {
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								  static async getInitialProps({ Component, router, ctx }) {
-												Expose app.js (#4129)

* Expose pages/_app.js

* Add tests for _app and _document

* Uncomment deprecation warnings

* Add documentation for _app, improve documentation of _document

* Update docs / test for _document

* Add _document to client compiler in development

* Add missing app.js to comment

* Only warn once

* Add url-deprecated error page

* Combine tests

* Yse same message for all methods of ‘props.url’

* Update docs around _app

* Update documentation

* Quotes

* Update table of contents

											
										
										
											2018-04-12 08:33:22 +00:00
+								    let pageProps = {}
 								    if (Component.getInitialProps) {
 								      pageProps = await Component.getInitialProps(ctx)
 								    }
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								    return { pageProps }
-												Expose app.js (#4129)

* Expose pages/_app.js

* Add tests for _app and _document

* Uncomment deprecation warnings

* Add documentation for _app, improve documentation of _document

* Update docs / test for _document

* Add _document to client compiler in development

* Add missing app.js to comment

* Only warn once

* Add url-deprecated error page

* Combine tests

* Yse same message for all methods of ‘props.url’

* Update docs around _app

* Update documentation

* Quotes

* Update table of contents

											
										
										
											2018-04-12 08:33:22 +00:00
+								  }
 								  render () {
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								    const { Component, pageProps } = this.props
 								    return (
 								      <Container>
 								        <Component {...pageProps} />
 								      </Container>
 								    )
-												Expose app.js (#4129)

* Expose pages/_app.js

* Add tests for _app and _document

* Uncomment deprecation warnings

* Add documentation for _app, improve documentation of _document

* Update docs / test for _document

* Add _document to client compiler in development

* Add missing app.js to comment

* Only warn once

* Add url-deprecated error page

* Combine tests

* Yse same message for all methods of ‘props.url’

* Update docs around _app

* Update documentation

* Quotes

* Update table of contents

											
										
										
											2018-04-12 08:33:22 +00:00
+								  }
 								}
 								```
-												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
-												Expose app.js (#4129)

* Expose pages/_app.js

* Add tests for _app and _document

* Uncomment deprecation warnings

* Add documentation for _app, improve documentation of _document

* Update docs / test for _document

* Add _document to client compiler in development

* Add missing app.js to comment

* Only warn once

* Add url-deprecated error page

* Combine tests

* Yse same message for all methods of ‘props.url’

* Update docs around _app

* Update documentation

* Quotes

* Update table of contents

											
										
										
											2018-04-12 08:33:22 +00:00
+								- Is rendered on the server side
 								- Is used to change the initial server side rendered document markup
 								- Commonly used to implement server side rendering for css-in-js libraries like [styled-components](./examples/with-styled-components), [glamorous](./examples/with-glamorous) or [emotion](with-emotion). [styled-jsx](https://github.com/zeit/styled-jsx) is included with Next.js by default.
-												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
-												Add note about _document being only server side

											
										
										
											2018-03-23 12:50:52 +00:00
+								// _document is only rendered on the server side and not on the client side
 								// Event handlers like onClick can't be added to this file
-												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'
-												Update README.md
											
										
										
											2016-12-19 21:34:19 +00:00
 								export default class MyDocument extends Document {
-												Expose app.js (#4129)

* Expose pages/_app.js

* Add tests for _app and _document

* Uncomment deprecation warnings

* Add documentation for _app, improve documentation of _document

* Update docs / test for _document

* Add _document to client compiler in development

* Add missing app.js to comment

* Only warn once

* Add url-deprecated error page

* Combine tests

* Yse same message for all methods of ‘props.url’

* Update docs around _app

* Update documentation

* Quotes

* Update table of contents

											
										
										
											2018-04-12 08:33:22 +00:00
+								  static async getInitialProps(ctx) {
 								    const initialProps = await Document.getInitialProps(ctx)
 								    return { ...initialProps }
-												Update README.md
											
										
										
											2016-12-19 21:34:19 +00:00
+								  }
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								  render() {
-												Update README.md
											
										
										
											2016-12-19 21:34:19 +00:00
+								    return (
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								      <html>
 								        <Head>
 								          <style>{`body { margin: 0 } /* custom! */`}</style>
 								        </Head>
 								        <body className="custom_class">
 								          <Main />
 								          <NextScript />
 								        </body>
 								      </html>
-												Update README.md
											
										
										
											2016-12-19 21:34:19 +00:00
+								    )
 								  }
 								}
 								```
-												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)
-												Expose app.js (#4129)

* Expose pages/_app.js

* Add tests for _app and _document

* Uncomment deprecation warnings

* Add documentation for _app, improve documentation of _document

* Update docs / test for _document

* Add _document to client compiler in development

* Add missing app.js to comment

* Only warn once

* Add url-deprecated error page

* Combine tests

* Yse same message for all methods of ‘props.url’

* Update docs around _app

* Update documentation

* Quotes

* Update table of contents

											
										
										
											2018-04-12 08:33:22 +00:00
+								__Note: React-components outside of `<Main />` will not be initialised by the browser. Do _not_ add application logic here. If you need shared components in all your pages (like a menu or a toolbar), take a look at the `App` component instead.__
-												#1874  - A warning when using _document.js (#1884)


											
										
										
											2017-05-04 23:44:28 +00:00
-												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
-												Update readme.md (#2412)

The _error.js works only if it is in the /pages folder
											
										
										
											2017-06-30 05:49:16 +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` in the pages folder:
-												Implemented missing pieces for overriding 404 and 500 pages. (#10)


											
										
										
											2016-10-15 22:36:54 +00:00
 								```jsx
 								import React from 'react'
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
-												Reverting default props for errors. (#12)


											
										
										
											2016-10-16 22:44:26 +00:00
+								export default class Error extends React.Component {
-												Change _error.js example to use `err` prop (#3197)

The `jsonPageRes` isn't always there, whereas `err` is, and when used,
provides a consistent statusCode in the client when compared to the
server.
											
										
										
											2017-10-28 07:23:15 +00:00
+								  static getInitialProps({ res, err }) {
 								    const statusCode = res ? res.statusCode : err ? err.statusCode : null;
-												Reverting default props for errors. (#12)


											
										
										
											2016-10-16 22:44:26 +00:00
+								    return { statusCode }
 								  }
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								  render() {
-												Reverting default props for errors. (#12)


											
										
										
											2016-10-16 22:44:26 +00:00
+								    return (
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								      <p>
 								        {this.props.statusCode
 								          ? `An error ${this.props.statusCode} occurred on server`
 								          : 'An error occurred on client'}
 								      </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
+								```
-												Fix spelling of built-in (#2546)


											
										
										
											2017-07-13 06:04:36 +00:00
+								### Reusing the built-in error page
-												Add docs for next/error (#2513)


											
										
										
											2017-07-09 04:54:27 +00:00
-												Fix spelling of built-in (#2546)


											
										
										
											2017-07-13 06:04:36 +00:00
+								If you want to render the built-in error page you can by using `next/error`:
-												Add docs for next/error (#2513)


											
										
										
											2017-07-09 04:54:27 +00:00
 								```jsx
 								import React from 'react'
 								import Error from 'next/error'
-												Dropped isomorphic-fetch in examples in favor of isomorphic-unfetch. (#3230)


											
										
										
											2017-11-04 14:05:16 +00:00
+								import fetch from 'isomorphic-unfetch'
-												Add docs for next/error (#2513)


											
										
										
											2017-07-09 04:54:27 +00:00
 								export default class Page extends React.Component {
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								  static async getInitialProps() {
-												Add docs for next/error (#2513)


											
										
										
											2017-07-09 04:54:27 +00:00
+								    const res = await fetch('https://api.github.com/repos/zeit/next.js')
 								    const statusCode = res.statusCode > 200 ? res.statusCode : false
 								    const json = await res.json()
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
-												Add docs for next/error (#2513)


											
										
										
											2017-07-09 04:54:27 +00:00
+								    return { statusCode, stars: json.stargazers_count }
 								  }
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								  render() {
 								    if (this.props.statusCode) {
 								      return <Error statusCode={this.props.statusCode} />
-												Add docs for next/error (#2513)


											
										
										
											2017-07-09 04:54:27 +00:00
+								    }
 								    return (
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								      <div>
 								        Next stars: {this.props.stars}
 								      </div>
-												Add docs for next/error (#2513)


											
										
										
											2017-07-09 04:54:27 +00:00
+								    )
 								  }
 								}
 								```
 								> If you have created a custom error page you have to import your own `_error` component instead of `next/error`
-												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.
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								```js
-												Update README.md
											
										
										
											2016-12-17 19:04:44 +00:00
+								// next.config.js
 								module.exports = {
 								  /* config options here */
 								}
 								```
-												Allow next.config.js to export a function (#3867)

* Allow next.config.js to export a function

* Expose phases to the configuration function

* Use same value as variable name

* Add next/constants

* Add documentation for config function / phases

* Add constants.js to npm bundle

											
										
										
											2018-02-23 13:42:06 +00:00
+								Or use a function:
 								```js
-												fixed small readme typo (#4083)


											
										
										
											2018-03-30 12:02:36 +00:00
+								module.exports = (phase, {defaultConfig}) => {
-												Show only Spectrum link

											
										
										
											2018-03-11 04:34:07 +00:00
+								  //
-												Allow next.config.js to export a function (#3867)

* Allow next.config.js to export a function

* Expose phases to the configuration function

* Use same value as variable name

* Add next/constants

* Add documentation for config function / phases

* Add constants.js to npm bundle

											
										
										
											2018-02-23 13:42:06 +00:00
+								  // https://github.com/zeit/
 								  return {
 								    /* config options here */
 								  }
 								}
 								```
-												Fix typo in documentation. (#3907)


											
										
										
											2018-02-27 08:36:49 +00:00
+								`phase` is the current context in which the configuration is loaded. You can see all phases here: [constants](./lib/constants.js)
-												Allow next.config.js to export a function (#3867)

* Allow next.config.js to export a function

* Expose phases to the configuration function

* Use same value as variable name

* Add next/constants

* Add documentation for config function / phases

* Add constants.js to npm bundle

											
										
										
											2018-02-23 13:42:06 +00:00
+								Phases can be imported from `next/constants`:
 								```js
 								const {PHASE_DEVELOPMENT_SERVER} = require('next/constants')
-												docs: add missing fat arrow (#4245)


											
										
										
											2018-05-01 20:12:16 +00:00
+								module.exports = (phase, {defaultConfig}) => {
-												Allow next.config.js to export a function (#3867)

* Allow next.config.js to export a function

* Expose phases to the configuration function

* Use same value as variable name

* Add next/constants

* Add documentation for config function / phases

* Add constants.js to npm bundle

											
										
										
											2018-02-23 13:42:06 +00:00
+								  if(phase === PHASE_DEVELOPMENT_SERVER) {
 								    return {
 								      /* development only config options here */
 								    }
 								  }
 								  return {
 								    /* config options for all phases except development here */
 								  }
 								}
 								```
-												Specify a different build directory for #1513 (#1599)

* Update references to `.next`

* Remove console logs and extraneous semi colons

* Remove lint errors

* Update references to .next and update docs

* Update options from nested to flat with `distDir`

* Add integration tests, and update `.gitignore`

* Rename integration folder to dist-dir to match standards

											
										
										
											2017-04-06 10:09:26 +00:00
+								#### Setting a custom build directory
 								You can specify a name to use for a custom build directory. For example, the following config will create a `build` folder instead of a `.next` folder. If no configuration is specified then next will create a `.next` folder.
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								```js
-												Specify a different build directory for #1513 (#1599)

* Update references to `.next`

* Remove console logs and extraneous semi colons

* Remove lint errors

* Update references to .next and update docs

* Update options from nested to flat with `distDir`

* Add integration tests, and update `.gitignore`

* Rename integration folder to dist-dir to match standards

											
										
										
											2017-04-06 10:09:26 +00:00
+								// next.config.js
 								module.exports = {
 								  distDir: 'build'
 								}
 								```
-												Allow etags to be disabled with config option (#3915)

* Allow etags to be disabled with config option

- CR Change: Rename option to generateEtags
- CR Change: Add tests for etag generation
- CR Change: Refactor to use next.config.js
- Update documentation

* Use renderOpts instead of passing nextConfig

											
										
										
											2018-03-13 13:18:59 +00:00
+								#### Disabling etag generation
 								You can disable etag generation for HTML pages depending on your cache strategy. If no configuration is specified then Next will generate etags for every page.
 								```js
 								// next.config.js
 								module.exports = {
 								  generateEtags: false
 								}
 								```
-												Add doc to onDemandEntries configuration (#3030)


											
										
										
											2017-10-05 06:28:15 +00:00
+								#### Configuring the onDemandEntries
 								Next exposes some options that give you some control over how the server will dispose or keep in memories pages built:
 								```js
 								module.exports = {
 								  onDemandEntries: {
 								    // period (in ms) where the server will keep pages in the buffer
 								    maxInactiveAge: 25 * 1000,
 								    // number of pages that should be kept simultaneously without being disposed
 								    pagesBufferLength: 2,
 								  }
 								}
 								```
-												Mention on demand entries are development-only (#3433)

Fixes #3430
											
										
										
											2017-12-10 20:18:17 +00:00
+								This is development-only feature. If you want to cache SSR pages in production, please see [SSR-caching](https://github.com/zeit/next.js/tree/canary/examples/ssr-caching) example.
-												Document pageExtensions

											
										
										
											2018-02-14 16:52:11 +00:00
+								#### Configuring extensions looked for when resolving pages in `pages`
 								Aimed at modules like [`@zeit/next-typescript`](https://github.com/zeit/next-plugins/tree/master/packages/next-typescript), that add support for pages ending in `.ts`. `pageExtensions` allows you to configure the extensions looked for in the `pages` directory when resolving pages.
 								```js
 								// next.config.js
 								module.exports = {
 								  pageExtensions: ['jsx', 'js']
 								}
 								```
-												Allow BUILD_ID to be set using `generateBuildId` (minor) (#3873)

* Allow BUILD_ID to be set in the environment

This makes multi server deploys with Capistrano possible.

* next.config.js generateBuildId support

enable customising the build id via config

* Provide default for generateBuildId

* This is not used

											
										
										
											2018-03-31 14:34:52 +00:00
+								#### Configuring the build ID
 								Next.js uses a constant generated at build time to identify which version of your application is being served. This can cause problems in multi-server deployments when `next build` is ran on every server. In order to keep a static build id between builds you can provide the `generateBuildId` function:
 								```js
 								// next.config.js
 								module.exports = {
 								  generateBuildId: async () => {
 								    // For example get the latest git commit hash here
 								    return 'my-build-id'
 								  }
 								}
 								```
-												Update README.md
											
										
										
											2016-12-17 19:04:44 +00:00
+								### Customizing webpack config
-												Get latest master into v3 (#2139)

* Merge branch 'master' into v3-beta

* Add send back to v3-beta.

											
										
										
											2017-06-02 05:05:04 +00:00
+								<p><details>
 								  <summary><b>Examples</b></summary>
 								  <ul><li><a href="./examples/with-webpack-bundle-analyzer">Custom webpack bundle analyzer</a></li></ul>
 								</details></p>
-												Move build directory outside of server folder (#4565)

The prepares for next-server.

I also took this as an opportunity to get all build directory paths from a single location, as they were previously scattered across webpack/babel plugins and loaders.
											
										
										
											2018-06-14 17:30:14 +00:00
+								Some commonly asked for features are available as modules:
 								- [@zeit/next-css](https://github.com/zeit/next-plugins/tree/master/packages/next-css)
 								- [@zeit/next-sass](https://github.com/zeit/next-plugins/tree/master/packages/next-sass)
 								- [@zeit/next-less](https://github.com/zeit/next-plugins/tree/master/packages/next-less)
 								- [@zeit/next-preact](https://github.com/zeit/next-plugins/tree/master/packages/next-preact)
 								- [@zeit/next-typescript](https://github.com/zeit/next-plugins/tree/master/packages/next-typescript)
 								*Warning: The `webpack` function is executed twice, once for the server and once for the client. This allows you to distinguish between client and server configuration using the `isServer` property*
 								Multiple configurations can be combined together with function composition. For example:
 								```js
 								const withTypescript = require('@zeit/next-typescript')
 								const withSass = require('@zeit/next-sass')
 								module.exports = withTypescript(withSass({
 								  webpack(config, options) {
 								    // Further custom configuration here
 								    return config
 								  }
 								}))
 								```
-												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
-												Move build directory outside of server folder (#4565)

The prepares for next-server.

I also took this as an opportunity to get all build directory paths from a single location, as they were previously scattered across webpack/babel plugins and loaders.
											
										
										
											2018-06-14 17:30:14 +00:00
+								// next.config.js is not transformed by Babel. So you can only use javascript features supported by your version of Node.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
 								module.exports = {
-												Universal Webpack (#3578)

* Speed up next build

* Document webpack config

* Speed up next build

* Remove comment

* Add comment

* Clean up rules

* Add comments

* Run in parallel

* Push plugins seperately

* Create a new chunk for react

* Don’t uglify react since it’s already uglified. Move react to commons in development

* Use the minified version directly

* Re-add globpattern

* Move loaders into a separate variable

* Add comment linking to Dan’s explanation

* Remove dot

* Add universal webpack

* Initial dev support

* Fix linting

* Add changes from Arunoda's work

* Made next dev works.
But super slow and no HMR support.

* Fix client side hot reload

* Server side hmr

* Only in dev

* Add on-demand-entries client + hot-middleware

* Add .babelrc support

* Speed up on demand entries by running in parallel

* Serve static generated files

* Add missing config in dev

* Add sass support

* Add support for .map

* Add cssloader config and fix .jsx support

* Rename

* use same defaults as css-loader. Fix linting

* Add NoEmitErrorsPlugin

* Add clientBootstrap

* Use webpackhotmiddleware on the multi compiler

* alpha.3

* Use babel 16.2.x

* Fix reloading after error

* Remove comment

* Release 5.0.0-univeral-alpha.1

* Remove check for React 16

* Release 5.0.0-universal-alpha.2

* React hot loader v4

* Use our static file rendering machanism to serve pages.
This should work well since the file path for a page is predictable.

* Release 5.0.0-universal-alpha.3

* Remove optional loaders

* Release 5.0.0-universal-alpha.4

* Remove clientBootstrap

* Remove renderScript

* Make sure pages bundles are served correctly

* Remove unused import

* Revert to using the same code as canary

* Fix hot loader

* Release 5.0.0-universal-alpha.5

* Check if externals dir exist before applying config

* Add typescript support

* Add support for transpiling certain packages in node_modules

Thanks to @giuseppeg’s work in https://github.com/zeit/next.js/pull/3319

* Add BABEL_DISABLE_CACHE support

* Make sourcemaps in production opt-in

* Revert "Add support for transpiling certain packages in node_modules"

This reverts commit d4b1d9babfb4b9ed4f4b12d56d52dee233e862da.

In favor of a better api around this.

* Support typescript through next.config.js

* Remove comments

* Bring back commons.js calculation

* Remove unused dependencies

* Move base.config.js to webpack.js

* Make sure to only invalidate webpackDevMiddleware one after other.

* Allow babel-loder caching by default.

* Add comment about preact support

* Bring back buildir replace

* Remove obsolete plugin

* Remove build replace, speed up build

* Resolve page entries like pages/day/index.js to pages/day.js

* Add componentDidCatch back

* Compile to bundles

* Use config.distDir everywhere

* Make sure the file is an array

* Remove console.log

* Apply optimization to uglifyjs

* Add comment pointing to source

* Create entries the same way in dev and production

* Remove unused and broken pagesGlobPattern

* day/index.js is automatically turned into day.js at build time

* Remove poweredByHeader option

* Load pages with the correct path.

* Release 5.0.0-universal-alpha.6

* Make sure react-dom/server can be overwritten by module-alias

* Only add react-hot-loader babel plugin in dev

* Release 5.0.0-universal-alpha.7

* Revert tests

* Release 5.0.0-universal-alpha.10

* Make sure next/head is working properly.

* Add wepack alias for 'next' back.

* Make sure overriding className in next/head works

* Alias react too

* Add missing r

* Fragment fallback has to wrap the children

* Use min.js

* Remove css.js

* Remove wallaby.js

* Release 5.0.0-universal-alpha.11

* Resolve relative to workdir instead of next

* Make sure we touch the right file

* Resolve next modules

* Remove dotjsx removal plugins since we use webpack on the server

* Revert "Resolve relative to workdir instead of next"

This reverts commit a13f3e4ab565df9e2c9a3dfc8eb4009c0c2e02ed.

* Externalize any locally loaded module lives outside of app dir.

* Remove server aliases

* Check node_modules reliably

* Add symlink to next for tests

* Make sure dynamic imports work locally.
This is why we need it: https://github.com/webpack/webpack/blob/b545b519b2024e3f8be3041385bd326bf5d24449/lib/MainTemplate.js#L68
We need to have the finally clause in the above in __webpack_require__.
webpack output option strictModuleExceptionHandling does that.

* dynmaic -> dynamic

* Remove webpack-node-externals

* Make sure dynamic imports support SSR.

* Remove css support in favor of next-css

* Make sure we load path from `/` since it’s included in the path matching

* Catch when ensurepage couldn’t be fulfilled for `.js.map`

* Register require cache flusher for both client and server

* Add comment explaining this is to facilitate hot reloading

* Only load module when needed

* Remove unused modules

* Release 5.0.0-universal-alpha.12

* Only log the `found babel` message once

* Make sure ondemand entries working correctly.
Now we are just using a single instance of OnDemandEntryHandler.

* Better sourcemaps

* Release 5.0.0-universal-alpha.13

* Lock uglify version to 1.1.6

* Release 5.0.0-universal-alpha.14

* Fix a typo.

* Introduce multi-zones support for mircofrontends

* Add section on css

											
										
										
											2018-01-30 15:40:52 +00:00
+								  webpack: (config, { buildId, dev, isServer, defaultLoaders }) => {
-												Add custom webpack dev middleware config (#1931)


											
										
										
											2017-05-13 23:44:21 +00:00
+								    // Perform customizations to webpack config
 								    // Important: return the modified config
 								    return config
 								  },
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								  webpackDevMiddleware: config => {
-												Add custom webpack dev middleware config (#1931)


											
										
										
											2017-05-13 23:44:21 +00:00
+								    // Perform customizations to webpack dev middleware 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
 								  }
 								}
 								```
-												Move build directory outside of server folder (#4565)

The prepares for next-server.

I also took this as an opportunity to get all build directory paths from a single location, as they were previously scattered across webpack/babel plugins and loaders.
											
										
										
											2018-06-14 17:30:14 +00:00
+								The second argument to `webpack` is an object containing properties useful when customing the WebPack configuration:
-												Universal Webpack (#3578)

* Speed up next build

* Document webpack config

* Speed up next build

* Remove comment

* Add comment

* Clean up rules

* Add comments

* Run in parallel

* Push plugins seperately

* Create a new chunk for react

* Don’t uglify react since it’s already uglified. Move react to commons in development

* Use the minified version directly

* Re-add globpattern

* Move loaders into a separate variable

* Add comment linking to Dan’s explanation

* Remove dot

* Add universal webpack

* Initial dev support

* Fix linting

* Add changes from Arunoda's work

* Made next dev works.
But super slow and no HMR support.

* Fix client side hot reload

* Server side hmr

* Only in dev

* Add on-demand-entries client + hot-middleware

* Add .babelrc support

* Speed up on demand entries by running in parallel

* Serve static generated files

* Add missing config in dev

* Add sass support

* Add support for .map

* Add cssloader config and fix .jsx support

* Rename

* use same defaults as css-loader. Fix linting

* Add NoEmitErrorsPlugin

* Add clientBootstrap

* Use webpackhotmiddleware on the multi compiler

* alpha.3

* Use babel 16.2.x

* Fix reloading after error

* Remove comment

* Release 5.0.0-univeral-alpha.1

* Remove check for React 16

* Release 5.0.0-universal-alpha.2

* React hot loader v4

* Use our static file rendering machanism to serve pages.
This should work well since the file path for a page is predictable.

* Release 5.0.0-universal-alpha.3

* Remove optional loaders

* Release 5.0.0-universal-alpha.4

* Remove clientBootstrap

* Remove renderScript

* Make sure pages bundles are served correctly

* Remove unused import

* Revert to using the same code as canary

* Fix hot loader

* Release 5.0.0-universal-alpha.5

* Check if externals dir exist before applying config

* Add typescript support

* Add support for transpiling certain packages in node_modules

Thanks to @giuseppeg’s work in https://github.com/zeit/next.js/pull/3319

* Add BABEL_DISABLE_CACHE support

* Make sourcemaps in production opt-in

* Revert "Add support for transpiling certain packages in node_modules"

This reverts commit d4b1d9babfb4b9ed4f4b12d56d52dee233e862da.

In favor of a better api around this.

* Support typescript through next.config.js

* Remove comments

* Bring back commons.js calculation

* Remove unused dependencies

* Move base.config.js to webpack.js

* Make sure to only invalidate webpackDevMiddleware one after other.

* Allow babel-loder caching by default.

* Add comment about preact support

* Bring back buildir replace

* Remove obsolete plugin

* Remove build replace, speed up build

* Resolve page entries like pages/day/index.js to pages/day.js

* Add componentDidCatch back

* Compile to bundles

* Use config.distDir everywhere

* Make sure the file is an array

* Remove console.log

* Apply optimization to uglifyjs

* Add comment pointing to source

* Create entries the same way in dev and production

* Remove unused and broken pagesGlobPattern

* day/index.js is automatically turned into day.js at build time

* Remove poweredByHeader option

* Load pages with the correct path.

* Release 5.0.0-universal-alpha.6

* Make sure react-dom/server can be overwritten by module-alias

* Only add react-hot-loader babel plugin in dev

* Release 5.0.0-universal-alpha.7

* Revert tests

* Release 5.0.0-universal-alpha.10

* Make sure next/head is working properly.

* Add wepack alias for 'next' back.

* Make sure overriding className in next/head works

* Alias react too

* Add missing r

* Fragment fallback has to wrap the children

* Use min.js

* Remove css.js

* Remove wallaby.js

* Release 5.0.0-universal-alpha.11

* Resolve relative to workdir instead of next

* Make sure we touch the right file

* Resolve next modules

* Remove dotjsx removal plugins since we use webpack on the server

* Revert "Resolve relative to workdir instead of next"

This reverts commit a13f3e4ab565df9e2c9a3dfc8eb4009c0c2e02ed.

* Externalize any locally loaded module lives outside of app dir.

* Remove server aliases

* Check node_modules reliably

* Add symlink to next for tests

* Make sure dynamic imports work locally.
This is why we need it: https://github.com/webpack/webpack/blob/b545b519b2024e3f8be3041385bd326bf5d24449/lib/MainTemplate.js#L68
We need to have the finally clause in the above in __webpack_require__.
webpack output option strictModuleExceptionHandling does that.

* dynmaic -> dynamic

* Remove webpack-node-externals

* Make sure dynamic imports support SSR.

* Remove css support in favor of next-css

* Make sure we load path from `/` since it’s included in the path matching

* Catch when ensurepage couldn’t be fulfilled for `.js.map`

* Register require cache flusher for both client and server

* Add comment explaining this is to facilitate hot reloading

* Only load module when needed

* Remove unused modules

* Release 5.0.0-universal-alpha.12

* Only log the `found babel` message once

* Make sure ondemand entries working correctly.
Now we are just using a single instance of OnDemandEntryHandler.

* Better sourcemaps

* Release 5.0.0-universal-alpha.13

* Lock uglify version to 1.1.6

* Release 5.0.0-universal-alpha.14

* Fix a typo.

* Introduce multi-zones support for mircofrontends

* Add section on css

											
										
										
											2018-01-30 15:40:52 +00:00
-												Move build directory outside of server folder (#4565)

The prepares for next-server.

I also took this as an opportunity to get all build directory paths from a single location, as they were previously scattered across webpack/babel plugins and loaders.
											
										
										
											2018-06-14 17:30:14 +00:00
+								- `buildId` - `String` the build id used as a unique identifier between builds
 								- `dev` - `Boolean` shows if the compilation is done in development mode
 								- `isServer` - `Boolean` shows if the resulting configuration will be used for server side (`true`), or client size compilation (`false`).
 								- `defaultLoaders` - `Object` Holds loader objects Next.js uses internally, so that you can use them in custom configuration
 								  - `babel` - `Object` the `babel-loader` configuration for Next.js.
 								  - `hotSelfAccept` - `Object` the `hot-self-accept-loader` configuration. This loader should only be used for advanced use cases. For example [`@zeit/next-typescript`](https://github.com/zeit/next-plugins/tree/master/packages/next-typescript) adds it for top-level typescript pages.
-												Warn about webpack loaders (#638)


											
										
										
											2017-01-03 18:06:55 +00:00
-												Move build directory outside of server folder (#4565)

The prepares for next-server.

I also took this as an opportunity to get all build directory paths from a single location, as they were previously scattered across webpack/babel plugins and loaders.
											
										
										
											2018-06-14 17:30:14 +00:00
+								Example usage of `defaultLoaders.babel`:
-												Add example of next-plugin composition (#3800)

* Add example of next-plugin composition

* Add require statements to the example

											
										
										
											2018-02-16 09:59:55 +00:00
 								```js
-												Move build directory outside of server folder (#4565)

The prepares for next-server.

I also took this as an opportunity to get all build directory paths from a single location, as they were previously scattered across webpack/babel plugins and loaders.
											
										
										
											2018-06-14 17:30:14 +00:00
+								// Example next.config.js for adding a loader that depends on babel-loader
 								// This source was taken from the @zeit/next-mdx plugin source:
 								// https://github.com/zeit/next-plugins/blob/master/packages/next-mdx
 								module.exports = {
 								  webpack: (config, {}) => {
 								    config.module.rules.push({
 								      test: /\.mdx/,
 								      use: [
 								        options.defaultLoaders.babel,
 								        {
 								          loader: '@mdx-js/loader',
 								          options: pluginOptions.options
 								        }
 								      ]
 								    })
-												Add example of next-plugin composition (#3800)

* Add example of next-plugin composition

* Add require statements to the example

											
										
										
											2018-02-16 09:59:55 +00:00
 								    return config
 								  }
-												Move build directory outside of server folder (#4565)

The prepares for next-server.

I also took this as an opportunity to get all build directory paths from a single location, as they were previously scattered across webpack/babel plugins and loaders.
											
										
										
											2018-06-14 17:30:14 +00:00
+								}
-												Add example of next-plugin composition (#3800)

* Add example of next-plugin composition

* Add require statements to the example

											
										
										
											2018-02-16 09:59:55 +00:00
+								```
-												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
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								```json
-												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
+								{
-												Fix svg-components example and improve babel example file (#3746)


											
										
										
											2018-02-09 14:41:09 +00:00
+								  "presets": ["next/babel"],
 								  "plugins": []
-												Update README.md
											
										
										
											2016-12-17 19:04:44 +00:00
+								}
 								```
-												Add section to the readme about configuring .babelrc

											
										
										
											2018-05-25 12:39:18 +00:00
+								The `next/babel` preset includes everything needed to transpile React applications. This includes:
 								- preset-env
 								- preset-react
 								- plugin-proposal-class-properties
 								- plugin-proposal-object-rest-spread
 								- plugin-transform-runtime
 								- styled-jsx
-												Add class properties configuration (#4619)


											
										
										
											2018-06-19 19:48:54 +00:00
+								These presets / plugins **should not** be added to your custom `.babelrc`. Instead, you can configure them on the `next/babel` preset:
-												Add section to the readme about configuring .babelrc

											
										
										
											2018-05-25 12:39:18 +00:00
 								```json
 								{
 								  "presets": [
 								    ["next/babel", {
 								      "preset-env": {},
 								      "transform-runtime": {},
-												Add class properties configuration (#4619)


											
										
										
											2018-06-19 19:48:54 +00:00
+								      "styled-jsx": {},
 								      "class-properties": {}
-												Add section to the readme about configuring .babelrc

											
										
										
											2018-05-25 12:39:18 +00:00
+								    }]
 								  ],
 								  "plugins": []
 								}
 								```
 								The `modules` option on `"preset-env"` should be kept to `false` otherwise webpack code splitting is disabled.
-												Improve documentation on runtime configuration (#4756)

* Remove nesting of runtime configuration under the babel section, since it's not related to babel.
* Clean up confusing verbiage relating to "keys."
											
										
										
											2018-07-10 21:02:45 +00:00
+								### Exposing configuration to the server / client side
-												Exposing configuration to the server / client side (minor) (#3882)

* Add next/config

* Set config on server start / client render

* Add documentation for next/config

* Add next/config support for next export

* Fix test

* Use the correct name

* Set default to empty object on the client side

* Add config tests

* Rename config to runtimeConfig

											
										
										
											2018-02-26 11:03:27 +00:00
-												Improve documentation on runtime configuration (#4756)

* Remove nesting of runtime configuration under the babel section, since it's not related to babel.
* Clean up confusing verbiage relating to "keys."
											
										
										
											2018-07-10 21:02:45 +00:00
+								The `next/config` module gives your app access to runtime configuration stored in your `next.config.js`. Place any server-only runtime config under a `serverRuntimeConfig` property and anything accessible to both client and server-side code under `publicRuntimeConfig`.
-												Exposing configuration to the server / client side (minor) (#3882)

* Add next/config

* Set config on server start / client render

* Add documentation for next/config

* Add next/config support for next export

* Fix test

* Use the correct name

* Set default to empty object on the client side

* Add config tests

* Rename config to runtimeConfig

											
										
										
											2018-02-26 11:03:27 +00:00
 								```js
 								// next.config.js
 								module.exports = {
-												Implement new next/config keys (#3909)


											
										
										
											2018-02-27 16:50:14 +00:00
+								  serverRuntimeConfig: { // Will only be available on the server side
 								    mySecret: 'secret'
 								  },
 								  publicRuntimeConfig: { // Will be available on both server and client
-												Add example of process.env runtimeConfig (#4759)


											
										
										
											2018-07-11 10:48:14 +00:00
+								    staticFolder: '/static',
 								    mySecret: process.env.MY_SECRET // Pass through env variables
-												Exposing configuration to the server / client side (minor) (#3882)

* Add next/config

* Set config on server start / client render

* Add documentation for next/config

* Add next/config support for next export

* Fix test

* Use the correct name

* Set default to empty object on the client side

* Add config tests

* Rename config to runtimeConfig

											
										
										
											2018-02-26 11:03:27 +00:00
+								  }
 								}
 								```
 								```js
 								// pages/index.js
 								import getConfig from 'next/config'
-												Move getConfig message to the line above in readme

											
										
										
											2018-03-29 08:19:21 +00:00
+								// Only holds serverRuntimeConfig and publicRuntimeConfig from next.config.js nothing else.
 								const {serverRuntimeConfig, publicRuntimeConfig} = getConfig()
-												Implement new next/config keys (#3909)


											
										
										
											2018-02-27 16:50:14 +00:00
 								console.log(serverRuntimeConfig.mySecret) // Will only be available on the server side
 								console.log(publicRuntimeConfig.staticFolder) // Will be available on both server and client
-												Exposing configuration to the server / client side (minor) (#3882)

* Add next/config

* Set config on server start / client render

* Add documentation for next/config

* Add next/config support for next export

* Fix test

* Use the correct name

* Set default to empty object on the client side

* Add config tests

* Rename config to runtimeConfig

											
										
										
											2018-02-26 11:03:27 +00:00
 								export default () => <div>
-												Add alt attributes to examples in readme.md (#4053)


											
										
										
											2018-03-25 10:43:36 +00:00
+								  <img src={`${publicRuntimeConfig.staticFolder}/logo.png`} alt="logo" />
-												Exposing configuration to the server / client side (minor) (#3882)

* Add next/config

* Set config on server start / client render

* Add documentation for next/config

* Add next/config support for next export

* Fix test

* Use the correct name

* Set default to empty object on the client side

* Add config tests

* Rename config to runtimeConfig

											
										
										
											2018-02-26 11:03:27 +00:00
+								</div>
 								```
-												Update readme with alternative hostname option (#4829)

Tackles the issue in #4025.
											
										
										
											2018-07-26 10:42:35 +00:00
+								### Starting the server on alternative hostname
 								To start the development server using a different default hostname you can use `--hostname hostname_here` or `-H hostname_here` option with next dev. This will start a TCP server listening for connections on the provided host.
-												Add CDN support with assetPrefix (#1700)

* Introduce script tag based page loading system.

* Call ensurePage only in the dev mode.

* Implement router using the page-loader.

* Fix a typo and remove unwanted code.

* Fix some issues related to rendering.

* Fix production tests.

* Fix ondemand test cases.

* Fix unit tests.

* Get rid of eval completely.

* Remove all the inline code.

* Remove the json-pages plugin.

* Rename NEXT_PAGE_LOADER into __NEXT_PAGE_LOADER__

* Rename NEXT_LOADED_PAGES into __NEXT_LOADED_PAGES__

* Remove some unwanted code.

* Load everything async.

* Remove lib/eval-script.js
We no longer need it.

* Move webpack idle wait code to the page-loader.
Because that's the place to do it.

* Remove pageNotFound key from the error.

* Remove unused error field 'buildError'

* Add much better logic to normalize routes.

* Get rid of mitt.

* Introduce a better way to register pages.

* Came back to the mitt() based page-loader.

* Add link rel=preload support.

* Add assetPrefix support to add support for CDNs.

* Add assetPrefix support for preload links.

* Update readme.md

											
										
										
											2017-04-18 04:18:43 +00:00
+								### CDN support with Asset Prefix
 								To set up a CDN, you can set up the `assetPrefix` setting and configure your CDN's origin to resolve to the domain that Next.js is hosted on.
 								```js
-												Update readme.md (#1818)


											
										
										
											2017-04-27 13:21:50 +00:00
+								const isProd = process.env.NODE_ENV === 'production'
-												Add CDN support with assetPrefix (#1700)

* Introduce script tag based page loading system.

* Call ensurePage only in the dev mode.

* Implement router using the page-loader.

* Fix a typo and remove unwanted code.

* Fix some issues related to rendering.

* Fix production tests.

* Fix ondemand test cases.

* Fix unit tests.

* Get rid of eval completely.

* Remove all the inline code.

* Remove the json-pages plugin.

* Rename NEXT_PAGE_LOADER into __NEXT_PAGE_LOADER__

* Rename NEXT_LOADED_PAGES into __NEXT_LOADED_PAGES__

* Remove some unwanted code.

* Load everything async.

* Remove lib/eval-script.js
We no longer need it.

* Move webpack idle wait code to the page-loader.
Because that's the place to do it.

* Remove pageNotFound key from the error.

* Remove unused error field 'buildError'

* Add much better logic to normalize routes.

* Get rid of mitt.

* Introduce a better way to register pages.

* Came back to the mitt() based page-loader.

* Add link rel=preload support.

* Add assetPrefix support to add support for CDNs.

* Add assetPrefix support for preload links.

* Update readme.md

											
										
										
											2017-04-18 04:18:43 +00:00
+								module.exports = {
 								  // You may only need to add assetPrefix in the production.
 								  assetPrefix: isProd ? 'https://cdn.mydomain.com' : ''
 								}
 								```
-												fix grammatical error in readme file (#3443)


											
										
										
											2017-12-13 09:49:44 +00:00
+								Note: Next.js will automatically use that prefix in the scripts it loads, but this has no effect whatsoever on `/static`. If you want to serve those assets over the CDN, you'll have to introduce the prefix yourself. One way of introducing a prefix that works inside your components and varies by environment is documented [in this example](https://github.com/zeit/next.js/tree/master/examples/with-universal-configuration).
-												Add CDN support with assetPrefix (#1700)

* Introduce script tag based page loading system.

* Call ensurePage only in the dev mode.

* Implement router using the page-loader.

* Fix a typo and remove unwanted code.

* Fix some issues related to rendering.

* Fix production tests.

* Fix ondemand test cases.

* Fix unit tests.

* Get rid of eval completely.

* Remove all the inline code.

* Remove the json-pages plugin.

* Rename NEXT_PAGE_LOADER into __NEXT_PAGE_LOADER__

* Rename NEXT_LOADED_PAGES into __NEXT_LOADED_PAGES__

* Remove some unwanted code.

* Load everything async.

* Remove lib/eval-script.js
We no longer need it.

* Move webpack idle wait code to the page-loader.
Because that's the place to do it.

* Remove pageNotFound key from the error.

* Remove unused error field 'buildError'

* Add much better logic to normalize routes.

* Get rid of mitt.

* Introduce a better way to register pages.

* Came back to the mitt() based page-loader.

* Add link rel=preload support.

* Add assetPrefix support to add support for CDNs.

* Add assetPrefix support for preload links.

* Update readme.md

											
										
										
											2017-04-18 04:18:43 +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
-												Add note about NODE_ENV being set automatically

											
										
										
											2017-10-28 22:39:45 +00:00
+								Note: `NODE_ENV` is properly configured by the `next` subcommands, if absent, to maximize performance. if you’re using Next.js [programmatically](#custom-server-and-routing), it’s your responsibility to set `NODE_ENV=production` manually!
-												clarify .next in .gitignore text (#4087)


											
										
										
											2018-03-31 06:14:54 +00:00
+								Note: we recommend putting `.next`, or your [custom dist folder](https://github.com/zeit/next.js#custom-configuration), in `.gitignore` or `.npmignore`. Otherwise, use `files` or `now.files` to opt-into a whitelist of files you want to deploy, excluding `.next` or your custom dist folder.
-												Update Readme.md
											
										
										
											2016-10-20 00:58:42 +00:00
-												Update README.md to include browser support and polyfills docs (#4601)

Fixes #4572

This PR intends to address https://github.com/zeit/next.js/issues/4572 around documenting browser support and what needs polyfills.

There are many outstanding issues on the tracker regarding browser support and polyfills. This may alleviate some of them.
											
										
										
											2018-06-14 10:39:13 +00:00
+								## Browser support
-												Document global Promise polyfill (#5006)

Depends on: https://github.com/zeit/next.js/pull/4988
											
										
										
											2018-08-22 15:21:16 +00:00
+								Next.js supports IE11 and all modern browsers out of the box using [`@babel/preset-env`](https://new.babeljs.io/docs/en/next/babel-preset-env.html). In order to support IE11 Next.js adds a global `Promise` polyfill. In cases where your own code or any external NPM dependencies you are using requires features not supported by your target browsers you will need to implement polyfills.
-												Update README.md to include browser support and polyfills docs (#4601)

Fixes #4572

This PR intends to address https://github.com/zeit/next.js/issues/4572 around documenting browser support and what needs polyfills.

There are many outstanding issues on the tracker regarding browser support and polyfills. This may alleviate some of them.
											
										
										
											2018-06-14 10:39:13 +00:00
 								The [polyfills](https://github.com/zeit/next.js/tree/canary/examples/with-polyfills) example demonstrates the recommended approach to implement polyfills.
-												Add docs.

											
										
										
											2017-05-15 03:42:27 +00:00
+								## Static HTML export
-												Add with-static-export example (#2234)


											
										
										
											2017-07-01 19:44:58 +00:00
+								<p><details>
 								  <summary><b>Examples</b></summary>
 								  <ul><li><a href="./examples/with-static-export">Static export</a></li></ul>
 								</details></p>
-												Make router properties update when re-rendering (#4541)

* Make router properties update when re-rendering

* Remove documentation about methods that have been deprecated since v2/v3

* Update next export documentation

											
										
										
											2018-06-05 15:10:28 +00:00
+								`next export` is a way to run your Next.js app as a standalone static app without the need for a Node.js server.
 								The exported app supports almost every feature of Next.js, including dynamic urls, prefetching, preloading and dynamic imports.
 								The way `next export` works is by pre-rendering all pages possible to HTML. It does so based on a mapping of `pathname` key to page object. This mapping is called the `exportPathMap`.
 								The page object has 2 values:
 								- `page` - `String` the page inside the `pages` directory to render
 								- `query` - `Object` the `query` object passed to `getInitialProps` when pre-rendering. Defaults to `{}`
-												Add docs.

											
										
										
											2017-05-15 03:42:27 +00:00
 								### Usage
-												Make router properties update when re-rendering (#4541)

* Make router properties update when re-rendering

* Remove documentation about methods that have been deprecated since v2/v3

* Update next export documentation

											
										
										
											2018-06-05 15:10:28 +00:00
+								Simply develop your app as you normally do with Next.js. Then run:
 								```
 								next build
 								next export
 								```
-												Provide a way to copy files in exportPathMap (#5089)

Related #4659 

Adds the possibility for users to copy files inside of `exportPathMap`. This allows for adding `robots.txt` `sitemap.xml` etc. another use case is for https://github.com/hanford/next-offline, currently it's manually reading the buildId in `exportPathMap`.

To allow users to do this we'll introduce a new parameter holding an object with the following keys:

- `dev` - `true` when `exportPathMap` is being called in development. `false` when running `next export`. In development `exportPathMap` is used to define routes and behavior like copying files is not required.
- `dir` - Absolute path to the project directory
- `outDir` - Absolute path to the `out` directory (configurable with `-o` or `--outdir`). When `dev` is `true` the value of `outDir` will be `null`.
- `distDir` - Absolute path to the `.next` directory (configurable using the `distDir` config key)
- `buildId` - The buildId the export is running for

Example usage:

```js
// next.config.js
const fs = require('fs')
const {join} = require('path')
const {promisify} = require('util')
const copyFile = promisify(fs.copyFile)

module.exports = {
  exportPathMap: async function (defaultPathMap, {dev, dir, outDir, distDir, buildId}) {
    if(dev) {
      return defaultPathMap
    }
    // This will copy robots.txt from your project root into the out directory
    await copyFile(join(dir, 'robots.txt'), join(outDir, 'robots.txt'))
    return defaultPathMap
  }
}
```
											
										
										
											2018-09-04 14:01:50 +00:00
+								By default `next export` doesn't require any configuration. It will generate a default `exportPathMap` containing the routes to pages inside the `pages` directory. This default mapping is available as `defaultPathMap` in the example below.
-												Make router properties update when re-rendering (#4541)

* Make router properties update when re-rendering

* Remove documentation about methods that have been deprecated since v2/v3

* Update next export documentation

											
										
										
											2018-06-05 15:10:28 +00:00
 								If your application has dynamic routes you can add a dynamic `exportPathMap` in `next.config.js`.
 								This function is asynchronous and gets the default `exportPathMap` as a parameter.
-												Add docs.

											
										
										
											2017-05-15 03:42:27 +00:00
 								```js
 								// next.config.js
 								module.exports = {
-												Make router properties update when re-rendering (#4541)

* Make router properties update when re-rendering

* Remove documentation about methods that have been deprecated since v2/v3

* Update next export documentation

											
										
										
											2018-06-05 15:10:28 +00:00
+								  exportPathMap: async function (defaultPathMap) {
-												Add docs.

											
										
										
											2017-05-15 03:42:27 +00:00
+								    return {
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								      '/': { page: '/' },
 								      '/about': { page: '/about' },
-												Allow use of filenames in exportPathMap (#2973)

* allow use of filenames in exportPathMap

* add link test and handling for file paths when flattening links for export

* add note about exporting file paths to readme.md

											
										
										
											2017-10-05 18:33:10 +00:00
+								      '/readme.md': { page: '/readme' },
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								      '/p/hello-nextjs': { page: '/post', query: { title: 'hello-nextjs' } },
 								      '/p/learn-nextjs': { page: '/post', query: { title: 'learn-nextjs' } },
 								      '/p/deploy-nextjs': { page: '/post', query: { title: 'deploy-nextjs' } }
-												Add docs.

											
										
										
											2017-05-15 03:42:27 +00:00
+								    }
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								  }
-												Add docs.

											
										
										
											2017-05-15 03:42:27 +00:00
+								}
 								```
-												Allow use of filenames in exportPathMap (#2973)

* allow use of filenames in exportPathMap

* add link test and handling for file paths when flattening links for export

* add note about exporting file paths to readme.md

											
										
										
											2017-10-05 18:33:10 +00:00
+								> Note that if the path ends with a directory, it will be exported as `/dir-name/index.html`, but if it ends with an extension, it will be exported as the specified filename, e.g. `/readme.md` above. If you use a file extension other than `.html`, you may need to set the `Content-Type` header to `text/html` when serving this content.
-												Add docs.

											
										
										
											2017-05-15 03:42:27 +00:00
+								Then simply run these commands:
 								```sh
 								next build
 								next export
 								```
 								For that you may need to add a NPM script to `package.json` like this:
 								```json
 								{
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								  "scripts": {
-												Make router properties update when re-rendering (#4541)

* Make router properties update when re-rendering

* Remove documentation about methods that have been deprecated since v2/v3

* Update next export documentation

											
										
										
											2018-06-05 15:10:28 +00:00
+								    "build": "next build",
 								    "export": "npm run build && next export"
-												Fix coding style of snippets (#2806)


											
										
										
											2017-09-08 21:22:59 +00:00
+								  }
-												Add docs.

											
										
										
											2017-05-15 03:42:27 +00:00
+								}
 								```
 								And run it at once with:
 								```sh
-												Make router properties update when re-rendering (#4541)

* Make router properties update when re-rendering

* Remove documentation about methods that have been deprecated since v2/v3

* Update next export documentation

											
										
										
											2018-06-05 15:10:28 +00:00
+								npm run export
-												Add docs.

											
										
										
											2017-05-15 03:42:27 +00:00
+								```
-												Make router properties update when re-rendering (#4541)

* Make router properties update when re-rendering

* Remove documentation about methods that have been deprecated since v2/v3

* Update next export documentation

											
										
										
											2018-06-05 15:10:28 +00:00
+								Then you have a static version of your app in the `out` directory.
-												Add docs.

											
										
										
											2017-05-15 03:42:27 +00:00
 								> You can also customize the output directory. For that run `next export -h` for the help.
-												Make router properties update when re-rendering (#4541)

* Make router properties update when re-rendering

* Remove documentation about methods that have been deprecated since v2/v3

* Update next export documentation

											
										
										
											2018-06-05 15:10:28 +00:00
+								Now you can deploy the `out` directory to any static hosting service. Note that there is an additional step for deploying to GitHub Pages, [documented here](https://github.com/zeit/next.js/wiki/Deploying-a-Next.js-app-into-GitHub-Pages).
-												Add docs.

											
										
										
											2017-05-15 03:42:27 +00:00
-												Make router properties update when re-rendering (#4541)

* Make router properties update when re-rendering

* Remove documentation about methods that have been deprecated since v2/v3

* Update next export documentation

											
										
										
											2018-06-05 15:10:28 +00:00
+								For an example, simply visit the `out` directory and run following command to deploy your app to [ZEIT Now](https://zeit.co/now).
-												Add docs.

											
										
										
											2017-05-15 03:42:27 +00:00
 								```sh
 								now
 								```
-												Provide a way to copy files in exportPathMap (#5089)

Related #4659 

Adds the possibility for users to copy files inside of `exportPathMap`. This allows for adding `robots.txt` `sitemap.xml` etc. another use case is for https://github.com/hanford/next-offline, currently it's manually reading the buildId in `exportPathMap`.

To allow users to do this we'll introduce a new parameter holding an object with the following keys:

- `dev` - `true` when `exportPathMap` is being called in development. `false` when running `next export`. In development `exportPathMap` is used to define routes and behavior like copying files is not required.
- `dir` - Absolute path to the project directory
- `outDir` - Absolute path to the `out` directory (configurable with `-o` or `--outdir`). When `dev` is `true` the value of `outDir` will be `null`.
- `distDir` - Absolute path to the `.next` directory (configurable using the `distDir` config key)
- `buildId` - The buildId the export is running for

Example usage:

```js
// next.config.js
const fs = require('fs')
const {join} = require('path')
const {promisify} = require('util')
const copyFile = promisify(fs.copyFile)

module.exports = {
  exportPathMap: async function (defaultPathMap, {dev, dir, outDir, distDir, buildId}) {
    if(dev) {
      return defaultPathMap
    }
    // This will copy robots.txt from your project root into the out directory
    await copyFile(join(dir, 'robots.txt'), join(outDir, 'robots.txt'))
    return defaultPathMap
  }
}
```
											
										
										
											2018-09-04 14:01:50 +00:00
+								### Copying custom files
 								In case you have to copy custom files like a robots.txt or generate a sitemap.xml you can do this inside of `exportPathMap`.
 								`exportPathMap` gets a few contextual parameter to aid you with creating/copying files:
 								- `dev` - `true` when `exportPathMap` is being called in development. `false` when running `next export`. In development `exportPathMap` is used to define routes and behavior like copying files is not required.
 								- `dir` - Absolute path to the project directory
 								- `outDir` - Absolute path to the `out` directory (configurable with `-o` or `--outdir`). When `dev` is `true` the value of `outDir` will be `null`.
 								- `distDir` - Absolute path to the `.next` directory (configurable using the `distDir` config key)
 								- `buildId` - The buildId the export is running for
 								```js
 								// next.config.js
 								const fs = require('fs')
-												Just some simple improvements in formatting codes in documentation (#5250)

I think it looks better for new people in JavaScript/React (and for my perfectionism 😄).
											
										
										
											2018-09-22 12:13:27 +00:00
+								const { join } = require('path')
 								const { promisify } = require('util')
-												Provide a way to copy files in exportPathMap (#5089)

Related #4659 

Adds the possibility for users to copy files inside of `exportPathMap`. This allows for adding `robots.txt` `sitemap.xml` etc. another use case is for https://github.com/hanford/next-offline, currently it's manually reading the buildId in `exportPathMap`.

To allow users to do this we'll introduce a new parameter holding an object with the following keys:

- `dev` - `true` when `exportPathMap` is being called in development. `false` when running `next export`. In development `exportPathMap` is used to define routes and behavior like copying files is not required.
- `dir` - Absolute path to the project directory
- `outDir` - Absolute path to the `out` directory (configurable with `-o` or `--outdir`). When `dev` is `true` the value of `outDir` will be `null`.
- `distDir` - Absolute path to the `.next` directory (configurable using the `distDir` config key)
- `buildId` - The buildId the export is running for

Example usage:

```js
// next.config.js
const fs = require('fs')
const {join} = require('path')
const {promisify} = require('util')
const copyFile = promisify(fs.copyFile)

module.exports = {
  exportPathMap: async function (defaultPathMap, {dev, dir, outDir, distDir, buildId}) {
    if(dev) {
      return defaultPathMap
    }
    // This will copy robots.txt from your project root into the out directory
    await copyFile(join(dir, 'robots.txt'), join(outDir, 'robots.txt'))
    return defaultPathMap
  }
}
```
											
										
										
											2018-09-04 14:01:50 +00:00
+								const copyFile = promisify(fs.copyFile)
 								module.exports = {
 								  exportPathMap: async function (defaultPathMap, {dev, dir, outDir, distDir, buildId}) {
 								    if (dev) {
 								      return defaultPathMap
 								    }
 								    // This will copy robots.txt from your project root into the out directory
 								    await copyFile(join(dir, 'robots.txt'), join(outDir, 'robots.txt'))
 								    return defaultPathMap
 								  }
 								}
 								```
-												Add docs.

											
										
										
											2017-05-15 03:42:27 +00:00
+								### Limitation
-												Make router properties update when re-rendering (#4541)

* Make router properties update when re-rendering

* Remove documentation about methods that have been deprecated since v2/v3

* Update next export documentation

											
										
										
											2018-06-05 15:10:28 +00:00
+								With `next export`, we build a HTML version of your app. At export time we will run `getInitialProps` of your pages.
-												Add docs.

											
										
										
											2017-05-15 03:42:27 +00:00
-												Make router properties update when re-rendering (#4541)

* Make router properties update when re-rendering

* Remove documentation about methods that have been deprecated since v2/v3

* Update next export documentation

											
										
										
											2018-06-05 15:10:28 +00:00
+								The `req` and `res` fields of the `context` object passed to `getInitialProps` are not available as there is no server running.
-												Add docs.

											
										
										
											2017-05-15 03:42:27 +00:00
-												Make router properties update when re-rendering (#4541)

* Make router properties update when re-rendering

* Remove documentation about methods that have been deprecated since v2/v3

* Update next export documentation

											
										
										
											2018-06-05 15:10:28 +00:00
+								> You won't be able to render HTML dynamically when static exporting, as we pre-build the HTML files. If you want to do dynamic rendering use `next start` or the custom server API
-												Add docs.

											
										
										
											2017-05-15 03:42:27 +00:00
-												Include next/dist/pages instead of exclude (patch) (#3704)

* Move security related test cases into a its own file.

* Removes the unused renderScript function

* Add a nerv example. (#3573)

* Add a nerv example.

* Fix for indentation/style

* Fix for name

* Release 5.0.0

* Add multi-zones docs. (#3688)

* Include next/dist/pages

* Fix linting

											
										
										
											2018-02-06 12:09:41 +00:00
+								## Multi Zones
 								<p><details>
 								  <summary><b>Examples</b></summary>
 								  <ul><li><a href="./examples/with-zones">With Zones</a></li></ul>
 								</details></p>
 								A zone is a single deployment of a Next.js app. Just like that, you can have multiple zones. Then you can merge them as a single app.
 								For an example, you can have two zones like this:
 								* https://docs.my-app.com for serving `/docs/**`
 								* https://ui.my-app.com for serving all other pages
 								With multi zones support, you can merge both these apps into a single one. Which allows your customers to browse it using a single URL. But you can develop and deploy both apps independently.
 								> This is exactly the same concept as microservices, but for frontend apps.
 								### How to define a zone
 								There are no special zones related APIs. You only need to do following things:
 								* Make sure to keep only the pages you need in your app. (For an example, https://ui.my-app.com should not contain pages for `/docs/**`)
 								* Make sure your app has an [assetPrefix](https://github.com/zeit/next.js#cdn-support-with-asset-prefix). (You can also define the assetPrefix [dynamically](https://github.com/zeit/next.js#dynamic-assetprefix).)
 								### How to merge them
 								You can merge zones using any HTTP proxy.
 								You can use [micro proxy](https://github.com/zeit/micro-proxy) as your local proxy server. It allows you to easily define routing rules like below:
 								```json
 								{
 								  "rules": [
 								    {"pathname": "/docs**", "method":["GET", "POST", "OPTIONS"], "dest": "https://docs.my-app.com"},
 								    {"pathname": "/**", "dest": "https://ui.my-app.com"}
 								  ]
 								}
 								```
 								For the production deployment, you can use the [path alias](https://zeit.co/docs/features/path-aliases) feature if you are using [ZEIT now](https://zeit.co/now). Otherwise, you can configure your existing proxy server to route HTML pages using a set of rules as show above.
-												added recipes section to readme (#1928)


											
										
										
											2017-05-09 18:22:14 +00:00
+								## Recipes
 								- [Setting up 301 redirects](https://www.raygesualdo.com/posts/301-redirects-with-nextjs/)
-												Update readme.md with some links and latest info.

											
										
										
											2017-07-01 11:04:52 +00:00
+								- [Dealing with SSR and server only modules](https://arunoda.me/blog/ssr-and-server-only-modules)
-												Add example to #recipes (#3789)


											
										
										
											2018-02-13 14:20:54 +00:00
+								- [Building with React-Material-UI-Next-Express-Mongoose-Mongodb](https://github.com/builderbook/builderbook)
-												Add example to `Recipes` section (#4661)


											
										
										
											2018-06-25 10:31:09 +00:00
+								- [Build a SaaS Product with React-Material-UI-Next-MobX-Express-Mongoose-MongoDB-TypeScript](https://github.com/async-labs/saas)
-												added recipes section to readme (#1928)


											
										
										
											2017-05-09 18:22:14 +00:00
-												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
-												Document SCSS/Less (#2742)

* Document SCSS/Less

* Add missing word

* Add docs for examples dir

* Add extra example

* uppercase J

											
										
										
											2017-08-09 19:44:37 +00:00
+								Next.js bundles [styled-jsx](https://github.com/zeit/styled-jsx) supporting scoped css. However you can use any CSS-in-JS solution in your Next app by just including your favorite library [as mentioned before](#css-in-js) in the document.
-												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.
-												Fix broken readme link (#4977)

As reported by @ranyitz the links in the documentation about ['What syntactic features are transpiled? How do I change them?'](https://github.com/zeit/next.js#faq) are broken.

I updated the links and the text to reflect the latest changes.

Closes #4974 
Related https://github.com/zeit/next.js/commit/eb74ff4bf9e3b83edee346fc0dfa99e7e7cc086c 
											
										
										
											2018-08-17 18:21:52 +00:00
+								See the  documentation about [customizing the babel config](#customizing-babel-config) and [next/preset](./build/babel/preset.js) for more information.
-												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>
-												Document SCSS/Less (#2742)

* Document SCSS/Less

* Add missing word

* Add docs for examples dir

* Add extra example

* uppercase J

											
										
										
											2017-08-09 19:44:37 +00:00
+								<details>
 								<summary>Can I use Next with my favorite Javascript library or toolkit?</summary>
 								Since our first release we've had **many** example contributions, you can check them out in the [examples](./examples) directory
 								</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>
-												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
-												Removed triangles and linked company name
											
										
										
											2018-01-12 09:30:48 +00:00
+								- Arunoda Susiripala ([@arunoda](https://twitter.com/arunoda)) – [ZEIT](https://zeit.co)
-												Rephrase url deprecation text and add link to next-codemod (#4649)

* Rephrase url deprecation text and add link to next-codemod

* Clean up double words

											
										
										
											2018-06-22 12:21:28 +00:00
+								- Tim Neutkens ([@timneutkens](https://twitter.com/timneutkens)) – [ZEIT](https://zeit.co)
-												Removed triangles and linked company name
											
										
										
											2018-01-12 09:30:48 +00:00
+								- Naoyuki Kanezawa ([@nkzawa](https://twitter.com/nkzawa)) – [ZEIT](https://zeit.co)
 								- Tony Kovanen ([@tonykovanen](https://twitter.com/tonykovanen)) – [ZEIT](https://zeit.co)
 								- Guillermo Rauch ([@rauchg](https://twitter.com/rauchg)) – [ZEIT](https://zeit.co)
-												Fix JSX in readme (#2512)

An unclosed tag was resulting in some broken syntax highlighting.
											
										
										
											2017-07-09 04:54:47 +00:00
+								- Dan Zajdband ([@impronunciable](https://twitter.com/impronunciable)) – Knight-Mozilla / Coral Project