Visit 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.
- How to use
- Setup
- Automatic code splitting
- CSS
- Static file serving (e.g.: images)
- Dynamic Routing
- Populating
<head>
- Fetching data and component lifecycle
- Routing
- Prefetching Pages
- API Routes
- Custom server and routing
- Dynamic Import
- Custom
<App>
- Custom
<Document>
- Custom error handling
- Reusing the built-in error page
- Custom configuration
- Customizing webpack config
- Customizing babel config
- Exposing configuration to the server / client side
- Starting the server on alternative hostname
- CDN support with Asset Prefix
- Automatic Static Optimization
- Automatic Static Optimization Indicator
- Production deployment
- Browser support
- TypeScript
- AMP Support
- Static HTML export
- Multi Zones
- FAQ
- Contributing
- Authors
npx create-next-app
(npx comes with npm 5.2+ and higher, see instructions for older npm versions)
Install it in your project:
npm install --save next react react-dom
and add a script to your package.json like this:
{
"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:
function Home() {
return <div>Welcome to Next.js!</div>
}
export default Home
and then just run npm run dev
and go to http:https://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.
./public/
is mapped to/
(given you create a./public/
directory inside your project)
Every import
you declare gets bundled and served with each page. That means pages never load unnecessary code!
import cowsay from 'cowsay-browser'
function CowsayHi() {
return <pre>{cowsay.say({ text: 'hi there!' })}</pre>
}
export default CowsayHi
Examples
We bundle 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.
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
Please see the styled-jsx documentation for more examples.
It's possible to use any existing CSS-in-JS solution. The simplest one is inline styles:
function HiThere() {
return <p style={{ color: 'red' }}>hi there</p>
}
export default HiThere
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>
component that wraps each page.
To support importing .css
, .scss
, .less
or .styl
files you can use these modules, which configure sensible defaults for server rendered applications.
Create a folder called public
in your project root directory. From your code you can then reference those files starting from the baseURL /
function MyImage() {
return <img src="/my-image.png" alt="my image" />
}
export default MyImage
Note: Don't name the public
directory anything else. The name can't be changed and is the only directory that Next.js uses for serving static assets.
Examples
Defining routes by using predefined paths is not always enough for complex applications, in Next.js you can add brackets to a page ([param]
) to create a dynamic route (a.k.a. url slugs, pretty urls, et al).
Consider the following page 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
Any route like /post/1
, /post/abc
, etc will be matched by pages/post/[pid].js
.
The matched path parameter will be sent as a query parameter to the page.
For example, the route /post/abc
will have the following query
object: { pid: 'abc' }
.
Similarly, the route /post/abc?foo=bar
will have the query
object: { foo: 'bar', pid: 'abc' }
.
Note: Multiple dynamic route segments work the same way.
For example,
pages/post/[pid]/[comment].js
would match/post/1/a-comment
. Itsquery
object would be:{ pid: '1', comment: 'a-comment' }
.
A <Link>
for /post/abc
looks like so:
<Link href="/post/[pid]" as="/post/abc">
<a>First Post</a>
</Link>
href
: the path insidepages
directory.as
: the path that will be rendered in the browser URL bar.
As href
is a filesystem path, it shouldn't change at runtime, instead, you will probably need to change as
dynamically according to your needs. Here's an example to create a list of links:
const pids = ['id1', 'id2', 'id3']
{
pids.map(pid => (
<Link href="/post/[pid]" as={`/post/${pid}`}>
<a>Post {pid}</a>
</Link>
))
}
You can read more about
<Link>
here.
However, if a query and route param name are the same, route parameters will override the matching query params.
For example, /post/abc?pid=bcd
will have the query
object: { pid: 'abc' }
.
Note: Predefined routes take precedence over dynamic routes. For example, if you have
pages/post/[pid].js
andpages/post/create.js
, the route/post/create
will be matched bypages/post/create.js
instead of the dynamic route ([pid]
).
Note: Pages that are statically optimized by automatic static optimization will be hydrated without their route parameters provided (
query
will be empty, i.e.{}
). After hydration, Next.js will trigger an update to your application to provide the route parameters in thequery
object. If your application cannot tolerate this behavior, you can opt-out of static optimization by capturing the query parameter ingetInitialProps
.
Note: If deploying to ZEIT Now dynamic routes will work out-of-the-box. You do not need to configure custom routes in a
now.json
file.If you are new to ZEIT Now, you can learn how to deploy a Next.js app to it in the Deploying a Next.js App Learn section.
Examples
We expose a built-in component for appending elements to the <head>
of the page.
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
To avoid duplicate tags in your <head>
you can use the key
property, which will make sure the tag is only rendered once:
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
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.
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.
Examples
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
Notice that to load data when the page loads, we use getInitialProps
which is an async
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.
getInitialProps
can not be used in children components. Only inpages
.- If you are using some server only modules inside
getInitialProps
, make sure to import them properly, otherwise, it'll slow down your app.
getInitialProps
receives a context object with the following properties:
pathname
- path section of URLquery
- query string section of URL parsed as an objectasPath
-String
of the actual path (including the query) shows in the browserreq
- HTTP request object (server only)res
- HTTP response object (server only)err
- Error object if any error is encountered during the rendering
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.
Examples
Client-side transitions between routes can be enabled via a <Link>
component.
This component is not required for navigations to static pages that require a hard refresh, like when using AMP.
Basic Example
Consider these two pages:
// 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>
</>
)
Custom routes (using props from URL)
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:
-
Consider you have the URL
/post/:slug
. -
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
-
You add the route to
express
(or any other server) onserver.js
file (this is only for SSR). This will route the url/post/:slug
topages/post.js
and provideslug
as part of thequery
object to the page.server.get('/post/:slug', (req, res) => { return app.render(req, res, '/post', { slug: req.params.slug }) })
-
For client side routing, use
next/link
:<Link href="/post?slug=something" as="/post/something">
href
: the path insidepages
directoryas
: the path used by your server routes
Client-side routing behaves exactly like the browser:
- The component is fetched.
- If it defines
getInitialProps
, data is fetched. If an error occurs,_error.js
is rendered. - After 1 and 2 complete,
pushState
is performed and the new component is rendered.
To inject the pathname
, query
or asPath
in your component, you can use the useRouter hook, or withRouter for class components.
Examples
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
That will generate the URL string /about?name=Zeit
, you can use every property as defined in the Node.js URL module documentation.
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 site’s 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>
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 routepathname
-String
of the current path excluding the query stringquery
-Object
with the parsed query string. Defaults to{}
.asPath
-String
of the actual path (including the query) shows in the browserpush(url, as=url)
- performs apushState
call with the given urlreplace(url, as=url)
- performs areplaceState
call with the given urlbeforePopState(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.
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 changerouteChangeComplete(url)
- Fires when a route changed completelyrouteChangeError(err, url)
- Fires when there's an error when changing routes, or a route load is cancelledbeforeHistoryChange(url)
- Fires just before changing the browser's historyhashChangeStart(url)
- Fires when the hash will change but not the pagehashChangeComplete(url)
- Fires when the hash has changed but not the page
Here
url
is the URL shown in the browser. If you callRouter.push(url, as)
(or similar), then the value ofurl
will beas
.
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
orcomponentDidMount
/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) } }, [])
Examples
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.
Examples
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 usewithRouter
(a higher order component) or wrap your class in a functional component.
The above router
object comes with an API similar to next/router
.
Examples
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)
Examples
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 vercel#6517 (comment).
<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>
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)
Examples
API routes provide a straightforward solution to build your API with Next.js.
Start by creating the api/
folder inside the ./pages/
folder.
Every file inside ./pages/api
is mapped to /api/*
.
For example, ./pages/api/posts.js
is mapped to the route /api/posts
.
Here's an example API route file:
export default (req, res) => {
res.setHeader('Content-Type', 'application/json')
res.statusCode = 200
res.end(JSON.stringify({ name: 'Nextjs' }))
}
-
req
refers to NextApiRequest which extends http.IncomingMessage -
res
refers to NextApiResponse which extends http.ServerResponse
For API routes there are built-in types NextApiRequest
and NextApiResponse
, which extend the Node.js
request and response objects.
import { NextApiRequest, NextApiResponse } from 'next'
export default (req: NextApiRequest, res: NextApiResponse) => {
res.status(200).json({ title: 'Next.js' })
}
To handle different HTTP methods for API calls you can access req.method
in your resolver function:
export default (req, res) => {
if (req.method === 'POST') {
// Process your POST request
} else {
// Handle the rest of your HTTP methods
}
}
Note: API Routes do not specify CORS headers, so they'll be same-origin only by default. You can customize this behavior by wrapping your export with CORS middleware. We provide an example of this below.
API Routes do not increase your client-side bundle size. They are server-side only bundles.
API pages support dynamic routing, so you can use all benefits mentioned already above.
Consider the following page ./pages/api/post/[pid].js
, here is how you get parameters inside the resolver method:
export default (req, res) => {
const {
query: { pid },
} = req
res.end(`Post: ${pid}`)
}
API routes provides built in middlewares which parse the incoming req
.
Those middlewares are:
req.cookies
- an object containing the cookies sent by the request. Defaults to{}
req.query
- an object containing the query string. Defaults to{}
req.body
- an object containing the body parsed bycontent-type
, ornull
if no body is sent
Body parsing is enabled by default with a size limit of 1mb
for the parsed body.
You can opt-out of automatic body parsing if you need to consume it as a Stream
:
// ./pages/api/my-endpoint.js
export default (req, res) => {
// ...
}
export const config = {
api: {
bodyParser: false,
},
}
You can adjust size of parsed body by adding sizeLimit
key to bodyParser
, supported values are by bytes library.
// ./pages/api/my-endpoint.js
export default (req, res) => {
// ...
}
export const config = {
api: {
bodyParser: {
sizeLimit: '1mb',
},
},
}
As an added bonus, you can also use any Micro compatible middleware!
For example, configuring CORS for your API endpoint can be done leveraging micro-cors
.
First, install micro-cors
:
npm i micro-cors
# or
yarn add micro-cors
Then, import micro-cors
and configure it. Finally, wrap your exported function in the middleware:
import Cors from 'micro-cors'
const cors = Cors({
allowMethods: ['GET', 'HEAD'],
})
function Endpoint(req, res) {
res.json({ message: 'Hello Everyone!' })
}
export default cors(Endpoint)
We're providing a set of Express.js-like methods to improve the developer experience and increase the speed of creating new API endpoints:
export default (req, res) => {
res.status(200).json({ name: 'Next.js' })
}
res.status(code)
- a function to set the status code.code
must be a valid HTTP status coderes.json(json)
- Sends aJSON
response.json
must be a validJSON
objectres.send(body)
- Sends the HTTP response.body
can be astring
, anobject
or aBuffer
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:
{
"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
:
// 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:https://localhost:3000')
})
})
The next
API is as follows:
next(opts: object)
Supported options:
dev
(bool
) whether to launch Next.js in dev mode - defaultfalse
dir
(string
) where the Next project is located - default'.'
quiet
(bool
) Hide error messages containing server information - defaultfalse
conf
(object
) the same object you would use innext.config.js
- default{}
Then, change your start
script to 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
.
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
:
// 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
.
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:
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:https://cdn.com/myapp')
} else {
app.setAssetPrefix('')
}
handleNextRequests(req, res)
})
server.listen(port, err => {
if (err) {
throw err
}
console.log(`> Ready on http:https://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,
}
Examples
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
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 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
- 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:
function MyApp({ Component, pageProps }) {
return <Component {...pageProps} />
}
// 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.
//
// MyApp.getInitialProps = async (appContext) => {
// // calls page's `getInitialProps` and fills `appProps.pageProps`
// const appProps = await App.getInitialProps(appContext);
//
// return { ...appProps }
// }
export default MyApp
Note: Adding a custom
getInitialProps
in App will affect Automatic Static Optimization
Examples
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>
'sgetInitialProps
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 ingetInitialProps
. These variables will beundefined
when a page is being statically exported fornext 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 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, { 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. Do not add application logic here. If you need shared components in all your pages (like a menu or a toolbar), take a look at the <App>
component instead.
The ctx
object is equivalent to the one received in all getInitialProps
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'srenderStatic
.
🚧 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 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:
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
If you want to render the built-in error page you can by using 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 ofnext/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
Examples
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 theisServer
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 buildsdev
-Boolean
shows if the compilation is done in development modeisServer
-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 configurationbabel
-Object
thebabel-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
},
}
Examples
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 these options are 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 usegetInitialProps
to opt-out of automatic static optimization. You can also de-optimize your entire application by creating a Custom<App>
withgetInitialProps
.
// 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>
withgetInitialProps
then this optimization will be disabled.
Note: If you have a custom
<Document>
withgetInitialProps
be sure you check ifctx.req
is defined before assuming the page is server-side rendered.ctx.req
will beundefined
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.
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,
}
Examples
- now.sh
- anna-artemov.now.sh
- We encourage contributing more examples to this section
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
- http.IncomingMessage
- http.ServerResponse
void
refers to the function not having a return value and is equivalent to JavaScript'sundefined
. Calling the function will finish the request.
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:https://localhost:3000'))
For specific platform examples see the examples section above.
- 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'
innext.config.js
- Does not load
next.config.js
when executing the function, note that this meanspublicRuntimeConfig
/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.
Next.js provides an integrated TypeScript experience out of the box, similar to an IDE.
To get started, create a empty tsconfig.json
file in the root of your project:
touch tsconfig.json
Next.js will automatically configure this file with default values (providing your own tsconfig.json
is also supported).
Then, run next dev
(normally npm run dev
) and Next.js will guide you through installing the necessary packages to complete setup.
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
#
# ...
You're now ready to start converting files from .js
to .tsx
and leveraging the benefits TypeScript provides!
To learn more about TypeScript checkout its documentation.
Note: Next.js will create a file named
next-env.d.ts
in the root of your project. This file ensures Next.js' types are picked up by the TypeScript compiler.You cannot remove this file, however, you can edit it (but don't need to).
Note: Next.js does not enable TypeScript's
strict
mode by default. When you feel comfortable with TypeScript, you may turn this option on in yourtsconfig.json
.
Note: By default, Next.js reports TypeScript errors during development for pages you are actively working on. TypeScript errors for inactive pages do not block the development process.
If you don't want to leverage this behavior and instead, e.g. prefer your editor's integration, you can set the following option in
next.config.js
:// next.config.js module.exports = { typescript: { ignoreDevErrors: true, }, }Next.js will still fail your production build (
next build
) when TypeScript errors are present in your project.If you'd like Next.js to dangerously produce production code even when your application is broken, you can set the following option in your
next.config.js
. Be sure you are running type checks as part of your build or deploy process!// next.config.js module.exports = { typescript: { // !! WARN !! // Dangerously allow production builds to successfully complete even if // your project has type errors. // // This option is rarely needed, and should be reserved for advanced // setups. You may be looking for `ignoreDevErrors` instead. // !! WARN !! ignoreBuildErrors: true, }, }
Next.js provides NextPage
type that can be used for pages in the pages
directory. NextPage
adds definitions for getInitialProps
so that it can be used without any extra typing needed.
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
For React.Component
you can use 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>
}
}
Examples
To enable AMP support for a page, add export const config = { amp: true }
to your page.
// 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 pages can specify two modes:
- AMP-only (default)
- Pages have no Next.js or React client-side runtime
- Pages are automatically optimized with AMP Optimizer, an optimizer that applies the same transformations as AMP caches (improves performance by up to 42%)
- Pages have a user-accessible (optimized) version of the page and a search-engine indexable (unoptimized) version of the page
- Opt-in via
export const config = { amp: true }
- Hybrid
- Pages are able to be rendered as traditional HTML (default) and AMP HTML (by adding
?amp=1
to the URL) - The AMP version of the page only has valid optimizations applied with AMP Optimizer so that it is indexable by search-engines
- Opt-in via
export const config = { amp: 'hybrid' }
- Able to differentiate between modes using
useAmp
fromnext/amp
- Pages are able to be rendered as traditional HTML (default) and AMP HTML (by adding
Both of these page modes provide a consistently fast experience for users accessing pages through search engines.
When using next export
to statically prerender pages Next.js will detect if the page supports AMP and change the exporting behavior based on that.
Hybrid AMP (pages/about.js
) would output:
out/about.html
- with client-side React runtimeout/about.amp.html
- AMP page
AMP-only (pages/about.js
) would output:
out/about.html
- Optimized AMP page
During export Next.js automatically detects if a page is hybrid AMP and outputs the AMP version to page.amp.html
. We also automatically insert the <link rel="amphtml" href="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/page.amp" />
and <link rel="canonical" href="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/" />
tags for you.
Note: When using
exportTrailingSlash: true
innext.config.js
, output will be different. For Hybrid AMP pages, output will beout/page/index.html
andout/page.amp/index.html
, and for AMP-only pages, output will beout/page/index.html
The AMP community provides many components to make AMP pages more interactive. You can add these components to your page by using next/head
:
// 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>
)
}
AMP pages are automatically validated with amphtml-validator during development. Errors and warnings will appear in the terminal where you started Next.js.
Pages are also validated during next export
and any warnings / errors will be printed to the terminal.
Any AMP errors will cause next export
to exit with status code 1
because the export is not valid AMP.
AMP currently doesn't have built-in types for TypeScript, but it's in their roadmap (#13791). As a workaround you can manually add the types to amp.d.ts
like here.
Examples
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 thepages
directory to renderquery
-Object
thequery
object passed togetInitialProps
when prerendering. Defaults to{}
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 theContent-Type
header totext/html
when serving this content.
The second argument is an object
with:
dev
-true
whenexportPathMap
is being called in development.false
when runningnext export
. In developmentexportPathMap
is used to define routes.dir
- Absolute path to the project directoryoutDir
- Absolute path to theout/
directory (configurable with-o
or--outdir
). Whendev
istrue
the value ofoutDir
will benull
.distDir
- Absolute path to the.next/
directory (configurable using thedistDir
config key)buildId
- ThebuildId
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
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 neednext 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
Examples
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 appB
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
.
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 importingnext/link
) - A way for components to alter
<head>
:<Head>
(by importingnext/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.
Please see our contributing.md.
- Arunoda Susiripala (@arunoda) – ZEIT
- Tim Neutkens (@timneutkens) – ZEIT
- Naoyuki Kanezawa (@nkzawa) – ZEIT
- Tony Kovanen (@tonykovanen) – ZEIT
- Guillermo Rauch (@rauchg) – ZEIT
- Dan Zajdband (@impronunciable) – Knight-Mozilla / Coral Project