diff --git a/README-zh-CN.md b/README-zh-CN.md deleted file mode 100644 index 9061ab8bb367..000000000000 --- a/README-zh-CN.md +++ /dev/null @@ -1,2110 +0,0 @@ -[![Next.js](https://assets.zeit.co/image/upload/v1538361091/repositories/next-js/next-js.png)](https://nextjs.org) - -

- - - - - - - - - - - - -

- -Next.js 是一个轻量级的 React 服务端渲染应用框架。 - -**可访问 [nextjs.org/learn](https://nextjs.org/learn) 开始学习 Next.js.** - -[README in English](https://github.com/zeit/next.js) - ---- - - - - - -- [怎么使用](#how-to-use) - - [安装](#setup) - - [代码自动分割](#automatic-code-splitting) - - [CSS](#css) - - [支持嵌入样式](#built-in-css-support) - - [内嵌样式](#css-in-js) - - [使用 CSS / Sass / Less / Stylus files](#importing-css--sass--less--stylus-files) - - [静态文件服务（如图像)](#static-file-serving-eg-images) - - [``](#populating-head) - - [获取数据以及组件生命周期](#fetching-data-and-component-lifecycle) - - [路由](#routing) - - [`` 用法](#with-link) - - [URL 对象](#with-url-object) - - [替换路由](#replace-instead-of-push-url) - - [组件支持点击事件`onClick`](#using-a-component-that-supports-onclick) - - [暴露`href`给子元素](#forcing-the-link-to-expose-href-to-its-child) - - [禁止滚动到页面顶部](#disabling-the-scroll-changes-to-top-on-page) - - [命令式](#imperatively) - - [拦截器 `popstate`](#intercepting-popstate) - - [URL 对象用法](#with-url-object-1) - - [路由事件](#router-events) - - [浅层路由](#shallow-routing) - - [高阶组件](#using-a-higher-order-component) - - [预加载页面](#prefetching-pages) - - [``用法](#with-link-1) - - [命令式 prefetch 写法](#imperatively-1) - - [自定义服务端路由](#custom-server-and-routing) - - [禁止文件路由](#disabling-file-system-routing) - - [动态前缀](#dynamic-assetprefix) - - [动态导入](#dynamic-import) - - [1. 基础支持 (同样支持 SSR)](#1-basic-usage-also-does-ssr) - - [2. 自定义加载组件](#2-with-custom-loading-component) - - [3. 禁止使用 SSR](#3-with-no-ssr) - - [4. 同时加载多个模块](#4-with-multiple-modules-at-once) - - [自定义 ``](#custom-app) - - [自定义 ``](#custom-document) - - [自定义错误处理](#custom-error-handling) - - [渲染内置错误页面](#reusing-the-built-in-error-page) - - [自定义配置](#custom-configuration) - - [设置自定义构建目录](#setting-a-custom-build-directory) - - [禁止 etag 生成](#disabling-etag-generation) - - [配置 onDemandEntries](#configuring-the-ondemandentries) - - [配置页面后缀名解析扩展](#configuring-extensions-looked-for-when-resolving-pages-in-pages) - - [配置构建 ID](#configuring-the-build-id) - - [自定义 webpack 配置](#customizing-webpack-config) - - [自定义 babel 配置](#customizing-babel-config) - - [暴露配置到服务端和客户端](#exposing-configuration-to-the-server--client-side) - - [启动服务选择 hostname](#starting-the-server-on-alternative-hostname) - - [CDN 支持前缀](#cdn-support-with-asset-prefix) -- [项目部署](#production-deployment) -- [浏览器支持](#browser-support) -- [导出静态页面](#static-html-export) - - [使用](#usage) - - [限制](#limitation) -- [多 zone](#multi-zones) - - [怎么定义一个 zone](#how-to-define-a-zone) - - [怎么合并他们](#how-to-merge-them) -- [技巧](#recipes) -- [FAQ](#faq) -- [贡献](#contributing) -- [作者](#authors) - - - - - -## 怎么使用 - - - -### 安装 - -在项目文件夹中运行: - -```bash -npm install --save next react react-dom -``` - -将下面脚本添加到 package.json 中: - -```json -{ - "scripts": { - "dev": "next", - "build": "next build", - "start": "next start" - } -} -``` - -下面, 文件系统是主要的 API. 每个`.js` 文件将变成一个路由，自动处理和渲染。 - -新建 `./pages/index.js` 到你的项目中: - -```jsx -export default () =>
Welcome to next.js!
-``` - -运行 `npm run dev` 命令并打开 `http://localhost:3000`。 要使用其他端口，你可以运行 `npm run dev -- -p `. - -到目前为止，我们做到: - -- 自动打包编译 (使用 webpack 和 babel) -- 热加载 -- 以 `./pages`作为服务的渲染和索引 -- 静态文件服务. `./public/` 映射到 `/` (可以 [创建一个静态目录](#static-file-serving-eg-images) 在你的项目中) - -这里有个简单的案例，可以下载看看 [sample app - nextgram](https://github.com/zeit/nextgram) - - - -### 代码自动分割 - -每个页面只会导入`import`中绑定以及被用到的代码. 这意味着页面不会加载不必要的代码 - -```jsx -import cowsay from 'cowsay-browser' - -export default () => 
{cowsay.say({ text: 'hi there!' })}
-``` - - - -### CSS - - - -#### 支持嵌入样式 - -

- 案例 - -

- -我们绑定 [styled-jsx](https://github.com/zeit/styled-jsx) 来生成独立作用域的 CSS. 目标是支持 "shadow CSS",但是 [不支持独立模块作用域的 JS](https://github.com/w3c/webcomponents/issues/71). - -```jsx -export default () => ( -
- Hello world -

scoped!

- - -
-) -``` - -想查看更多案例可以点击 [styled-jsx documentation](https://www.npmjs.com/package/styled-jsx). - - - -#### 内嵌样式 - -

- - Examples - - -

- -有些情况可以使用 CSS 内嵌 JS 写法。如下所示： - -```jsx -export default () =>

hi there

-``` - -更复杂的内嵌样式解决方案，特别是服务端渲染时的样式更改。我们可以通过包裹自定义 Document，来添加样式，案例如下：[custom ``](#user-content-custom-document) - - - -#### 使用 CSS / Sass / Less / Stylus files - -支持用`.css`, `.scss`, `.less` or `.styl`，需要配置默认文件 next.config.js，具体可查看下面链接 - -- [@zeit/next-css](https://github.com/zeit/next-plugins/tree/master/packages/next-css) -- [@zeit/next-sass](https://github.com/zeit/next-plugins/tree/master/packages/next-sass) -- [@zeit/next-less](https://github.com/zeit/next-plugins/tree/master/packages/next-less) -- [@zeit/next-stylus](https://github.com/zeit/next-plugins/tree/master/packages/next-stylus) - - - -### 静态文件服务（如图像） - -在根目录下新建文件夹叫`public`。代码可以通过`/`来引入相关的静态资源。 - -```jsx -export default () => my image -``` - -_注意：不要自定义静态文件夹的名字，只能叫`public` ，因为只有这个名字 Next.js 才会把它当作静态资源。_ - - - -### 生成`` - -`` - -

- Examples - -

- -我们设置一个内置组件来装载``到页面中。 - -```jsx -import Head from 'next/head' - -export default () => ( -
- - My page title - - -

Hello world!

-
-) -``` - -我们定义`key`属性来避免重复的``标签，保证``只渲染一次，如下所示： - -```jsx -import Head from 'next/head' -export default () => ( -
- - My page title - - - - - -

Hello world!

-
-) -``` - -只有第二个``才被渲染。 - -_注意：在卸载组件时，``的内容将被清除。请确保每个页面都在其``定义了所需要的内容，而不是假设其他页面已经加过了_ - - - -### 获取数据以及组件生命周期 - -

- Examples - -

- -当你需要状态，生命周期钩子或初始数据填充时，你可以导出`React.Component`（而不是上面的无状态函数），如下所示： - -```jsx -import React from 'react' - -export default class extends React.Component { - static async getInitialProps({ req }) { - const userAgent = req ? req.headers['user-agent'] : navigator.userAgent - return { userAgent } - } - - render() { - return
Hello World {this.props.userAgent}
- } -} -``` - -请注意，当页面渲染时加载数据，我们使用了一个异步静态方法`getInitialProps`。它能异步获取 JS 普通对象，并绑定在`props`上。 - -当服务渲染时，`getInitialProps`将会把数据序列化，就像`JSON.stringify`。所以确保`getInitialProps`返回的是一个普通 JS 对象，而不是`Date`, `Map` 或 `Set`类型。 - -当页面初次加载时，`getInitialProps`只会在服务端执行一次。`getInitialProps`只有在路由切换的时候（如`Link`组件跳转或路由自定义跳转）时，客户端的才会被执行。 - -当页面初始化加载时，`getInitialProps`仅在服务端上执行。只有当路由跳转（`Link`组件跳转或 API 方法跳转）时，客户端才会执行`getInitialProps`。 - -注意：`getInitialProps`将不能在子组件中使用。只能在`pages`页面中使用。 - -
- -> 只有服务端用到的模块放在`getInitialProps`里，请确保正确的导入了它们，可参考[import them properly](https://arunoda.me/blog/ssr-and-server-only-modules)。 -> 否则会拖慢你的应用速度。 - -
- -你也可以给无状态组件定义`getInitialProps`： - -```jsx -const Page = ({ stars }) =>
Next stars: {stars}
- -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 -``` - -`getInitialProps`入参对象的属性如下： - -- `pathname` - URL 的 path 部分 -- `query` - URL 的 query 部分，并被解析成对象 -- `asPath` - 显示在浏览器中的实际路径（包含查询部分），为`String`类型 -- `req` - HTTP 请求对象 (仅限服务器端) -- `res` - HTTP 返回对象 (仅限服务器端) -- `jsonPageRes` - 获取响应对象（仅限客户端） -- `err` - 渲染过程中的任何错误 - - - -### 路由 - -Next.js 不会随应用程序中每个可能的路由一起发布路由清单，因此当前页面不知道客户端上的任何其他页面。出于可扩展性考虑，所有后续路由都会惰性加载。 - - - -#### ``用法 - -

- Examples - -

- -可以用 `` 组件实现客户端的路由切换。 - -**基本例子** - -参考下面的两个页面: - -```jsx -// pages/index.js -import Link from 'next/link' - -function Home() { - return ( -
- Click{' '} - - here - {' '} - to read more -
- ) -} - -export default Home -``` - -```jsx -// pages/about.js -function About() { - return

Welcome to About!

-} - -export default About -``` - -**自定义路由 (使用 URL 中的 props)** - -`` 组件有两个主要属性: - -- `href`: `pages`目录内的路径+查询字符串. -- `as`: 将在浏览器 URL 栏中呈现的路径. - -例子: - -1. 假设你有个这样的路由 `/post/:slug`. - -2. 你可以创建文件 `pages/post.js` - -```jsx -class Post extends React.Component { - static async getInitialProps({ query }) { - console.log('SLUG', query.slug) - return {} - } - render() { - return

My blog post

- } -} - -export default Post -``` - -3. 将路由添加到 `express` (或者其他服务端) 的 `server.js` 文件 (这仅适用于 SSR). 这将解析`/post/:slug`到`pages/post.js`并在 getInitialProps 中提供`slug`作为查询的一部分。 - -```jsx -server.get('/post/:slug', (req, res) => { - return app.render(req, res, '/post', { slug: req.params.slug }) -}) -``` - -4. 对于客户端路由，使用 `next/link`: - -```jsx - -``` - -_注意：可以使用[``](#prefetching-pages)使链接和预加载在后台同时进行，来达到页面的最佳性能。_ - -客户端路由行为与浏览器很相似： - -1. 获取组件 -2. 如果组件定义了`getInitialProps`，则获取数据。如果有错误情况将会渲染 `_error.js`。 -3. 1 和 2 都完成了，`pushState`执行，新组件被渲染。 - -如果需要注入`pathname`, `query` 或 `asPath`到你组件中，你可以使用[withRouter](#using-a-higher-order-component)。 - - - -##### URL 对象 - -

- Examples - -

- -组件``接收 URL 对象，而且它会自动格式化生成 URL 字符串 - -```jsx -// pages/index.js -import Link from 'next/link' - -export default () => ( -
- Click{' '} - - here - {' '} - to read more -
-) -``` - -将生成 URL 字符串`/about?name=Zeit`，你可以使用任何在[Node.js URL module documentation](https://nodejs.org/api/url.html#url_url_strings_and_url_objects)定义过的属性。 - - - -##### 替换路由 - -``组件默认将新 url 推入路由栈中。你可以使用`replace`属性来防止添加新输入。 - -```jsx -// pages/index.js -import Link from 'next/link' - -export default () => ( -
- Click{' '} - - here - {' '} - to read more -
-) -``` - - - -##### 组件支持点击事件 `onClick` - -``支持每个组件所支持的`onClick`事件。如果你不提供``标签，只会处理`onClick`事件而`href`将不起作用。 - -```jsx -// pages/index.js -import Link from 'next/link' - -export default () => ( -
- Click{' '} - - image - -
-) -``` - - - -##### 暴露 `href` 给子元素 - -如子元素是一个没有 href 属性的``标签，我们将会指定它以免用户重复操作。然而有些时候，我们需要里面有``标签，但是`Link`组件不会被识别成*超链接*，结果不能将`href`传递给子元素。在这种场景下，你可以定义一个`Link`组件中的布尔属性`passHref`，强制将`href`传递给子元素。 - -**注意**: 使用`a`之外的标签而且没有通过`passHref`的链接可能会使导航看上去正确，但是当搜索引擎爬行检测时，将不会识别成链接（由于缺乏 href 属性），这会对你网站的 SEO 产生负面影响。 - -```jsx -import Link from 'next/link' -import Unexpected_A from 'third-library' - -export default ({ href, name }) => ( - - {name} - -) -``` - - - -##### 禁止滚动到页面顶部 - -``的默认行为就是滚到页面顶部。当有 hash 定义时（＃），页面将会滚动到对应的 id 上，就像``标签一样。为了预防滚动到顶部，可以给``加 -`scroll={false}`属性： - -```jsx -Disables scrolling -Changes with scrolling to top -``` - - - -#### 命令式 - -

- Examples - -

- -你也可以用`next/router`实现客户端路由切换 - -```jsx -import Router from 'next/router' - -export default () => ( -
- Click Router.push('/about')}>here to read more -
-) -``` - - - -#### 拦截器 `popstate` - -有些情况（比如使用[custom router](#custom-server-and-routing)），你可能想监听[`popstate`](https://developer.mozilla.org/en-US/docs/Web/Events/popstate)，在路由跳转前做一些动作。 -比如，你可以操作 request 或强制 SSR 刷新 - -```jsx -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 -}) -``` - -如果你在`beforePopState`中返回 false，`Router`将不会执行`popstate`事件。 -例如[Disabling File-System Routing](#disabling-file-system-routing)。 - -以上`Router`对象的 API 如下： - -- `route` - 当前路由，为`String`类型 -- `pathname` - 不包含查询内容的当前路径，为`String`类型 -- `query` - 查询内容，被解析成`Object`类型. 默认为`{}` -- `asPath` - 展现在浏览器上的实际路径，包含查询内容，为`String`类型 -- `push(url, as=url)` - 用给定的 url 调用`pushState` -- `replace(url, as=url)` - 用给定的 url 调用`replaceState` -- `beforePopState(cb=function)` - 在路由器处理事件之前拦截. - -`push` 和 `replace` 函数的第二个参数`as`，是为了装饰 URL 作用。如果你在服务器端设置了自定义路由将会起作用。 - - - -##### URL 对象用法 - -`push` 或 `replace`可接收的 URL 对象（``组件的 URL 对象一样）来生成 URL。 - -```jsx -import Router from 'next/router' - -const handler = () => - Router.push({ - pathname: '/about', - query: { name: 'Zeit' }, - }) - -export default () => ( -
- Click here to read more -
-) -``` - -也可以像``组件一样添加额外的参数。 - - - -##### 路由事件 - -你可以监听路由相关事件。 -下面是支持的事件列表： - -- `routeChangeStart(url)` - 路由开始切换时触发 -- `routeChangeComplete(url)` - 完成路由切换时触发 -- `routeChangeError(err, url)` - 路由切换报错时触发 -- `beforeHistoryChange(url)` - 浏览器 history 模式开始切换时触发 -- `hashChangeStart(url)` - 开始切换 hash 值但是没有切换页面路由时触发 -- `hashChangeComplete(url)` - 完成切换 hash 值但是没有切换页面路由时触发 - -> 这里的`url`是指显示在浏览器中的 url。如果你用了`Router.push(url, as)`（或类似的方法），那浏览器中的 url 将会显示 as 的值。 - -下面是如何正确使用路由事件`routeChangeStart`的例子： - -```js -const handleRouteChange = url => { - console.log('App is changing to: ', url) -} - -Router.events.on('routeChangeStart', handleRouteChange) -``` - -如果你不想再监听该事件，你可以用`off`事件去取消监听： - -```js -Router.events.off('routeChangeStart', handleRouteChange) -``` - -如果路由加载被取消（比如快速连续双击链接），`routeChangeError`将触发。传递 err,并且属性 cancelled 的值为 true。 - -```js -Router.events.on('routeChangeError', (err, url) => { - if (err.cancelled) { - console.log(`Route to ${url} was cancelled!`) - } -}) -``` - - - -##### 浅层路由 - -

- Examples - -

- -浅层路由允许你改变 URL 但是不执行`getInitialProps`生命周期。你可以加载相同页面的 URL，得到更新后的路由属性`pathname`和`query`，并不失去 state 状态。 - -你可以给`Router.push` 或 `Router.replace`方法加`shallow: true`参数。如下面的例子所示： - -```js -// Current URL is "/" -const href = '/?counter=10' -const as = href -Router.push(href, as, { shallow: true }) -``` - -现在 URL 更新为`/?counter=10`。在组件里查看`this.props.router.query`你将会看到更新的 URL。 - -你可以在[`componentdidupdate`](https://facebook.github.io/react/docs/react-component.html#componentdidupdate)钩子函数中监听 URL 的变化。 - -```js -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 - } -} -``` - -> 注意: -> -> 浅层路由只作用于相同 URL 的参数改变，比如我们假定有个其他路由`about`，而你向下面代码样运行: -> -> ```js -> Router.push('/?counter=10', '/about?counter=10', { shallow: true }) -> ``` -> -> 那么这将会出现新页面，即使我们加了浅层路由，但是它还是会卸载当前页，会加载新的页面并触发新页面的`getInitialProps`。 - - - -#### 高阶组件 - -

