# next.js
Next.js is a minimalistic framework for server-rendered React applications.
## How to use
Install it:
```
$ npm install next --save
```
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 `next` 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/`
### Bundling (code splitting)
Every `import` you declare gets bundled and served with each page
```jsx
import React from 'react'
import cowsay from 'cowsay-browser'
export default () => (
{ cowsay({ text: 'hi there!' }) }
)
```
That means pages never load unneccessary 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
```jsx
import React from 'react'
import { style } from 'next/css'
export default () => (
Hello world
)
const style = style({
main: {
background: 'red',
':hover': {
background: 'gray'
}
'@media (max-width: 600px)': {
background: 'blue'
}
}
})
```
### `` side effects
We expose a built-in component for appending elements to the `` of the page.
```jsx
import React from 'react'
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.userAgent }
: { userAgent: navigator.userAgent }
}
render () {
return
Hello World {this.props.userAgent}
}
}
```
### Routing
Client-side transitions between routes are enabled via a `` component
#### pages/index.js
```jsx
import React from 'react'
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:
- `path` - `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`
### 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.status
return { statusCode }
}
render () {
return (
An error { this.props.statusCode } occurred
)
}
}
```
## 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 `.gitigore`. 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 **${X}kb** gzipped.
The Next runtime (lazy loading, routing, ``) contributes **${Y}%** 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.
In the future, however, we _might_ be able to take advantage of custom elements / shadow DOM to also support the full CSS syntax once browser support is wide enough.
### 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, specially 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 `