Commit c890dc35 authored by Arunoda Susiripala's avatar Arunoda Susiripala Committed by Guillermo Rauch

Implement Router Events (#511)

* Move route loading logic to a common place.

* Add router events.

* Add EventEmitter's core API methods.

* Add example app for loading events and docs.

* Fix some typos.

* Get rid of Router.ready()

* Remove events package.
It's already shipping with webpack.

* Handling aborting properly.

* Expose simple attribute based events listener API.
Removed the proposed event listener API from the public API.

* Remove error logged when there's an abort error.
There are many other ways to capture this error.
So, it doesn't look nice to print this always.

* Change router events to pass only the current URL as arguments.

* Add a section about Cancelled Routes to README.
parent 6d8079a2
...@@ -182,13 +182,15 @@ For the initial page load, `getInitialProps` will execute on the server only. `g ...@@ -182,13 +182,15 @@ For the initial page load, `getInitialProps` will execute on the server only. `g
### Routing ### Routing
#### With `<Link>`
<p><details> <p><details>
<summary><b>Examples</b></summary> <summary><b>Examples</b></summary>
<ul><li><a href="./examples/using-routing">Basic routing</a></li></ul> <ul>
<li><a href="./examples/hello-world">Hello World</a></li>
</ul>
</details></p> </details></p>
#### With `<Link>`
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:
```jsx ```jsx
...@@ -225,6 +227,14 @@ The second `as` parameter for `push` and `replace` is an optional _decoration_ o ...@@ -225,6 +227,14 @@ The second `as` parameter for `push` and `replace` is an optional _decoration_ o
#### Imperatively #### Imperatively
<p><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>
You can also do client-side page transitions using the `next/router` You can also do client-side page transitions using the `next/router`
```jsx ```jsx
...@@ -247,6 +257,49 @@ The second `as` parameter for `push` and `replace` is an optional _decoration_ o ...@@ -247,6 +257,49 @@ The second `as` parameter for `push` and `replace` is an optional _decoration_ o
_Note: in order to programmatically change the route without triggering navigation and component-fetching, use `props.url.push` and `props.url.replace` within a component_ _Note: in order to programmatically change the route without triggering navigation and component-fetching, use `props.url.push` and `props.url.replace` within a component_
##### Router Events
You can also listen to different events happening inside the Router.
Here's a list of supported events:
- `routeChangeStart(url)` - Fires when a route starts to change
- `routeChangeComplete(url)` - Fires when a route changed completely
- `routeChangeError(err, url)` - Fires when there's an error when changing routes
> Here `url` is the URL shown in the browser. If you call `Router.push(url, as)` (or similar), then the value of `url` will be `as`.
Here's how to property listen to the router event `routeChangeStart`:
```js
Router.onRouteChangeStart = (url) => {
console.log('App is changing to: ', url)
}
```
If you are no longer want to listen to that event, you can simply unset the event listener like this:
```js
Router.onRouteChangeStart = null
```
##### Cancelled (Abort) Routes
Sometimes, you might want to change a route before the current route gets completed. Current route may be downloading the page or running `getInitialProps`.
In that case, we abort the current route and process with the new route.
If you need, you could capture those cancelled routes via `routeChangeError` router event. See:
```js
Router.onRouteChangeError = (err, url) => {
if (err.cancelled) {
console.log(`Route to ${url} is cancelled!`)
return
}
// Some other error
}
```
### Prefetching Pages ### Prefetching Pages
<p><details> <p><details>
......
# Example app with page loading indicator
## How to use
Download the example (or clone the repo)[https://github.com/zeit/next.js.git]:
```bash
curl https://codeload.github.com/zeit/next.js/tar.gz/master | tar -xz --strip=2 next.js-master/examples/with-loading
cd with-loading
```
Install it and run:
```bash
npm install
npm run dev
```
Deploy it to the cloud with [now](https://zeit.co/now) ([download](https://zeit.co/download))
```bash
now
```
## The idea behind the example
Sometimes when switching between pages, Next.js needs to download pages(chunks) from the server before rendering the page. And it may also need to wait for the data. So while doing these tasks, browser might be non responsive.
We can simply fix this issue by showing a loading indicator. That's what this examples shows.
It features:
* An app with two pages which uses a common [Header](./components/Header.js) component for navigation links.
* Using `next/router` to identify different router events
* Uses [nprogress](https://github.com/rstacruz/nprogress) as the loading indicator.
import React from 'react'
import Head from 'next/head'
import Link from 'next/link'
import NProgress from 'nprogress'
import Router from 'next/router'
Router.onRouteChangeStart = (url) => {
console.log(`Loading: ${url}`)
NProgress.start()
}
Router.onRouteChangeComplete = () => NProgress.done()
Router.onRouteChangeError = () => NProgress.done()
const linkStyle = {
margin: '0 10px 0 0'
}
export default () => (
<div style={{ marginBottom: 20 }}>
<Head>
{/* Import CSS for nprogress */}
<link rel='stylesheet' type='text/css' href='/static/nprogress.css' />
</Head>
<Link href='/'><a style={linkStyle}>Home</a></Link>
<Link href='/about'><a style={linkStyle}>About</a></Link>
<Link href='/forever'><a style={linkStyle}>Forever</a></Link>
<Link href='/non-existing'><a style={linkStyle}>Non Existing Page</a></Link>
</div>
)
{
"name": "with-loading",
"version": "1.0.0",
"description": "This example features:",
"main": "index.js",
"scripts": {
"dev": "next",
"build": "next build",
"start": "next start"
},
"dependencies": {
"next": "^2.0.0-beta",
"nprogress": "^0.2.0"
},
"author": "",
"license": "ISC"
}
import React, { Component } from 'react'
import Header from '../components/Header'
export default class About extends Component {
// Add some delay
static getInitialProps () {
return new Promise((resolve) => {
setTimeout(resolve, 500)
})
}
render () {
return (
<div>
<Header />
<p>This is about Next!</p>
</div>
)
}
}
import React, { Component } from 'react'
import Header from '../components/Header'
export default class Forever extends Component {
// Add some delay
static getInitialProps () {
return new Promise((resolve) => {
setTimeout(resolve, 3000)
})
}
render () {
return (
<div>
<Header />
<p>This page was rendered for a while!</p>
</div>
)
}
}
import React from 'react'
import Header from '../components/Header'
export default () => (
<div>
<Header />
<p>Hello Next!</p>
</div>
)
/* Make clicks pass-through */
#nprogress {
pointer-events: none;
}
#nprogress .bar {
background: #29d;
position: fixed;
z-index: 1031;
top: 0;
left: 0;
width: 100%;
height: 2px;
}
/* Fancy blur effect */
#nprogress .peg {
display: block;
position: absolute;
right: 0px;
width: 100px;
height: 100%;
box-shadow: 0 0 10px #29d, 0 0 5px #29d;
opacity: 1.0;
-webkit-transform: rotate(3deg) translate(0px, -4px);
-ms-transform: rotate(3deg) translate(0px, -4px);
transform: rotate(3deg) translate(0px, -4px);
}
/* Remove these to get rid of the spinner */
#nprogress .spinner {
display: block;
position: fixed;
z-index: 1031;
top: 15px;
right: 15px;
}
#nprogress .spinner-icon {
width: 18px;
height: 18px;
box-sizing: border-box;
border: solid 2px transparent;
border-top-color: #29d;
border-left-color: #29d;
border-radius: 50%;
-webkit-animation: nprogress-spinner 400ms linear infinite;
animation: nprogress-spinner 400ms linear infinite;
}
.nprogress-custom-parent {
overflow: hidden;
position: relative;
}
.nprogress-custom-parent #nprogress .spinner,
.nprogress-custom-parent #nprogress .bar {
position: absolute;
}
@-webkit-keyframes nprogress-spinner {
0% { -webkit-transform: rotate(0deg); }
100% { -webkit-transform: rotate(360deg); }
}
@keyframes nprogress-spinner {
0% { transform: rotate(0deg); }
100% { transform: rotate(360deg); }
}
import _Router from './router' import _Router from './router'
// holds the actual router instance const SingletonRouter = {
let router = null router: null, // holds the actual router instance
readyCallbacks: [],
const SingletonRouter = {} ready (cb) {
if (this.router) return cb()
if (typeof window !== 'undefined') {
this.readyCallbacks.push(cb)
}
}
}
// Create public properties and methods of the router in the SingletonRouter // Create public properties and methods of the router in the SingletonRouter
const propertyFields = ['components', 'pathname', 'route', 'query'] const propertyFields = ['components', 'pathname', 'route', 'query']
const methodFields = ['push', 'replace', 'reload', 'back'] const coreMethodFields = ['push', 'replace', 'reload', 'back']
const routerEvents = ['routeChangeStart', 'routeChangeComplete', 'routeChangeError']
propertyFields.forEach((field) => { propertyFields.forEach((field) => {
// Here we need to use Object.defineProperty because, we need to return // Here we need to use Object.defineProperty because, we need to return
...@@ -17,20 +24,31 @@ propertyFields.forEach((field) => { ...@@ -17,20 +24,31 @@ propertyFields.forEach((field) => {
Object.defineProperty(SingletonRouter, field, { Object.defineProperty(SingletonRouter, field, {
get () { get () {
throwIfNoRouter() throwIfNoRouter()
return router[field] return SingletonRouter.router[field]
} }
}) })
}) })
methodFields.forEach((field) => { coreMethodFields.forEach((field) => {
SingletonRouter[field] = (...args) => { SingletonRouter[field] = (...args) => {
throwIfNoRouter() throwIfNoRouter()
return router[field](...args) return SingletonRouter.router[field](...args)
}
})
routerEvents.forEach((event) => {
SingletonRouter.ready(() => {
SingletonRouter.router.on(event, (...args) => {
const eventField = `on${event.charAt(0).toUpperCase()}${event.substring(1)}`
if (SingletonRouter[eventField]) {
SingletonRouter[eventField](...args)
} }
})
})
}) })
function throwIfNoRouter () { function throwIfNoRouter () {
if (!router) { if (!SingletonRouter.router) {
const message = 'No router instance found.\n' + const message = 'No router instance found.\n' +
'You should only use "next/router" inside the client side of your app.\n' 'You should only use "next/router" inside the client side of your app.\n'
throw new Error(message) throw new Error(message)
...@@ -48,8 +66,11 @@ export default SingletonRouter ...@@ -48,8 +66,11 @@ export default SingletonRouter
// This is used in client side when we are initilizing the app. // This is used in client side when we are initilizing the app.
// This should **not** use inside the server. // This should **not** use inside the server.
export const createRouter = function (...args) { export const createRouter = function (...args) {
router = new _Router(...args) SingletonRouter.router = new _Router(...args)
return router SingletonRouter.readyCallbacks.forEach(cb => cb())
SingletonRouter.readyCallbacks = []
return SingletonRouter.router
} }
// Export the actual Router class, which is usually used inside the server // Export the actual Router class, which is usually used inside the server
......
import { parse, format } from 'url' import { parse, format } from 'url'
import evalScript from '../eval-script' import evalScript from '../eval-script'
import shallowEquals from '../shallow-equals' import shallowEquals from '../shallow-equals'
import { EventEmitter } from 'events'
export default class Router { export default class Router extends EventEmitter {
constructor (pathname, query, { Component, ErrorComponent, ctx } = {}) { constructor (pathname, query, { Component, ErrorComponent, ctx } = {}) {
super()
// represents the current component key // represents the current component key
this.route = toRoute(pathname) this.route = toRoute(pathname)
...@@ -14,6 +16,7 @@ export default class Router { ...@@ -14,6 +16,7 @@ export default class Router {
this.pathname = pathname this.pathname = pathname
this.query = query this.query = query
this.subscriptions = new Set() this.subscriptions = new Set()
this.componentLoadCancel = null this.componentLoadCancel = null
this.onPopState = this.onPopState.bind(this) this.onPopState = this.onPopState.bind(this)
...@@ -26,40 +29,37 @@ export default class Router { ...@@ -26,40 +29,37 @@ export default class Router {
} }
} }
onPopState (e) { async onPopState (e) {
this.abortComponentLoad() this.abortComponentLoad()
const as = getURL() const { url, as } = e.state
const { url = as } = e.state || {}
const { pathname, query } = parse(url, true) const { pathname, query } = parse(url, true)
if (!this.urlIsNew(pathname, query)) return if (!this.urlIsNew(pathname, query)) {
this.emit('routeChangeStart', as)
this.emit('routeChangeComplete', as)
return
}
const route = toRoute(pathname) const route = toRoute(pathname)
Promise.resolve() this.emit('routeChangeStart', as)
.then(async () => { const {
const data = await this.fetchComponent(route) data,
const ctx = { ...data.ctx, pathname, query } props,
const props = await this.getInitialProps(data.Component, ctx) error
} = await this.getRouteInfo(route, pathname, query)
this.route = route
this.set(pathname, query, { ...data, props }) if (error) {
}) this.emit('routeChangeError', error, as)
.catch(async (err) => { // We don't need to throw here since the error is already logged by
if (err.cancelled) return // this.getRouteInfo
return
const data = { Component: this.ErrorComponent, ctx: { err } } }
const ctx = { ...data.ctx, pathname, query }
const props = await this.getInitialProps(data.Component, ctx)
this.route = route this.route = route
this.set(pathname, query, { ...data, props }) this.set(pathname, query, { ...data, props })
console.error(err) this.emit('routeChangeComplete', as)
})
.catch((err) => {
console.error(err)
})
} }
update (route, Component) { update (route, Component) {
...@@ -77,29 +77,24 @@ export default class Router { ...@@ -77,29 +77,24 @@ export default class Router {
if (route !== this.route) return if (route !== this.route) return
const { pathname, query } = parse(window.location.href, true) const url = window.location.href
const { pathname, query } = parse(url, true)
let data
let props
let _err
try {
data = await this.fetchComponent(route)
const ctx = { ...data.ctx, pathname, query }
props = await this.getInitialProps(data.Component, ctx)
} catch (err) {
if (err.cancelled) return false
data = { Component: this.ErrorComponent, ctx: { err } } this.emit('routeChangeStart', url)
const ctx = { ...data.ctx, pathname, query } const {
props = await this.getInitialProps(data.Component, ctx) data,
props,
error
} = await this.getRouteInfo(route, pathname, query)
_err = err if (error) {
console.error(err) this.emit('routeChangeError', error, url)
throw error
} }
this.notify({ ...data, props }) this.notify({ ...data, props })
if (_err) throw _err this.emit('routeChangeComplete', url)
} }
back () { back () {
...@@ -115,33 +110,26 @@ export default class Router { ...@@ -115,33 +110,26 @@ export default class Router {
} }
async change (method, url, as) { async change (method, url, as) {
this.abortComponentLoad()
const { pathname, query } = parse(url, true) const { pathname, query } = parse(url, true)
if (!this.urlIsNew(pathname, query)) { if (!this.urlIsNew(pathname, query)) {
this.emit('routeChangeStart', as)
changeState() changeState()
this.emit('routeChangeComplete', as)
return true return true
} }
const route = toRoute(pathname) const route = toRoute(pathname)
this.abortComponentLoad() this.emit('routeChangeStart', as)
const {
let data data, props, error
let props } = await this.getRouteInfo(route, pathname, query)
let _err
try {
data = await this.fetchComponent(route)
const ctx = { ...data.ctx, pathname, query }
props = await this.getInitialProps(data.Component, ctx)
} catch (err) {
if (err.cancelled) return false
data = { Component: this.ErrorComponent, ctx: { err } } if (error) {
const ctx = { ...data.ctx, pathname, query } this.emit('routeChangeError', error, as)
props = await this.getInitialProps(data.Component, ctx) throw error
_err = err
console.error(err)
} }
changeState() changeState()
...@@ -149,17 +137,39 @@ export default class Router { ...@@ -149,17 +137,39 @@ export default class Router {
this.route = route this.route = route
this.set(pathname, query, { ...data, props }) this.set(pathname, query, { ...data, props })
if (_err) throw _err this.emit('routeChangeComplete', as)
return true return true
function changeState () { function changeState () {
if (method !== 'pushState' || getURL() !== as) { if (method !== 'pushState' || getURL() !== as) {
window.history[method]({ url }, null, as) window.history[method]({ url, as }, null, as)
} }
} }
} }
async getRouteInfo (route, pathname, query) {
const routeInfo = {}
try {
const data = routeInfo.data = await this.fetchComponent(route)
const ctx = { ...data.ctx, pathname, query }
routeInfo.props = await this.getInitialProps(data.Component, ctx)
} catch (err) {
if (err.cancelled) {
return { error: err }
}
const data = routeInfo.data = { Component: this.ErrorComponent, ctx: { err } }
const ctx = { ...data.ctx, pathname, query }
routeInfo.props = await this.getInitialProps(data.Component, ctx)
routeInfo.error = err
console.error(err)
}
return routeInfo
}
set (pathname, query, data) { set (pathname, query, data) {
this.pathname = pathname this.pathname = pathname
this.query = query this.query = query
...@@ -177,7 +187,12 @@ export default class Router { ...@@ -177,7 +187,12 @@ export default class Router {
data = await new Promise((resolve, reject) => { data = await new Promise((resolve, reject) => {
this.componentLoadCancel = cancel = () => { this.componentLoadCancel = cancel = () => {
if (xhr.abort) xhr.abort() if (xhr.abort) {
xhr.abort()
const error = new Error('Fetching componenet cancelled')
error.cancelled = true
reject(error)
}
} }
const url = `/_next/pages${route}` const url = `/_next/pages${route}`
...@@ -211,7 +226,7 @@ export default class Router { ...@@ -211,7 +226,7 @@ export default class Router {
} }
if (cancelled) { if (cancelled) {
const err = new Error('Cancelled') const err = new Error('Loading initial props cancelled')
err.cancelled = true err.cancelled = true
throw err throw err
} }
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment