gatsby-link: add push (same as navigateTo) and replace methods (#5934)

* gatsby-link: add push (same as navigateTo) and replace

This addresses #5910

* Update README.md

* Update example

Author: tremby

packages/gatsby-link/README.md

@@ -53,19 +53,20 @@ render () {
 
 ## Programmatic navigation
 
-For cases when you can only use event handlers for navigation, you can use
-`navigateTo`:
+For cases when you can only use event handlers for navigation, you can use `push` or `replace`. `push` is a wrapper for `history.push` and `replace` wraps `history.replace`.
 
 ```jsx
-import { navigateTo } from "gatsby-link"
+import { push } from "gatsby-link"
 
 render () {
-  <div onClick={ () => navigateTo('/example')}>
+  <div onClick={ () => push('/example')}>
     <p>Example</p>
   </div>
 }
 ```
 
+Note that `push` was previously named `navigateTo`. `navigateTo` will be deprecated in Gatsby v2.
+
 ## Prefixed paths helper
 
 Gatsby allows you to [automatically prefix links](/docs/path-prefix/) for sites

packages/gatsby-link/index.d.ts

@@ -8,6 +8,8 @@ export interface GatsbyLinkProps extends NavLinkProps {
   style?:any;
 }
 
+export const push: (to: LocationDescriptor) => void;
+export const replace: (to: LocationDescriptor) => void;
 export const navigateTo: (to: LocationDescriptor) => void;
 
 export const withPrefix: (path: string) => string;

packages/gatsby-link/src/__tests__/index.js

@@ -14,12 +14,20 @@ const getInstance = (props, pathPrefix = ``) => {
   return new Link(props, context)
 }
 
-const getNavigateTo = () => {
+const getPush = () => {
   Object.assign(global.window, {
-    ___navigateTo: jest.fn(),
+    ___push: jest.fn(),
   })
 
-  return require(`../`).navigateTo
+  return require(`../`).push
+}
+
+const getReplace = () => {
+  Object.assign(global.window, {
+    ___replace: jest.fn(),
+  })
+
+  return require(`../`).replace
 }
 
 const getWithPrefix = (pathPrefix = ``) => {
@@ -135,10 +143,16 @@ describe(`<Link />`, () => {
     })
   })
 
-  it(`navigateTo is called with correct args`, () => {
-    getNavigateTo()(`/some-path`)
+  it(`push is called with correct args`, () => {
+    getPush()(`/some-path`)
+
+    expect(global.window.___push).toHaveBeenCalledWith(`/some-path`)
+  })
+
+  it(`replace is called with correct args`, () => {
+    getReplace()(`/some-path`)
 
-    expect(global.window.___navigateTo).toHaveBeenCalledWith(`/some-path`)
+    expect(global.window.___replace).toHaveBeenCalledWith(`/some-path`)
   })
 })
 
@@ -151,7 +165,7 @@ describe(`withRouter`, () => {
     })
 
     /*
-     * Same as above, settings a path perfix does not work because the 
+     * Same as above, settings a path perfix does not work because the
      * link module sets variables on first import
      */
     it.skip(`respects path prefix`, () => {

packages/gatsby-link/src/index.js

@@ -158,7 +158,7 @@ class GatsbyLink extends React.Component {
             // loaded before continuing.
             if (process.env.NODE_ENV === `production`) {
               e.preventDefault()
-              window.___navigateTo(this.state.to)
+              window.___push(this.state.to)
             }
           }
 
@@ -186,6 +186,12 @@ GatsbyLink.contextTypes = {
 
 export default GatsbyLink
 
-export const navigateTo = to => {
-  window.___navigateTo(to)
+export const push = to => {
+  window.___push(to)
 }
+
+export const replace = to => {
+  window.___replace(to)
+}
+
+export const navigateTo = push

packages/gatsby/cache-dir/production-app.js

@@ -51,7 +51,7 @@ apiRunnerAsync(`onClientEntry`).then(() => {
     require(`./register-service-worker`)
   }
 
-  const navigateTo = to => {
+  const navigate = (to, replace) => {
     const location = createLocation(to, null, null, history.location)
     let { pathname } = location
     const redirect = redirectMap[pathname]
@@ -72,13 +72,17 @@ apiRunnerAsync(`onClientEntry`).then(() => {
       return
     }
 
+    const historyNavigateFunc = replace
+      ? window.___history.replace
+      : window.___history.push
+
     // Listen to loading events. If page resources load before
     // a second, navigate immediately.
     function eventHandler(e) {
       if (e.page.path === loader.getPage(pathname).path) {
         emitter.off(`onPostLoadPageResources`, eventHandler)
         clearTimeout(timeoutId)
-        window.___history.push(location)
+        historyNavigateFunc(location)
       }
     }
 
@@ -87,13 +91,13 @@ apiRunnerAsync(`onClientEntry`).then(() => {
     const timeoutId = setTimeout(() => {
       emitter.off(`onPostLoadPageResources`, eventHandler)
       emitter.emit(`onDelayedLoadPageResources`, { pathname })
-      window.___history.push(location)
+      historyNavigateFunc(location)
     }, 1000)
 
     if (loader.getResourcesForPathname(pathname)) {
       // The resources are already loaded so off we go.
       clearTimeout(timeoutId)
-      window.___history.push(location)
+      historyNavigateFunc(location)
     } else {
       // They're not loaded yet so let's add a listener for when
       // they finish loading.
@@ -102,7 +106,9 @@ apiRunnerAsync(`onClientEntry`).then(() => {
   }
 
   // window.___loadScriptsForPath = loadScriptsForPath
-  window.___navigateTo = navigateTo
+  window.___push = (to) => navigate(to, false)
+  window.___replace = (to) => navigate(to, true)
+  window.___navigateTo = window.___push
 
   // Call onRouteUpdate on the initial page load.
   apiRunner(`onRouteUpdate`, {

packages/gatsby/cache-dir/root.js

@@ -134,11 +134,17 @@ const addNotFoundRoute = () => {
   }
 }
 
-const navigateTo = to => {
+const push = (to) => {
   window.___history.push(to)
 }
 
-window.___navigateTo = navigateTo
+const replace = (to) => {
+  window.___history.replace(to)
+}
+
+window.___push = push
+window.___replace = replace
+window.___navigateTo = push
 
 const AltRouter = apiRunner(`replaceRouterComponent`, { history })[0]
 const DefaultRouter = ({ children }) => (