[](https://travis-ci.org/zeit/next.js)
[](https://coveralls.io/r/zeit/next.js?branch=master)
[](https://zeit.chat)
Next.js is a minimalistic framework for server-rendered React applications.
**NOTE! the README on the `master` branch might not match that of the [latest stable release](https://github.com/zeit/next.js/releases/latest)! **
## How to use
Install it:
```
$ npm install next --save
```
and add a script to your package.json like this:
```json
{
"scripts": {
"dev": "next"
}
}
```
After that, the file-system is the main API. Every `.js` file becomes a route that gets automatically processed and rendered.
Populate `./pages/index.js` inside your project:
```jsx
import React from 'react'
export default () => (
Welcome to next.js!
)
```
and then just run `npm run dev` and go to `http://localhost:3000`
So far, we get:
- Automatic transpilation and bundling (with webpack and babel)
- Hot code reloading
- Server rendering and indexing of `./pages`
- Static file serving. `./static/` is mapped to `/static/`
To see how simple this is, check out the [sample app - nextgram](https://github.com/zeit/nextgram)
### Bundling (code splitting)
Every `import` you declare gets bundled and served with each page
```jsx
import cowsay from 'cowsay-browser'
export default () => (
{ cowsay.say({ text: 'hi there!' }) }
)
```
That means pages never load unnecessary code!
### CSS
We use [glamor](https://github.com/threepointone/glamor) to provide a great built-in solution for CSS isolation and modularization without trading off any CSS features.
Glamor's [HowTo](https://github.com/threepointone/glamor/blob/master/docs/howto.md) shows converting various CSS use cases to Glamor. See Glamor's [API docs](https://github.com/threepointone/glamor/blob/master/docs/api.md) for more details.
```jsx
import css from 'next/css'
export default () => (
Hello world
)
const style = css({
background: 'red',
':hover': {
background: 'gray'
},
'@media (max-width: 600px)': {
background: 'blue'
}
})
```
### Images and other static files
Create a folder called `static` in your project root directory. From your code you can then reference those files with `/static/` URLs, e.g.: ``.
### `` side effects
We expose a built-in component for appending elements to the `` of the page.
```jsx
import Head from 'next/head'
export default () => (
My page title
Hello world!
)
```
### Component lifecycle
When you need state, lifecycle hooks or **initial data population** you can export a `React.Component`.
```jsx
import React from 'react'
export default class extends React.Component {
static async getInitialProps ({ req }) {
return req
? { userAgent: req.headers['user-agent'] }
: { userAgent: navigator.userAgent }
}
render () {
return
Hello World {this.props.userAgent}
}
}
```
Notice that to load data when the page loads, we use `getInitialProps` which is an [`async`](https://zeit.co/blog/async-and-await) static method. It can asynchronously fetch anything that resolves to a JavaScript plain `Object`, which populates `props`.
For the initial page load, `getInitialProps` will execute on the server only. `getInitialProps` will only be executed on the client when navigating to a different route via the `Link` component and the `props.url`.
`getInitialProps` receives a context object with the following properties:
- `pathname` - path section of URL
- `query` - query string section of URL parsed as an object
- `req` - HTTP request object (server only)
- `res` - HTTP response object (server only)
- `xhr` - XMLHttpRequest object (client only)
- `err` - Error object if any error is encountered during the rendering
### Routing
Client-side transitions between routes are enabled via a `` component
#### pages/index.js
```jsx
import Link from 'next/link'
export default () => (
)
```
Client-side routing behaves exactly like the native UA:
1. The component is fetched
2. If it defines `getInitialProps`, data is fetched. If an error occurs, `_error.js` is rendered
3. After 1 and 2 complete, `pushState` is performed and the new component rendered
Each top-level component receives a `url` property with the following API:
- `pathname` - `String` of the current path excluding the query string
- `query` - `Object` with the parsed query string. Defaults to `{}`
- `push(url)` - performs a `pushState` call associated with the current component
- `replace(url)` - performs a `replaceState` call associated with the current component
- `pushTo(url)` - performs a `pushState` call that renders the new `url`. This is equivalent to following a ``
- `replaceTo(url)` - performs a `replaceState` call that renders the new `url`
### Prefetching Pages
When you are switching between pages, Next.js will download new pages from the server and render them for you. So, it'll take some time to download. Because of that, when you click on a page, it might wait few milliseconds (depending on the network speed) before it render the page.
> Once the Next.js has download the page, it'll reuse it in the next time when you navigate to that same page.
This is a problem specially in UX wise. "Prefetching Pages" is one of our solutions for this problem. With this, Next.js will prefetch pages behind the scene using the support of [Service Workers](https://developers.google.com/web/fundamentals/getting-started/primers/service-workers).
#### Declarative API
You can simply ask Next.js to prefetch pages using `next/prefetch`. See:
```jsx
import Link from 'next/prefetch'
// This is the header component
export default () => (
Home
Home
Home
)
```
Here you are using `` from `next/prefetch` instead of `next/link`. It's an extended version of `next/link` with prefetching support.
Then Next.js will start to prefetch all the pages behind the scene. So, when you click on any of the link it won't need to do a network hit to fetch the page.
If you need, you could stop prefetching like this:
```jsx
Home
```
#### Imperative API
You can get started with prefetching using `` pretty quickly. But you may want to prefetch based on your own logic. (You may need to write a custom prefetching `` based on [premonish](https://github.com/mathisonian/premonish).)
Then you can use the imperative API like this:
```jsx
import { prefetch } from 'next/prefetch'
prefetch('/')
prefetch('/features')
```
When you simply run `prefetch('/page_url')` we'll start prefetching that page.
> We can only do this, if `prefetch` is called when loading the current page. So in general, make sure to run `prefetch` calls in a common module all of your pages import.
### Error handling
404 or 500 errors are handled both client and server side by a default component `error.js`. If you wish to override it, define a `_error.js`:
```jsx
import React from 'react'
export default class Error extends React.Component {
static getInitialProps ({ res, xhr }) {
const statusCode = res ? res.statusCode : (xhr ? xhr.status : null)
return { statusCode }
}
render () {
return (
{
this.props.statusCode
? `An error ${this.props.statusCode} occurred on server`
: 'An error occurred on client'
}
)
}
}
```
## Production deployment
To deploy, instead of running `next`, you probably want to build ahead of time. Therefore, building and starting are separate commands:
```bash
next build
next start
```
For example, to deploy with [`now`](https://zeit.co/now) a `package.json` like follows is recommended:
```json
{
"name": "my-app",
"dependencies": {
"next": "latest"
},
"scripts": {
"dev": "next",
"build": "next build",
"start": "next start"
}
}
```
Then run `now` and enjoy!
Note: we recommend putting `.next` in `.npmignore` or `.gitignore`. Otherwise, use `files` or `now.files` to opt-into a whitelist of files you want to deploy (and obviously exclude `.next`)
## FAQ
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 next bundle, which includes React and Glamor is **73kb** gzipped.
The Next runtime (lazy loading, routing, ``) contributes around **15%** to the size of that bundle.
The codebase is ~1500LOC (excluding CLI programs).
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: `` (by importing `next/link`)
- A way for components to alter ``: `` (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!
Why CSS-in-JS?
`next/css` is powered by [Glamor](https://github.com/threepointone/glamor). While it exposes a JavaScript API, it produces regular CSS and therefore important features like `:hover`, animations, media queries all work.
There’s *no tradeoff* in power. Instead, we gain the power of simpler composition and usage of JavaScript expressions.
*Compiling* regular CSS files would be counter-productive to some of our goals. Some of these are listed below.
**Please note**: we are very interested in supporting regular CSS, since it's so much easier to write and already familiar. To that end, we're currently exploring the possibility of leveraging Shadow DOM to avoid the entire CSS parsing and mangling step [[#22](https://github.com/zeit/next.js/issues/22)]
### Compilation performance
Parsing, prefixing, modularizing and hot-code-reloading CSS can be avoided by just using JavaScript.
This results in better compilation performance and less memory usage (especially for large projects). No `cssom`, `postcss`, `cssnext` or transformation plugins.
It also means fewer dependencies and fewer things for Next to do. Everything is Just JavaScript® (since JSX is completely optional)
### Lifecycle performance
Since every class name is invoked with the `css()` helper, Next.js can intelligently add or remove `
[](https://travis-ci.org/zeit/next.js)
[](https://coveralls.io/r/zeit/next.js?branch=master)
[](https://zeit.chat)
Next.js is a minimalistic framework for server-rendered React applications.
**NOTE! the README on the `master` branch might not match that of the [latest stable release](https://github.com/zeit/next.js/releases/latest)! **
## How to use
Install it:
```
$ npm install next --save
```
and add a script to your package.json like this:
```json
{
"scripts": {
"dev": "next"
}
}
```
After that, the file-system is the main API. Every `.js` file becomes a route that gets automatically processed and rendered.
Populate `./pages/index.js` inside your project:
```jsx
import React from 'react'
export default () => (
`.
### `` side effects
We expose a built-in component for appending elements to the `` of the page.
```jsx
import Head from 'next/head'
export default () => (