1
0
Fork 0
mirror of https://github.com/terribleplan/next.js.git synced 2024-01-19 02:48:18 +00:00
next.js/README.md

474 lines
17 KiB
Markdown
Raw Normal View History

2016-10-25 12:37:55 +00:00
<img width="112" alt="screen shot 2016-10-25 at 2 37 27 pm" src="https://cloud.githubusercontent.com/assets/13041/19686250/971bf7f8-9ac0-11e6-975c-188defd82df1.png">
2016-10-05 23:35:00 +00:00
2016-11-05 18:21:32 +00:00
[![Build Status](https://travis-ci.org/zeit/next.js.svg?branch=master)](https://travis-ci.org/zeit/next.js)
2016-11-15 08:24:20 +00:00
[![Coverage Status](https://coveralls.io/repos/zeit/next.js/badge.svg?branch=master)](https://coveralls.io/r/zeit/next.js?branch=master)
2016-11-02 19:02:56 +00:00
[![Slack Channel](https://zeit-slackin.now.sh/badge.svg)](https://zeit.chat)
2016-10-25 06:09:45 +00:00
Next.js is a minimalistic framework for server-rendered React applications.
2016-10-05 23:35:00 +00:00
2016-12-16 20:22:55 +00:00
**NOTE! the README on the `master` branch might not match that of the [latest stable release](https://github.com/zeit/next.js/releases/latest)! **
2016-10-05 23:35:00 +00:00
## How to use
2016-10-25 06:09:45 +00:00
Install it:
```
$ npm install next --save
```
and add a script to your package.json like this:
```json
{
"scripts": {
2016-10-26 23:07:33 +00:00
"dev": "next"
2016-12-17 19:48:52 +00:00
}
}
```
2016-10-25 06:09:45 +00:00
After that, the file-system is the main API. Every `.js` file becomes a route that gets automatically processed and rendered.
2016-10-05 23:35:00 +00:00
2016-10-05 23:36:18 +00:00
Populate `./pages/index.js` inside your project:
2016-10-05 23:35:00 +00:00
2016-10-05 23:58:36 +00:00
```jsx
2016-10-05 23:35:00 +00:00
export default () => (
<div>Welcome to next.js!</div>
)
```
2016-10-26 23:07:33 +00:00
and then just run `npm run dev` and go to `http://localhost:3000`
2016-10-05 23:35:00 +00:00
So far, we get:
- Automatic transpilation and bundling (with webpack and babel)
- Hot code reloading
2016-10-05 23:36:18 +00:00
- Server rendering and indexing of `./pages`
- Static file serving. `./static/` is mapped to `/static/`
2016-10-05 23:35:00 +00:00
2016-10-25 16:26:27 +00:00
To see how simple this is, check out the [sample app - nextgram](https://github.com/zeit/nextgram)
2016-10-25 16:18:57 +00:00
2016-10-05 23:35:00 +00:00
### Bundling (code splitting)
Every `import` you declare gets bundled and served with each page
2016-10-05 23:58:36 +00:00
```jsx
2016-10-14 21:13:46 +00:00
import cowsay from 'cowsay-browser'
2016-10-05 23:35:00 +00:00
export default () => (
2016-10-25 17:03:20 +00:00
<pre>{ cowsay.say({ text: 'hi there!' }) }</pre>
2016-10-05 23:35:00 +00:00
)
```
2016-10-26 07:19:05 +00:00
That means pages never load unnecessary code!
2016-10-05 23:35:00 +00:00
### 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.
2016-10-05 23:35:00 +00:00
2016-10-05 23:58:36 +00:00
```jsx
2016-11-13 16:50:10 +00:00
import css from 'next/css'
2016-10-05 23:35:00 +00:00
2016-10-14 21:13:46 +00:00
export default () => (
2016-10-19 23:59:18 +00:00
<div className={style}>
2016-10-05 23:35:00 +00:00
Hello world
</div>
2016-10-14 21:13:46 +00:00
)
2016-10-05 23:35:00 +00:00
2016-10-25 13:44:20 +00:00
const style = css({
background: 'red',
':hover': {
background: 'gray'
},
'@media (max-width: 600px)': {
background: 'blue'
2016-10-05 23:35:00 +00:00
}
})
```
### 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.: `<img src="/static/file-name.jpg" />`.
2016-12-17 19:16:22 +00:00
### Populating `<head>`
2016-10-05 23:35:00 +00:00
We expose a built-in component for appending elements to the `<head>` of the page.
2016-10-05 23:58:36 +00:00
```jsx
2016-10-05 23:35:00 +00:00
import Head from 'next/head'
export default () => (
2016-10-14 21:13:46 +00:00
<div>
<Head>
<title>My page title</title>
<meta name="viewport" content="initial-scale=1.0, width=device-width" />
</Head>
<p>Hello world!</p>
</div>
2016-10-05 23:35:00 +00:00
)
```
2016-12-17 19:16:22 +00:00
_Note: The contents of `<head>` get cleared upon unmounting the component, so make sure each page completely defines what it needs in `<head>`, without making assumptions about what other pages added_
### Fetching data and component lifecycle
2016-10-05 23:35:00 +00:00
2016-11-01 01:13:42 +00:00
When you need state, lifecycle hooks or **initial data population** you can export a `React.Component`.
2016-10-05 23:35:00 +00:00
2016-10-05 23:58:36 +00:00
```jsx
2016-10-05 23:35:00 +00:00
import React from 'react'
export default class extends React.Component {
2016-10-09 00:50:09 +00:00
static async getInitialProps ({ req }) {
return req
? { userAgent: req.headers['user-agent'] }
2016-10-05 23:35:00 +00:00
: { userAgent: navigator.userAgent }
}
render () {
return <div>
Hello World {this.props.userAgent}
</div>
}
}
```
2016-11-01 01:13:42 +00:00
Notice that to load data when the page loads, we use `getInitialProps` which is an [`async`](https://zeit.co/blog/async-and-await) static method. It can asynchronously fetch anything that resolves to a JavaScript plain `Object`, which populates `props`.
2016-12-17 19:16:22 +00:00
For the initial page load, `getInitialProps` will execute on the server only. `getInitialProps` will only be executed on the client when navigating to a different route via the `Link` component or invoking `props.url.*` methods like `pushTo`.
`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
2016-10-05 23:35:00 +00:00
### Routing
Client-side transitions between routes are enabled via a `<Link>` component
#### pages/index.js
2016-10-05 23:58:36 +00:00
```jsx
2016-10-05 23:35:00 +00:00
import Link from 'next/link'
export default () => (
<div>Click <Link href="/about"><a>here</a></Link> to read more</div>
)
```
#### pages/about.js
2016-10-05 23:58:36 +00:00
```jsx
2016-10-05 23:35:00 +00:00
export default () => (
<p>Welcome to About!</p>
)
```
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
2016-10-05 23:35:00 +00:00
- `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 `<Link>`
- `replaceTo(url)` - performs a `replaceState` call that renders the new `url`
### Prefetching Pages
2016-12-17 19:16:22 +00:00
Next.js exposes a module that configures a `ServiceWorker` automatically to prefetch pages: `next/prefetch`.
2016-12-17 19:16:22 +00:00
Since Next.js server-renders your pages, this allows all the future interaction paths of your app to be instant. Effectively Next.js gives you the great initial download performance of a _website_, with the ahead-of-time download capabilities of an _app_. [Read more](https://zeit.co/blog/next#anticipation-is-the-key-to-performance).
2016-12-17 19:33:07 +00:00
#### Link prefetching
2016-12-17 19:33:07 +00:00
You can substitute your usage of `<Link>` with the default export of `next/prefetch`. For example:
```jsx
import Link from 'next/prefetch'
2016-12-17 19:16:22 +00:00
// example header component
export default () => (
2016-12-17 19:16:22 +00:00
<nav>
<ul>
<li><Link href='/'><a>Home</a></Link></li>
<li><Link href='/about'><a>About</a></Link></li>
<li><Link href='/contact'><a>Contact</a></Link></li>
</ul>
</nav>
)
```
2016-12-17 19:16:22 +00:00
When this higher-level `<Link>` component is first used, the `ServiceWorker` gets installed. To turn off prefetching on a per-`<Link>` basis, you can use the `prefetch` attribute:
```jsx
<Link href='/contact' prefetch={false}>Home</Link>
```
#### Imperative API
2016-12-17 19:16:22 +00:00
Most needs are addressed by `<Link />`, but we also expose an imperative API for advanced usage:
```jsx
import { prefetch } from 'next/prefetch'
2016-12-17 19:48:52 +00:00
export default ({ url }) => (
<a onClick={ () => setTimeout(() => url.pushTo('/dynamic'), 100) }>
A route transition will happen after 100ms
</a>
{
// but we can prefetch it!
prefetch('/dynamic')
}
2016-12-17 19:16:22 +00:00
)
```
2016-12-17 19:33:07 +00:00
### Custom error handling
404 or 500 errors are handled both client and server side by a default component `error.js`. If you wish to override it, define a `_error.js`:
```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 (
<p>{
this.props.statusCode
? `An error ${this.props.statusCode} occurred on server`
: 'An error occurred on client'
}</p>
)
}
}
```
2016-12-17 19:33:07 +00:00
### Custom configuration
2016-12-17 19:04:44 +00:00
For custom advanced behavior of Next.js, you can create a `next.config.js` in the root of your project directory (next to `pages/` and `package.json`).
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.
```javascript
// next.config.js
module.exports = {
/* config options here */
}
```
### Customizing webpack config
In order to extend our usage of `webpack`, you can define a function that extends its config.
The following example shows how you can use [`react-svg-loader`](https://github.com/boopathi/react-svg-loader) to easily import any `.svg` file as a React component, without modification.
```js
module.exports = {
webpack: (cfg, { dev }) => {
cfg.module.rules.push({ test: /\.svg$/, loader: 'babel!react-svg' })
return cfg
}
}
```
2016-10-20 00:58:42 +00:00
## Production deployment
2016-10-05 23:35:00 +00:00
2016-10-20 00:58:42 +00:00
To deploy, instead of running `next`, you probably want to build ahead of time. Therefore, building and starting are separate commands:
2016-10-05 23:35:00 +00:00
2016-10-05 23:58:36 +00:00
```bash
2016-10-05 23:35:00 +00:00
next build
next start
```
2016-10-20 00:58:42 +00:00
For example, to deploy with [`now`](https://zeit.co/now) a `package.json` like follows is recommended:
2016-10-05 23:35:00 +00:00
2016-10-05 23:58:36 +00:00
```json
2016-10-05 23:35:00 +00:00
{
"name": "my-app",
"dependencies": {
"next": "latest"
},
"scripts": {
"dev": "next",
"build": "next build",
"start": "next start"
}
}
```
2016-10-15 13:15:10 +00:00
2016-10-20 00:58:42 +00:00
Then run `now` and enjoy!
2016-10-25 16:58:31 +00:00
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`)
2016-10-20 00:58:42 +00:00
## FAQ
2016-10-15 13:15:10 +00:00
2016-10-24 19:59:46 +00:00
<details>
<summary>Is this production ready?</summary>
Next.js has been powering `https://zeit.co` since its inception.
2016-10-25 10:32:03 +00:00
2016-10-24 19:59:46 +00:00
Were ecstatic about both the developer experience and end-user performance, so we decided to share it with the community.
</details>
2016-10-15 13:16:25 +00:00
2016-10-24 19:59:46 +00:00
<details>
<summary>How big is it?</summary>
2016-10-25 10:32:03 +00:00
The client side next bundle, which includes React and Glamor is **73kb** gzipped.
The Next runtime (lazy loading, routing, `<Head>`) contributes around **15%** to the size of that bundle.
2016-10-24 19:59:46 +00:00
The codebase is ~1500LOC (excluding CLI programs).
</details>
<details>
<summary>Is this like `create-react-app`?</summary>
2016-10-25 10:32:03 +00:00
2016-10-24 19:59:46 +00:00
Yes and No.
Yes in that both make your life easier.
No in that it enforces a _structure_ so that we can do more advanced things like:
2016-10-25 06:09:45 +00:00
- Server side rendering
- Automatic code splitting
2016-10-24 19:59:46 +00:00
In addition, Next.js provides two built-in features that are critical for every single website:
2016-12-17 19:33:07 +00:00
- Routing with lazy component loading: `
>` (by importing `next/link`)
2016-10-25 06:09:45 +00:00
- A way for components to alter `<head>`: `<Head>` (by importing `next/head`)
2016-10-24 19:59:46 +00:00
2016-10-25 06:09:45 +00:00
If you want to create re-usable React components that you can embed in your Next.js app or other React applications, using `create-react-app` is a great idea. You can later `import` it and keep your codebase clean!
2016-10-24 19:59:46 +00:00
</details>
<details>
<summary>Why CSS-in-JS?</summary>
2016-10-25 10:32:03 +00:00
`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.
2016-10-24 19:59:46 +00:00
Theres *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.
2016-10-25 06:15:50 +00:00
**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)]
2016-10-24 19:59:46 +00:00
### Compilation performance
2016-10-25 10:32:03 +00:00
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.
2016-10-24 19:59:46 +00:00
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 `<style>` elements that are not being used.
2016-10-25 06:09:45 +00:00
This is important for server-side rendering, but also during the lifecycle of the page. Since Next.js enables `pushState` transitions that load components dynamically, unnecessary `<style>` elements would bring down performance over time.
2016-10-24 19:59:46 +00:00
2016-10-26 07:19:05 +00:00
This is a very significant benefit over approaches like `require(xxxxx.css')`.
2016-10-24 19:59:46 +00:00
### Correctness
Since the class names and styles are defined as JavaScript objects, a variety of aids for correctness are much more easily enabled:
2016-10-25 10:32:03 +00:00
2016-10-24 19:59:46 +00:00
- Linting
- Type checking
- Autocompletion
While these are tractable for CSS itself, we dont need to duplicate the efforts in tooling and libraries to accomplish them.
</details>
<details>
<summary>What syntactic features are transpiled? How do I change them?</summary>
We track V8. Since V8 has wide support for ES6 and `async` and `await`, we transpile those. Since V8 doesnt support class decorators, we dont transpile those.
2016-10-26 10:04:01 +00:00
See [this](https://github.com/zeit/next.js/blob/master/server/build/webpack.js#L79) and [this](https://github.com/zeit/next.js/issues/26)
2016-10-24 19:59:46 +00:00
</details>
<details>
<summary>Why a new Router?</summary>
Next.js is special in that:
- Routes dont need to be known ahead of time
2016-10-26 09:47:41 +00:00
- Routes are always lazy-loadable
2016-10-24 19:59:46 +00:00
- Top-level components can define `getInitialProps` that should _block_ the loading of the route (either when server-rendering or lazy-loading)
As a result, we were able to introduce a very simple approach to routing that consists of two pieces:
- Every top level component receives a `url` object to inspect the url or perform modifications to the history
- A `<Link />` component is used to wrap elements like anchors (`<a/>`) to perform client-side transitions
We tested the flexibility of the routing with some interesting scenarios. For an example, check out [nextgram](https://github.com/zeit/nextgram).
</details>
<details>
<summary>How do I define a custom fancy route?</summary>
Were adding the ability to map between an arbitrary URL and any component by supplying a request handler: [#25](https://github.com/zeit/next.js/issues/25)
On the client side, we'll add a parameter to `<Link>` so that it _decorates_ the URL differently from the URL it _fetches_.
</details>
<details>
<summary>How do I fetch data?</summary>
Its up to you. `getInitialProps` is an `async` function (or a regular function that returns a `Promise`). It can retrieve data from anywhere.
</details>
2016-10-25 10:34:14 +00:00
<details>
<summary>Can I use it with Redux?</summary>
Yes! Here's an [example](https://github.com/zeit/next.js/wiki/Redux-example)
</details>
2016-10-24 19:59:46 +00:00
<details>
<summary>Why does it load the runtime from a CDN by default?</summary>
2016-10-25 06:09:45 +00:00
We intend for Next.js to be a great starting point for any website or app, no matter how small.
2016-10-24 19:59:46 +00:00
If youre building a very small mostly-content website, you still want to benefit from features like lazy-loading, a component architecture and module bundling.
But in some cases, the size of React itself would far exceed the content of the page!
2016-10-25 10:32:03 +00:00
2016-10-24 19:59:46 +00:00
For this reason we want to promote a situation where users can share the cache for the basic runtime across internet properties. The application code continues to load from your server as usual.
2016-10-26 09:42:39 +00:00
We are committed to providing a great uptime and levels of security for our CDN. Even so, we also **automatically fall back** if the CDN script fails to load [with a simple trick](http://www.hanselman.com/blog/CDNsFailButYourScriptsDontHaveToFallbackFromCDNToLocalJQuery.aspx).
2016-10-25 10:32:03 +00:00
To turn the CDN off, just set `module.exports = { cdn: false }` in `next.config.js`.
2016-10-24 19:59:46 +00:00
</details>
<details>
<summary>What is this inspired by?</summary>
Many of the goals we set out to accomplish were the ones listed in [The 7 principles of Rich Web Applications](http://rauchg.com/2014/7-principles-of-rich-web-applications/) by Guillermo Rauch.
The ease-of-use of PHP is a great inspiration. We feel Next.js is a suitable replacement for many scenarios where you otherwise would use PHP to output HTML.
Unlike PHP, we benefit from the ES6 module system and every file exports a **component or function** that can be easily imported for lazy evaluation or testing.
As we were researching options for server-rendering React that didnt involve a large number of steps, we came across [react-page](https://github.com/facebookarchive/react-page) (now deprecated), a similar approach to Next.js by the creator of React Jordan Walke.
</details>
2016-12-08 17:16:05 +00:00
## Roadmap
2016-10-24 19:59:46 +00:00
2016-12-08 17:16:05 +00:00
Our Roadmap towards 2.0.0 [is public](https://github.com/zeit/next.js/wiki/Roadmap#nextjs-200).
2016-10-24 19:40:29 +00:00
## Authors
2016-10-25 10:32:03 +00:00
- Naoyuki Kanezawa ([@nkzawa](https://twitter.com/nkzawa)) ▲ZEIT
2016-10-25 18:42:57 +00:00
- Tony Kovanen ([@tonykovanen](https://twitter.com/tonykovanen)) ▲ZEIT
2016-10-25 10:32:03 +00:00
- Guillermo Rauch ([@rauchg](https://twitter.com/rauchg)) ▲ZEIT
2016-10-24 19:40:29 +00:00
- Dan Zajdband ([@impronunciable](https://twitter.com/impronunciable)) Knight-Mozilla / Coral Project