From 2bd9bdce129af33b73ba91473c40e8b8301150fa Mon Sep 17 00:00:00 2001
From: Bart Nagel <bart@tremby.net>
Date: Sat, 16 Jun 2018 15:39:26 -0700
Subject: [PATCH 1/3] gatsby-link: add push (deprecates navigateTo) and replace

This addresses gatsbyjs/gatsby#5910
---
 packages/gatsby-link/index.d.ts               |  4 +++
 packages/gatsby-link/src/__tests__/index.js   | 26 ++++++++++++++-----
 packages/gatsby-link/src/index.js             | 16 ++++++++++--
 packages/gatsby/README.md                     |  6 ++---
 .../src/cache-dir/gatsby-browser-entry.js     |  6 +++--
 .../gatsby/src/cache-dir/production-app.js    | 15 +++++++----
 packages/gatsby/src/cache-dir/root.js         |  9 +++++--
 7 files changed, 62 insertions(+), 20 deletions(-)

diff --git a/packages/gatsby-link/index.d.ts b/packages/gatsby-link/index.d.ts
index cd97a84ec0065..ea3f42a5168e4 100644
--- a/packages/gatsby-link/index.d.ts
+++ b/packages/gatsby-link/index.d.ts
@@ -8,6 +8,10 @@ export interface GatsbyLinkProps extends NavLinkProps {
   style?:any;
 }
 
+export const push: (to: LocationDescriptor) => void;
+export const replace: (to: LocationDescriptor) => void;
+
+// TODO: Remove navigateTo for Gatsby v3
 export const navigateTo: (to: LocationDescriptor) => void;
 
 export const withPrefix: (path: string) => string;
diff --git a/packages/gatsby-link/src/__tests__/index.js b/packages/gatsby-link/src/__tests__/index.js
index d146adf37faa8..7dfe945691237 100644
--- a/packages/gatsby-link/src/__tests__/index.js
+++ b/packages/gatsby-link/src/__tests__/index.js
@@ -13,12 +13,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 = ``) => {
@@ -113,10 +121,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`)
   })
 })
 
diff --git a/packages/gatsby-link/src/index.js b/packages/gatsby-link/src/index.js
index 2faf0deb04542..26fe3adc474d7 100644
--- a/packages/gatsby-link/src/index.js
+++ b/packages/gatsby-link/src/index.js
@@ -153,7 +153,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)
             }
           }
 
@@ -180,6 +180,18 @@ GatsbyLink.contextTypes = {
 
 export default polyfill(GatsbyLink)
 
+export const push = to => {
+  window.___push(to)
+}
+
+export const replace = to => {
+  window.___replace(to)
+}
+
+// TODO: Remove navigateTo for Gatsby v3
 export const navigateTo = to => {
-  window.___navigateTo(to)
+  console.warn(
+    `The "navigateTo" method is now deprecated and will be removed in Gatsby v3. Please use "push" instead.`
+  )
+  return push(to)
 }
diff --git a/packages/gatsby/README.md b/packages/gatsby/README.md
index 0cadf91a256a1..e2fc8b6e917cd 100644
--- a/packages/gatsby/README.md
+++ b/packages/gatsby/README.md
@@ -66,13 +66,13 @@ render () {
 ### Programmatic navigation
 
 For cases when you can only use event handlers for navigation, you can use
-`navigateTo`:
+`push` (which uses `history.push`) or `replace` (which uses `history.replace`):
 
 ```jsx
-import { navigateTo } from "gatsby"
+import { push } from "gatsby"
 
 render () {
-  <div onClick={ () => navigateTo('/example')}>
+  <div onClick={ () => push('/example')}>
     <p>Example</p>
   </div>
 }
diff --git a/packages/gatsby/src/cache-dir/gatsby-browser-entry.js b/packages/gatsby/src/cache-dir/gatsby-browser-entry.js
index 44cea4df05f30..1d7e22d5a9c8f 100644
--- a/packages/gatsby/src/cache-dir/gatsby-browser-entry.js
+++ b/packages/gatsby/src/cache-dir/gatsby-browser-entry.js
@@ -1,6 +1,6 @@
 import React from "react"
 import PropTypes from "prop-types"
-import Link, { withPrefix, navigateTo } from "gatsby-link"
+import Link, { withPrefix, push, replace, navigateTo } from "gatsby-link"
 import pages from "./pages.json"
 import loader from "./loader"
 import JSONStore from "./json-store"
@@ -48,7 +48,9 @@ StaticQuery.propTypes = {
 export {
   Link,
   withPrefix,
-  navigateTo,
+  push,
+  replace,
+  navigateTo, // TODO: remove navigateTo for v3
   StaticQueryContext,
   StaticQuery,
   PageRenderer,
diff --git a/packages/gatsby/src/cache-dir/production-app.js b/packages/gatsby/src/cache-dir/production-app.js
index 2fd704990eb21..37f56b50f2a20 100644
--- a/packages/gatsby/src/cache-dir/production-app.js
+++ b/packages/gatsby/src/cache-dir/production-app.js
@@ -52,7 +52,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]
@@ -73,13 +73,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)
       }
     }
 