- Examples - -

- -如果你想应用里每个组件都处理路由对象，你可以使用`withRouter`高阶组件。下面是如何使用它： - -```jsx -import { withRouter } from 'next/router' - -const ActiveLink = ({ children, router, href }) => { - const style = { - marginRight: 10, - color: router.pathname === href ? 'red' : 'black', - } - - const handleClick = e => { - e.preventDefault() - router.push(href) - } - - return ( - - {children} - - ) -} - -export default withRouter(ActiveLink) -``` - -上面路由对象的 API 可以参考[`next/router`](#imperatively). - - - -### 预加载页面 - -⚠️ 只有生产环境才有此功能 ⚠️ - -

- Examples - -

- -Next.js 有允许你预加载页面的 API。 - -用 Next.js 服务端渲染你的页面，可以达到所有你应用里所有未来会跳转的路径即时响应，有效的应用 Next.js，可以通过预加载应用程序的功能，最大程度的初始化网站性能。[查看更多](https://zeit.co/blog/next#anticipation-is-the-key-to-performance). - -> Next.js 的预加载功能只预加载 JS 代码。当页面渲染时，你可能需要等待数据请求。 - - - -#### ``用法 - -你可以给添加 `prefetch` 属性，Next.js 将会在后台预加载这些页面。 - -```jsx -import Link from 'next/link' - -// example header component -export default () => ( - -) -``` - - - -#### 命令式 prefetch 写法 - -大多数预加载是通过处理的，但是我们还提供了命令式 API 用于更复杂的场景。 - -```jsx -import { withRouter } from 'next/router' - -export default withRouter(({ router }) => ( -
- setTimeout(() => router.push('/dynamic'), 100)}> - A route transition will happen after 100ms - - {// but we can prefetch it! - router.prefetch('/dynamic')} -
-)) -``` - -路由实例只允许在应用程序的客户端。以防服务端渲染发生错误，建议 prefetch 事件写在`componentDidMount()`生命周期里。 - -```jsx -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 ( -
- setTimeout(() => router.push('/dynamic'), 100)}> - A route transition will happen after 100ms - -
- ) - } -} - -export default withRouter(MyLink) -``` - - - -### 自定义服务端路由 - -

- Examples - -

- -一般你使用`next start`命令来启动 next 服务，你还可以编写代码来自定义路由，如使用路由正则等。 - -当使用自定义服务文件，如下面例子所示叫 server.js 时，确保你更新了 package.json 中的脚本。 - -```json -{ - "scripts": { - "dev": "node server.js", - "build": "next build", - "start": "NODE_ENV=production node server.js" - } -} -``` - -下面这个例子使 `/a` 路由解析为`./pages/b`，以及`/b` 路由解析为`./pages/a`; - -```js -// This file doesn't go through babel or webpack transformation. -// Make sure the syntax and sources this file requires are compatible with the current node version you are running -// See https://github.com/zeit/next.js/issues/1245 for discussions on Universal Webpack or universal Babel -const { createServer } = require('http') -const { parse } = require('url') -const next = require('next') - -const dev = process.env.NODE_ENV !== 'production' -const app = next({ dev }) -const handle = app.getRequestHandler() - -app.prepare().then(() => { - createServer((req, res) => { - // Be sure to pass `true` as the second argument to `url.parse`. - // This tells it to parse the query portion of the URL. - const parsedUrl = parse(req.url, true) - const { pathname, query } = parsedUrl - - if (pathname === '/a') { - app.render(req, res, '/b', query) - } else if (pathname === '/b') { - app.render(req, res, '/a', query) - } else { - handle(req, res, parsedUrl) - } - }).listen(3000, err => { - if (err) throw err - console.log('> Ready on http://localhost:3000') - }) -}) -``` - -`next`的 API 如下所示 - -- `next(opts: object)` - -opts 的属性如下: - -- `dev` (`boolean`) 判断 Next.js 应用是否在开发环境 - 默认`false` -- `dir` (`string`) Next 项目路径 - 默认`'.'` -- `quiet` (`boolean`) 是否隐藏包含服务端消息在内的错误信息 - 默认`false` -- `conf` (`object`) 与`next.config.js`的对象相同 - 默认`{}` - -生产环境的话，可以更改 package.json 里的`start`脚本为`NODE_ENV=production node server.js`。 - - - -#### 禁止文件路由 - -默认情况，`Next`将会把`/pages`下的所有文件匹配路由（如`/pages/some-file.js` 渲染为 `site.com/some-file`） - -如果你的项目使用自定义路由，那么有可能不同的路由会得到相同的内容，可以优化 SEO 和用户体验。 - -禁止路由链接到`/pages`下的文件，只需设置`next.config.js`文件如下所示： - -```js -// next.config.js -module.exports = { - useFileSystemPublicRoutes: false, -} -``` - -注意`useFileSystemPublicRoutes`只禁止服务端的文件路由；但是客户端的还是禁止不了。 - -你如果想配置客户端路由不能跳转文件路由，可以参考[Intercepting `popstate`](#intercepting-popstate)。 - - - -#### 动态前缀 - -有时你需要设置动态前缀，可以在请求时设置`assetPrefix`改变前缀。 - -使用方法如下： - -```js -const next = require('next') -const micro = require('micro') - -const dev = process.env.NODE_ENV !== 'production' -const app = next({ dev }) -const handleNextRequests = app.getRequestHandler() - -app.prepare().then(() => { - const server = micro((req, res) => { - // Add assetPrefix support based on the hostname - if (req.headers.host === 'my-app.com') { - app.setAssetPrefix('http://cdn.com/myapp') - } else { - app.setAssetPrefix('') - } - - handleNextRequests(req, res) - }) - - server.listen(port, err => { - if (err) { - throw err - } - - console.log(`> Ready on http://localhost:${port}`) - }) -}) -``` - - - -### 动态导入 - -

- Examples - -

