Next.js: Document events interface for router?

Created on 27 Jun 2018 · 7Comments · Source: vercel/next.js

Feature request

Officially support & document router.events.

Is your feature request related to a problem? Please describe.

I am creating a component that needs visibility into router events. There are some awkward global functions you can set, like onRouteChangeComplete, but it's difficult to use this interface in the case where that property is already set. There's no documented way to attach to and detach from events. However, it appears that there's an EventEmitter under an events property that is available and would be perfect for this scenario:

import * as React from 'react';

class MyComponent extends React.Component {
  // ...

  componentDidMount() {
    this.props.router.events.on('routeChangeComplete', this.handleRouteChange);
  }

  componentWillUnmount() {
    this.props.router.events.off('routeChangeComplete', this.handleRouteChange);
  }
}

Describe the solution you'd like

Is this events interface officially supported? If so, should that be added to the documentation? My fear for using any undocumented feature is that it may go away at any time.

Describe alternatives you've considered

I briefly considered inspecting Router.onRouteChangeComplete functions to try to "add" a listener, but that is extremely hacky and doesn't lend itself well to multiple components subscribing/unsubscribing to events:

const originalFn = Router.onRouteChangeComplete;
Router.onRouteChangeComplete = url => {
  originalFn(url);
  // The rest of the functionality
};

// Then later
Router.onRouteChangeComplete = originalFn; // Not really safe

Source

DullReferenceException

👍5

Most helpful comment

@DullReferenceException @timneutkens thanks for adding this! This is excellent. We were just working on analytics and ran into this so this is a welcome piece of work :) 👍 thanks guys :) :)

codinronan on 5 Jul 2018

🎉3

All 7 comments

I'm also interested if this is the safe way to add multiple listeners to router events.
@timneutkens could you provide some info?

isBatak on 3 Jul 2018

We ran into this with nextjs.org and hyper.is too. Especially when we start creating plugins to implement things like analytics etc. this will be a needed feature. This also solves unsubscribing to events, which doesn't seem reliably possible currently. Also, this doesn't even involve code changes, just documentation changes. So it seems like a great way to handle this.

Thanks for the great write-up @DullReferenceException 🙏

timneutkens on 3 Jul 2018

Looks like we need slightly more than a documentation change since events isn't exposed via context.router. This seems to fix it: https://github.com/zeit/next.js/pull/4726

DullReferenceException on 4 Jul 2018

That's totally fine 👍

timneutkens on 4 Jul 2018