@@ -88,13 +92,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.
@@ -103,7 +107,8 @@ apiRunnerAsync(`onClientEntry`).then(() => {
   }
 
   // window.___loadScriptsForPath = loadScriptsForPath
-  window.___navigateTo = navigateTo
+  window.___push = to => navigate(to, false)
+  window.___replace = to => navigate(to, true)
 
   // Call onRouteUpdate on the initial page load.
   apiRunner(`onRouteUpdate`, {
diff --git a/packages/gatsby/src/cache-dir/root.js b/packages/gatsby/src/cache-dir/root.js
index 2b18079d36904..08e5e2f156169 100644
--- a/packages/gatsby/src/cache-dir/root.js
+++ b/packages/gatsby/src/cache-dir/root.js
@@ -112,11 +112,16 @@ function shouldUpdateScroll(prevRouterProps, { location: { pathname } }) {
   return true
 }
 
-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
 
 const AltRouter = apiRunner(`replaceRouterComponent`, { history })[0]
 

From c3a4b66a47779c1caf5ff02dc3bf2b39418bbb52 Mon Sep 17 00:00:00 2001
From: Bart Nagel <bart@tremby.net>
Date: Sat, 16 Jun 2018 15:40:30 -0700
Subject: [PATCH 2/3] Use push rather than (deprecated) navigateTo throughout

---
 examples/gatsbygram/src/components/modal.js          | 12 ++++++------
 packages/gatsby-plugin-catch-links/README.md         |  2 +-
 .../gatsby-plugin-catch-links/src/gatsby-browser.js  |  4 ++--
 www/src/components/layout.js                         |  6 +++---
 www/src/components/search-form.js                    |  4 ++--
 www/src/templates/template-showcase-details.js       |  6 +++---
 6 files changed, 17 insertions(+), 17 deletions(-)

diff --git a/examples/gatsbygram/src/components/modal.js b/examples/gatsbygram/src/components/modal.js
index cfbf230699a6d..37dc537975aad 100644
--- a/examples/gatsbygram/src/components/modal.js
+++ b/examples/gatsbygram/src/components/modal.js
@@ -6,7 +6,7 @@ import Close from "react-icons/lib/md/close"
 import findIndex from "lodash/findIndex"
 import mousetrap from "mousetrap"
 import * as PropTypes from "prop-types"
-import { navigateTo, StaticQuery } from "gatsby"
+import { push, StaticQuery } from "gatsby"
 
 import { rhythm } from "../utils/typography"
 
@@ -55,7 +55,7 @@ class GatsbyGramModal extends React.Component {
       } else {
         nextPost = posts[currentIndex + 1]
       }
-      navigateTo(`/${nextPost.id}/`)
+      push(`/${nextPost.id}/`)
     }
   }
 
@@ -72,7 +72,7 @@ class GatsbyGramModal extends React.Component {
       } else {
         previousPost = posts[currentIndex - 1]
       }
-      navigateTo(`/${previousPost.id}/`)
+      push(`/${previousPost.id}/`)
     }
   }
 
