このドキュメント日本語翻訳は、ドキュメント原文の登録されているリポジトリのコミットd16f39a20bbdcaf821480817bc283ab2ead3aa64を元に翻訳されています。

情報が古くなっている場合もありますので、できるだけ原文のドキュメントで最新の情報を参照ください。

使い方permalink

npx create-next-app

(npx は npm 5.2 以上に同梱されています。古いバージョンの npm ではこちらの手順を参照ください。)

以下をプロジェクトにインストールしてください。

npm install --save next react react-dom

次に、package.json にスクリプトを追加してください。

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

ファイルシステム自体をメインの API として利用できます。すべての .js ファイルがルーティングとして機能し、それらのファイルは自動的に処理されレンダリングされます。

./pages/index.js ファイルをプロジェクトに追加してみましょう:

function Home() {
  return <div>Welcome to Next.js!</div>
}

export default Home

追加したら、npm run dev を実行し、http://localhost:3000 を開いてください。別のポートに変更したい場合は npm run dev -- -p <ポート番号> として起動します。

これだけで以下が実現できています:

  • (webpack と babel を利用した) 自動的なトランスパイルとビルド
  • コードのホットリローディング
  • ./pages 配下のファイルの構造化とサーバーサイドレンダリング
  • 静的ファイルの配布./public// にマッピングされます (プロジェクトに ./static/ ディレクトリを作成する必要があります。)

import したものはすべて「各ページごとに」バンドルされて配布されます。これはつまり、ページに必要のないコードが無駄に読み込まれることがないということを意味しています!

import cowsay from 'cowsay-browser'

function CowsayHi() {
  return <pre>{cowsay.say({ text: 'hi there!' })}</pre>
}

export default CowsayHi

CSSpermalink

Next.js には styled-jsx の機能が同梱されており、スコープを分離した CSS の適用が可能になっています。これは Web Components の「Shadow CSS」に似た機能を提供することを目的としています (残念ながら Shadow CSS はサーバーサイドレンダリングで利用することができません)

function HelloWorld() {
  return (
    <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>
  )
}

export default HelloWorld

styled-jsx のドキュメント により多くの例が書かれています。

CSS-in-JSpermalink

既存のどんな CSS-in-JS も利用することができます。一番シンプルなのはインラインで記述するものです:

function HiThere() {
  return <p style={{ color: 'red' }}>hi there</p>
}

export default HiThere

より洗練された CSS-in-JS のソリューションを使いたい場合には、サーバーサイドレンダリングでスタイルを設定するための実装を追加する必要があるでしょう。これは、各ページをラップする独自のカスタム <Document> コンポーネントを定義することで実現できます。

.css / .scss / .less / .styl ファイルをインポートするためには、サーバーサイドでリンダリングされるアプリケーション用の設定が施された以下のモジュールを利用してください。

プロジェクトのルートディレクトリに public というディレクトリを作成します。配置したファイルをコードから参照するには、 / のベース URL 直下を指定します。

function MyImage() {
  return <img src="/my-image.png" alt="my image" />
}

export default MyImage

つまり、ルートディレクトリで静的ファイルを公開するには、 public というフォルダーを追加し、そこに置かれたファイルはルートから参照可能ということです (例えば /robots.txt) 。

注意: ディレクトリ名を public 以外にはしないようにしてください。この名前は変更不可能であり、Next.js は唯一このディレクトリだけを静的ファイルの公開に利用します。

複雑なアプリケーションでは、事前に定義されたパスによってルートを定義するのだけでは不足な場合があります。そのため、Next.js では、 [param] のようにページに角括弧 (ブラケット) を設定することで動的なルーティングをすることができます。(これは slug や pretty url などと呼ばれることもあります)

pages/post/[pid].js というページが以下の内容であるとします:

import { useRouter } from 'next/router'

const Post = () => {
  const router = useRouter()
  const { pid } = router.query

  return <p>Post: {pid}</p>
}

export default Post

このとき、/post/1/post/abc などのルートは pages/post/[pid].js にマッチします。 そして、マッチしたパスのパラメータはクエリパラメータとしてページに送られます。

例えば、/post/abc というルートは次の query オブジェクトを持ちます: { pid: 'abc' } 。 同様に、/post/abc?foo=bar であれば query オブジェクトは次のようになります: { foo: 'bar', pid: 'abc' }

注意: 複数の動的なルートセグメントがあるときも同様です。

例えば、pages/post/[pid]/[comment].js/post/1/a-comment にマッチしますが、 そのときの query オブジェクトは次のようになります: { pid: '1', comment: 'a-comment' }

/post/abc に対する <Link> はこのようになります:

<Link href="/post/[pid]" as="/post/abc">
  <a>First Post</a>
</Link>
  • href: pages ディレクトリ以下のパス
  • as: ブラウザのアドレスバーに表示されるパス

href はファイルシステム上のパスなので、ランタイムにそれを変更することはできません。したがって、パスを動的に設定する必要がある場合には as を動的に設定します。例えば、以下はリンクのリストを作成する例です:

const pids = ['id1', 'id2', 'id3']
{
  pids.map(pid => (
    <Link href="/post/[pid]" as={`/post/${pid}`}>
      <a>Post {pid}</a>
    </Link>
  ))
}

<Link> リンクに関しての詳細はこちらを参照ください

もしクエリとルートのパラメータが同一の名前だった場合には、クエリのパラメータはルートのパラメータで上書きされることに注意してください。 例えば、/post/abc?pid=bcd は次の query オブジェクトを持ちます: { pid: 'abc' }

メモ: 事前定義された静的なルーティングは動的なルーティングより優先されます。 例えば、pages/post/[pid].jspages/post/create.js というルートが存在する場合、/post/createpages/post/create.js にマッチします。[pid] の動的なルーティングにはマッチしません。

メモ: 自動静的最適化 されたページはルートパラメータなしで hydrate されます (query{} のように空になります) 。 hydration されたあと、Next.js はクエリパラメータを query オブジェクトで渡すようにアプリケーションを更新します。 アプリケーション的にこの挙動だと都合が悪い場合には、getInitialProps 内でクエリパラメータをキャプチャすることでこの静的最適化をオプトアウトすることができます。

メモ: ZEIT Now にデプロイする場合、動的ルーティングは特に設定なしで動作します。 したがって、now.json でカスタムルーティングを構成する必要はありません。

ZEIT Now に Next.js アプリケーションをデプロイすることについてもっと知りたいときは、Deploying a Next.js App Learn section を参照ください。

Examples

ページの <head> に要素を追加するために組み込みのコンポーネントを利用することができます。

import Head from 'next/head'

function IndexPage() {
  return (
    <div>
      <Head>
        <title>My page title</title>
        <meta name="viewport" content="initial-scale=1.0, width=device-width" />
      </Head>
      <p>Hello world!</p>
    </div>
  )
}

export default IndexPage

<head> の中で要素が重複するのを避けるために key プロパティを使うことができます。これによって、あるタグが一度だけレンダリングされることを保証することができます。

import Head from 'next/head'

function IndexPage() {
  return (
    <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>
  )
}

export default IndexPage

例えば上記の例では、2番目の <meta name="viewport" /> のみがレンダリングされます。

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.

Note: <title> and <meta> elements need to be contained as direct children of the <Head> element, or wrapped into maximum one level of <React.Fragment>, otherwise the metatags won't be correctly picked up on clientside navigation.

When you need state, lifecycle hooks or initial data population you can export a function component that uses Hooks or a class component.

Using a function component:

import fetch from 'isomorphic-unfetch'

function Page({ stars }) {
  return <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

Using a class component:

import React from 'react'

class HelloUA 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>
  }
}

export default HelloUA

ページが読み込まれるときのデータを設定するために async で static な getInitialProps メソッドを使っていることに注目してください。このメソッドは、JavaScript のプレーンな Object として扱えるものであれば何でも非同期的に取得して、それを props に含めます。

サーバーサイドレンダリング時には getInitialProps の戻り値のデータはシリアライズされます。ちょうど JSON.stringify と似た感じです。getInitialProps が返すオブジェクトは必ず「プレーンな Object」でなければならず、Date,/ Map / Set は使用できないことに注意してください。

最初にページが読み込まれるとき、getInitialProps はサーバーサイドでのみ実行されます。getInitialProps がクライアントサイドで実行されるのは、Link コンポーネントかルーティング API を用いて別のルートに移動した場合のみです。


  • getInitialProps can not be used in children components. Only in pages.
  • If you are using some server only modules inside getInitialProps, make sure to import them properly, otherwise, it'll slow down your app.

getInitialProps は context オブジェクトを受け取り、それは以下のプロパティを含みます:

  • 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)
  • err - Error object if any error is encountered during the rendering

Routingpermalink

Next.js does not ship a routes manifest with every possible route in the application, so the current page is not aware of any other pages on the client side. All subsequent routes get lazy-loaded, for scalability sake.

With <Link>permalink

クライアントサイドでのルートの遷移は <Link> コンポーネントによって実現されます。

This component is not required for navigations to static pages that require a hard refresh, like when using AMP.

Basic Examplepermalink

以下の2つのページがある場合を考えてみてください:

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

function Home() {
  return (
    <>
      <ul>
        <li>Home</li>
        <li>
          <Link href="/about">
            <a>About Us</a>
          </Link>
        </li>
      </ul>

      <h1>This is our homepage.</h1>
    </>
  )
}

export default Home
// pages/about.js
import Link from 'next/link'

function About() {
  return (
    <>
      <ul>
        <li>
          <Link href="/">
            <a>Home</a>
          </Link>
        </li>
        <li>About Us</li>
      </ul>

      <h1>About</h1>
      <p>We are a cool company.</p>
    </>
  )
}

export default About

Note: if passing a functional component as a child of <Link> you will need to wrap it in React.forwardRef

Example with React.forwardRef

import React from 'react'
import Link from 'next/link'

// `onClick`, `href`, and `ref` need to be passed to the DOM element
// for proper handling
const MyButton = React.forwardRef(({ onClick, href }, ref) => (
  <a href={href} onClick={onClick} ref={ref}>
    Click Me
  </a>
))

export default () => (
  <>
    <Link href="/another">
      <MyButton />
    </Link>
  </>
)

If you find that your use case is not covered by Dynamic Routing then you can create a custom server and manually add dynamic routes.

Example:

  1. Consider you have the URL /post/:slug.

  2. You created pages/post.js:

    import { useRouter } from 'next/router'
    
    const Post = () => {
      const router = useRouter()
      const { slug } = router.query
    
      return <p>My Blog Post: {slug}</p>
    }
    
    export default Post
    
  3. You add the route to express (or any other server) on server.js file (this is only for SSR). This will route the url /post/:slug to pages/post.js and provide slug as part of the query object to the page.

    server.get('/post/:slug', (req, res) => {
      return app.render(req, res, '/post', { slug: req.params.slug })
    })
    
  4. For client side routing, use next/link:

    <Link href="/post?slug=something" as="/post/something">
    
    • href: the path inside pages directory
    • as: the path used by your server routes

クライアントサイドでのルーティングはブラウザとほぼ同じです:

  1. The component is fetched.
  2. もし getInitialProps が定義されていればデータを取得する。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 the useRouter hook, or withRouter for class components.

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

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

function Home() {
  return (
    <div>
      Click{' '}
      <Link href={{ pathname: '/about', query: { name: 'Zeit' } }}>
        <a>here</a>
      </Link>{' '}
      to read more
    </div>
  )
}

export default Home

URL文字列/about?name=Zeitが作成され、Node.jsモジュールドキュメントに定義されている全てのプロパティを利用することができます。

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.

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

function Home() {
  return (
    <div>
      Click{' '}
      <Link href="/about" replace>
        <a>here</a>
      </Link>{' '}
      to read more
    </div>
  )
}

export default Home

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

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

function Home() {
  return (
    <div>
      Click{' '}
      <Link href="/about">
        <img src="/static/image.png" alt="image" />
      </Link>
    </div>
  )
}

export default Home

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.

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

function NavLink({ href, name }) {
  return (
    <Link href={href} passHref>
      <Unexpected_A>{name}</Unexpected_A>
    </Link>
  )
}

export default NavLink

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

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

Imperativelypermalink

You can also do client-side page transitions using next/router:

import Router from 'next/router'

function ReadMore() {
  return (
    <div>
      Click <span onClick={() => Router.push('/about')}>here</span> to read more
    </div>
  )
}

export default ReadMore

In some cases (for example, if using a custom router), you may wish to listen to popstate and react before the router acts on it. For example, you could use this to manipulate the request, or force an SSR refresh.

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 the function you pass into beforePopState returns false, Router will not handle popstate; you'll be responsible for handling it, in that case. See 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.

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

import Router from 'next/router'

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

function ReadMore() {
  return (
    <div>
      Click <span onClick={handler}>here</span> to read more
    </div>
  )
}

export default ReadMore

This uses the same exact parameters as in the <Link> component. The first parameter maps to href while the second parameter maps to as in the <Link> component as documented here.

Router Eventspermalink

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, or a route load is cancelled
  • 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:

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:

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.

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

Note: Using router events in getInitialProps is discouraged as it may result in unexpected behavior.
Router events should be registered when a component mounts (useEffect or componentDidMount/componentWillUnmount) or imperatively when an event happens.

useEffect(() => {
  const handleRouteChange = url => {
    console.log('App is changing to: ', url)
  }

  Router.events.on('routeChangeStart', handleRouteChange)
  return () => {
    Router.events.off('routeChangeStart', handleRouteChange)
  }
}, [])

Shallow routing allows you to change the URL without running getInitialProps. You'll receive the updated pathname and the query via the router prop (injected by using useRouter or withRouter), without losing state.

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

// 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 around your Component to inject the router prop).

You can watch for URL changes via componentDidUpdate hook as shown below:

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:

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.

useRouterpermalink

If you want to access the router object inside any functional component in your app, you can use the useRouter hook, here's how to use it:

import { useRouter } from 'next/router'

export default function ActiveLink({ children, href }) {
  const router = useRouter()
  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>
  )
}

Note: useRouter is a React hook, meaning it cannot be used with classes. You can either use withRouter (a higher order component) or wrap your class in a functional component.

The above router object comes with an API similar to next/router.

If useRouter is not the best fit for you, withRouter can also add the same router object to any component, here's how to use it:

import { withRouter } from 'next/router'

function Page({ router }) {
  return <p>{router.pathname}</p>
}

export default withRouter(Page)

⚠️ This is a production only feature ⚠️

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.

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

Automatic prefetching is disabled if your device is connected with 2G network or Save-Data header is on.

<link rel="preload"> is used for prefetching. Sometimes browsers will show a warning if the resource is not used within 3 seconds, these warnings can be ignored as per https://github.com/zeit/next.js/issues/6517#issuecomment-469063892.

With <Link>permalink

<Link> will automatically prefetch pages in the background as they appear in the view. If certain pages are rarely visited you can manually set prefetch to false, here's how:

<Link href="/about" prefetch={false}>
  <a>About</a>
</Link>

Imperativelypermalink

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

import { useRouter } from 'next/router'

export default function MyLink() {
  const router = useRouter()

  return (
    <>
      <a onClick={() => setTimeout(() => router.push('/dynamic'), 100)}>
        A route transition will happen after 100ms
      </a>
      {// and we can prefetch it!
      router.prefetch('/dynamic')}
    </>
  )
}

router methods should be only used inside the client side of your app though. In order to prevent any error regarding this subject use the imperatively prefetch method in the useEffect() hook:

import { useRouter } from 'next/router'

export default function MyLink() {
  const router = useRouter()

  useEffect(() => {
    router.prefetch('/dynamic')
  })

  return (
    <a onClick={() => setTimeout(() => router.push('/dynamic'), 100)}>
      A route transition will happen after 100ms
    </a>
  )
}

You can also add it to the componentDidMount() lifecycle method when using React.Component:

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 (
      <a onClick={() => setTimeout(() => router.push('/dynamic'), 100)}>
        A route transition will happen after 100ms
      </a>
    )
  }
}

export default withRouter(MyLink)

API ルートpermalink

API ルートによって、Next.js で API を構築することはとても簡単です。 まず、./pages フォルダーに api/ フォルダーを作成します。

./pages/api に格納されているすべてのファイルは /api/* にマッピングされます。 例えば、./pages/api/posts.js/api/posts というルートにマッピングされます。

以下が API ルートのファイルの例です:

export default (req, res) => {
  res.setHeader('Content-Type', 'application/json')
  res.statusCode = 200
  res.end(JSON.stringify({ name: 'Nextjs' }))
}

API ルートのために用意されているこれらの NextApiRequestNextApiResponse という型は、それぞれ Node.js の request と response 型の拡張です。

import { NextApiRequest, NextApiResponse } from 'next'

export default (req: NextApiRequest, res: NextApiResponse) => {
  res.status(200).json({ title: 'Next.js' })
}

API 呼び出しで様々な HTTP メソッドを扱いたい場合は、リゾルバ関数内で req.method にアクセスすることができます:

export default (req, res) => {
  if (req.method === 'POST') {
    // Process your POST request
  } else {
    // Handle the rest of your HTTP methods
  }
}

注意: API ルートには CORS ヘッダーが設定されていません。したがって、デフォルトでは 同一オリジンのみ で機能します。 この挙動をカスタマイズしたい場合は、CORS ミドルウェアでラップして export することができます。 その例はこちらです

API ルートによってクライアントサイドのバンドルのサイズが大きくなることはありません。それらはサーバーサイドのみのバンドルとなります。

API ページは動的なルーティングをサポートしているので、その機能のすべてを利用することが可能です。

例えば ./pages/api/post/[pid].js というページがあった場合、リゾルバー関数では以下のようにしてパラメータを取得することができます。

export default (req, res) => {
  const {
    query: { pid },
  } = req

  res.end(`Post: ${pid}`)
}

API ルートには、送信されてきた req をパースするための組み込みミドルウェアが提供されています。 以下がそれらのミドルウェアです:

  • req.cookies : request で送られてきた cookies を格納しているオブジェクトです。デフォルト値は {} です
  • req.query クエリストリングを格納しているオブジェクトです。デフォルト値は {} です
  • req.body content-type にしたがってパースされた body を格納するオブジェクトで、body が含まれない場合には null となります

リクエスト body のパースはデフォルトで有効になっていて、サイズの制限は 1mb です。 もし Stream として利用する必要がある場合には、以下のようにして上記のデフォルトの挙動をオプトアウトすることが可能です:

// ./pages/api/my-endpoint.js
export default (req, res) => {
  // ...
}

export const config = {
  api: {
    bodyParser: false,
  },
}

パースされる body のサイズを変更したい場合は、sizeLimit キーを bodyParser に追加し、bytes ライブラリがサポートしている値を設定します:

// ./pages/api/my-endpoint.js
export default (req, res) => {
  // ...
}

export const config = {
  api: {
    bodyParser: {
      sizeLimit: '1mb',
    },
  },
}

更に嬉しい点として、[Micro])(https://github.com/zeit/micro) 互換のミドルウェアを使うこともできます!

例えば、API エンドポイントで CORS の構成をしたいときは、micro-cors を利用することが可能です。

まず、micro-cors をインストールします:

npm i micro-cors
# or
yarn add micro-cors

そして、micro-cors を import し設定してください。最後に、export される関数をそのミドルウェアでラップすれば完成です。

import Cors from 'micro-cors'

const cors = Cors({
  allowedMethods: ['GET', 'HEAD'],
})

function Endpoint(req, res) {
  res.json({ message: 'Hello Everyone!' })
}

export default cors(Endpoint)

より良い developer experience を提供し、API エンドポイントをより高速に開発できるように、Express.js ライクなメソッドを用意しています:

export default (req, res) => {
  res.status(200).json({ name: 'Next.js' })
}
  • res.status(code) - ステータスコードを設定するための関数です。code は正しい HTTP ステータスコード である必要があります
  • res.json(json) - JSON レスポンスを送信します。json は正しい JSON オブジェクトである必要があります
  • res.send(body) - HTTP レスポンスを送信します。bodystringobject、または Buffer である必要があります

一般的にnext serverでサーバーを立てます。しかし、ルーティングをカスタマイズするためやルーティングパターンを使うためなどにサーバーを100%プログラムで起動することができます。

例えばserver.jsと呼ばれるサーバーのためのファイルでカスタムなサーバーを使おうとする時は, package.json内のscriptsのkeyを下記のように上書きしていることを確認してください:

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

この例では /a./pages/bに対応させ, /b./pages/aに対応させるようにしております:

// 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 {}

それから、startというscriptを NODE_ENV=production node server.jsに変更してください。

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.

もしあなたのプロジェクトがカスタムルーティングを使用しているのなら, この挙動によって異なるパスでも同じコンテンツが読み込まれるようになり、SEOやUX的な問題が起きます。

この挙動を無効にして、 /pagesのファイルに基づいたルーティングを防ぐのなら, next.config.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.

しばしば、私たちは動的にassetPrefixを設定する必要があります。これは入ってくるリクエストに基づくassetPrefixを変更するときに役に立ちます。 そのために、私たちは app.setAssetPrefixを使うことができます。

ここに使用例があります。

const next = require('next')
const http = require('http')

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

app.prepare().then(() => {
  const server = new http.Server((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}`)
  })
})

By default Next.js will add x-powered-by to the request headers. There's an optional way to opt-out of this:

// next.config.js
module.exports = {
  poweredByHeader: false,
}

Next.js supports ES2020 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.

import dynamic from 'next/dynamic'

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

function Home() {
  return (
    <div>
      <Header />
      <DynamicComponent />
      <p>HOME PAGE is here!</p>
    </div>
  )
}

export default Home
// components/hello.js
export function Hello() {
  return <p>Hello!</p>
}
import dynamic from 'next/dynamic'

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

function Home() {
  return (
    <div>
      <Header />
      <DynamicComponent />
      <p>HOME PAGE is here!</p>
    </div>
  )
}

export default Home
import dynamic from 'next/dynamic'

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

function Home() {
  return (
    <div>
      <Header />
      <DynamicComponentWithCustomLoading />
      <p>HOME PAGE is here!</p>
    </div>
  )
}

export default Home

With No SSRpermalink

import dynamic from 'next/dynamic'

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

function Home() {
  return (
    <div>
      <Header />
      <DynamicComponentWithNoSSR />
      <p>HOME PAGE is here!</p>
    </div>
  )
}

export default Home

Next.jsはページを初期化するためにAppコンポーネントを使用します。Appコンポーネントをオーバーライドし、ページの初期化をコントロールすることが可能です。それによってこのような素晴らしい事が可能になります:

  • ページ移動間の固定レイアウト
  • ページ移動する際にステートを保持
  • componentDidCatchを使用したカスタムエラーハンドリング
  • ページに追加のデータを注入(例えばGraphQLクエリを使用することによって)

オーバーライドするには./pages/_app.jsファイルを作成し、以下のようにAppクラスをオーバーライドします:

import React from 'react'
import App from 'next/app'

class MyApp extends App {
  // Only uncomment this method if you have blocking data requirements for
  // every single page in your application. This disables the ability to
  // perform automatic static optimization, causing every page in your app to
  // be server-side rendered.
  //
  // static async getInitialProps(appContext) {
  //   // calls page's `getInitialProps` and fills `appProps.pageProps`
  //   const appProps = await App.getInitialProps(appContext);
  //
  //   return { ...appProps }
  // }

  render() {
    const { Component, pageProps } = this.props
    return <Component {...pageProps} />
  }
}

export default MyApp

Note: Adding a custom getInitialProps in App will affect Automatic Static Optimization

A custom <Document> is commonly used to augment your application's <html> and <body> tags. This is necessary because Next.js pages skip the definition of the surrounding document's markup.

This allows you to support Server-Side Rendering for CSS-in-JS libraries like styled-components or emotion. Note, styled-jsx is included in Next.js by default.

A custom <Document> can also include getInitialProps for expressing asynchronous server-rendering data requirements.

Note: <Document>'s getInitialProps function is not called during client-side transitions, nor when a page is automatically statically optimized.

Note: Make sure to check if ctx.req / ctx.res are defined in getInitialProps. These variables will be undefined when a page is being statically exported for next export or automatic static optimization.

To use a custom <Document>, you must create a file at ./pages/_document.js and extend the Document class:

// _documentはサーバーサイドのみでレンダリングされ、クライアントサイドでは使われません
// onClickのようなイベントハンドラはこのファイルには書けません

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

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

  render() {
    return (
      <Html>
        <Head />
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    )
  }
}

export default MyDocument

All of <Html>, <Head />, <Main /> and <NextScript /> are required for page to be properly rendered.

Note: React-components outside of <Main /> will not be initialised by the browser. アプリケーションロジックをここに追加しないでください。If you need shared components in all your pages (like a menu or a toolbar), take a look at the <App> component instead.

ctxオブジェクトは、すべてのgetInitialPropsフックで受け取るオブジェクトと同等です。さらに加えて:

  • renderPage (Function)は実際のReactのレンダリングロジック(同期的)を実行するコールバックです。It's useful to decorate this function in order to support server-rendering wrappers like Aphrodite's renderStatic.

🚧 It should be noted that the only reason you should be customizing renderPage is for usage with css-in-js libraries that need to wrap the application to properly work with server-rendering. 🚧

  • It takes as argument an options object for further customization:
import Document from 'next/document'

class MyDocument extends Document {
  static async getInitialProps(ctx) {
    const originalRenderPage = ctx.renderPage

    ctx.renderPage = () =>
      originalRenderPage({
        // useful for wrapping the whole react tree
        enhanceApp: App => App,
        // useful for wrapping in a per-page basis
        enhanceComponent: Component => Component,
      })

    // Run the parent `getInitialProps` using `ctx` that now includes our custom `renderPage`
    const initialProps = await Document.getInitialProps(ctx)

    return initialProps
  }
}

export default MyDocument

ステータスコードが404もしくは500のエラーは、error.jsというデフォルトのコンポーネントによってクライアントとサーバーサイドの両方でハンドリングされます。もしデフォルトのエラーコンポーネントをオーバーライドしたいのなら、_error.jsをpagesフォルダーの中に定義して下さい:

⚠️ The pages/_error.js component is only used in production. In development you get an error with call stack to know where the error originated from. ⚠️

import React from 'react'

function Error({ statusCode }) {
  return (
    <p>
      {statusCode
        ?`An error ${statusCode} occurred on server`
        : 'An error occurred on client'}
    </p>
  )
}

Error.getInitialProps = ({ res, err }) => {
  const statusCode = res ? res.statusCode : err ? err.statusCode : 404
  return { statusCode }
}

export default Error

組み込みのエラーページをレンダリングしたいのならば、next/errorを使用すれば可能です:

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

const Page = ({ errorCode, stars }) => {
  if (errorCode) {
    return <Error statusCode={errorCode} />
  }

  return <div>Next stars: {stars}</div>
}

Page.getInitialProps = async () => {
  const res = await fetch('https://api.github.com/repos/zeit/next.js')
  const errorCode = res.statusCode > 200 ?res.statusCode : false
  const json = await res.json()

  return { errorCode, stars: json.stargazers_count }
}

export default Page

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

The Error component also takes title as a property if you want to pass in a text message along with a statusCode.

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.

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

Or use a function:

module.exports = (phase, { defaultConfig }) => {
  return {
    /* config options here */
  }
}

phase is the current context in which the configuration is loaded. You can see all phases here: constants Phases can be imported from next/constants:

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 */
  }
}

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.

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

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.

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

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

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

Aimed at modules like @next/mdx, that add support for pages ending with .mdx. pageExtensions allows you to configure the extensions looked for in the pages directory when resolving pages.

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

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:

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

To fall back to the default of generating a unique id return null from the function:

module.exports = {
  generateBuildId: async () => {
    // When process.env.YOUR_BUILD_ID is undefined we fall back to the default
    if (process.env.YOUR_BUILD_ID) {
      return process.env.YOUR_BUILD_ID
    }

    return null
  },
}

You can pass any node arguments to next CLI command.

NODE_OPTIONS="--throw-deprecation" next
NODE_OPTIONS="-r esm" next
NODE_OPTIONS="--inspect" next

Some commonly asked for features are available as modules:

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:

const withMDX = require('@next/mdx')
const withSass = require('@zeit/next-sass')

module.exports = withMDX(
  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.

// 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, webpack }) => {
    // Note: we provide webpack above so you should not `require` it
    // Perform customizations to webpack config
    // Important: return the modified config

    // Example using webpack option
    config.plugins.push(new webpack.IgnorePlugin(/\/__tests__\//))
    return config
  },
  webpackDevMiddleware: config => {
    // Perform customizations to webpack dev middleware config
    // Important: return the modified config
    return config
  },
}

The second argument to webpack is an object containing properties useful when customizing its configuration:

  • buildId - String the build id used as a unique identifier between builds
  • dev - Boolean shows if the compilation is done in development mode
  • isServer - Boolean shows if the resulting configuration will be used for server side (true), or client side 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

Example usage of defaultLoaders.babel:

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

    return config
  },
}

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:

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

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

  • preset-env
  • preset-react
  • preset-typescript
  • 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:

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

There is a common need in applications to provide configuration values.

Next.js supports 2 ways of providing configuration:

  • Build-time configuration
  • Runtime configuration

The way build-time configuration works is by inlining the provided values into the Javascript bundle.

You can add the env key in next.config.js:

// next.config.js
module.exports = {
  env: {
    customKey: 'value',
  },
}

This will allow you to use process.env.customKey in your code. For example:

// pages/index.js
function Index() {
  return <h1>The value of customKey is: {process.env.customKey}</h1>
}

export default Index

Warning: Note that it is not possible to destructure process.env variables due to the webpack DefinePlugin replacing process.env.XXXX inline at build time.

// Will not work
const { CUSTOM_KEY, CUSTOM_SECRET } = process.env
AuthMethod({ key: CUSTOM_KEY, secret: CUSTOM_SECRET })

// Will work as replaced inline
AuthMethod({ key: process.env.CUSTOM_KEY, secret: process.env.CUSTOM_SECRET })

Warning: Note that this option is not available when using target: 'serverless'

Warning: Generally you want to use build-time configuration to provide your configuration. The reason for this is that runtime configuration adds rendering / initialization overhead and is incompatible with automatic static optimization.

The next/config module gives your app access to the publicRuntimeConfig and serverRuntimeConfig stored in your next.config.js.

Place any server-only runtime config under a serverRuntimeConfig property.

Anything accessible to both client and server-side code should be under publicRuntimeConfig.

Note: A page that relies on publicRuntimeConfig must use getInitialProps to opt-out of automatic static optimization. You can also de-optimize your entire application by creating a Custom <App> with getInitialProps.

// next.config.js
module.exports = {
  serverRuntimeConfig: {
    // Will only be available on the server side
    mySecret: 'secret',
    secondSecret: process.env.SECOND_SECRET, // Pass through env variables
  },
  publicRuntimeConfig: {
    // Will be available on both server and client
    staticFolder: '/static',
  },
}
// 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

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

export default MyImage

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.

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.

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.

If your CDN is on a separate domain and you would like assets to be requested using a CORS aware request you can set a config option for that.

// next.config.js
module.exports = {
  crossOrigin: 'anonymous',
}

Next.js automatically determines that a page is static (can be prerendered) if it has no blocking data requirements. This determination is made by the absence of getInitialProps in the page.

If getInitialProps is present, Next.js will not statically optimize the page. Instead, Next.js will use its default behavior and render the page on-demand, per-request (meaning Server-Side Rendering).

If getInitialProps is absent, Next.js will statically optimize your page automatically by prerendering it to static HTML. During prerendering, the router's query object will be empty since we do not have query information to provide during this phase. Any query values will be populated client side after hydration.

This feature allows Next.js to emit hybrid applications that contain both server-rendered and statically generated pages. This ensures Next.js always emits applications that are fast by default.

Note: Statically generated pages are still reactive: Next.js will hydrate your application client-side to give it full interactivity.

This feature provides many benefits. For example, optimized pages require no server-side computation and can be instantly streamed to the end-user from CDN locations.

The result is an ultra fast loading experience for your users.

next build will emit .html files for statically optimized pages. The result will be a file named .next/server/static/${BUILD_ID}/about.html instead of .next/server/static/${BUILD_ID}/about.js. This behavior is similar for target: 'serverless'.

The built-in Next.js server (next start) and programmatic API (app.getRequestHandler()) both support this build output transparently. There is no configuration or special handling required.

Note: If you have a custom <App> with getInitialProps then this optimization will be disabled.

Note: If you have a custom <Document> with getInitialProps be sure you check if ctx.req is defined before assuming the page is server-side rendered. ctx.req will be undefined for pages that are prerendered.

When a page qualifies for automatic static optimization we show an indicator to let you know. This is helpful since the automatic static optimization can be very beneficial and knowing immediately in development if it qualifies can be useful. See above for information on the benefits of this optimization.

In some cases this indicator might not be as useful like when working on electron applications. For these cases you can disable the indicator in your next.config.js by setting

module.exports = {
  devIndicators: {
    autoPrerender: false,
  },
}

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

next build
next start

To deploy Next.js with ZEIT Now see the ZEIT Guide for Deploying Next.js or the Next.js Learn section about deploying on ZEIT Now.

Next.js can be deployed to other hosting solutions too. Please have a look at the '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, it’s your responsibility to set NODE_ENV=production manually!

Note: we recommend putting .next, or your custom dist folder, 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.

Compressionpermalink

Next.js provides gzip compression to compress rendered content and static files. Compression only works with the server target. In general you will want to enable compression on a HTTP proxy like nginx, to offload load from the Node.js process.

To disable compression in Next.js, set compress to false in next.config.js:

// next.config.js
module.exports = {
  compress: false,
}

Serverless deployment dramatically improves reliability and scalability by splitting your application into smaller parts (also called lambdas). In the case of Next.js, each page in the pages directory becomes a serverless lambda.

There are a number of benefits to serverless. The referenced link talks about some of them in the context of Express, but the principles apply universally: serverless allows for distributed points of failure, infinite scalability, and is incredibly affordable with a "pay for what you use" model.

To enable serverless mode in Next.js, add the serverless build target in next.config.js:

// next.config.js
module.exports = {
  target: 'serverless',
}

The serverless target will output a single lambda or HTML file per page. This file is completely standalone and doesn't require any dependencies to run:

  • pages/index.js => .next/serverless/pages/index.js
  • pages/about.js => .next/serverless/pages/about.js
  • pages/blog.js => .next/serverless/pages/blog.html

The signature of the Next.js Serverless function is similar to the Node.js HTTP server callback:

export function render(req: http.IncomingMessage, res: http.ServerResponse) => void

The static HTML files are ready to be served as-is. You can read more about this feature, including how to opt-out, in the Automatic Static Optimization section.

Using the serverless target, you can deploy Next.js to ZEIT Now with all of the benefits and added ease of control like for example; custom routes and caching headers. See the ZEIT Guide for Deploying Next.js with Now for more information.

Next.js provides low-level APIs for serverless deployments as hosting platforms have different function signatures. In general you will want to wrap the output of a Next.js serverless build with a compatibility layer.

