Change 'upsertPage' to 'createPage' and document it

docs/blog/gatsbygram-case-study/index.md

@@ -175,7 +175,7 @@ const slash = require(`slash`)
 // access to any information necessary to programatically
 // create pages.
 exports.createPages = ({ graphql, boundActionCreators }) => {
-  const { upsertPage } = boundActionCreators
+  const { createPage } = boundActionCreators
 
   return new Promise((resolve, reject) => {
     // The “graphql” function allows us to run arbitrary
@@ -214,9 +214,9 @@ exports.createPages = ({ graphql, boundActionCreators }) => {
         // each page's path.
         _.each(result.data.allPostsJson.edges, edge => {
           // Gatsby uses Redux to manage its internal state.
-          // Plugins and sites can use functions like "upsertPage"
+          // Plugins and sites can use functions like "createPage"
           // to interact with Gatsby.
-          upsertPage({
+          createPage({
             // Each page is required to have a `path` as well
             // as a template component. The `context` is
             // optional but is often necessary so the template

docs/docs/creating-and-modifying-pages.md

@@ -24,10 +24,10 @@ To do this, in your site's `gatsby-node.js` add code
 similar to the following:
 
 ```javascript
-// Implement the Gatsby API “onUpsertPage”. This is
+// Implement the Gatsby API “onCreatePage”. This is
 // called after every page is created.
-exports.onUpsertPage = ({ page, boundActionCreators }) => {
-  const { upsertPage, deletePage } = boundActionCreators
+exports.onCreatePage = ({ page, boundActionCreators }) => {
+  const { createPage, deletePage } = boundActionCreators
 
   return new Promise((resolve, reject) => {
     // Remove trailing slash
@@ -41,7 +41,7 @@ exports.onUpsertPage = ({ page, boundActionCreators }) => {
       deletePage({ path: oldPath })
 
       // Add the new page
-      upsertPage(page)
+      createPage(page)
     }
 
     resolve()
@@ -57,10 +57,10 @@ your app that lives under `/app/*`, you want to add code to your `gatsby-node.js
 like the following:
 
 ```javascript
-// Implement the Gatsby API “onUpsertPage”. This is
+// Implement the Gatsby API “onCreatePage”. This is
 // called after every page is created.
-exports.onUpsertPage = async ({ page, boundActionCreators }) => {
-  const { upsertPage } = boundActionCreators
+exports.onCreatePage = async ({ page, boundActionCreators }) => {
+  const { createPage } = boundActionCreators
 
   return new Promise((resolve, reject) => {
     // page.matchPath is a special key that's used for matching pages
@@ -69,7 +69,7 @@ exports.onUpsertPage = async ({ page, boundActionCreators }) => {
       page.matchPath = "/app/:path"
 
       // Update the page.
-      upsertPage(page)
+      createPage(page)
     }
 
     resolve()

docs/docs/migrating-from-v0-to-v1.md

@@ -158,7 +158,7 @@ Now we can create pages for each markdown file using our slug. In the same
 
 ```javascript
 exports.createPages = ({ graphql, boundActionCreators }) => {
-  const { upsertPage } = boundActionCreators
+  const { createPage } = boundActionCreators
 
   return new Promise((resolve, reject) => {
     const pages = []
@@ -187,7 +187,7 @@ exports.createPages = ({ graphql, boundActionCreators }) => {
 
         // Create blog posts pages.
         result.data.allMarkdownRemark.edges.forEach(edge => {
-          upsertPage({
+          createPage({
             path: edge.node.fields.slug, // required
             component: blogPost,
             context: {

examples/client-only-paths/gatsby-node.js

@@ -3,16 +3,16 @@ const Promise = require(`bluebird`)
 const path = require(`path`)
 const slash = require(`slash`)
 
-// Implement the Gatsby API “onUpsertPage”. This is
+// Implement the Gatsby API “onCreatePage”. This is
 // called after every page is created.
-exports.onUpsertPage = ({ page, boundActionCreators }) => {
-  const { upsertPage } = boundActionCreators
+exports.onCreatePage = ({ page, boundActionCreators }) => {
+  const { createPage } = boundActionCreators
   return new Promise((resolve, reject) => {
     // Make the front page match everything client side.
     // Normally your paths should be a bit more judicious.
     if (page.path === `/`) {
       page.matchPath = `/:path`
-      upsertPage(page)
+      createPage(page)
     }
     resolve()
   })

examples/gatsbygram/gatsby-node.js

@@ -9,7 +9,7 @@ const slash = require(`slash`)
 // access to any information necessary to programatically
 // create pages.
 exports.createPages = ({ graphql, boundActionCreators }) => {
-  const { upsertPage } = boundActionCreators
+  const { createPage } = boundActionCreators
 
   return new Promise((resolve, reject) => {
     // The “graphql” function allows us to run arbitrary
@@ -48,9 +48,9 @@ exports.createPages = ({ graphql, boundActionCreators }) => {
         // each page's path.
         _.each(result.data.allPostsJson.edges, edge => {
           // Gatsby uses Redux to manage its internal state.
-          // Plugins and sites can use functions like "upsertPage"
+          // Plugins and sites can use functions like "createPage"
           // to interact with Gatsby.
-          upsertPage({
+          createPage({
             // Each page is required to have a `path` as well
             // as a template component. The `context` is
             // optional but is often necessary so the template

examples/hn/gatsby-node.js

@@ -8,7 +8,7 @@ const slash = require(`slash`)
 // access to any information necessary to programatically
 // create pages.
 exports.createPages = ({ graphql, boundActionCreators }) => {
-  const { upsertPage } = boundActionCreators
+  const { createPage } = boundActionCreators
   return new Promise((resolve, reject) => {
     // The “graphql” function allows us to run arbitrary
     // queries against local Hacker News graphql schema. Think of
@@ -41,9 +41,9 @@ exports.createPages = ({ graphql, boundActionCreators }) => {
       // story page. We'll just use the HN story ID for the slug.
       _.each(result.data.allHnStory.edges, edge => {
         // Gatsby uses Redux to manage its internal state.
-        // Plugins and sites can use functions like "upsertPage"
+        // Plugins and sites can use functions like "createPage"
         // to interact with Gatsby.
-        upsertPage({
+        createPage({
           // Each page is required to have a `path` as well
           // as a template component. The `context` is
           // optional but is often necessary so the template

examples/no-trailing-slashes/gatsby-node.js

@@ -1,7 +1,7 @@
 const Promise = require(`bluebird`)
 
-exports.onUpsertPage = ({ page, boundActionCreators }) => {
-  const { upsertPage, deletePage } = boundActionCreators
+exports.onCreatePage = ({ page, boundActionCreators }) => {
+  const { createPage, deletePage } = boundActionCreators
 
   return new Promise((resolve, reject) => {
     // Remove trailing slash
@@ -12,7 +12,7 @@ exports.onUpsertPage = ({ page, boundActionCreators }) => {
       deletePage({ path: oldPath })
 
       // Add the new page
-      upsertPage(page)
+      createPage(page)
     }
 
     resolve()

examples/using-drupal/gatsby-node.js

@@ -8,7 +8,7 @@ const slash = require(`slash`)
 // access to any information necessary to programatically
 // create pages.
 exports.createPages = ({ graphql, boundActionCreators }) => {
-  const { upsertPage } = boundActionCreators
+  const { createPage } = boundActionCreators
   return new Promise((resolve, reject) => {
     // The “graphql” function allows us to run arbitrary
     // queries against the local Drupal graphql schema. Think of
@@ -38,9 +38,9 @@ exports.createPages = ({ graphql, boundActionCreators }) => {
       // article node. We'll just use the Drupal NID for the slug.
       _.each(result.data.allDrupalNodeArticle.edges, edge => {
         // Gatsby uses Redux to manage its internal state.
-        // Plugins and sites can use functions like "upsertPage"
+        // Plugins and sites can use functions like "createPage"
         // to interact with Gatsby.
-        upsertPage({
+        createPage({
           // Each page is required to have a `path` as well
           // as a template component. The `context` is
           // optional but is often necessary so the template

packages/gatsby-plugin-offline/src/gatsby-node.js

@@ -5,8 +5,8 @@ const _ = require(`lodash`)
 
 exports.createPages = ({ boundActionCreators }) => {
   if (process.env.NODE_ENV === `production`) {
-    const { upsertPage } = boundActionCreators
-    upsertPage({
+    const { createPage } = boundActionCreators
+    createPage({
       path: `/offline-plugin-app-shell-fallback/`,
       component: slash(path.resolve(`${__dirname}/app-shell.js`)),
     })

packages/gatsby/src/bootstrap/index.js

@@ -249,7 +249,7 @@ data
   if (!exists404html) {
     store.getState().pages.forEach(page => {
       if (page.path === `/404/`) {
-        boundActionCreators.upsertPage({
+        boundActionCreators.createPage({
           ...page,
           path: `/404.html`,
         })

packages/gatsby/src/bootstrap/internal-plugins/component-page-creator/gatsby-node.js

@@ -14,21 +14,21 @@ const createPath = require(`./create-path`)
 // underscored. Then create url w/ our path algorithm *unless* user
 // takes control of that page component in gatsby-node.
 exports.createPagesStateful = async ({ store, boundActionCreators }) => {
-  const { upsertPage, deletePage } = boundActionCreators
+  const { createPage, deletePage } = boundActionCreators
   const program = store.getState().program
   const pagesDirectory = systemPath.posix.join(program.directory, `/src/pages`)
   const exts = program.extensions.map(e => `${e.slice(1)}`).join(`,`)
 
   // Get initial list of files.
   let files = await glob(`${pagesDirectory}/**/?(${exts})`)
-  files.forEach(file => createPage(file, pagesDirectory, upsertPage))
+  files.forEach(file => _createPage(file, pagesDirectory, createPage))
 
   // Listen for new component pages to be added or removed.
   chokidar
     .watch(`${pagesDirectory}/**/*.{${exts}}`)
     .on(`add`, path => {
       if (!_.includes(files, path)) {
-        createPage(path, pagesDirectory, upsertPage)
+        _createPage(path, pagesDirectory, createPage)
         files.push(path)
       }
     })
@@ -40,7 +40,7 @@ exports.createPagesStateful = async ({ store, boundActionCreators }) => {
       })
     })
 }
-const createPage = (filePath, pagesDirectory, upsertPage) => {
+const _createPage = (filePath, pagesDirectory, createPage) => {
   // Filter out special components that shouldn't be made into
   // pages.
   if (!validatePath(systemPath.posix.relative(pagesDirectory, filePath))) {
@@ -54,7 +54,7 @@ const createPage = (filePath, pagesDirectory, upsertPage) => {
   }
 
   // Add page
-  upsertPage(page)
+  createPage(page)
 }
 
 const validatePath = path => {

packages/gatsby/src/bootstrap/internal-plugins/dev-404-page/gatsby-node.js

@@ -4,13 +4,13 @@ const fs = require(`fs-extra`)
 exports.createPages = async ({ store, boundActionCreators }) => {
   if (process.env.NODE_ENV !== `production`) {
     const { program } = store.getState()
-    const { upsertPage } = boundActionCreators
+    const { createPage } = boundActionCreators
     const currentPath = path.join(__dirname, `./raw_dev-404-page.js`)
     const newPath = path.join(program.directory, `.cache`, `dev-404-page.js`)
 
     fs.copySync(currentPath, newPath)
 
-    upsertPage({
+    createPage({
       component: newPath,
       path: `/dev-404-page/`,
     })

packages/gatsby/src/bootstrap/internal-plugins/internal-data-bridge/gatsby-node.js

@@ -101,7 +101,7 @@ exports.sourceNodes = ({ boundActionCreators, store }) => {
 
 const createPageId = path => `SitePage ${path}`
 
-exports.onUpsertPage = ({ page, boundActionCreators }) => {
+exports.onCreatePage = ({ page, boundActionCreators }) => {
   const { createNode } = boundActionCreators
 
   // Add page.

packages/gatsby/src/redux/__tests__/pages.js

@@ -3,7 +3,7 @@ const { actions } = require(`../actions`)
 
 describe(`Add pages`, () => {
   it(`allows you to add pages`, () => {
-    const action = actions.upsertPage({
+    const action = actions.createPage({
       path: `/hi/`,
       component: `/whatever/index.js`,
     })
@@ -13,7 +13,7 @@ describe(`Add pages`, () => {
   })
 
   it(`allows you to add pages with context`, () => {
-    const action = actions.upsertPage({
+    const action = actions.createPage({
       path: `/hi/`,
       component: `/whatever/index.js`,
       context: {
@@ -26,11 +26,11 @@ describe(`Add pages`, () => {
   })
 
   it(`allows you to add multiple pages`, () => {
-    const action = actions.upsertPage({
+    const action = actions.createPage({
       path: `/hi/`,
       component: `/whatever/index.js`,
     })
-    const action2 = actions.upsertPage({
+    const action2 = actions.createPage({
       path: `/hi/pizza/`,
       component: `/whatever/index.js`,
     })
@@ -41,13 +41,13 @@ describe(`Add pages`, () => {
   })
 
   it(`allows you to update existing pages (based on path)`, () => {
-    const action = actions.upsertPage({
+    const action = actions.createPage({
       path: `/hi/`,
       component: `/whatever/index.js`,
     })
 
     // Change the component
-    const action2 = actions.upsertPage({
+    const action2 = actions.createPage({
       path: `/hi/`,
       component: `/whatever2/index.js`,
     })
@@ -59,7 +59,7 @@ describe(`Add pages`, () => {
   })
 
   it(`allows you to delete paths`, () => {
-    const action = actions.upsertPage({
+    const action = actions.createPage({
       path: `/hi/`,
       component: `/whatever/index.js`,
     })

packages/gatsby/src/redux/actions.js

@@ -27,8 +27,27 @@ actions.deletePage = (page, plugin = ``) => {
 }
 
 const pascalCase = _.flow(_.camelCase, _.upperFirst)
-// "createPage"
-actions.upsertPage = (page, plugin = ``) => {
+/**
+ * Create a page. See https://gatsbyjs.org/docs/creating-and-modifying-pages/
+ * for detailed documenation about creating pages.
+ * @param {object} page a page object
+ * @param {string} page.path Any valid URL. Must start with a forward slash
+ * @param {string} page.component The absolute path to the component for this page
+ * @param {object} page.context Context data for this page. Passed as props
+ * to the component `this.props.pathContext` as well as to the graphql query
+ * as graphql arguments.
+ * @example
+ * createPage({
+ *   path: `/my-sweet-new-page/`,
+ *   component: path.resolve('./src/templates/my-sweet-new-page.js`),
+ *   // context gets passed in as props to the page as well
+ *   // as into the page/template's GraphQL query.
+ *   context: {
+ *     id: `123456`,
+ *   },
+ * })
+ */
+actions.createPage = (page, plugin = ``) => {
   page.componentChunkName = layoutComponentChunkName(page.component)
 
   let jsonName = `${_.kebabCase(page.path)}.json`
@@ -54,6 +73,11 @@ actions.upsertPage = (page, plugin = ``) => {
     return
   }
 
+  // If the path doesn't have an initial forward slash, add it.
+  if (page.path[0] !== `/`) {
+    page.path = `/` + page.path
+  }
+
   return {
     type: `UPSERT_PAGE`,
     plugin,

packages/gatsby/src/redux/plugin-runner.js

@@ -10,5 +10,5 @@ emitter.on(`CREATE_NODE`, action => {
 
 emitter.on(`UPSERT_PAGE`, action => {
   const page = action.payload
-  apiRunnerNode(`onUpsertPage`, { page }, action.plugin.name)
+  apiRunnerNode(`onCreatePage`, { page }, action.plugin.name)
 })

packages/gatsby/src/utils/api-runner-node.js

@@ -49,7 +49,7 @@ const runAPI = (plugin, api, args) => {
 
   const gatsbyNode = require(`${plugin.resolve}/gatsby-node`)
   if (gatsbyNode[api]) {
-    // if (!_.includes([`onNodeCreate`, `onUpsertPage`], api)) {
+    // if (!_.includes([`onNodeCreate`, `onCreatePage`], api)) {
     // console.log(`calling api handler in ${plugin.resolve} for api ${api}`)
     // }
     const result = gatsbyNode[api](
@@ -89,7 +89,7 @@ module.exports = async (api, args = {}, pluginSource) =>
     // Break infinite loops.
     // Sometimes a plugin will implement an API and call an
     // action which will trigger the same API being called.
-    // "onUpsertPage" is the only example right now.
+    // "onCreatePage" is the only example right now.
     // In these cases, we should avoid calling the originating plugin
     // again.
     let noSourcePluginPlugins = filteredPlugins