@@ -97,7 +97,7 @@ class GatsbyGramModal extends React.Component {
           return (
             <Modal
               isOpen={this.props.isOpen}
-              onRequestClose={() => navigateTo(`/`)}
+              onRequestClose={() => push(`/`)}
               style={{
                 overlay: {
                   position: `fixed`,
@@ -123,7 +123,7 @@ class GatsbyGramModal extends React.Component {
               contentLabel="Modal"
             >
               <div
-                onClick={() => navigateTo(`/`)}
+                onClick={() => push(`/`)}
                 css={{
                   display: `flex`,
                   position: `relative`,
@@ -164,7 +164,7 @@ class GatsbyGramModal extends React.Component {
                 </div>
                 <Close
                   data-testid="modal-close"
-                  onClick={() => navigateTo(`/`)}
+                  onClick={() => push(`/`)}
                   css={{
                     cursor: `pointer`,
                     color: `rgba(255,255,255,0.8)`,
diff --git a/packages/gatsby-plugin-catch-links/README.md b/packages/gatsby-plugin-catch-links/README.md
index cfd40b31d88ca..631bf8fa9246f 100644
--- a/packages/gatsby-plugin-catch-links/README.md
+++ b/packages/gatsby-plugin-catch-links/README.md
@@ -7,7 +7,7 @@ For instance, in a markdown file with relative links (transformed
 to `a` tags by 
 [`gatsby-transformer-remark`](/packages/gatsby-transformer-remark/)), this 
 plugin replaces the default link behaviour 
-with that of [`gatsby-link`'s `navigateTo`](https://www.gatsbyjs.org/packages/gatsby-link/#programmatic-navigation), preserving the 
+with that of [`gatsby-link`'s `push`](https://www.gatsbyjs.org/packages/gatsby-link/#programmatic-navigation), preserving the 
 SPA-like page change without reload.
 
 Check out the [_Using Remark_ example](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-remark) to see this plugin in action.
diff --git a/packages/gatsby-plugin-catch-links/src/gatsby-browser.js b/packages/gatsby-plugin-catch-links/src/gatsby-browser.js
index a2074710a9a8e..526fef49a4cd8 100644
--- a/packages/gatsby-plugin-catch-links/src/gatsby-browser.js
+++ b/packages/gatsby-plugin-catch-links/src/gatsby-browser.js
@@ -1,9 +1,9 @@
-import { navigateTo } from "gatsby-link"
+import { push } from "gatsby-link"
 
 import catchLinks from "./catch-links"
 
 exports.onClientEntry = () => {
   catchLinks(window, href => {
-    navigateTo(href)
+    push(href)
   })
 }
diff --git a/www/src/components/layout.js b/www/src/components/layout.js
index 37a52e04e78f0..703b77839f2d5 100644
--- a/www/src/components/layout.js
+++ b/www/src/components/layout.js
@@ -3,7 +3,7 @@ import Modal from "react-modal"
 import Helmet from "react-helmet"
 import MdClose from "react-icons/lib/md/close"
 
-import { navigateTo, PageRenderer } from "gatsby"
+import { push, PageRenderer } from "gatsby"
 
 import presets, { colors } from "../utils/presets"
 import Navigation from "../components/navigation"
@@ -32,7 +32,7 @@ class DefaultLayout extends React.Component {
   }
 
   handleCloseModal() {
-    navigateTo(this.props.modalBackgroundPath)
+    push(this.props.modalBackgroundPath)
   }
 
   componentDidMount() {
@@ -104,7 +104,7 @@ class DefaultLayout extends React.Component {
                 backgroundColor: `rgba(255, 255, 255, 0.95)`,
               },
             }}
-            onRequestClose={() => navigateTo(this.props.modalBackgroundPath)}
+            onRequestClose={() => push(this.props.modalBackgroundPath)}
             contentLabel="Site Details Modal"
           >
             <div
diff --git a/www/src/components/search-form.js b/www/src/components/search-form.js
index ab27d52ab93a5..03eded64468a2 100644
--- a/www/src/components/search-form.js
+++ b/www/src/components/search-form.js
@@ -1,6 +1,6 @@
 import React, { Component } from "react"
 import PropTypes from "prop-types"
-import { navigateTo } from "gatsby"
+import { push } from "gatsby"
 import { rhythm } from "../utils/typography"
 
 import presets, { colors } from "../utils/presets"
@@ -253,7 +253,7 @@ class SearchForm extends Component {
     const a = document.createElement(`a`)
     a.href = e._args[0].url
     this.searchInput.blur()
-    navigateTo(`${a.pathname}${a.hash}`)
+    push(`${a.pathname}${a.hash}`)
   }
 
   componentDidMount() {
diff --git a/www/src/templates/template-showcase-details.js b/www/src/templates/template-showcase-details.js
index 666efc90d1a93..8763bd983be46 100644
--- a/www/src/templates/template-showcase-details.js
+++ b/www/src/templates/template-showcase-details.js
@@ -5,7 +5,7 @@ import hex2rgba from "hex2rgba"
 
 import presets, { colors } from "../utils/presets"
 import { options, scale, rhythm } from "../utils/typography"
-import { navigateTo, Link } from "gatsby"
+import { push, Link } from "gatsby"
 import Layout from "../components/layout"
 import ShareMenu from "../components/share-menu"
 
@@ -59,7 +59,7 @@ class ShowcaseTemplate extends React.Component {
 
     const nextSite = this.getNext()
 
-    navigateTo({
+    push({
       pathname: nextSite.fields.slug,
       state: {
         isModal: location.state.isModal,
@@ -82,7 +82,7 @@ class ShowcaseTemplate extends React.Component {
     const { location } = this.props
 
     const previousSite = this.getPrevious()
-    navigateTo({
+    push({
       pathname: previousSite.fields.slug,
       state: {
         isModal: location.state.isModal,

From a5afc3a24aada71db7b7d89d51fe788e511b876b Mon Sep 17 00:00:00 2001
From: Kyle Mathews <mathews.kyle@gmail.com>
Date: Sat, 16 Jun 2018 16:41:27 -0700
Subject: [PATCH 3/3] Document change

---
 docs/docs/migrating-from-v1-to-v2.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md
index 80bd6149e77c4..af12148da9f32 100644
--- a/docs/docs/migrating-from-v1-to-v2.md
+++ b/docs/docs/migrating-from-v1-to-v2.md
@@ -24,6 +24,7 @@ This is a reference for upgrading your site from Gatsby v1 to Gatsby v2. While t
 - [Remove explicit polyfills](#remove-explicit-polyfills)
 - [Change `modifyBabelrc` to `onCreateBabelConfig`](#change-modifybabelrc-to-oncreatebabelconfig)
 - [Change `modifyWebpackConfig` to `onCreateWebpackConfig`](#change-modifywebpackconfig-to-oncreatewebpackconfig)
+- [Change `navigateTo` to `push`](#change-navigateto-to-push)
 - [Remove inlined CSS in `html.js`](#remove-inlined-css-in-htmljs)
 - [Only allow defined keys on node.internal object](#only-allow-defined-keys-on-the-node-internal-object)
 - [Import `graphql` types from `gatsby/graphql`](#import-graphql-types-from-gatsbygraphql)
@@ -403,6 +404,26 @@ Note usage of the new [`setWebpackConfig` action](/docs/actions/#setWebpackConfi
 
 See [Gatsby's webpack docs for more details](/docs/add-custom-webpack-config) about configuring webpack.
 
+## Change `navigateTo` to `push`
+
+The `navigateTo` method in `gatsby-link` was renamed to `push` so as to mirror the browser history function. We also
+added support for using `replace` as well.
+
+In addition to the name change, `gatsby-link` is now directly exported from the `gatsby` package.
+
+```diff
+import React from "react"
+- import { navigateTo } from "gatsby-link"
++ import { push } from "gatsby"
+
+// Don't use push with an onClick btw :-)
+// Generally just use the `<Link>` component.
+export default props => (
+-  <div onClick={() => navigateTo(`/`)}>Click to go to home</div>
++  <div onClick={() => push(`/`)}>Click to go to home</div>
+)
+```
+
 ## Remove inlined CSS in `html.js`
 
 Gatsby v2 automatically inlines CSS. You can remove any custom CSS inlining from your custom `html.js`.