For example if the platform supports the Node.js http.Server class:

const http = require('http')
const page = require('./.next/serverless/pages/about.js')
const server = new http.Server((req, res) => page.render(req, res))
server.listen(3000, () => console.log('Listening on http://localhost:3000'))

For specific platform examples see the examples section above.

Summarypermalink

  • Low-level API for implementing serverless deployment
  • Every page in the pages directory becomes a serverless function (lambda)
  • Creates the smallest possible serverless function (50Kb base zip size)
  • Optimized for fast cold start of the function
  • The serverless function has 0 dependencies (they are included in the function bundle)
  • Uses the http.IncomingMessage and http.ServerResponse from Node.js
  • opt-in using target: 'serverless' in next.config.js
  • Does not load next.config.js when executing the function, note that this means publicRuntimeConfig / serverRuntimeConfig are not supported

Next.js supports IE11 and all modern browsers out of the box using @babel/preset-env. 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 example demonstrates the recommended approach to implement polyfills.

TypeScriptpermalink

IDEのようにNext.jsではTypeScriptを簡単に扱えます。

はじめに、空のtsconfig.jsonファイルをプロジェクトのroot上に作成します。

touch tsconfig.json

先程作成したファイルは、Next.jsによって自動でデフォルト値をもとに構成されます。(独自の tsconfig.json を用いることでのカスタマイズも可能です)

それから、next dev(または、npm run dev)を実行すると環境構築に必要なパッケージをインストールするようメッセージがでますので、インストールしてセットアップを完了してください。

npm run dev

# You'll see instructions like these:
#
# Please install typescript, @types/react, and @types/node by running:
#
#         yarn add --dev typescript @types/react @types/node
#
# ...

これで、.jsから.tsx変換をすることで、TypeScriptが提供する利点を活用できる準備ができました。

TypeScriptに関して詳しく知りたい方は、ドキュメントを確認してください。

注意点 : Next.jsがnext-env.d.tsというファイルをプロジェクトのroot上に作成します。 これはTypeScriptのコンパイラーが型を確実に選択するようにするためです。 このファイルを削除することはできませんが、編集することはできます (ただし、削除する必要はありません)

注意点 : Next.jsは、デフォルトではTypeScriptのstrictモードは有効ではありません。 したがって、TypeScriptに慣れたら別途 tsconfig.json にて設定するとよいでしょう。

Next.js では、NextPage という型が提供されており、pages ディレクトリの中にあるページで使用することができます。NextPagegetInitialProps に対して型情報を提供するため、自分で型定義をすることなく簡単に利用できます。

import { NextPage } from 'next'

interface Props {
  userAgent?: string
}

const Page: NextPage<Props> = ({ userAgent }) => (
  <main>Your user agent: {userAgent}</main>
)

Page.getInitialProps = async ({ req }) => {
  const userAgent = req ?req.headers['user-agent'] : navigator.userAgent
  return { userAgent }
}

export default Page

React.Component の場合は NextPageContext を使います:

import React from 'react'
import { NextPageContext } from 'next'

interface Props {
  userAgent?: string
}

export default class Page extends React.Component<Props> {
  static async getInitialProps({ req }: NextPageContext) {
    const userAgent = req ?req.headers['user-agent'] : navigator.userAgent
    return { userAgent }
  }

  render() {
    const { userAgent } = this.props
    return <main>Your user agent: {userAgent}</main>
  }
}

export const config = { amp: true } をページに追記することで、AMP を有効化することができます。

// pages/about.js
export const config = { amp: true }

export default function AboutPage(props) {
  return <h3>My AMP About Page!</h3>
}
// pages/hybrid-about.js
import { useAmp } from 'next/amp'

export const config = { amp: 'hybrid' }

export default function AboutPage(props) {
  return (
    <div>
      <h3>My AMP Page</h3>
      {useAmp() ?(
        <amp-img
          width="300"
          height="300"
          src="/my-img.jpg"
          alt="a cool image"
          layout="responsive"
        />
      ) : (
        <img width="300" height="300" src="/my-img.jpg" alt="a cool image" />
      )}
    </div>
  )
}

AMP化するには、2つのモードがあります:

  • AMP-only (デフォルト)
    • ページには、Next.js および React のクライアント側でのランタイムはありません
    • ページには AMP キャッシュと同じ変換が適用され、AMP Optimizerによって自動的に最適化されます (最大で、パフォーマンスを42%向上します)
    • ページには、ユーザーがアクセス可能な(最適化された)バージョンと、検索エンジンでインデックス可能な(最適化されていない)バージョンがあります
    • export const config = { amp: true }で設定します
  • ハイブリッド
    • 従来のHTML(デフォルト)のレンダリングに加えて、URLの末尾に ?amp=1 を指定することで AMP HTML としてレンダリングすることが可能です
    • AMPバージョンのページでは、 AMP Optimizer による valid な最適化のみが行われるため、検索エンジンでのインデックスが可能です
    • export const config = { amp: 'hybrid' } で設定します
    • next/ampuseAmp を使用することで、AMP-only とハイブリッドモードを区別することができます

どちらのモードも、検索エンジン経由でのアクセスにおいて一貫した高速な UX を提供します。

next export で静的にページを事前レンダリングする際、Next.js はページが AMP をサポートしているかを検出し、結果に応じて挙動を変更します。

ハイブリッド AMP (pages/about.js) での出力例は以下です:

  • out/about.html - クライアントサイドの React ランタイム
  • out/about.amp.html - AMP ページ

AMP-only (pages/about.js) での出力例は以下です:

  • out/about.html - 最適化された AMP ページ

エクスポートの際に、ページがハイブリッド AMP ページかどうかを自動的に検出し、AMP バージョンを page.amp.html へ出力します。エクスポート中にページがハイブリッドAMPページかどうかを自動的に検出し、AMPバージョンを page.amp.htmlへ出力します。また、自動的に<link rel="amphtml" href="/page.amp" /><link rel="canonical" href="/" />タグを埋め込みます。

