terribleplan/next.js
1
0
Fork 0
mirror of https://github.com/terribleplan/next.js.git synced 2024-01-19 02:48:18 +00:00
Code Issues Releases Wiki Activity

Improve README.md (#5331)

Browse source 
- `<details>` and `<ul>` cannot be inside `<p>` and it will not be parsed correctly by the MDX tokenizer.
- `sh` is not a valid language name for syntax highlighting libs (e.g. [highlight.js](https://github.com/highlightjs/highlight.js/tree/master/src/languages)).
This commit is contained in:
Shu Ding 2018-09-29 09:16:49 -05:00 committed by Tim Neutkens
parent c0945392f4
commit ae805a0bcf
1 changed files with 137 additions and 52 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

189
README.md
View file

@ -142,10 +142,14 @@ export default () => (
#### Built-in CSS support #### Built-in CSS support
<p><details> <details>
<summary><b>Examples</b></summary> <summary><b>Examples</b></summary>
<ul><li><a href="./examples/basic-css">Basic css</a></li></ul> <ul>
</details></p> <li><a href="./examples/basic-css">Basic css</a></li>
</ul>
</details>
<p></p>
We bundle [styled-jsx](https://github.com/zeit/styled-jsx) to provide support for isolated scoped CSS. The aim is to support "shadow CSS" similar to Web Components, which unfortunately [do not support server-rendering and are JS-only](https://github.com/w3c/webcomponents/issues/71). We bundle [styled-jsx](https://github.com/zeit/styled-jsx) to provide support for isolated scoped CSS. The aim is to support "shadow CSS" similar to Web Components, which unfortunately [do not support server-rendering and are JS-only](https://github.com/w3c/webcomponents/issues/71).
@ -180,12 +184,21 @@ Please see the [styled-jsx documentation](https://www.npmjs.com/package/styled-j
#### CSS-in-JS #### CSS-in-JS
<p><details> <details>
<summary> <summary>
<b>Examples</b> <b>Examples</b>
</summary> </summary>
<ul><li><a href="./examples/with-styled-components">Styled components</a></li><li><a href="./examples/with-styletron">Styletron</a></li><li><a href="./examples/with-glamor">Glamor</a></li><li><a href="./examples/with-glamorous">Glamorous</a></li><li><a href="./examples/with-cxs">Cxs</a></li><li><a href="./examples/with-aphrodite">Aphrodite</a></li><li><a href="./examples/with-fela">Fela</a></li></ul> <ul>
</details></p> <li><a href="./examples/with-styled-components">Styled components</a></li>
<li><a href="./examples/with-styletron">Styletron</a></li>
<li><a href="./examples/with-glamor">Glamor</a></li>
<li><a href="./examples/with-glamorous">Glamorous</a></li>
<li><a href="./examples/with-cxs">Cxs</a></li><li><a href="./examples/with-aphrodite">Aphrodite</a></li>
<li><a href="./examples/with-fela">Fela</a></li>
</ul>
</details>
<p></p>
It's possible to use any existing CSS-in-JS solution. The simplest one is inline styles: It's possible to use any existing CSS-in-JS solution. The simplest one is inline styles:
@ -216,13 +229,15 @@ _Note: Don't name the `static` directory anything else. The name is required and
### Populating `<head>` ### Populating `<head>`
<p><details> <details>
<summary><b>Examples</b></summary> <summary><b>Examples</b></summary>
<ul> <ul>
<li><a href="./examples/head-elements">Head elements</a></li> <li><a href="./examples/head-elements">Head elements</a></li>
<li><a href="./examples/layout-component">Layout component</a></li> <li><a href="./examples/layout-component">Layout component</a></li>
</ul> </ul>
</details></p> </details>
<p></p>
We expose a built-in component for appending elements to the `<head>` of the page. We expose a built-in component for appending elements to the `<head>` of the page.
@ -265,10 +280,14 @@ _Note: The contents of `<head>` get cleared upon unmounting the component, so ma
### Fetching data and component lifecycle ### Fetching data and component lifecycle
<p><details> <details>
<summary><b>Examples</b></summary> <summary><b>Examples</b></summary>
<ul><li><a href="./examples/data-fetch">Data fetch</a></li></ul> <ul>
</details></p> <li><a href="./examples/data-fetch">Data fetch</a></li>
</ul>
</details>
<p></p>
When you need state, lifecycle hooks or **initial data population** you can export a `React.Component` (instead of a stateless function, like shown above): When you need state, lifecycle hooks or **initial data population** you can export a `React.Component` (instead of a stateless function, like shown above):
@ -337,12 +356,14 @@ export default Page
#### With `<Link>` #### With `<Link>`
<p><details> <details>
<summary><b>Examples</b></summary> <summary><b>Examples</b></summary>
<ul> <ul>
<li><a href="./examples/hello-world">Hello World</a></li> <li><a href="./examples/hello-world">Hello World</a></li>
</ul> </ul>
</details></p> </details>
<p></p>
Client-side transitions between routes can be enabled via a `<Link>` component. Consider these two pages: Client-side transitions between routes can be enabled via a `<Link>` component. Consider these two pages:
@ -378,12 +399,14 @@ To inject the `pathname`, `query` or `asPath` in your component, you can use [wi
##### With URL object ##### With URL object
<p><details> <details>
<summary><b>Examples</b></summary> <summary><b>Examples</b></summary>
<ul> <ul>
<li><a href="./examples/with-url-object-routing">With URL Object Routing</a></li> <li><a href="./examples/with-url-object-routing">With URL Object Routing</a></li>
</ul> </ul>
</details></p> </details>
<p></p>
The component `<Link>` can also receive an URL object and it will automatically format it to create the URL string. The component `<Link>` can also receive an URL object and it will automatically format it to create the URL string.
@ -471,13 +494,15 @@ The default behaviour of `<Link>` is to scroll to the top of the page. When ther
#### Imperatively #### Imperatively
<p><details> <details>
<summary><b>Examples</b></summary> <summary><b>Examples</b></summary>
<ul> <ul>
<li><a href="./examples/using-router">Basic routing</a></li> <li><a href="./examples/using-router">Basic routing</a></li>
<li><a href="./examples/with-loading">With a page loading indicator</a></li> <li><a href="./examples/with-loading">With a page loading indicator</a></li>
</ul> </ul>
</details></p> </details>
<p></p>
You can also do client-side page transitions using the `next/router` You can also do client-side page transitions using the `next/router`
@ -592,12 +617,14 @@ Router.events.on('routeChangeError', (err, url) => {
##### Shallow Routing ##### Shallow Routing
<p><details> <details>
<summary><b>Examples</b></summary> <summary><b>Examples</b></summary>
<ul> <ul>
<li><a href="./examples/with-shallow-routing">Shallow Routing</a></li> <li><a href="./examples/with-shallow-routing">Shallow Routing</a></li>
</ul> </ul>
</details></p> </details>
<p></p>
Shallow routing allows you to change the URL without running `getInitialProps`. You'll receive the updated `pathname` and the `query` via the `url` prop of the same page that's loaded, without losing state. Shallow routing allows you to change the URL without running `getInitialProps`. You'll receive the updated `pathname` and the `query` via the `url` prop of the same page that's loaded, without losing state.
@ -634,12 +661,14 @@ componentDidUpdate(prevProps) {
#### Using a Higher Order Component #### Using a Higher Order Component
<p><details> <details>
<summary><b>Examples</b></summary> <summary><b>Examples</b></summary>
<ul> <ul>
<li><a href="./examples/using-with-router">Using the `withRouter` utility</a></li> <li><a href="./examples/using-with-router">Using the `withRouter` utility</a></li>
</ul> </ul>
</details></p> </details>
<p></p>
If you want to access the `router` object inside any component in your app, you can use the `withRouter` Higher-Order Component. Here's how to use it: If you want to access the `router` object inside any component in your app, you can use the `withRouter` Higher-Order Component. Here's how to use it:
@ -673,10 +702,14 @@ The above `router` object comes with an API similar to [`next/router`](#imperati
⚠️ This is a production only feature ⚠️ ⚠️ This is a production only feature ⚠️
<p><details> <details>
<summary><b>Examples</b></summary> <summary><b>Examples</b></summary>
<ul><li><a href="./examples/with-prefetching">Prefetching</a></li></ul> <ul>
</details></p> <li><a href="./examples/with-prefetching">Prefetching</a></li>
</ul>
</details>
<p></p>
Next.js has an API which allows you to prefetch pages. Next.js has an API which allows you to prefetch pages.
@ -763,7 +796,7 @@ export default withRouter(MyLink)
### Custom server and routing ### Custom server and routing
<p><details> <details>
<summary><b>Examples</b></summary> <summary><b>Examples</b></summary>
<ul> <ul>
<li><a href="./examples/custom-server">Basic custom server</a></li> <li><a href="./examples/custom-server">Basic custom server</a></li>
@ -773,7 +806,9 @@ export default withRouter(MyLink)
<li><a href="./examples/parameterized-routing">Parameterized routing</a></li> <li><a href="./examples/parameterized-routing">Parameterized routing</a></li>
<li><a href="./examples/ssr-caching">SSR caching</a></li> <li><a href="./examples/ssr-caching">SSR caching</a></li>
</ul> </ul>
</details></p> </details>
<p></p>
Typically you start your next server with `next start`. It's possible, however, to start a server 100% programmatically in order to customize routes, use route patterns, etc. Typically you start your next server with `next start`. It's possible, however, to start a server 100% programmatically in order to customize routes, use route patterns, etc.
@ -896,12 +931,14 @@ app.prepare().then(() => {
### Dynamic Import ### Dynamic Import
<p><details> <details>
<summary><b>Examples</b></summary> <summary><b>Examples</b></summary>
<ul> <ul>
<li><a href="./examples/with-dynamic-import">With Dynamic Import</a></li> <li><a href="./examples/with-dynamic-import">With Dynamic Import</a></li>
</ul> </ul>
</details></p> </details>
<p></p>
Next.js supports TC39 [dynamic import proposal](https://github.com/tc39/proposal-dynamic-import) for JavaScript. Next.js supports TC39 [dynamic import proposal](https://github.com/tc39/proposal-dynamic-import) for JavaScript.
With that, you could import JavaScript modules (inc. React Components) dynamically and work with them. With that, you could import JavaScript modules (inc. React Components) dynamically and work with them.
@ -992,11 +1029,15 @@ export default () => <HelloBundle title="Dynamic Bundle" />
### Custom `<App>` ### Custom `<App>`
<p><details> <details>
<summary><b>Examples</b></summary> <summary><b>Examples</b></summary>
<ul><li><a href="./examples/with-app-layout">Using `_app.js` for layout</a></li></ul> <ul>
<ul><li><a href="./examples/with-componentdidcatch">Using `_app.js` to override `componentDidCatch`</a></li></ul> <li><a href="./examples/with-app-layout">Using `_app.js` for layout</a></li>
</details></p> <li><a href="./examples/with-componentdidcatch">Using `_app.js` to override `componentDidCatch`</a></li>
</ul>
</details>
<p></p>
Next.js uses the `App` component to initialize pages. You can override it and control the page initialization. Which allows you to do amazing things like: Next.js uses the `App` component to initialize pages. You can override it and control the page initialization. Which allows you to do amazing things like:
@ -1036,11 +1077,15 @@ export default class MyApp extends App {
### Custom `<Document>` ### Custom `<Document>`
<p><details> <details>
<summary><b>Examples</b></summary> <summary><b>Examples</b></summary>
<ul><li><a href="./examples/with-styled-components">Styled components custom document</a></li></ul> <ul>
<ul><li><a href="./examples/with-amp">Google AMP</a></li></ul> <li><a href="./examples/with-styled-components">Styled components custom document</a></li>
</details></p> <li><a href="./examples/with-amp">Google AMP</a></li>
</ul>
</details>
<p></p>
- Is rendered on the server side - Is rendered on the server side
- Is used to change the initial server side rendered document markup - Is used to change the initial server side rendered document markup
@ -1251,10 +1296,14 @@ module.exports = {
### Customizing webpack config ### Customizing webpack config
<p><details> <details>
<summary><b>Examples</b></summary> <summary><b>Examples</b></summary>
<ul><li><a href="./examples/with-webpack-bundle-analyzer">Custom webpack bundle analyzer</a></li></ul> <ul>
</details></p> <li><a href="./examples/with-webpack-bundle-analyzer">Custom webpack bundle analyzer</a></li>
</ul>
</details>
<p></p>
Some commonly asked for features are available as modules: Some commonly asked for features are available as modules:
@ -1334,10 +1383,14 @@ module.exports = {
### Customizing babel config ### Customizing babel config
<p><details> <details>
<summary><b>Examples</b></summary> <summary><b>Examples</b></summary>
<ul><li><a href="./examples/with-custom-babel-config">Custom babel configuration</a></li></ul> <ul>
</details></p> <li><a href="./examples/with-custom-babel-config">Custom babel configuration</a></li>
</ul>
</details>
<p></p>
In order to extend our usage of `babel`, you can simply define a `.babelrc` file at the root of your app. This file is optional. In order to extend our usage of `babel`, you can simply define a `.babelrc` file at the root of your app. This file is optional.
@ -1471,10 +1524,14 @@ The [polyfills](https://github.com/zeit/next.js/tree/canary/examples/with-polyfi
## Static HTML export ## Static HTML export
<p><details> <details>
<summary><b>Examples</b></summary> <summary><b>Examples</b></summary>
<ul><li><a href="./examples/with-static-export">Static export</a></li></ul> <ul>
</details></p> <li><a href="./examples/with-static-export">Static export</a></li>
</ul>
</details>
<p></p>
`next export` is a way to run your Next.js app as a standalone static app without the need for a Node.js server. `next export` is a way to run your Next.js app as a standalone static app without the need for a Node.js server.
The exported app supports almost every feature of Next.js, including dynamic urls, prefetching, preloading and dynamic imports. The exported app supports almost every feature of Next.js, including dynamic urls, prefetching, preloading and dynamic imports.
@ -1521,7 +1578,7 @@ module.exports = {
Then simply run these commands: Then simply run these commands:
```sh ```bash
next build next build
next export next export
``` ```
@ -1539,7 +1596,7 @@ For that you may need to add a NPM script to `package.json` like this:
And run it at once with: And run it at once with:
```sh ```bash
npm run export npm run export
``` ```
@ -1551,7 +1608,7 @@ Now you can deploy the `out` directory to any static hosting service. Note that
For an example, simply visit the `out` directory and run following command to deploy your app to [ZEIT Now](https://zeit.co/now). For an example, simply visit the `out` directory and run following command to deploy your app to [ZEIT Now](https://zeit.co/now).
```sh ```bash
now now
``` ```
@ -1595,10 +1652,14 @@ The `req` and `res` fields of the `context` object passed to `getInitialProps` a
## Multi Zones ## Multi Zones
<p><details> <details>
<summary><b>Examples</b></summary> <summary><b>Examples</b></summary>
<ul><li><a href="./examples/with-zones">With Zones</a></li></ul> <ul>
</details></p> <li><a href="./examples/with-zones">With Zones</a></li>
</ul>
</details>
<p></p>
A zone is a single deployment of a Next.js app. Just like that, you can have multiple zones. Then you can merge them as a single app. A zone is a single deployment of a Next.js app. Just like that, you can have multiple zones. Then you can merge them as a single app.
@ -1651,6 +1712,8 @@ For the production deployment, you can use the [path alias](https://zeit.co/docs
We’re ecstatic about both the developer experience and end-user performance, so we decided to share it with the community. We’re ecstatic about both the developer experience and end-user performance, so we decided to share it with the community.
</details> </details>
<p></p>
<details> <details>
<summary>How big is it?</summary> <summary>How big is it?</summary>
@ -1659,6 +1722,8 @@ A small Next main bundle is around 65kb gzipped.
</details> </details>
<p></p>
<details> <details>
<summary>Is this like `create-react-app`?</summary> <summary>Is this like `create-react-app`?</summary>
@ -1678,12 +1743,16 @@ If you want to create re-usable React components that you can embed in your Next
</details> </details>
<p></p>
<details> <details>
<summary>How do I use CSS-in-JS solutions?</summary> <summary>How do I use CSS-in-JS solutions?</summary>
Next.js bundles [styled-jsx](https://github.com/zeit/styled-jsx) supporting scoped css. However you can use any CSS-in-JS solution in your Next app by just including your favorite library [as mentioned before](#css-in-js) in the document. Next.js bundles [styled-jsx](https://github.com/zeit/styled-jsx) supporting scoped css. However you can use any CSS-in-JS solution in your Next app by just including your favorite library [as mentioned before](#css-in-js) in the document.
</details> </details>
<p></p>
<details> <details>
<summary>What syntactic features are transpiled? How do I change them?</summary> <summary>What syntactic features are transpiled? How do I change them?</summary>
@ -1693,6 +1762,8 @@ See the documentation about [customizing the babel config](#customizing-babel-c
</details> </details>
<p></p>
<details> <details>
<summary>Why a new Router?</summary> <summary>Why a new Router?</summary>
@ -1711,6 +1782,8 @@ We tested the flexibility of the routing with some interesting scenarios. For an
</details> </details>
<p></p>
<details> <details>
<summary>How do I define a custom fancy route?</summary> <summary>How do I define a custom fancy route?</summary>
@ -1719,12 +1792,16 @@ We [added](#custom-server-and-routing) the ability to map between an arbitrary U
On the client side, we have a parameter call `as` on `<Link>` that _decorates_ the URL differently from the URL it _fetches_. On the client side, we have a parameter call `as` on `<Link>` that _decorates_ the URL differently from the URL it _fetches_.
</details> </details>
<p></p>
<details> <details>
<summary>How do I fetch data?</summary> <summary>How do I fetch data?</summary>
It’s up to you. `getInitialProps` is an `async` function (or a regular function that returns a `Promise`). It can retrieve data from anywhere. It’s up to you. `getInitialProps` is an `async` function (or a regular function that returns a `Promise`). It can retrieve data from anywhere.
</details> </details>
<p></p>
<details> <details>
<summary>Can I use it with GraphQL?</summary> <summary>Can I use it with GraphQL?</summary>
@ -1732,18 +1809,24 @@ Yes! Here's an example with [Apollo](./examples/with-apollo).
</details> </details>
<p></p>
<details> <details>
<summary>Can I use it with Redux?</summary> <summary>Can I use it with Redux?</summary>
Yes! Here's an [example](./examples/with-redux) Yes! Here's an [example](./examples/with-redux)
</details> </details>
<p></p>
<details> <details>
<summary>Can I use Next with my favorite Javascript library or toolkit?</summary> <summary>Can I use Next with my favorite Javascript library or toolkit?</summary>
Since our first release we've had **many** example contributions, you can check them out in the [examples](./examples) directory Since our first release we've had **many** example contributions, you can check them out in the [examples](./examples) directory
</details> </details>
<p></p>
<details> <details>
<summary>What is this inspired by?</summary> <summary>What is this inspired by?</summary>
@ -1757,6 +1840,8 @@ As we were researching options for server-rendering React that didn’t involve
</details> </details>
<p></p>
## Contributing ## Contributing
Please see our [contributing.md](./contributing.md) Please see our [contributing.md](./contributing.md)