Skip to content

Commit

Permalink
Fix merge conflict (vercel#2)
Browse files Browse the repository at this point in the history 
* Add better hash URL support. (vercel#1250)

* Add better hash URL support.
1. Add scrolling to given id related to hash
2. Hash changes won't trigger getInitialProps

* Add some comments.

* Fix tests.

* Add some test cases.

* Fire the route cancel event only when needed. (vercel#1316)

Earlier we do it for every route change.

* Update Koa example for Koa 2 with async/await (vercel#1317)

* Release 2.0.0-beta.36

* Update prefetch docs and mention it's production only. (vercel#1324)

* fix(package): update friendly-errors-webpack-plugin to version 1.6.0 (vercel#1320)

https://greenkeeper.io/

* chore(package): update standard to version 9.0.0 (vercel#1318)

https://greenkeeper.io/

* Example with next-routes (vercel#1290)

* Example with next-routes

* optimize description

* rename to with-next-routes

* Throw Error when url.parse without true is parsed (vercel#1282)

* Throw Error when url.parse without true is parsed

This is a bit more descriptive when this mistake is made by the user.

* Parse when needed

* Parse querystring if it is not provided

* With global stylesheet paths (vercel#1327)

* with-global-stylesheet without relative paths and with node_modules

* a parenthetical remark about material-components-web not being part of the example

* Revert "Update friendly-errors-webpack-plugin to the latest version 🚀" (vercel#1328)

* chore(package): update husky to version 0.13.2 (vercel#1330)

https://greenkeeper.io/

* Fixed some problems with standard (vercel#1331)

* Remove unused webpack import in flyfile.js (vercel#1332)

* Fix linting errors in standard 9.0 (vercel#1333)

* Fix linting errors in standard 9.0

* Update lockfile

* fix(package): update unfetch to version 2.1.2 (vercel#1338)

https://greenkeeper.io/

* Add a global Promise polyfill. (vercel#1344)

* Add a global Promise polyfill.
This is because Webpack2 depends on it.

* Change the polyfill location.

* Add default entries to main.js (vercel#1343)

So, we don't need to add them to individual pages.
This also fix the issue where, error pages doesn't ping the server.

* chore(package): update cross-env to version 3.2.0 (vercel#1348)

https://greenkeeper.io/

* Implement preact/inferno SSR (vercel#1346)

* Use module-alias to alias preact server side

* Use module-alias to alias inferno server side

* Remove unneeded routes example

* postcss-loader, postcss-easy-import, normalize.css and autoprefixer (vercel#1352)

* Add missing ! in using-preact example (vercel#1355) (vercel#1356)

* Revert "Update cross-env to the latest version 🚀" (vercel#1358)

* Introducing Shallow Routing (vercel#1357)

* Simplify route info handling.

* Add basic resolve=false support.

* Make sure to render getInitialProps always if it's the first render.

* Change resolve=false to shallow routing.

* Add test cases for shallow routing.

* Update README for shallow routing docs.

* Update docs.

* Update docs.

* Update docs.

* Update readme.md

* fix(package): update loader-utils to version 1.0.3 (vercel#1361)

https://greenkeeper.io/

* fix(package): update babel-loader to version 6.4.0 (vercel#1359)

https://greenkeeper.io/

* Disable uglify the pretty way (vercel#1351)

* fix(package): update send to version 0.15.1 (vercel#1350)

https://greenkeeper.io/

* Shallow routing changes (vercel#1363)

* Fix a typo in a test suite.

* Add old props.url API with warn for all tags.

* Update README.md (vercel#1368)

Fix graph.cool link in example

* Add content based HASH to main.js and common.js (vercel#1336)

* Use file hashes instead of BUILD_ID.
Now JSON pages also not prefixed with a hash and
doesn't support immutable caching.
Instead it supports Etag bases caching.

* Remove appUpdated Router Events hook.
Becuase now we don't need it because there's no buildId validation.

* Remove buildId generation.

* Turn off hash checks in the dev mode.

* Update tests.

* Revert "Remove buildId generation."

This reverts commit fdd36a5.

* Bring back the buildId validation.

* Handle buildId validation only in production.

* Add BUILD_ID to path again.

* Remove duplicate immutable header.

* Fix tests.

* update yarn

* send credentials when fetching new route (vercel#1371)

* [WIP] Improve test setup (vercel#1372)

* Run tests serially.

* Make test result verbose.

* Don't wait until closing the browser.

* Add some debug logs.

* Add bailing support.

* Get the browser with a timeout.

* Add some comments.

* Remove istanbul babel tranformation.
Jest already do it and it's breaking our coveralls hit.

* Add beforeHistoryChange router event. (vercel#1360)

* Fix styled-components server-render example (vercel#1382)

* Fix typo (vercel#1380)

port 300 -> 3000

* fix(package): update write-file-webpack-plugin to version 4.0.0 (vercel#1383)

https://greenkeeper.io/

* chore(package): update chromedriver to version 2.28.0 (vercel#1386)

https://greenkeeper.io/

* Ping to on-demand-entries on every page change. (vercel#1384)

This will prevent disposing the page after viewing it.
Otherwise, it'll possible to dispose the page even
we load the page on the client.

* Add support for URL objects in Link and Router (vercel#1345)

* Add support for URL objects in Link and Router

* Fix typo in comment

* Fix possible bug if the `href` prop is `null`

* Document the usage of URL objects in Link and Router

* Update readme.md

* Parse URL to get the host & hostname in `isLocal`

This should check if the current location and the checked URL have the same `host` or `hostname`.

* Format `as` parameter from object to string if required

* Format `href` and `as` inside the construct and componentWillReceiveProps

* Use `JSON.stringify` to compare objects

* Add usage example

* chore(package): update chromedriver to version 2.28.0 (vercel#1386)

https://greenkeeper.io/

* Refactor the codebase a bit.

* Change the example name.

* Add a few test cases.

* Add the example to the README.

* Updated with-apollo example. (vercel#1389)

- Deleted several unused dependencies.
- Updated dependencies.
- Simplified Apollo related imports thanks to react-apollo exporting apollo-client and graphql-tag since [v0.13.2](https://github.com/apollographql/react-apollo/blob/master/Changelog.md#0132).
- Tidied the readme and added a link to the Apollo docs.

* Use a private Router event API for the ondemand-pinger. (vercel#1397)

* Use mitt instead of EventEmitter. (vercel#1398)

EventEmitter is quite bit and mitt is a pretty good/small replacement.

* Use mitt instead of EventEmitter for the client HMR (vercel#1399)

error handling.

* fix(package): update babel-plugin-transform-es2015-modules-commonjs to version 6.24.0 (vercel#1400)

https://greenkeeper.io/

* chore(package): update husky to version 0.13.3-0 (vercel#1395)

https://greenkeeper.io/

* chore(package): update babel-preset-es2015 to version 6.24.0 (vercel#1401)

https://greenkeeper.io/

* fix(package): update babel-preset-latest to version 6.24.0 (vercel#1402)

https://greenkeeper.io/

* fix(package): update babel-generator to version 6.24.0 (vercel#1404)

https://greenkeeper.io/

* fix(package): update babel-core to version 6.24.0 (vercel#1403)

https://greenkeeper.io/

* Release 2.0.0-beta.37

* fix(package): update source-map-support to version 0.4.12 (vercel#1405)

https://greenkeeper.io/

* Examples: Update Inferno & Preact (vercel#1407)

* clean & bump inferno & preact pkgs

* reenable UglifyJS for preact

* chore(package): update fly-esnext to version 2.0.1 (vercel#1408)

https://greenkeeper.io/

* fix(package): update loader-utils to version 1.0.4 (vercel#1411)

https://greenkeeper.io/

* chore(package): update cross-env to version 3.2.4 (vercel#1417)

https://greenkeeper.io/

* Remove patch-react.js (vercel#1420)

This is a pretty complex code base and it cause
issues for some React components.
And React/fiber is coming with a proper solution.

* Release 2.0.0-beta.38

* Upgrade styled-components. Fixes vercel#1416 (vercel#1422)

* Update with-apollo example (vercel#1394)

* Add minimal apollo example

* Update apollo example README

* Update apollo example demo link in README

* Fix button styles

* Fix show more button

* Alias demo url

* Include the data field on the Apollo store when hydrating

* Revert

* Include the data field on the Apollo store when hydrating per tpreusse's suggestion.

* Add example to faq section in README

* Sort by newest; Add active state to buttons

* Make optimization suggestions

* Use process.browser; inline props

* Pass wrapped component's initial props into component heirarchy if they exist

* Remove unnecessary sorting of array

* Update Apollo example

* Remove trailing comma

* Update reduxRootKey

* Remove unnecessary babelrc

* Update with-apollo example

- Remove use of deprecated 'reduxRootKey' option
- Add loading indicator inside pagination button

* Add/link replace (vercel#1419)

* Using developit/unfetch as the Fetch API polyfill

* Added the replace prop into the Link component

* Added integration test for replace prop on Link component

* Use jsonPageRes instead of xhr (vercel#1424)

* Add reference to deployment wiki page (vercel#1423)

* Fix deployment wiki link.

* Fix typo in README (vercel#1427)

`routing`not `routig`

* Example to create next application with scoped/external css. (vercel#1340)

* First structure for external css example

* Remove: Builded files

* Fix: Identation to 2 spaces

* Fix example

* Fix lint

* Fix: Review points

* An example with react-helmet (vercel#1264)

* upload example

* fix

* fix

* fix

* fix .babelrc

* fix standard style

* fix indent

* rename helmetHead to helmet

* added gitignore

* package.json

* removed yarn.lock

* Added more examples of using react-helmet

* removed gitignore

* [POC] Pretty url routing (vercel#1001)

* [example] with pretty url routing

* use single quotes even in React components

* improve Link import

* examples: add `svg-components` (vercel#982)

* Remove .DS_Store file from helmet example (vercel#1435)

* Document babel caching (vercel#1432)

* Update readme to reflect latest changes

* Remove deprecated methods
  • Loading branch information
@timneutkens @dopry
timneutkens authored and dopry committed Jun 7, 2017
1 parent 25e61d1 commit 10f817b
Showing 1 changed file with 61 additions and 19 deletions.
80 changes: 61 additions & 19 deletions readme.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# <img width="112" alt="Next.js" src="https://cloud.githubusercontent.com/assets/13041/19686250/971bf7f8-9ac0-11e6-975c-188defd82df1.png">
<img width="112" alt="Next.js" src="https://cloud.githubusercontent.com/assets/13041/19686250/971bf7f8-9ac0-11e6-975c-188defd82df1.png">

> A complete framework for universal JavaScript applications with zero setup.
Expand Down Expand Up @@ -64,7 +64,7 @@ Hereafter it takes __three simple steps__ to set up your app.

### Install the `next` Package

First up, install Next.js and it's peer dependencies via [npm](https://npmjs.com/package/next):
First up, install Next.js and its peer dependencies via [npm](https://npmjs.com/package/next):

```bash
npm install next react react-dom --save
Expand Down Expand Up @@ -106,6 +106,7 @@ For production run `npm run build` and serve it via `npm start`. :boom:
> - Automatic transpilation and bundling (with [Babel](https://babeljs.io/) and [webpack](https://webpack.js.org/))
> - Hot code reloading
> - Server rendering and indexing of `./pages/`
> - Static file serving. `./static/` is mapped to `/static/`
To see how simple it is, check out the [sample app - Nextgram](https://github.com/zeit/nextgram).

Expand Down Expand Up @@ -236,6 +237,8 @@ export default class Hello extends React.Component {
}
```

Notice that to load data when the page loads, we use `getInitialProps` which is an [`async`](https://zeit.co/blog/async-and-await) static method. It can asynchronously fetch anything that resolves to a JavaScript plain `Object`, which populates `props`.

We expect the return value of `getInitialProps` to resolve to a JavaScript plain `Object` which then populates the page's `props`.

:information_source: _`getInitialProps` will execute on the server or the client&mdash;never both. For the initial page load it will be executed on the server only. When navigation to a different route using the [routing APIs](#routing-client-side) it will be executed on the client only._
Expand All @@ -246,13 +249,12 @@ We expect the return value of `getInitialProps` to resolve to a JavaScript plain
- `query: Object` &ndash; Query string section of URL, parsed as an object
- `req?: Object` &ndash; HTTP request object (server only)
- `res?: Object` &ndash; HTTP response object (server only)
- `xhr?: Object` &ndash; `XMLHttpRequest` object (client only)
- `jsonPageRes` - [Fetch Response](https://developer.mozilla.org/en-US/docs/Web/API/Response)
- `err?: Error` &ndash; `Error` object if any error is encountered during rendering

### Routing Client-Side

#### Using `<Link/>` Component

<p><details>
<summary><b>Examples</b></summary>
<ul>
Expand All @@ -262,13 +264,15 @@ We expect the return value of `getInitialProps` to resolve to a JavaScript plain

Client-side transitions between routes may be enabled via the exposed `<Link>` component. Consider these two pages:


```jsx
// pages/index.js
import Link from 'next/link'

export default () => (
<div>Click <Link href="/about"><a>here</a></Link> to read more</div>
)

```

```jsx
Expand All @@ -281,32 +285,25 @@ export default () => (
The `<Link>` component accepts the following `props`:

- `href: string` &ndash; the path to link to.
- `as?: string` &ndash; An optional _decoration_ of the URL. Useful if you configured [custom routes on the server](#customizing-server-routes).
- `prefetch?: boolean` &ndash; Prefetches the route. Defaults to `false`. Read [more about prefetching](#prefetching-pages).

:information_source: _The `<Link>` component doesn't implicitly render an `<a>` tag. This is so you can choose any element you'd like (e.g. `<button>`). Also, in case it's child is in fact an `<a>` element, the `href` property on `<Link>` gets passed down. This prevents you from having to repeat it._

- `as?: string` &ndash; An optional _decoration_ of the URL. Useful if you configured [custom routes on the server](#customizing-server-routes).
Client-side routing behaves exactly like the browser:
- `prefetch?: boolean` &ndash; Prefetches the route. Defaults to `false`. Read [more about prefetching](#prefetching-pages).

1. The component is fetched.
2. If it defines [`getInitialProps`](#fetching-initial-data), data is fetched. If an error occurs, [`_error.js`](#handling-errors) is rendered.
3. After 1 and 2 complete, [`pushState`](https://developer.mozilla.org/en-US/docs/Web/API/History_API#Example_of_pushState()_method) is performed and the new component rendered.

:information_source: _For maximum performance use [`<Link prefetch/>`](#prefetching-pages) to link to and prefetch a page at the same time._


#### Using `url` Property

For routing imperatively each page component receives a `url` property, an object with the following API:

- `pathname: string` &ndash; Current path excluding the query string
- `query: Object` &ndash; Parsed query string. Defaults to `{}`.
- `push(url: string, as?: string): boolean` &ndash; Performs a [`pushState`](https://developer.mozilla.org/en-US/docs/Web/API/History_API#Example_of_pushState()_method) call with the given url. Returns `true` on success, else `false`.
- `replace(url: string, as?: string): boolean` &ndash; Performs a [`replaceState`](https://developer.mozilla.org/en-US/docs/Web/API/History_API#Example_of_replaceState()_method) call with the given url. Returns `true` on success, else `false`.

The `as` parameter for `push` and `replace` corresponds to the equally named [`<Link>` property](#using-link-component).

#### Using `Router` Class

<p><details>
<summary><b>Examples</b></summary>
<ul>
Expand All @@ -323,15 +320,17 @@ import Router from 'next/router'
export default () => (
<div>Click <span onClick={() => Router.push('/about')}>here</span> to read more.</div>
)

```

Above `Router` object comes with the following API:

- `route: string` &ndash; Current route.
- `pathname: string` &ndash; Current path excluding the query string.
- `query: Object` &ndash; Parsed query string. Defaults to `{}`.
- `push(url: string, as?: string): boolean` &ndash; Performs a [`pushState`](https://developer.mozilla.org/en-US/docs/Web/API/History_API#Example_of_pushState()_method) call with the given url. Returns `true` on success, else `false`.
- `replace(url: string, as?: string): boolean` &ndash; Performs a [`replaceState`](https://developer.mozilla.org/en-US/docs/Web/API/History_API#Example_of_replaceState()_method) call with the given url. Returns `true` on success, else `false`.
- `push(url: string, as?: string): boolean` &ndash; Performs a [`pushState`](https://developer.mozilla.org/en-US/docs/Web/API/History_API#Example_of_pushState()) method call with the given url. Returns `true` on success, else `false`.
- `replace(url: string, as?: string): boolean` &ndash; Performs a [`replaceState`](https://developer.mozilla.org/en-US/docs/Web/API/History_API#Example_of_replaceState()) method call with the given url. Returns `true` on success, else `false`.

- `prefetch(url: string): Promise` &ndash; Prefetches a given url. Works analogous to the `prefetch` prop on [`<Link/>`](#using-link-component). [Read more here](#prefetching-pages).

The `as` parameter for `push` and `replace` corresponds to the equally named [`<Link>` property](#using-link-component).
Expand Down Expand Up @@ -384,8 +383,49 @@ Router.onAppUpdated = (nextRoute) => {
}
```

##### Shallow Routing

<p><details>
<summary><b>Examples</b></summary>
<ul>
<li><a href="./examples/with-shallow-routing">Shallow Routing</a></li>
</ul>
</details></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.

You can do this by invoking either `Router.push` or `Router.replace` with `shallow: true` option. Here's an example:

```jsx
// Current URL is "/"
const href = '/?counter=10'
const as = href
Router.push(href, as, { shallow: true })
```

Now, the URL is updated to `/?counter=10`. You can see the updated URL with `this.props.url` inside the `Component`.

You can watch for URL changes via [`componentWillReceiveProps`](https://facebook.github.io/react/docs/react-component.html#componentwillreceiveprops) hook as shown below:

```jsx
componentWillReceiveProps(nextProps) {
const { pathname, query } = nextProps.url
// fetch data based on the new query
}
```

> NOTES:
>
> Shallow routing works **only** for same page URL changes. For an example, let's assume we've another page called `about`, and you run this:
> ```js
> Router.push('/about?counter=10', '/about?counter=10', { shallow: true })
> ```
> Since that's a new page, it'll unload the current page, load the new one and call `getInitialProps` even we asked to do shallow routing.
#### Prefetching Pages
(This is a production only feature)
<p><details>
<summary><b>Examples</b></summary>
<ul><li><a href="./examples/with-prefetching">Prefetching</a></li></ul>
Expand Down Expand Up @@ -566,8 +606,8 @@ import React from 'react'

export default class Error extends React.Component {

static getInitialProps ({ res, xhr }) {
const statusCode = res ? res.statusCode : (xhr ? xhr.status : null)
static getInitialProps ({ res, jsonPageRes }) {
const statusCode = res ? res.statusCode : (jsonPageRes ? jsonPageRes.status : null)
const env = xhr ? 'client' : 'server'

return { statusCode, env }
Expand Down Expand Up @@ -684,7 +724,7 @@ Here's an example `.babelrc` file:

## Production Deployment

To deploy, instead of running `next`, you probably want to build ahead of time. Therefore, building and starting are separate commands:
To deploy, instead of running `next`, you want to build for production usage ahead of time. Therefore, building and starting are separate commands:

```bash
next build
Expand All @@ -709,6 +749,8 @@ For example, to deploy with [`now`](https://zeit.co/now) a `package.json` like f

Then run `now` and enjoy!

Next.js can be deployed to other hosting solutions too. Please have a look at the ['Deployment'](https://github.com/zeit/next.js/wiki/Deployment) section of the wiki.

:information_source: _We recommend putting `.next` in `.npmignore` or `.gitignore`. Otherwise, use `files` or `now.files` to opt-into a whitelist of files you want to deploy (and obviously exclude `.next`)._

## FAQ
Expand Down

0 comments on commit 10f817b

Please sign in to comment.