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
<p><details>
<details>
<summary><b>Examples</b></summary>
<ul><li><a href="./examples/basic-css">Basic css</a></li></ul>
</details></p>
<ul>
<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).
@ -180,12 +184,21 @@ Please see the [styled-jsx documentation](https://www.npmjs.com/package/styled-j
#### CSS-in-JS
<p><details>
<details>
<summary>
<b>Examples</b>
</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>
</details></p>
</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>
</details>
<p></p>
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>`
<p><details>
<details>
<summary><b>Examples</b></summary>
<ul>
<li><a href="./examples/head-elements">Head elements</a></li>
<li><a href="./examples/layout-component">Layout component</a></li>
</ul>
</details></p>
</details>
<p></p>
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
<p><details>
<details>
<summary><b>Examples</b></summary>
<ul><li><a href="./examples/data-fetch">Data fetch</a></li></ul>
</details></p>
<ul>
<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):
@ -337,12 +356,14 @@ export default Page
#### With `<Link>`
<p><details>
<details>
<summary><b>Examples</b></summary>
<ul>
<li><a href="./examples/hello-world">Hello World</a></li>
</ul>
</details></p>
</details>
<p></p>
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
<p><details>
<details>
<summary><b>Examples</b></summary>
<ul>
<li><a href="./examples/with-url-object-routing">With URL Object Routing</a></li>
</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.
@ -471,13 +494,15 @@ The default behaviour of `<Link>` is to scroll to the top of the page. When ther
#### Imperatively
<p><details>
<details>
<summary><b>Examples</b></summary>
<ul>
<li><a href="./examples/using-router">Basic routing</a></li>
<li><a href="./examples/with-loading">With a page loading indicator</a></li>
</ul>
</details></p>
</details>
<p></p>
You can also do client-side page transitions using the `next/router`
@ -592,12 +617,14 @@ Router.events.on('routeChangeError', (err, url) => {
##### Shallow Routing
<p><details>
<details>
<summary><b>Examples</b></summary>
<ul>
<li><a href="./examples/with-shallow-routing">Shallow Routing</a></li>
</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.
@ -634,12 +661,14 @@ componentDidUpdate(prevProps) {
#### Using a Higher Order Component
<p><details>
<details>
<summary><b>Examples</b></summary>
<ul>
<li><a href="./examples/using-with-router">Using the `withRouter` utility</a></li>
</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:
@ -673,10 +702,14 @@ The above `router` object comes with an API similar to [`next/router`](#imperati
⚠️ This is a production only feature ⚠️
<p><details>
<details>
<summary><b>Examples</b></summary>
<ul><li><a href="./examples/with-prefetching">Prefetching</a></li></ul>
</details></p>
<ul>
<li><a href="./examples/with-prefetching">Prefetching</a></li>
</ul>
</details>
<p></p>
Next.js has an API which allows you to prefetch pages.
@ -763,7 +796,7 @@ export default withRouter(MyLink)
### Custom server and routing
<p><details>
<details>
<summary><b>Examples</b></summary>
<ul>
<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/ssr-caching">SSR caching</a></li>
</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.
@ -896,12 +931,14 @@ app.prepare().then(() => {
### Dynamic Import
<p><details>
<details>
<summary><b>Examples</b></summary>
<ul>
<li><a href="./examples/with-dynamic-import">With Dynamic Import</a></li>
</ul>
</details></p>
</details>
<p></p>
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.
@ -992,11 +1029,15 @@ export default () => <HelloBundle title="Dynamic Bundle" />
### Custom `<App>`
<p><details>
<details>
<summary><b>Examples</b></summary>
<ul><li><a href="./examples/with-app-layout">Using `_app.js` for layout</a></li></ul>
<ul><li><a href="./examples/with-componentdidcatch">Using `_app.js` to override `componentDidCatch`</a></li></ul>
</details></p>
<ul>
<li><a href="./examples/with-app-layout">Using `_app.js` for layout</a></li>
<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:
@ -1036,11 +1077,15 @@ export default class MyApp extends App {
### Custom `<Document>`
<p><details>
<details>
<summary><b>Examples</b></summary>
<ul><li><a href="./examples/with-styled-components">Styled components custom document</a></li></ul>
<ul><li><a href="./examples/with-amp">Google AMP</a></li></ul>
</details></p>
<ul>
<li><a href="./examples/with-styled-components">Styled components custom document</a></li>
<li><a href="./examples/with-amp">Google AMP</a></li>
</ul>
</details>
<p></p>
- Is rendered on the server side
- Is used to change the initial server side rendered document markup
@ -1251,10 +1296,14 @@ module.exports = {
### Customizing webpack config
<p><details>
<details>
<summary><b>Examples</b></summary>
<ul><li><a href="./examples/with-webpack-bundle-analyzer">Custom webpack bundle analyzer</a></li></ul>
</details></p>
<ul>
<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:
@ -1334,10 +1383,14 @@ module.exports = {
### Customizing babel config
<p><details>
<details>
<summary><b>Examples</b></summary>
<ul><li><a href="./examples/with-custom-babel-config">Custom babel configuration</a></li></ul>
</details></p>
<ul>
<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.
@ -1471,10 +1524,14 @@ The [polyfills](https://github.com/zeit/next.js/tree/canary/examples/with-polyfi
## Static HTML export
<p><details>
<details>
<summary><b>Examples</b></summary>
<ul><li><a href="./examples/with-static-export">Static export</a></li></ul>
</details></p>
<ul>
<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.
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:
```sh
```bash
next build
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:
```sh
```bash
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).
```sh
```bash
now
```
@ -1595,10 +1652,14 @@ The `req` and `res` fields of the `context` object passed to `getInitialProps` a
## Multi Zones
<p><details>
<details>
<summary><b>Examples</b></summary>
<ul><li><a href="./examples/with-zones">With Zones</a></li></ul>
</details></p>
<ul>
<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.
@ -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.
</details>
<p></p>
<details>
<summary>How big is it?</summary>
@ -1659,6 +1722,8 @@ A small Next main bundle is around 65kb gzipped.
</details>
<p></p>
<details>
<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>
<p></p>
<details>
<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.
</details>
<p></p>
<details>
<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>
<p></p>
<details>
<summary>Why a new Router?</summary>
@ -1711,6 +1782,8 @@ We tested the flexibility of the routing with some interesting scenarios. For an
</details>
<p></p>
<details>
<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_.
</details>
<p></p>
<details>
<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.
</details>
<p></p>
<details>
<summary>Can I use it with GraphQL?</summary>
@ -1732,18 +1809,24 @@ Yes! Here's an example with [Apollo](./examples/with-apollo).
</details>
<p></p>
<details>
<summary>Can I use it with Redux?</summary>
Yes! Here's an [example](./examples/with-redux)
</details>
<p></p>
<details>
<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
</details>
<p></p>
<details>
<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>
<p></p>
## Contributing
Please see our [contributing.md](./contributing.md)