Fix merge conflict (vercel#2)

timneutkens · dopry · commit 10f817b42726 · 2017-06-06T20:54:20.000-04:00
* 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
diff --git a/readme.md b/readme.md
@@ -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.
 
@@ -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
@@ -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).
 
@@ -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._
@@ -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>
@@ -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
@@ -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>
@@ -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).
@@ -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>
@@ -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 }
@@ -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
@@ -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