注意: next.config.jsexportTrailingSlash: true と記載した場合、出力先がそれぞれのモードにおいて異なります。ハイブリッド AMPページの場合、出力先が out/page/index.htmlout/page.amp/index.html となり、AMP-only ページだと out/page/index.html となります。

AMP コミュニティではたくさんのコンポーネントが用意されており、AMP ページをよりインタラクティブにします。下記のように next/head を使ってAMP Componentsを追加することができます:

// pages/hello.js
import Head from 'next/head'

export const config = { amp: true }

export default function MyAmpPage() {
  return (
    <div>
      <Head>
        <script
          async
          key="amp-timeago"
          custom-element="amp-timeago"
          src="https://cdn.ampproject.org/v0/amp-timeago-0.1.js"
        />
      </Head>

      <p>Some time: {date.toJSON()}</p>
      <amp-timeago
        width="0"
        height="15"
        datetime={date.toJSON()}
        layout="responsive"
      >
        .
      </amp-timeago>
    </div>
  )
}

開発中は、amphtml-validatorによって、自動で AMP ページが検証されます。エラーと警告に関しては、Next.js を起動したターミナルに表示されます。

また、next export の際にも AMP に関する検証が行われ、エラーや警告があればターミナルに表示されます。 出力が有効な AMP ではなく AMP に関するエラーが起きた場合は、next export はステータスコード 1 をもって処理を終了します。

現在AMPにはTypeScriptの組み込み型はありません。しかし、ロードマップ (#13791)にあるため、近い将来実装されるかもしれません。回避策としては、参考例のように手動で amp.d.ts に型を定義することで TypeScript 化を行えます。

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 prerendering 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 prerendering. Defaults to {}

Usagepermalink

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.

// next.config.js
module.exports = {
  exportPathMap: async function(
    defaultPathMap,
    { dev, dir, outDir, distDir, buildId }
  ) {
    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' } },
    }
  },
}

The pages will be exported as html files, i.e. /about will become /about.html.

It is possible to configure Next.js to export pages as index.html files and require trailing slashes, i.e. /about becomes /about/index.html and is routable via /about/. This was the default behavior prior to Next.js 9. You can use the following next.config.js to switch back to this behavior:

// next.config.js
module.exports = {
  exportTrailingSlash: true,
}

Note: If the export path is a filename (e.g. /readme.md) and is different than .html, you may need to set the Content-Type header to text/html when serving this content.

The second argument is an object with:

  • dev - true when exportPathMap is being called in development. false when running next export. In development exportPathMap is used to define routes.
  • 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

Then simply run these commands:

next build
next export

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

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

And run it at once with:

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.

For an example, simply visit the out directory and run following command to deploy your app to ZEIT Now.

now

Limitationpermalink

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 empty objects during export as there is no server running.

Note: If your pages don't have getInitialProps you may not need next export at all, next build is already enough thanks to automatic static optimization.

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 Zonespermalink

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

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

  • An app for serving /blog/**
  • Another app for serving all other pages

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

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

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

  • Make sure to keep only the pages you need in your app, meaning that an app can't have pages from another app, if app A has /blog then app B shouldn't have it too.
  • Make sure to add an assetPrefix to avoid conflicts with static files.

You can merge zones using any HTTP proxy.

You can use now dev as your local development server. It allows you to easily define routing routes for multiple apps like below:

{
  "version": 2,
  "builds": [
    { "src": "docs/next.config.js", "use": "@now/next" },
    { "src": "home/next.config.js", "use": "@now/next" }
  ],
  "routes": [
    { "src": "/docs(.*)", "dest": "docs$1", "continue": true },
    { "src": "(?!/?docs)(.*)", "dest": "home$1", "continue": true }
  ]
}

For the production deployment, you can use the same configuration and run now to do the deployment with ZEIT Now. Otherwise you can also configure a proxy server to route using a set of routes like the ones above, e.g deploy the docs app to https://docs.example.com and the home app to https://home.example.com and then add a proxy server for both apps in https://example.com.

FAQpermalink

Is this production ready?

Next.js has been powering https://zeit.co since its inception.

We’re ecstatic about both the developer experience and end-user performance, so we decided to share it with the community.

How big is it?

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

Is this like `create-react-app`?

Yes and No.

Yes in that both make your life easier.

No in that it enforces a structure so that we can do more advanced things like:

  • Server side rendering
  • Automatic code splitting

In addition, Next.js provides two built-in features that are critical for every single website:

  • Routing with lazy component loading: <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!

How do I use CSS-in-JS solutions?

Next.js bundles 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 in the document.

What syntactic features are transpiled?How do I change them?

We track V8. Since V8 has wide support for ES6 and async and await, we transpile those. Since V8 doesn’t support class decorators, we don’t transpile those.

See the documentation about customizing the babel config and next/preset for more information.

Why a new Router?

Next.js is special in that:

  • Routes don’t need to be known ahead of time
  • Routes are always lazy-loadable
  • Top-level components can define getInitialProps that should block the loading of the route (either when server-rendering or lazy-loading)

As a result, we were able to introduce a very simple approach to routing that consists of two pieces:

  • Every top level component receives a url object to inspect the url or perform modifications to the history
  • A <Link /> component is used to wrap elements like anchors (<a/>) to perform client-side transitions
How do I define a custom fancy route?

Next.js provide dynamic routing solution out of the box. This allows to use pretty links in url.

You can check an example to see how it works.

How do I fetch data?

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

Can I use it with GraphQL?

Yes! Here's an example with Apollo.

Can I use it with Redux and thunk?

Yes! Here's an example.

Can I use it with Redux?

Yes! Here's an example.

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

Since our first release we've had many example contributions, you can check them out in the examples directory.

What is this inspired by?

Many of the goals we set out to accomplish were the ones listed in The 7 principles of Rich Web Applications 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 (now deprecated), a similar approach to Next.js by the creator of React Jordan Walke.

Contributingpermalink

Please see our contributing.md.

Authorspermalink