- -ext.js 支持 JavaScript 的 TC39 提议[dynamic import proposal](https://github.com/tc39/proposal-dynamic-import)。你可以动态导入 JavaScript 模块（如 React 组件）。 - -动态导入相当于把代码分成各个块管理。Next.js 服务端动态导入功能，你可以做很多炫酷事情。 - -下面介绍一些动态导入方式： - - - -#### 1. 基础用法 (也就是 SSR) - -```jsx -import dynamic from 'next/dynamic' - -const DynamicComponent = dynamic(import('../components/hello')) - -export default () => ( -
-
- -

HOME PAGE is here!

-
-) -``` - - - -#### 2. 自定义加载组件 - -```jsx -import dynamic from 'next/dynamic' - -const DynamicComponentWithCustomLoading = dynamic( - import('../components/hello2'), - { - loading: () =>

...

, - } -) - -export default () => ( -
-
- -

HOME PAGE is here!

-
-) -``` - - - -#### 3. 禁止使用 SSR - -```jsx -import dynamic from 'next/dynamic' - -const DynamicComponentWithNoSSR = dynamic(import('../components/hello3'), { - ssr: false, -}) - -export default () => ( -
-
- -

HOME PAGE is here!

-
-) -``` - - - -#### 4. 同时加载多个模块 - -```jsx -import dynamic from 'next/dynamic' - -const HelloBundle = dynamic({ - modules: () => { - const components = { - Hello1: import('../components/hello1'), - Hello2: import('../components/hello2'), - } - - return components - }, - render: (props, { Hello1, Hello2 }) => ( -
-

{props.title}

- - -
- ), -}) - -export default () => -``` - - - -### 自定义 `` - -

- Examples - - -

- -组件来初始化页面。你可以重写它来控制页面初始化，如下面的事： - -- 当页面变化时保持页面布局 -- 当路由变化时保持页面状态 -- 使用`componentDidCatch`自定义处理错误 -- 注入额外数据到页面里 (如 GraphQL 查询) - -重写的话，新建`./pages/_app.js`文件，重写 App 模块如下所示： - -```js -import App, { Container } from 'next/app' -import React from 'react' - -export default class MyApp extends App { - static async getInitialProps({ Component, router, ctx }) { - let pageProps = {} - - if (Component.getInitialProps) { - pageProps = await Component.getInitialProps(ctx) - } - - return { pageProps } - } - - render() { - const { Component, pageProps } = this.props - return ( - - - - ) - } -} -``` - - - -### 自定义 `` - -

- Examples - - -

- -- 在服务端呈现 -- 初始化服务端时添加文档标记元素 -- 通常实现服务端渲染会使用一些 css-in-js 库，如[styled-components](./examples/with-styled-components), [glamorous](./examples/with-glamorous) 或 [emotion](with-emotion)。[styled-jsx](https://github.com/zeit/styled-jsx)是 Next.js 自带默认使用的 css-in-js 库 - -`Next.js`会自动定义文档标记，比如，你从来不需要添加``, ``等。如果想自定义文档标记，你可以新建`./pages/_document.js`，然后扩展`Document`类： - -```jsx -// _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, { Head, Main, NextScript } from 'next/document' - -export default class MyDocument extends Document { - static async getInitialProps(ctx) { - const initialProps = await Document.getInitialProps(ctx) - return { ...initialProps } - } - - render() { - return ( - - - - - -
- - - - ) - } -} -``` - -钩子[`getInitialProps`](#fetching-data-and-component-lifecycle)接收到的参数`ctx`对象都是一样的 - -- 回调函数`renderPage`是会执行 React 渲染逻辑的函数(同步)，这种做法有助于此函数支持一些类似于 Aphrodite 的 renderStatic 等一些服务器端渲染容器。 - -**注意：`
`外的 React 组件将不会渲染到浏览器中，所以那添加应用逻辑代码。如果你页面需要公共组件（菜单或工具栏），可以参照上面说的`App`组件代替。** - - - -#### 自定义 `renderPage` - -🚧 应该注意的是，您应该定制“renderPage”的唯一原因是使用 css-in-js 库，需要将应用程序包装起来以正确使用服务端渲染。 🚧 - -- 它将一个选项对象作为参数进行进一步的自定义： - -```js -import Document from 'next/document' - -class MyDocument extends Document { - static async getInitialProps(ctx) { - const originalRenderPage = ctx.renderPage - - ctx.renderPage = () => - originalRenderPage({ - // useful for wrapping the whole react tree - enhanceApp: App => App, - // useful for wrapping in a per-page basis - enhanceComponent: Component => Component, - }) - - // Run the parent `getInitialProps` using `ctx` that now includes our custom `renderPage` - const initialProps = await Document.getInitialProps(ctx) - - return initialProps - } -} - -export default MyDocument -``` - -### 自定义错误处理 - -404 和 500 错误客户端和服务端都会通过`error.js`组件处理。如果你想改写它，则新建`_error.js`在文件夹中： - -⚠️ 该`pages/_error.js`组件仅用于生产。在开发过程中，您会收到调用堆栈错误，以了解错误源自何处。 ⚠️ - -```jsx -import React from 'react' - -export default class Error extends React.Component { - static getInitialProps({ res, err }) { - const statusCode = res ? res.statusCode : err ? err.statusCode : null - return { statusCode } - } - - render() { - return ( -

- {this.props.statusCode - ? `An error ${this.props.statusCode} occurred on server` - : 'An error occurred on client'} -

- ) - } -} -``` - - - -### 渲染内置错误页面 - -如果你想渲染内置错误页面，你可以使用`next/error`： - -```jsx -import React from 'react' -import Error from 'next/error' -import fetch from 'isomorphic-unfetch' - -export default class Page extends React.Component { - static async getInitialProps() { - const res = await fetch('https://api.github.com/repos/zeit/next.js') - const statusCode = res.statusCode > 200 ? res.statusCode : false - const json = await res.json() - - return { statusCode, stars: json.stargazers_count } - } - - render() { - if (this.props.statusCode) { - return - } - - return
Next stars: {this.props.stars}
- } -} -``` - -> 如果你自定义了个错误页面，你可以引入自己的错误页面来代替`next/error` - - - -### 自定义配置 - -如果你想自定义 Next.js 的高级配置，可以在根目录下新建`next.config.js`文件（与`pages/` 和 `package.json`一起） - -注意：`next.config.js`是一个 Node.js 模块，不是一个 JSON 文件，可以用于 Next 启动服务已经构建阶段，但是不作用于浏览器端。 - -```js -// next.config.js -module.exports = { - /* config options here */ -} -``` - -或使用一个函数： - -```js -module.exports = (phase, { defaultConfig }) => { - // - // https://github.com/zeit/ - return { - /* config options here */ - } -} -``` - -`phase`是配置文件被加载时的当前内容。你可看到所有的 phases 常量：[constants](./lib/constants.js) -这些常量可以通过`next/constants`引入： - -```js -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 */ - } -} -``` - - - -#### 设置自定义构建目录 - -你可以自定义一个构建目录，如新建`build`文件夹来代替`.next` 文件夹成为构建目录。如果没有配置构建目录，构建时将会自动新建`.next`文件夹 - -```js -// next.config.js -module.exports = { - distDir: 'build', -} -``` - - - -#### 禁止 etag 生成 - -你可以禁止 etag 生成根据你的缓存策略。如果没有配置，Next 将会生成 etags 到每个页面中。 - -```js -// next.config.js -module.exports = { - generateEtags: false, -} -``` - - - -#### 配置 onDemandEntries - -Next 暴露一些选项来给你控制服务器部署以及缓存页面： - -```js -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, - }, -} -``` - -这个只是在开发环境才有的功能。如果你在生成环境中想缓存 SSR 页面，请查看[SSR-caching](https://github.com/zeit/next.js/tree/canary/examples/ssr-caching) - - - -#### 配置解析路由时的页面文件后缀名 - -如 typescript 模块[`@zeit/next-typescript`](https://github.com/zeit/next-plugins/tree/master/packages/next-typescript)，需要支持解析后缀名为`.ts`的文件。`pageExtensions` 允许你扩展后缀名来解析各种 pages 下的文件。 - -```js -// next.config.js -module.exports = { - pageExtensions: ['jsx', 'js'], -} -``` - - - -#### 配置构建 ID - -Next.js 使用构建时生成的常量来标识你的应用服务是哪个版本。在每台服务器上运行构建命令时，可能会导致多服务器部署出现问题。为了保持同一个构建 ID，可以配置`generateBuildId`函数： - -```js -// next.config.js -module.exports = { - generateBuildId: async () => { - // For example get the latest git commit hash here - return 'my-build-id' - }, -} -``` - - - -### 自定义 webpack 配置 - -

- Examples - -

- -可以使用些一些常见的模块 - -- [@zeit/next-css](https://github.com/zeit/next-plugins/tree/master/packages/next-css) -- [@zeit/next-sass](https://github.com/zeit/next-plugins/tree/master/packages/next-sass) -- [@zeit/next-less](https://github.com/zeit/next-plugins/tree/master/packages/next-less) -- [@zeit/next-preact](https://github.com/zeit/next-plugins/tree/master/packages/next-preact) -- [@zeit/next-typescript](https://github.com/zeit/next-plugins/tree/master/packages/next-typescript) - -_注意： `webpack`方法将被执行两次，一次在服务端一次在客户端。你可以用`isServer`属性区分客户端和服务端来配置_ - -多配置可以组合在一起，如： - -```js -const withTypescript = require('@zeit/next-typescript') -const withSass = require('@zeit/next-sass') - -module.exports = withTypescript( - withSass({ - webpack(config, options) { - // Further custom configuration here - return config - }, - }) -) -``` - -为了扩展`webpack`使用，可以在`next.config.js`定义函数。 - -```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 }) => { - // Perform customizations to webpack config - // Important: return the modified config - return config - }, - webpackDevMiddleware: config => { - // Perform customizations to webpack dev middleware config - // Important: return the modified config - return config - }, -} -``` - -`webpack`的第二个参数是个对象，你可以自定义配置它，对象属性如下所示： - -- `buildId` - 字符串类型，构建的唯一标示 -- `dev` - `Boolean`型，判断你是否在开发环境下 -- `isServer` - `Boolean` 型，为`true`使用在服务端, 为`false`使用在客户端. -- `defaultLoaders` - 对象型 ，内部加载器, 你可以如下配置 - - `babel` - 对象型，配置`babel-loader`. - -`defaultLoaders.babel`使用案例如下： - -```js -// Example next.config.js for adding a loader that depends on babel-loader -// This source was taken from the @zeit/next-mdx plugin source: -// https://github.com/zeit/next-plugins/blob/master/packages/next-mdx -module.exports = { - webpack: (config, {}) => { - config.module.rules.push({ - test: /\.mdx/, - use: [ - options.defaultLoaders.babel, - { - loader: '@mdx-js/loader', - options: pluginOptions.options, - }, - ], - }) - - return config - }, -} -``` - - - -### 自定义 babel 配置 - -

- Examples - -

- -为了扩展方便我们使用`babel`，可以在应用根目录新建`.babelrc`文件，该文件可配置。 - -如果有该文件，我们将会考虑数据源，因此也需要定义 next 项目需要的东西，也就是 `next/babel`预设。 - -这种设计方案将会使你不诧异于我们可以定制 babel 配置。 - -下面是`.babelrc`文件案例： - -```json -{ - "presets": ["next/babel"], - "plugins": [] -} -``` - -`next/babel`预设可处理各种 React 应用所需要的情况。包括： - -- preset-env -- preset-react -- plugin-proposal-class-properties -- plugin-proposal-object-rest-spread -- plugin-transform-runtime -- styled-jsx - -presets / plugins 不允许添加到`.babelrc`中，然而你可以配置`next/babel`预设： - -```json -{ - "presets": [ - [ - "next/babel", - { - "preset-env": {}, - "transform-runtime": {}, - "styled-jsx": {}, - "class-properties": {} - } - ] - ], - "plugins": [] -} -``` - -`"preset-env"`模块选项应该保持为 false，否则 webpack 代码分割将被禁用。 - - - -### 暴露配置到服务端和客户端 - -在应用程序中通常需要提供配置值 - -Next.js 支持 2 种提供配置的方式： - -- 构建时配置 -- 运行时配置 - -#### 构建时配置 - -构建时配置的工作方式是将提供的值内联到 Javascript 包中。 - -你可以在`next.config.js`设置`env`: - -```js -// next.config.js -module.exports = { - env: { - customKey: 'value', - }, -} -``` - -这将允许你在代码中使用`process.env.customKey`，例如： - -```jsx -// pages/index.js -function Index() { - return

The value of customKey is: {process.env.customKey}

-} - -export default Index -``` - -#### 运行时配置 - -> ⚠️ 请注意，使用此选项时不可用 `target: 'serverless'` - -> ⚠️ 通常，您希望使用构建时配置来提供配置。原因是运行时配置增加了一个小的 rendering/initialization 开销。 - -`next/config`模块使你应用运行时可以读取些存储在`next.config.js`的配置项。`serverRuntimeConfig`属性只在服务器端可用，`publicRuntimeConfig`属性在服务端和客户端可用。 - -```js -// 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', - }, -} -``` - -```js -// 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 ( -
- logo -
- ) -} - -export default MyImage -``` - -### 启动服务选择 hostname - -启动开发环境服务可以设置不同的 hostname，你可以在启动命令后面加上`--hostname 主机名` 或 `-H 主机名`。它将会启动一个 TCP 服务器来监听连接所提供的主机。 - - - -### CDN 支持前缀 - -建立一个 CDN，你能配置`assetPrefix`选项，去配置你的 CDN 源。 - -```js -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' : '', -} -``` - -注意：Next.js 运行时将会自动添加前缀，但是对于`/static`是没有效果的，如果你想这些静态资源也能使用 CDN，你需要自己添加前缀。有一个方法可以判断你的环境来加前缀，如 [in this example](https://github.com/zeit/next.js/tree/master/examples/with-universal-configuration-build-time)。 - - - -## 项目部署 - -部署中，你可以先构建打包生成环境代码，再启动服务。因此，构建和启动分为下面两条命令： - -```bash -next build -next start -``` - -例如，使用[`now`](https://zeit.co/now)去部署`package.json`配置文件如下： - -```json -{ - "name": "my-app", - "dependencies": { - "next": "latest" - }, - "scripts": { - "dev": "next", - "build": "next build", - "start": "next start" - } -} -``` - -然后就可以直接运行`now`了。 - -Next.js 也有其他托管解决方案。请查考 wiki 章节['Deployment'](https://github.com/zeit/next.js/wiki/Deployment) 。 - -注意：`NODE_ENV`可以通过`next`命令配置，如果没有配置，会最大渲染，如果你使用编程式写法的话[programmatically](#custom-server-and-routing)，你需要手动设置`NODE_ENV=production`。 - -注意：推荐将`.next`或自定义打包文件夹[custom dist folder](https://github.com/zeit/next.js#custom-configuration)放入`.gitignore` 或 `.npmignore`中。否则，使用`files` 或 `now.files` -添加部署白名单，并排除`.next`或自定义打包文件夹。 - - - -### 无服务器部署 - -
- 例子 - -
- -无服务器部署通过将应用程序拆分为更小的部分（也称为[**lambdas**](https://zeit.co/docs/v2/deployments/concepts/lambdas/)）来显着提高可靠性和可伸缩性。在 Next.js 中，`pages`目录中的每个页面都变成了无服务器的 lambda。 -对于无服务器的人来说，有[许多好处](https://zeit.co/blog/serverless-express-js-lambdas-with-now-2#benefits-of-serverless-express)。引用的链接在 Express 的上下文中讨论了其中的一些，但这些原则普遍适用：无服务器允许分布式故障点，无限的可扩展性，并且通过“为您使用的内容付费”的模式来提供难以置信的价格。 - -要在 Next.js 中启用**无服务器模式**，可在`Next.config.js`中配置`target`值为`serverless`: - -```js -// next.config.js -module.exports = { - target: 'serverless', -} -``` - -`serverless`将每页输出一个 lambda。此文件是完全独立的，不需要运行任何依赖项： - -- `pages/index.js` => `.next/serverless/pages/index.js` -- `pages/about.js` => `.next/serverless/pages/about.js` - -Next.js 无服务器功能的签名类似于 Node.js HTTP 服务器回调: - -```ts -export function render(req: http.IncomingMessage, res: http.ServerResponse) => void -``` - -- [http.IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage) -- [http.ServerResponse](https://nodejs.org/api/http.html#http_class_http_serverresponse) -- `void` 指的是没有返回值的函数，它等同于 JavaScript`undefined`。调用该函数将完成请求。 - -使用无服务配置, 你可以讲 Next.js 部署到[ZEIT Now](https://zeit.co/now) 并提供所有的好处和易于控制; [custom routes](https://zeit.co/guides/custom-next-js-server-to-routes/) 缓存头. 要了解更多信息，请参阅 [ZEIT Guide for Deploying Next.js with Now](https://zeit.co/guides/deploying-nextjs-with-now/) - -#### 降级部署 - -Next.js 为无服务器部署提供低级 API，因为托管平台具有不同的功能签名。通常，您需要使用兼容性层包装 Next.js 无服务器构建的输出。 - -例如，如果平台支持 Node.js[`http.Server`](https://nodejs.org/api/http.html#http_class_http_server)类： - -```js -const http = require('http') -const page = require('./.next/serverless/pages/about.js') -const server = new http.Server((req, res) => page.render(req, res)) -server.listen(3000, () => console.log('Listening on http://localhost:3000')) -``` - -有关特定平台示例，请参阅[the examples section above](#serverless-deployment). - -#### 摘要 - -- 用于实现无服务器部署的 Low-level API -- `pages`目录中的每个页面都成为无服务器功能(lambda) -- 创建最小的无服务器功能 (50Kb base zip size) -- 针对功能的快速[cold start](https://zeit.co/blog/serverless-ssr#cold-start) 进行了优化 -- 无服务器函数有 0 个依赖项 (依赖项包含在函数包中) -- 使用 Node.js 中的[http.IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage)和[http.ServerResponse](https://nodejs.org/api/http.html#http_class_http_serverresponse) -- 选择使用`target: 'serverless'` in `next.config.js` -- 在执行函数时不要加载`next.config.js`，请注意这意味着`publicRuntimeConfig` / `serverRuntimeConfig`不支持。 - -## 浏览器支持 - -Next.js 支持 IE11 和所有的现代浏览器使用了[`@babel/preset-env`](https://new.babeljs.io/docs/en/next/babel-preset-env.html)。为了支持 IE11，Next.js 需要全局添加`Promise`的 polyfill。有时你的代码或引入的其他 NPM 包的部分功能现代浏览器不支持，则需要用 polyfills 去实现。 - -ployflls 实现案例为[polyfills](https://github.com/zeit/next.js/tree/canary/examples/with-polyfills)。 - - - -## 导出静态页面 - -

- Examples - -

- -`next export`可以输出一个 Next.js 应用作为静态资源应用而不依靠 Node.js 服务。 -这个输出的应用几乎支持 Next.js 的所有功能，包括动态路由，预获取，预加载以及动态导入。 - -`next export`将把所有有可能渲染出的 HTML 都生成。这是基于映射对象的`pathname`关键字关联到页面对象。这个映射叫做`exportPathMap`。 - -页面对象有 2 个属性: - -- `page` - 字符串类型，页面生成目录 -- `query` - 对象类型，当预渲染时，`query`对象将会传入页面的生命周期`getInitialProps`中。默认为`{}`。 - - - -### 使用 - -通常开发 Next.js 应用你将会运行： - -``` -next build -next export -``` - -`next export`命令默认不需要任何配置，将会自动生成默认`exportPathMap`生成`pages`目录下的路由你页面。 - -如果你想动态配置路由，可以在`next.config.js`中添加异步函数`exportPathMap`。 - -```js -// next.config.js -module.exports = { - exportPathMap: async function(defaultPathMap) { - 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' } }, - } - }, -} -``` - -> 注意：如果 path 的结尾是目录名，则将导出`/dir-name/index.html`，但是如果结尾有扩展名，将会导出对应的文件，如上`/readme.md`。如果你使用`.html`以外的扩展名解析文件时，你需要设置 header 的`Content-Type`头为"text/html". - -输入下面命令： - -```sh -next build -next export -``` - -你可以在`package.json`添加一个 NPM 脚本，如下所示： - -```json -{ - "scripts": { - "build": "next build", - "export": "npm run build && next export" - } -} -``` - -接着只用执行一次下面命令： - -```sh -npm run export -``` - -然后你将会有一个静态页面应用在`out` 目录下。 - -> 你也可以自定义输出目录。可以运行`next export -h`命令查看帮助。 - -现在你可以部署`out`目录到任意静态资源服务器上。注意如果部署 GitHub Pages 需要加个额外的步骤，[文档如下](https://github.com/zeit/next.js/wiki/Deploying-a-Next.js-app-into-GitHub-Pages) - -例如，访问`out`目录并用下面命令部署应用[ZEIT Now](https://zeit.co/now). - -```sh -now -``` - - - -### 复制自定义文件 - -如果您必须复制 robots.txt 等自定义文件或生成 sitemap.xml，您可以在其中执行此操作`exportPathMap`。 `exportPathMap`获取一些上下文参数来帮助您创建/复制文件： - -- `dev` - `true`表示在开发环境下使用`exportPathMap`. `false`表示运行于`next export`. 在开发中，“exportpathmap”用于定义路由，不需要复制文件等行为。 -- `dir` - 项目目录的绝对路径 -- `outDir` - 指向`out`目录的绝对路径（可配置为`-o`或`--outdir`）。当`dev`为`true`时，`outdir`的值将为`null`。 -- `distDir` - `.next`目录的绝对路径(可使用`distDir`配置键配置) -- `buildId` - 导出正在运行的 buildId - -```js -// next.config.js -const fs = require('fs') -const { join } = require('path') -const { promisify } = require('util') -const copyFile = promisify(fs.copyFile) - -module.exports = { - exportPathMap: async function( - defaultPathMap, - { dev, dir, outDir, distDir, buildId } - ) { - if (dev) { - return defaultPathMap - } - // This will copy robots.txt from your project root into the out directory - await copyFile(join(dir, 'robots.txt'), join(outDir, 'robots.txt')) - return defaultPathMap - }, -} -``` - -### 限制 - -使用`next export`，我们创建了个静态 HTML 应用。构建时将会运行页面里生命周期`getInitialProps` 函数。 - -`req`和`res`只在服务端可用，不能通过`getInitialProps`。 - -> 所以你不能预构建 HTML 文件时动态渲染 HTML 页面。如果你想动态渲染可以运行`next start`或其他自定义服务端 API。 - - - -## 多 zone - -

- Examples - -

- -一个 zone 时一个单独的 Next.js 应用。如果你有很多 zone，你可以合并成一个应用。 - -例如，你如下有两个 zone： - -- https://docs.my-app.com 服务于路由 `/docs/**` -- https://ui.my-app.com 服务于所有页面 - -有多 zone 应用技术支持，你可以将几个应用合并到一个，而且可以自定义 URL 路径，使你能同时单独开发各个应用。 - -> 与 microservices 观念类似, 只是应用于前端应用. - - - -### 怎么定义一个 zone - -zone 没有单独的 API 文档。你需要做下面事即可： - -- 确保你的应用里只有需要的页面 (例如, https://ui.my-app.com 不包含 `/docs/**`) -- 确保你的应用有个前缀[assetPrefix](https://github.com/zeit/next.js#cdn-support-with-asset-prefix)。（你也可以定义动态前缀[dynamically](https://github.com/zeit/next.js#dynamic-assetprefix)） - - - -### 怎么合并他们 - -你能使用 HTTP 代理合并 zone - -你能使用代理[micro proxy](https://github.com/zeit/micro-proxy)来作为你的本地代理服务。它允许你定义路由规则如下： - -```json -{ - "rules": [ - { - "pathname": "/docs**", - "method": ["GET", "POST", "OPTIONS"], - "dest": "https://docs.my-app.com" - }, - { "pathname": "/**", "dest": "https://ui.my-app.com" } - ] -} -``` - -生产环境部署，如果你使用了[ZEIT now](https://zeit.co/now)，可以它的使用[path alias](https://zeit.co/docs/features/path-aliases) 功能。否则，你可以设置你已使用的代理服务编写上面规则来路由 HTML 页面 - - - -## 技巧 - -- [设置 301 重定向](https://www.raygesualdo.com/posts/301-redirects-with-nextjs/) -- [只处理服务器端模块](https://arunoda.me/blog/ssr-and-server-only-modules) -- [构建项目 React-Material-UI-Next-Express-Mongoose-Mongodb](https://github.com/builderbook/builderbook) -- [构建一个 SaaS 产品 React-Material-UI-Next-MobX-Express-Mongoose-MongoDB-TypeScript](https://github.com/async-labs/saas) - - - -## 问答 - -
- 这个产品可以用于生产环境吗？ - https://zeit.co 都是一直用 Next.js 写的。 - -它的开发体验和终端用户体验都很好，所以我们决定开源出来给大家共享。 - -
- -
- 体积多大？ - -客户端大小根据应用需求不一样大小也不一样。 - -一个最简单 Next 应该用 gzip 压缩后大约 65kb - -
- -
- 这个像 `create-react-app`? - -是或不是. - -是，因为它让你的 SSR 开发更简单。 - -不是，因为它规定了一定的目录结构，使我们能做以下更高级的事： - -- 服务端渲染 -- 自动代码分割 - -此外，Next.js 还提供两个内置特性： - -- 路由与懒加载组件: `` (通过引入 `next/link`) -- 修改``的组件: `` (通过引入 `next/head`) - -如果你想写共用组件，可以嵌入 Next.js 应用和 React 应用中，推荐使用`create-react-app`。你可以更改`import`保持代码清晰。 - -
- -
- 怎么解决 CSS 嵌入 JS 问题? - -Next.js 自带[styled-jsx](https://github.com/zeit/styled-jsx)库支持 CSS 嵌入 JS。而且你可以选择其他嵌入方法到你的项目中，可参考文档[as mentioned before](#css-in-js)。 - -
- -
- 哪些语法会被转换？怎么转换它们？ - -我们遵循 V8 引擎的，如今 V8 引擎广泛支持 ES6 语法以及`async`和`await`语法，所以我们支持转换它们。但是 V8 引擎不支持修饰器语法，所以我们也不支持转换这语法。 - -可以参照[这些](https://github.com/zeit/next.js/blob/master/server/build/webpack.js#L79) 以及 [这些](https://github.com/zeit/next.js/issues/26) - -
- -
- 为什么使用新路由? - -Next.js 的特别之处如下所示: - -- 路由不需要被提前知道 -- 路由总是被懒加载 -- 顶层组件可以定义生命周期`getInitialProps`来阻止路由加载（当服务端渲染或路由懒加载时） - -因此,我们可以介绍一个非常简单的路由方法,它由下面两部分组成: - -- 每个顶层组件都将会收到一个`url`对象，来检查 url 或修改历史记录 -- ``组件用于包装如(``)标签的元素容器，来执行客户端转换。 - -我们使用了些有趣的场景来测试路由的灵活性，例如，可查看[nextgram](https://github.com/zeit/nextgram)。 - -
- -
-我怎么定义自定义路由? - -我们通过请求处理来[添加](#custom-server-and-routing)任意 URL 与任意组件之前的映射关系。 - -在客户端，我们``组件有个属性`as`，可以装饰改变获取到的 URL。 - -
- -
-怎么获取数据? - -这由你决定。`getInitialProps`是一个异步函数`async`（也就是函数将会返回个`Promise`）。你可以在任意位置获取数据。 - -
- -
- 我可以使用 GraphQL 吗? - -是的! 这里有个例子[Apollo](./examples/with-apollo). - -
- -
-我可以使用 Redux 吗? - -是的! 这里有个[例子](./examples/with-redux) - -
- -
-我可以在 Next 应用中使用我喜欢的 Javascript 库或工具包吗? - -从我们第一次发版就已经提供**很多**例子，你可以查看这些[例子](./examples)。 - -
- -
-什么启发我们做这个? - -我们实现的大部分目标都是通过 Guillermo Rauch 的[Web 应用的 7 原则](http://rauchg.com/2014/7-principles-of-rich-web-applications/)来启发出的。 - -PHP 的易用性也是个很好的灵感来源，我们觉得 Next.js 可以替代很多需要用 PHP 输出 HTML 的场景。 - -与 PHP 不同的是，我们得利于 ES6 模块系统，每个文件会输出一个**组件或方法**，以便可以轻松的导入用于懒加载和测试 - -我们研究 React 的服务器渲染时并没有花费很大的步骤，因为我们发现一个类似于 Next.js 的产品，React 作者 Jordan Walke 写的[react-page](https://github.com/facebookarchive/react-page) (现在已经废弃) - -
- - - -## 贡献 - -可查看 [contributing.md](./contributing.md) - - - -## 作者 - -- Arunoda Susiripala ([@arunoda](https://twitter.com/arunoda)) – [ZEIT](https://zeit.co) -- Tim Neutkens ([@timneutkens](https://twitter.com/timneutkens)) – [ZEIT](https://zeit.co) -- Naoyuki Kanezawa ([@nkzawa](https://twitter.com/nkzawa)) – [ZEIT](https://zeit.co) -- Tony Kovanen ([@tonykovanen](https://twitter.com/tonykovanen)) – [ZEIT](https://zeit.co) -- Guillermo Rauch ([@rauchg](https://twitter.com/rauchg)) – [ZEIT](https://zeit.co) -- Dan Zajdband ([@impronunciable](https://twitter.com/impronunciable)) – Knight-Mozilla / Coral Project diff --git a/contributing.md b/contributing.md index 6ca78b5a2e67..8d1d05d6fe13 100644 --- a/contributing.md +++ b/contributing.md @@ -12,6 +12,8 @@ Our Commitment to Open Source can be found [here](https://zeit.co/blog/oss) > You may need to run `yarn types` again if your types get outdated. +To contribute to [our examples](examples), take a look at the [“Adding examples” section](#adding-examples). + ## To run tests Make sure you have `chromedriver` installed for your Chrome version. You can install it with @@ -112,3 +114,62 @@ EXAMPLE=./test/integration/basic ```sh yarn install --force ``` + +## Adding examples + +When you add an example to the [examples](examples) directory, don’t forget to add a `README.md` file with the following format: + +- Replace `DIRECTORY_NAME` with the directory name you’re adding. +- Fill in `Example Name` and `Description`. +- To add additional installation instructions, please add it where appropriate. +- To add additional notes, add `## Notes` section at the end. +- Remove the `Deploy your own` section if your example can’t be immediately deployed to ZEIT Now. + +````markdown +# Example Name + +Description + +## Deploy your own + +Deploy the example using [ZEIT Now](https://zeit.co/now): + +[![Deploy with ZEIT Now](https://zeit.co/button)](https://zeit.co/new/project?template=https://github.com/zeit/next.js/tree/canary/examples/DIRECTORY_NAME) + +## How to use + +### Using `create-next-app` + +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: + +```bash +npx create-next-app --example DIRECTORY_NAME DIRECTORY_NAME-app +# or +yarn create next-app --example DIRECTORY_NAME DIRECTORY_NAME-app +``` + +### Download manually + +Download the example: + +```bash +curl https://codeload.github.com/zeit/next.js/tar.gz/canary | tar -xz --strip=2 next.js-canary/examples/DIRECTORY_NAME +cd DIRECTORY_NAME +``` + +Install it and run: + +```bash +npm install +npm run dev +# or +yarn +yarn dev +``` + +Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit.co/download)): + +```bash +now +``` +```` diff --git a/examples/active-class-name/README.md b/examples/active-class-name/README.md index a822eae9ad6f..f18cff6a5c74 100644 --- a/examples/active-class-name/README.md +++ b/examples/active-class-name/README.md @@ -1,5 +1,7 @@ # activeClassName example +ReactRouter has a convenience property on the `Link` element to allow an author to set the _active_ className on a link. This example replicates that functionality using Next's own `Link`. + ## Deploy your own Deploy the example using [ZEIT Now](https://zeit.co/now): @@ -10,10 +12,10 @@ Deploy the example using [ZEIT Now](https://zeit.co/now): ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example active-class-name active-class-name-app +npm init next-app --example active-class-name active-class-name-app # or yarn create next-app --example active-class-name active-class-name-app ``` @@ -42,7 +44,3 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind the example - -ReactRouter has a convenience property on the `Link` element to allow an author to set the _active_ className on a link. This example replicates that functionality using Next's own `Link`. diff --git a/examples/amp-first/README.md b/examples/amp-first/README.md index 369cfb40665c..a3599e527efc 100644 --- a/examples/amp-first/README.md +++ b/examples/amp-first/README.md @@ -13,12 +13,35 @@ Deploy the example using [ZEIT Now](https://zeit.co/now): [![Deploy with ZEIT Now](https://zeit.co/button)](https://zeit.co/new/project?template=https://github.com/zeit/next.js/tree/canary/examples/amp-first) -## Getting started +## How to use -To run the app in development, run the following command in the project director: +### Using `create-next-app` -```shell -$ yarn dev +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: + +```bash +npm init next-app --example amp-first amp-first-app +# or +yarn create next-app --example amp-first amp-first-app +``` + +### Download manually + +Download the example: + +```bash +curl https://codeload.github.com/zeit/next.js/tar.gz/canary | tar -xz --strip=2 next.js-canary/examples/amp-first +cd amp-first +``` + +Install it and run: + +```bash +npm install +npm run dev +# or +yarn +yarn dev ``` Open [http://localhost:3000](http://localhost:3000) to view it in the browser. The page will reload if you make edits. You will also see AMP validation errors in the console. diff --git a/examples/amp-story/README.md b/examples/amp-story/README.md index be4c74f9095e..816c6febe431 100644 --- a/examples/amp-story/README.md +++ b/examples/amp-story/README.md @@ -1,5 +1,7 @@ # Google AMP Story +This example shows how to create an AMP page with `amp-story` using Next.js and the AMP feature. + ## Deploy your own Deploy the example using [ZEIT Now](https://zeit.co/now): @@ -10,10 +12,10 @@ Deploy the example using [ZEIT Now](https://zeit.co/now): ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example amp-story amp-app +npm init next-app --example amp-story amp-app # or yarn create next-app --example amp-story amp-app ``` @@ -42,7 +44,3 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind the example - -This example shows how to create an AMP page with `amp-story` using Next.js and the AMP feature. diff --git a/examples/amp/README.md b/examples/amp/README.md index 5aa3fd6c327c..b828d6d6c537 100644 --- a/examples/amp/README.md +++ b/examples/amp/README.md @@ -1,5 +1,7 @@ # Google AMP +This example shows how to create AMP pages using Next.js and the AMP feature. It shows a normal page (non-AMP), an AMP only page, and a hybrid AMP page. + ## Deploy your own Deploy the example using [ZEIT Now](https://zeit.co/now): @@ -10,10 +12,10 @@ Deploy the example using [ZEIT Now](https://zeit.co/now): ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example amp amp-app +npm init next-app --example amp amp-app # or yarn create next-app --example amp amp-app ``` @@ -42,7 +44,3 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind the example - -This example shows how to create AMP pages using Next.js and the AMP feature. It shows a normal page (non-AMP), an AMP only page, and a hybrid AMP page. diff --git a/examples/amp/pages/index.js b/examples/amp/pages/index.js index b9af23a3cf63..f7952214e0f1 100644 --- a/examples/amp/pages/index.js +++ b/examples/amp/pages/index.js @@ -18,6 +18,22 @@ export default () => {

The Cat (AMP-first Page)

Meowwwwwwww

+ + +

Cat ipsum dolor sit amet, eat grass, throw it back up but refuse to leave cardboard box or groom diff --git a/examples/analyze-bundles/README.md b/examples/analyze-bundles/README.md index eda6eea533b1..445051ff5c1f 100644 --- a/examples/analyze-bundles/README.md +++ b/examples/analyze-bundles/README.md @@ -1,5 +1,7 @@ # Analyzer Bundles example +This example shows how to analyze the output bundles using [@next/bundle-analyzer](https://github.com/zeit/next.js/tree/master/packages/next-bundle-analyzer) + ## Deploy your own Deploy the example using [ZEIT Now](https://zeit.co/now): @@ -10,10 +12,10 @@ Deploy the example using [ZEIT Now](https://zeit.co/now): ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example analyze-bundles analyze-bundles-app +npm init next-app --example analyze-bundles analyze-bundles-app # or yarn create next-app --example analyze-bundles analyze-bundles-app ``` @@ -37,9 +39,7 @@ yarn yarn dev ``` -## The idea behind the example - -This example shows how to analyze the output bundles using [@next/bundle-analyzer](https://github.com/zeit/next.js/tree/master/packages/next-bundle-analyzer) +### Analyze webpack output To analyze your webpack output, invoke the following command: diff --git a/examples/api-routes-apollo-server-and-client/README.md b/examples/api-routes-apollo-server-and-client/README.md index 325f085eacb9..b1d07a06b974 100644 --- a/examples/api-routes-apollo-server-and-client/README.md +++ b/examples/api-routes-apollo-server-and-client/README.md @@ -1,5 +1,14 @@ # Apollo Server and Client Example +[Apollo](https://www.apollographql.com/client/) is a GraphQL client that allows you to easily query the exact data you need from a GraphQL server. In addition to fetching and mutating data, Apollo analyzes your queries and their results to construct a client-side cache of your data, which is kept up to date as further queries and mutations are run, fetching more results from the server. + +In this simple example, we integrate Apollo seamlessly with Next by wrapping our _pages/\_app.js_ inside a [higher-order component (HOC)](https://facebook.github.io/react/docs/higher-order-components.html). Using the HOC pattern we're able to pass down a central store of query result data created by Apollo into our React component hierarchy defined inside each page of our Next application. + +On initial page load, while on the server and inside `getInitialProps`, we invoke the Apollo method, [`getDataFromTree`](https://www.apollographql.com/docs/react/api/react-ssr/#getdatafromtree). This method returns a promise; at the point in which the promise resolves, our Apollo Client store is completely initialized. + +Note: Do not be alarmed that you see two renders being executed. Apollo recursively traverses the React render tree looking for Apollo query components. When it has done that, it fetches all these queries and then passes the result to a cache. This cache is then used to render the data on the server side (another React render). +https://www.apollographql.com/docs/react/api/react-ssr/#getdatafromtree + ## Deploy your own Deploy the example using [ZEIT Now](https://zeit.co/now): @@ -10,10 +19,10 @@ Deploy the example using [ZEIT Now](https://zeit.co/now): ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example api-routes-apollo-server-and-client api-routes-apollo-server-and-client-app +npm init next-app --example api-routes-apollo-server-and-client api-routes-apollo-server-and-client-app # or yarn create next-app --example api-routes-apollo-server-and-client api-routes-apollo-server-and-client-app ``` @@ -42,14 +51,3 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind the example - -[Apollo](https://www.apollographql.com/client/) is a GraphQL client that allows you to easily query the exact data you need from a GraphQL server. In addition to fetching and mutating data, Apollo analyzes your queries and their results to construct a client-side cache of your data, which is kept up to date as further queries and mutations are run, fetching more results from the server. - -In this simple example, we integrate Apollo seamlessly with Next by wrapping our _pages/\_app.js_ inside a [higher-order component (HOC)](https://facebook.github.io/react/docs/higher-order-components.html). Using the HOC pattern we're able to pass down a central store of query result data created by Apollo into our React component hierarchy defined inside each page of our Next application. - -On initial page load, while on the server and inside `getInitialProps`, we invoke the Apollo method, [`getDataFromTree`](https://www.apollographql.com/docs/react/api/react-ssr/#getdatafromtree). This method returns a promise; at the point in which the promise resolves, our Apollo Client store is completely initialized. - -Note: Do not be alarmed that you see two renders being executed. Apollo recursively traverses the React render tree looking for Apollo query components. When it has done that, it fetches all these queries and then passes the result to a cache. This cache is then used to render the data on the server side (another React render). -https://www.apollographql.com/docs/react/api/react-ssr/#getdatafromtree diff --git a/examples/api-routes-graphql/README.md b/examples/api-routes-graphql/README.md index 66f1bcdd3602..ec0442b82331 100644 --- a/examples/api-routes-graphql/README.md +++ b/examples/api-routes-graphql/README.md @@ -1,5 +1,7 @@ # API routes with GraphQL server +Next.js ships with [API routes](https://github.com/zeit/next.js#api-routes), which provide an easy solution to build your own `API`. This example shows their usage alongside [apollo-server-micro](https://github.com/apollographql/apollo-server/tree/master/packages/apollo-server-micro) to provide simple GraphQL server consumed by Next.js app. + ## Deploy your own Deploy the example using [ZEIT Now](https://zeit.co/now): @@ -10,10 +12,10 @@ Deploy the example using [ZEIT Now](https://zeit.co/now): ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example api-routes-graphql api-routes-graphql-app +npm init next-app --example api-routes-graphql api-routes-graphql-app # or yarn create next-app --example api-routes-graphql api-routes-graphql-app ``` @@ -42,7 +44,3 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind the example - -Next.js ships with [API routes](https://github.com/zeit/next.js#api-routes), which provide an easy solution to build your own `API`. This example shows their usage alongside [apollo-server-micro](https://github.com/apollographql/apollo-server/tree/master/packages/apollo-server-micro) to provide simple GraphQL server consumed by Next.js app. diff --git a/examples/api-routes-micro/README.md b/examples/api-routes-micro/README.md index 61f80c35d19a..7fb0d0b449cd 100644 --- a/examples/api-routes-micro/README.md +++ b/examples/api-routes-micro/README.md @@ -1,5 +1,7 @@ # API routes with Micro example +Next.js ships with [API routes](https://github.com/zeit/next.js#api-routes), which provide an easy solution to build your own `API`. This example shows their usage alongside [Micro](https://github.com/zeit/micro), an `http` server for microservices + ## Deploy your own Deploy the example using [ZEIT Now](https://zeit.co/now): @@ -10,10 +12,10 @@ Deploy the example using [ZEIT Now](https://zeit.co/now): ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example api-routes-micro api-routes-micro-app +npm init next-app --example api-routes-micro api-routes-micro-app # or yarn create next-app --example api-routes-micro api-routes-micro-app ``` @@ -42,7 +44,3 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind the example - -Next.js ships with [API routes](https://github.com/zeit/next.js#api-routes), which provide an easy solution to build your own `API`. This example shows their usage alongside [Micro](https://github.com/zeit/micro), an `http` server for microservices diff --git a/examples/api-routes-middleware/README.md b/examples/api-routes-middleware/README.md index 83ac10eeb72d..c11e0ff5f3a8 100644 --- a/examples/api-routes-middleware/README.md +++ b/examples/api-routes-middleware/README.md @@ -1,5 +1,7 @@ # API routes with middleware +Next.js ships with [API routes](https://github.com/zeit/next.js#api-routes), which provide an easy solution to build your own `API`. This example shows how to implement simple `middleware` to wrap around your `API` endpoints. + ## Deploy your own Deploy the example using [ZEIT Now](https://zeit.co/now): @@ -10,10 +12,10 @@ Deploy the example using [ZEIT Now](https://zeit.co/now): ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example api-routes-middleware api-routes-middleware-app +npm init next-app --example api-routes-middleware api-routes-middleware-app # or yarn create next-app --example api-routes-middleware api-routes-middleware-app ``` @@ -42,7 +44,3 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind the example - -Next.js ships with [API routes](https://github.com/zeit/next.js#api-routes), which provide an easy solution to build your own `API`. This example shows how to implement simple `middleware` to wrap around your `API` endpoints. diff --git a/examples/api-routes-rest/README.md b/examples/api-routes-rest/README.md index f1422c294e90..61902da4db29 100644 --- a/examples/api-routes-rest/README.md +++ b/examples/api-routes-rest/README.md @@ -1,5 +1,7 @@ # API routes with REST +Next.js ships with [API routes](https://github.com/zeit/next.js#api-routes), which provide an easy solution to build your own `API`. This example shows how it can be used to create your [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) api. + ## Deploy your own Deploy the example using [ZEIT Now](https://zeit.co/now): @@ -10,10 +12,10 @@ Deploy the example using [ZEIT Now](https://zeit.co/now): ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example api-routes-rest api-routes-rest-app +npm init next-app --example api-routes-rest api-routes-rest-app # or yarn create next-app --example api-routes-rest api-routes-rest-app ``` @@ -25,7 +27,3 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind the example - -Next.js ships with [API routes](https://github.com/zeit/next.js#api-routes), which provide an easy solution to build your own `API`. This example shows how it can be used to create your [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) api. diff --git a/examples/api-routes/README.md b/examples/api-routes/README.md index f7885a7c7116..8a67988109a7 100644 --- a/examples/api-routes/README.md +++ b/examples/api-routes/README.md @@ -1,5 +1,7 @@ # Basic API routes example +Next.js ships with [API routes](https://github.com/zeit/next.js#api-routes) which provides an easy solution to build your own `API`. This example shows how to create multiple `API` endpoints with serverless functions, which can execute independently. + ## Deploy your own Deploy the example using [ZEIT Now](https://zeit.co/now): @@ -10,10 +12,10 @@ Deploy the example using [ZEIT Now](https://zeit.co/now): ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example api-routes api-routes-app +npm init next-app --example api-routes api-routes-app # or yarn create next-app --example api-routes api-routes-app ``` @@ -42,7 +44,3 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind the example - -Next.js ships with [API routes](https://github.com/zeit/next.js#api-routes) which provides an easy solution to build your own `API`. This example shows how to create multiple `API` endpoints with serverless functions, which can execute independently. diff --git a/examples/auth0/README.md b/examples/auth0/README.md index f120b72e91a6..ef4dfe8be1c3 100644 --- a/examples/auth0/README.md +++ b/examples/auth0/README.md @@ -6,10 +6,10 @@ Read more: [https://auth0.com/blog/ultimate-guide-nextjs-authentication-auth0/]( ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example auth0 auth0 +npm init next-app --example auth0 auth0 # or yarn create next-app --example auth0 auth0 ``` diff --git a/examples/basic-css/README.md b/examples/basic-css/README.md index 483c37fc8956..dcf18ca4e64d 100644 --- a/examples/basic-css/README.md +++ b/examples/basic-css/README.md @@ -1,5 +1,7 @@ # Basic CSS example +Next.js ships with [styled-jsx](https://github.com/zeit/styled-jsx) allowing you to write scope styled components with full css support. This is important for the modularity and code size of your bundles and also for the learning curve of the framework. If you know css you can write styled-jsx right away. + ## Deploy your own Deploy the example using [ZEIT Now](https://zeit.co/now): @@ -10,10 +12,10 @@ Deploy the example using [ZEIT Now](https://zeit.co/now): ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example basic-css basic-css-app +npm init next-app --example basic-css basic-css-app # or yarn create next-app --example basic-css basic-css-app ``` @@ -42,9 +44,3 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind the example - -Next.js ships with [styled-jsx](https://github.com/zeit/styled-jsx) allowing you -to write scope styled components with full css support. This is important for -the modularity and code size of your bundles and also for the learning curve of the framework. If you know css you can write styled-jsx right away. diff --git a/examples/basic-export/README.md b/examples/basic-export/README.md index 747032cafc6c..7ed82b4597b3 100644 --- a/examples/basic-export/README.md +++ b/examples/basic-export/README.md @@ -1,5 +1,7 @@ # Basic export example +This example shows the most basic usage of `next export`. Without `exportPathMap`. + ## Deploy your own Deploy the example using [ZEIT Now](https://zeit.co/now): @@ -10,10 +12,10 @@ Deploy the example using [ZEIT Now](https://zeit.co/now): ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example basic-export basic-export-app +npm init next-app --example basic-export basic-export-app # or yarn create next-app --example basic-export basic-export-app ``` @@ -42,7 +44,3 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind the example - -This example shows the most basic usage of `next export`. Without `exportPathMap`. diff --git a/examples/blog-starter/README.md b/examples/blog-starter/README.md index 16de925cd7e1..5de0a8b380ae 100644 --- a/examples/blog-starter/README.md +++ b/examples/blog-starter/README.md @@ -1,5 +1,11 @@ # Blog starter example +This is an example of a blog built with Next.js. [Read more about the motivation and how it is built](https://jolvera.dev/posts/rebuilding-my-blog-with-nextjs). + +The blog is still barebones and need more improvements and styling, but this should be enough to get you started. + +[Demo deployed in Now](https://nextjs-blog-starter.now.sh/) + ## Deploy your own Deploy the example using [ZEIT Now](https://zeit.co/now): @@ -10,11 +16,12 @@ Deploy the example using [ZEIT Now](https://zeit.co/now): ### Using `create-next-app` -Download [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: -``` -npm i -g create-next-app -create-next-app --example blog-starter +```bash +npm init next-app --example blog-starter blog-starter-app +# or +yarn create next-app --example blog-starter blog-starter-app ``` ### Download manually @@ -42,11 +49,3 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind the example - -This is an example of a blog built with Next.js. [Read more about the motivation and how it is built](https://jolvera.dev/posts/rebuilding-my-blog-with-nextjs). - -The blog is still barebones and need more improvements and styling, but this should be enough to get you started. - -[Demo deployed in Now](https://nextjs-blog-starter.now.sh/) diff --git a/examples/custom-charset/README.md b/examples/custom-charset/README.md index 7e9d3b7667a3..52436a27df0e 100644 --- a/examples/custom-charset/README.md +++ b/examples/custom-charset/README.md @@ -1,13 +1,18 @@ # Custom server example +The HTTP/1.1 specification says - if charset is not set in the http header then the browser defaults use ISO-8859-1. +For languages like Polish, Albanian, Hungarian, Czech, Slovak, Slovene, there will be broken characters encoding from SSR. + +You can overwrite Content-Type in getInitialProps. But if you want to handle it as a server side concern, you can use this as an simple example. + ## How to use ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example custom-charset custom-charset-app +npm init next-app --example custom-charset custom-charset-app # or yarn create next-app --example custom-charset custom-charset-app ``` @@ -36,10 +41,3 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind the example - -The HTTP/1.1 specification says - if charset is not set in the http header then the browser defaults use ISO-8859-1. -For languages like Polish, Albanian, Hungarian, Czech, Slovak, Slovene, there will be broken characters encoding from SSR. - -You can overwrite Content-Type in getInitialProps. But if you want to handle it as a server side concern, you can use this as an simple example. diff --git a/examples/custom-server-actionhero/README.md b/examples/custom-server-actionhero/README.md index 5c2067d9d5b0..a41794570df6 100644 --- a/examples/custom-server-actionhero/README.md +++ b/examples/custom-server-actionhero/README.md @@ -9,10 +9,10 @@ A more detailed example showcasing how to use fetch and web sockets to interact ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example custom-server-actionhero custom-server-actionhero-app +npm init next-app --example custom-server-actionhero custom-server-actionhero-app # or yarn create next-app --example custom-server-actionhero custom-server-actionhero-app ``` diff --git a/examples/custom-server-express/README.md b/examples/custom-server-express/README.md index 0ad50f6e2ac1..090bff8f1b2a 100644 --- a/examples/custom-server-express/README.md +++ b/examples/custom-server-express/README.md @@ -1,13 +1,19 @@ # Custom Express Server example +Most of the times the default Next server will be enough but sometimes you want to run your own server to customize routes or other kind of the app behavior. Next provides a [Custom server and routing](https://github.com/zeit/next.js#custom-server-and-routing) so you can customize as much as you want. + +Because the Next.js server is just a node.js module you can combine it with any other part of the node.js ecosystem. in this case we are using express to build a custom router on top of Next. + +The example shows a server that serves the component living in `pages/a.js` when the route `/b` is requested and `pages/b.js` when the route `/a` is accessed. This is obviously a non-standard routing strategy. You can see how this custom routing is being made inside `server.js`. + ## How to use ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example custom-server-express custom-server-express-app +npm init next-app --example custom-server-express custom-server-express-app # or yarn create next-app --example custom-server-express custom-server-express-app ``` @@ -36,11 +42,3 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind the example - -Most of the times the default Next server will be enough but sometimes you want to run your own server to customize routes or other kind of the app behavior. Next provides a [Custom server and routing](https://github.com/zeit/next.js#custom-server-and-routing) so you can customize as much as you want. - -Because the Next.js server is just a node.js module you can combine it with any other part of the node.js ecosystem. in this case we are using express to build a custom router on top of Next. - -The example shows a server that serves the component living in `pages/a.js` when the route `/b` is requested and `pages/b.js` when the route `/a` is accessed. This is obviously a non-standard routing strategy. You can see how this custom routing is being made inside `server.js`. diff --git a/examples/custom-server-fastify/README.md b/examples/custom-server-fastify/README.md index e6807325b602..a59590ba63e5 100644 --- a/examples/custom-server-fastify/README.md +++ b/examples/custom-server-fastify/README.md @@ -1,13 +1,19 @@ # Custom Fastify Server example +Most of the times the default Next server will be enough but sometimes you want to run your own server to customize routes or other kind of the app behavior. Next provides a [Custom server and routing](https://github.com/zeit/next.js#custom-server-and-routing) so you can customize as much as you want. + +Because the Next.js server is just a node.js module you can combine it with any other part of the node.js ecosystem. in this case we are using [Fastify](https://github.com/fastify/fastify) to build a custom router on top of Next. + +The example shows a server that serves the component living in `pages/a.js` when the route `/b` is requested and `pages/b.js` when the route `/a` is accessed. This is obviously a non-standard routing strategy. You can see how this custom routing is being made inside `server.js`. + ## How to use ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example custom-server-fastify custom-server-fastify-app +npm init next-app --example custom-server-fastify custom-server-fastify-app # or yarn create next-app --example custom-server-fastify custom-server-fastify-app ``` @@ -37,11 +43,3 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind the example - -Most of the times the default Next server will be enough but sometimes you want to run your own server to customize routes or other kind of the app behavior. Next provides a [Custom server and routing](https://github.com/zeit/next.js#custom-server-and-routing) so you can customize as much as you want. - -Because the Next.js server is just a node.js module you can combine it with any other part of the node.js ecosystem. in this case we are using [Fastify](https://github.com/fastify/fastify) to build a custom router on top of Next. - -The example shows a server that serves the component living in `pages/a.js` when the route `/b` is requested and `pages/b.js` when the route `/a` is accessed. This is obviously a non-standard routing strategy. You can see how this custom routing is being made inside `server.js`. diff --git a/examples/custom-server-hapi/README.md b/examples/custom-server-hapi/README.md index 4f049db126ab..5f69a48c9ce1 100644 --- a/examples/custom-server-hapi/README.md +++ b/examples/custom-server-hapi/README.md @@ -1,13 +1,19 @@ # Custom server using Hapi example +Most of the times the default Next server will be enough but sometimes you want to run your own server to customize routes or other kind of the app behavior. Next provides a [Custom server and routing](https://github.com/zeit/next.js#custom-server-and-routing) so you can customize as much as you want. + +Because the Next.js server is just a node.js module you can combine it with any other part of the node.js ecosystem. in this case we are using [Hapi](https://hapijs.com) to build a custom router on top of Next. + +The example shows a server that serves the component living in `pages/a.js` when the route `/b` is requested and `pages/b.js` when the route `/a` is accessed. This is obviously a non-standard routing strategy. You can see how this custom routing is being made inside `server.js`. + ## How to use ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example custom-server-hapi custom-server-hapi-app +npm init next-app --example custom-server-hapi custom-server-hapi-app # or yarn create next-app --example custom-server-hapi custom-server-hapi-app ``` @@ -36,11 +42,3 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind the example - -Most of the times the default Next server will be enough but sometimes you want to run your own server to customize routes or other kind of the app behavior. Next provides a [Custom server and routing](https://github.com/zeit/next.js#custom-server-and-routing) so you can customize as much as you want. - -Because the Next.js server is just a node.js module you can combine it with any other part of the node.js ecosystem. in this case we are using [Hapi](https://hapijs.com) to build a custom router on top of Next. - -The example shows a server that serves the component living in `pages/a.js` when the route `/b` is requested and `pages/b.js` when the route `/a` is accessed. This is obviously a non-standard routing strategy. You can see how this custom routing is being made inside `server.js`. diff --git a/examples/custom-server-koa/README.md b/examples/custom-server-koa/README.md index 13a693d3869e..7bb2f74ff6e8 100644 --- a/examples/custom-server-koa/README.md +++ b/examples/custom-server-koa/README.md @@ -1,13 +1,19 @@ # Custom Koa Server example +Most of the times the default Next server will be enough but sometimes you want to run your own server to customize routes or other kind of the app behavior. Next provides a [Custom server and routing](https://github.com/zeit/next.js#custom-server-and-routing) so you can customize as much as you want. + +Because the Next.js server is just a node.js module you can combine it with any other part of the node.js ecosystem. in this case we are using [Koa](http://koajs.com/) to build a custom router on top of Next. + +The example shows a server that serves the component living in `pages/a.js` when the route `/b` is requested and `pages/b.js` when the route `/a` is accessed. This is obviously a non-standard routing strategy. You can see how this custom routing is being made inside `server.js`. + ## How to use ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example custom-server-koa custom-server-koa-app +npm init next-app --example custom-server-koa custom-server-koa-app # or yarn create next-app --example custom-server-koa custom-server-koa-app ``` @@ -37,14 +43,6 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. now ``` -## The idea behind the example - -Most of the times the default Next server will be enough but sometimes you want to run your own server to customize routes or other kind of the app behavior. Next provides a [Custom server and routing](https://github.com/zeit/next.js#custom-server-and-routing) so you can customize as much as you want. - -Because the Next.js server is just a node.js module you can combine it with any other part of the node.js ecosystem. in this case we are using [Koa](http://koajs.com/) to build a custom router on top of Next. - -The example shows a server that serves the component living in `pages/a.js` when the route `/b` is requested and `pages/b.js` when the route `/a` is accessed. This is obviously a non-standard routing strategy. You can see how this custom routing is being made inside `server.js`. - ## Side note: Enabling gzip compression The most common Koa middleware for handling the gzip compression is [compress](https://github.com/koajs/compress), but unfortunately it is currently not compatible with Next.
diff --git a/examples/custom-server-micro/README.md b/examples/custom-server-micro/README.md index 8d65ad9b4f2c..544a2bfb6465 100644 --- a/examples/custom-server-micro/README.md +++ b/examples/custom-server-micro/README.md @@ -1,13 +1,19 @@ # Custom Micro Server example +Most of the times the default Next server will be enough but sometimes you want to run your own server to customize routes or other kind of the app behavior. Next provides a [Custom server and routing](https://github.com/zeit/next.js#custom-server-and-routing) so you can customize as much as you want. + +Because the Next.js server is just a node.js module you can combine it with any other part of the node.js ecosystem. in this case we are using micro and micro-route to build a custom router on top of Next. + +The example shows a server that serves the component living in `pages/a.js` when the route `/b` is requested and `pages/b.js` when the route `/a` is accessed. This is obviously a non-standard routing strategy. You can see how this custom routing is being made inside `server.js`. + ## How to use ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example custom-server-micro custom-server-micro-app +npm init next-app --example custom-server-micro custom-server-micro-app # or yarn create next-app --example custom-server-micro custom-server-micro-app ``` @@ -36,11 +42,3 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind the example - -Most of the times the default Next server will be enough but sometimes you want to run your own server to customize routes or other kind of the app behavior. Next provides a [Custom server and routing](https://github.com/zeit/next.js#custom-server-and-routing) so you can customize as much as you want. - -Because the Next.js server is just a node.js module you can combine it with any other part of the node.js ecosystem. in this case we are using micro and micro-route to build a custom router on top of Next. - -The example shows a server that serves the component living in `pages/a.js` when the route `/b` is requested and `pages/b.js` when the route `/a` is accessed. This is obviously a non-standard routing strategy. You can see how this custom routing is being made inside `server.js`. diff --git a/examples/custom-server-nodemon/README.md b/examples/custom-server-nodemon/README.md index d77a5d5e21a9..8c509a358123 100644 --- a/examples/custom-server-nodemon/README.md +++ b/examples/custom-server-nodemon/README.md @@ -1,13 +1,15 @@ # Custom server with Nodemon example +The example shows how you can apply [Nodemon](https://nodemon.io/) to a custom server to have live reload of the server code without being affected by the Next.js universal code. + ## How to use ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example custom-server-nodemon custom-server-nodemon-app +npm init next-app --example custom-server-nodemon custom-server-nodemon-app # or yarn create next-app --example custom-server-nodemon custom-server-nodemon-app ``` @@ -36,7 +38,3 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind the example - -The example shows how you can apply [Nodemon](https://nodemon.io/) to a custom server to have live reload of the server code without being affected by the Next.js universal code. diff --git a/examples/custom-server-polka/README.md b/examples/custom-server-polka/README.md index 41a4c71dfaf8..49bb96cf7581 100644 --- a/examples/custom-server-polka/README.md +++ b/examples/custom-server-polka/README.md @@ -1,13 +1,19 @@ # Custom [Polka](https://github.com/lukeed/polka) Server example +Most of the times the default Next server will be enough but sometimes you want to run your own server to customize routes or other kind of the app behavior. Next provides a [Custom server and routing](https://github.com/zeit/next.js#custom-server-and-routing) so you can customize as much as you want. + +Because the Next.js server is just a node.js module you can combine it with any other part of the node.js ecosystem. in this case we are using express to build a custom router on top of Next. + +The example shows a server that serves the component living in `pages/a.js` when the route `/b` is requested and `pages/b.js` when the route `/a` is accessed. This is obviously a non-standard routing strategy. You can see how this custom routing is being made inside `server.js`. + ## How to use ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example custom-server-polka custom-server-polka-app +npm init next-app --example custom-server-polka custom-server-polka-app # or yarn create next-app --example custom-server-polka custom-server-polka-app ``` @@ -36,11 +42,3 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind the example - -Most of the times the default Next server will be enough but sometimes you want to run your own server to customize routes or other kind of the app behavior. Next provides a [Custom server and routing](https://github.com/zeit/next.js#custom-server-and-routing) so you can customize as much as you want. - -Because the Next.js server is just a node.js module you can combine it with any other part of the node.js ecosystem. in this case we are using express to build a custom router on top of Next. - -The example shows a server that serves the component living in `pages/a.js` when the route `/b` is requested and `pages/b.js` when the route `/a` is accessed. This is obviously a non-standard routing strategy. You can see how this custom routing is being made inside `server.js`. diff --git a/examples/custom-server-reasonml/README.md b/examples/custom-server-reasonml/README.md index ab2544164e9e..333011f9847c 100644 --- a/examples/custom-server-reasonml/README.md +++ b/examples/custom-server-reasonml/README.md @@ -1,13 +1,19 @@ # Custom server ReasonML example +ReasonML is an exciting new language. Since it can compile directly to JS via [BuckleScript](https://bucklescript.github.io/en/), +we can power our backend server with ReasonML and also build the frontend with +[ReasonReact](https://reasonml.github.io/reason-react/en/) (covered in the [with-reasonml example](https://github.com/zeit/next.js/tree/canary/examples/with-reasonml)). + +This example shows how powerful and helpful it is to build a Next.js custom server with a typesafe language. It is based off the [custom-server example](https://github.com/zeit/next.js/tree/canary/examples/custom-server) that uses pure Node.js to build the custom server. + ## How to use ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example custom-server-reasonml custom-server-reasonml-app +npm init next-app --example custom-server-reasonml custom-server-reasonml-app # or yarn create next-app --example custom-server-reasonml custom-server-reasonml-app ``` @@ -58,11 +64,3 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind this example - -ReasonML is an exciting new language. Since it can compile directly to JS via [BuckleScript](https://bucklescript.github.io/en/), -we can power our backend server with ReasonML and also build the frontend with -[ReasonReact](https://reasonml.github.io/reason-react/en/) (covered in the [with-reasonml example](https://github.com/zeit/next.js/tree/canary/examples/with-reasonml)). - -This example shows how powerful and helpful it is to build a Next.js custom server with a typesafe language. It is based off the [custom-server example](https://github.com/zeit/next.js/tree/canary/examples/custom-server) that uses pure Node.js to build the custom server. diff --git a/examples/custom-server-typescript/README.md b/examples/custom-server-typescript/README.md index 6f10728bb270..b77a6c48d8c5 100644 --- a/examples/custom-server-typescript/README.md +++ b/examples/custom-server-typescript/README.md @@ -1,13 +1,18 @@ # Custom server with TypeScript + Nodemon example +The example shows how you can use [TypeScript](https://typescriptlang.com) on both the server and the client while using [Nodemon](https://nodemon.io/) to live reload the server code without affecting the Next.js universal code. + +Server entry point is `server/index.ts` in development and `dist/index.js` in production. +The second directory should be added to `.gitignore`. + ## How to use ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example custom-server-typescript custom-server-typescript-app +npm init next-app --example custom-server-typescript custom-server-typescript-app # or yarn create next-app --example custom-server-typescript custom-server-typescript-app ``` @@ -36,10 +41,3 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind the example - -The example shows how you can use [TypeScript](https://typescriptlang.com) on both the server and the client while using [Nodemon](https://nodemon.io/) to live reload the server code without affecting the Next.js universal code. - -Server entry point is `server/index.ts` in development and `dist/index.js` in production. -The second directory should be added to `.gitignore`. diff --git a/examples/custom-server/README.md b/examples/custom-server/README.md index 29452a0d8be0..8c9e8bf7c9f5 100644 --- a/examples/custom-server/README.md +++ b/examples/custom-server/README.md @@ -1,13 +1,17 @@ # Custom server example +Most of the times the default Next server will be enough but sometimes you want to run your own server to customize routes or other kind of the app behavior. Next provides a [Custom server and routing](https://github.com/zeit/next.js#custom-server-and-routing) so you can customize as much as you want. + +The example shows a server that serves the component living in `pages/a.js` when the route `/b` is requested and `pages/b.js` when the route `/a` is accessed. This is obviously a non-standard routing strategy. You can see how this custom routing is being made inside `server.js`. + ## How to use ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example custom-server custom-server-app +npm init next-app --example custom-server custom-server-app # or yarn create next-app --example custom-server custom-server-app ``` @@ -36,9 +40,3 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind the example - -Most of the times the default Next server will be enough but sometimes you want to run your own server to customize routes or other kind of the app behavior. Next provides a [Custom server and routing](https://github.com/zeit/next.js#custom-server-and-routing) so you can customize as much as you want. - -The example shows a server that serves the component living in `pages/a.js` when the route `/b` is requested and `pages/b.js` when the route `/a` is accessed. This is obviously a non-standard routing strategy. You can see how this custom routing is being made inside `server.js`. diff --git a/examples/data-fetch/README.md b/examples/data-fetch/README.md index 3ee3ac9782c0..ec0a093d03bb 100644 --- a/examples/data-fetch/README.md +++ b/examples/data-fetch/README.md @@ -1,5 +1,10 @@ # Data fetch example +Next.js was conceived to make it easy to create universal apps. That's why fetching data +on the server and the client when necessary is so easy with Next. + +Using `getInitialProps` fetches data on the server for SSR and then on the client when the component is re-mounted (not on the first paint). + ## Deploy your own Deploy the example using [ZEIT Now](https://zeit.co/now): @@ -10,10 +15,10 @@ Deploy the example using [ZEIT Now](https://zeit.co/now): ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example data-fetch data-fetch-app +npm init next-app --example data-fetch data-fetch-app # or yarn create next-app --example data-fetch data-fetch-app ``` @@ -42,10 +47,3 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind the example - -Next.js was conceived to make it easy to create universal apps. That's why fetching data -on the server and the client when necessary is so easy with Next. - -Using `getInitialProps` fetches data on the server for SSR and then on the client when the component is re-mounted (not on the first paint). diff --git a/examples/dynamic-routing/README.md b/examples/dynamic-routing/README.md index 1103444fc183..9d791190e900 100644 --- a/examples/dynamic-routing/README.md +++ b/examples/dynamic-routing/README.md @@ -1,5 +1,17 @@ # Dynamic Routing example +This example shows usage of dynamic routing. + +This example contains two dynamic pages: + +1. `pages/post/[id]/index.js` + - e.g. matches `/post/my-example` (`/post/:id`) +1. `pages/post/[id]/[comment].js` + - e.g. matches `/post/my-example/a-comment` (`/post/:id/:comment`) + +These routes are automatically matched by the server. +You can use `next/link` as displayed in this example to route to these pages client side. + ## Deploy your own Deploy the example using [ZEIT Now](https://zeit.co/now): @@ -10,10 +22,10 @@ Deploy the example using [ZEIT Now](https://zeit.co/now): ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example dynamic-routing dynamic-routing-app +npm init next-app --example dynamic-routing dynamic-routing-app # or yarn create next-app --example dynamic-routing dynamic-routing-app ``` @@ -42,17 +54,3 @@ Deploy it to the cloud with [Now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind the example - -This example shows usage of dynamic routing. - -This example contains two dynamic pages: - -1. `pages/post/[id]/index.js` - - e.g. matches `/post/my-example` (`/post/:id`) -1. `pages/post/[id]/[comment].js` - - e.g. matches `/post/my-example/a-comment` (`/post/:id/:comment`) - -These routes are automatically matched by the server. -You can use `next/link` as displayed in this example to route to these pages client side. diff --git a/examples/form-handler/README.md b/examples/form-handler/README.md index 0c37d04eae14..b75b9c10c982 100644 --- a/examples/form-handler/README.md +++ b/examples/form-handler/README.md @@ -1,13 +1,15 @@ # Form Handler +Sometimes handle multiple forms can be tricky, the idea is to have a global reducer with the name of each form and the inputs of it; making accessible everywhere. + ## How to use ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example form-handler form-handler-app +npm init next-app --example form-handler form-handler-app # or yarn create next-app --example form-handler form-handler-app ``` @@ -36,8 +38,3 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind the example - -Sometimes handle multiple forms can be tricky, the idea is to have a global reducer -with the name of each form and the inputs of it; making accessible everywhere. diff --git a/examples/gh-pages/README.md b/examples/gh-pages/README.md index cec9e33ba363..4f4893e09ed3 100644 --- a/examples/gh-pages/README.md +++ b/examples/gh-pages/README.md @@ -1,13 +1,15 @@ # gh-pages Hello World example +This example shows the most basic idea behind Next. We have 2 pages: `pages/index.js` and `pages/about.js`. The former responds to `/` requests and the latter to `/about`. Using `next/link` you can add hyperlinks between them with universal routing capabilities. + ## How to use ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example gh-pages gh-pages-app +npm init next-app --example gh-pages gh-pages-app # or yarn create next-app --example gh-pages gh-pages-app ``` @@ -60,7 +62,3 @@ https://github.com/thierryc/Next-gh-page-example/ https://thierryc.github.io/Next-gh-page-example/ ``` - -## The idea behind the example - -This example shows the most basic idea behind Next. We have 2 pages: `pages/index.js` and `pages/about.js`. The former responds to `/` requests and the latter to `/about`. Using `next/link` you can add hyperlinks between them with universal routing capabilities. diff --git a/examples/head-elements/README.md b/examples/head-elements/README.md index c1145f1e274d..72f04f159545 100644 --- a/examples/head-elements/README.md +++ b/examples/head-elements/README.md @@ -1,5 +1,9 @@ # Head elements example +For every page you can inject elements into the page head. This way you can add stylesheets, JS scripts, meta tags, a custom title or whatever you think is convenient to add inside the `` of your page. + +This example shows in `pages/index.js` how to add a title and a couple of meta tags. + ## Deploy your own Deploy the example using [ZEIT Now](https://zeit.co/now): @@ -10,10 +14,10 @@ Deploy the example using [ZEIT Now](https://zeit.co/now): ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example head-elements head-elements-app +npm init next-app --example head-elements head-elements-app # or yarn create next-app --example head-elements head-elements-app ``` @@ -42,9 +46,3 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind the example - -For every page you can inject elements into the page head. This way you can add stylesheets, JS scripts, meta tags, a custom title or whatever you think is convenient to add inside the `` of your page. - -This example shows in `pages/index.js` how to add a title and a couple of meta tags. diff --git a/examples/hello-world/README.md b/examples/hello-world/README.md index c195fea160d4..f6a38a2b0548 100644 --- a/examples/hello-world/README.md +++ b/examples/hello-world/README.md @@ -1,5 +1,7 @@ # Hello World example +This example shows the most basic idea behind Next. We have 2 pages: `pages/index.js` and `pages/about.js`. The former responds to `/` requests and the latter to `/about`. Using `next/link` you can add hyperlinks between them with universal routing capabilities. The `day` directory shows that you can have subdirectories. + ## Deploy your own Deploy the example using [ZEIT Now](https://zeit.co/now): @@ -10,10 +12,10 @@ Deploy the example using [ZEIT Now](https://zeit.co/now): ### Using `create-next-app` -Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) or [npx](https://github.com/zkat/npx#readme) to bootstrap the example: +Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example: ```bash -npx create-next-app --example hello-world hello-world-app +npm init next-app --example hello-world hello-world-app # or yarn create next-app --example hello-world hello-world-app ``` @@ -42,7 +44,3 @@ Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit. ```bash now ``` - -## The idea behind the example - -This example shows the most basic idea behind Next. We have 2 pages: `pages/index.js` and `pages/about.js`. The former responds to `/` requests and the latter to `/about`. Using `next/link` you can add hyperlinks between them with universal routing capabilities. The `day` directory shows that you can have subdirectories. diff --git a/examples/layout-component/README.md b/examples/layout-component/README.md index 6ae480355365..d4c50f741a7d 100644 --- a/examples/layout-component/README.md +++ b/examples/layout-component/README.md @@ -1,5 +1,7 @@ # Layout component example +This example shows a very common use case when building websites where you need to repeat some sort of layout for all your pages. Our pages are: `home`, `about` and `contact` and they all share the same `` settings, the `