feat(gatsby): trailingSlash config option

.circleci/config.yml

@@ -467,6 +467,17 @@ jobs:
       - store_test_results:
           path: e2e-tests/contentful/cypress/results
 
+  e2e_tests_trailing-slash:
+    <<: *e2e-executor
+    steps:
+      - e2e-test:
+          test_path: e2e-tests/trailing-slash
+          test_command: TODO
+      - store_artifacts:
+          path: e2e-tests/trailing-slash/__diff_output__
+      - store_test_results:
+          path: e2e-tests/trailing-slash/cypress/results
+
   starters_validate:
     executor: node
     steps:
@@ -669,6 +680,8 @@ workflows:
           <<: *e2e-test-workflow
       - e2e_tests_contentful:
           <<: *e2e-test-workflow
+      - e2e_tests_trailing-slash:
+          <<: *e2e-test-workflow
       - e2e_tests_development_runtime:
           <<: *e2e-test-workflow
       - e2e_tests_production_runtime:

.eslintrc.js

@@ -38,6 +38,7 @@ module.exports = {
     __ASSET_PREFIX__: true,
     _CFLAGS_: true,
     __GATSBY: true,
+    __TRAILING_SLASH__: true,
   },
   rules: {
     "@babel/no-unused-expressions": [

docs/docs/reference/config-files/gatsby-config.md

@@ -42,13 +42,16 @@ module.exports = {
 Options available to set within `gatsby-config.js` include:
 
 1. [siteMetadata](#sitemetadata) (object)
-2. [plugins](#plugins) (array)
-3. [flags](#flags) (object)
-4. [pathPrefix](#pathprefix) (string)
-5. [polyfill](#polyfill) (boolean)
-6. [mapping](#mapping-node-types) (object)
-7. [proxy](#proxy) (object)
-8. [developMiddleware](#advanced-proxying-with-developmiddleware) (function)
+1. [plugins](#plugins) (array)
+1. [flags](#flags) (object)
+1. [pathPrefix](#pathprefix) (string)
+1. [trailingSlash](#trailingslash) (string)
+1. [polyfill](#polyfill) (boolean)
+1. [mapping](#mapping-node-types) (object)
+1. [proxy](#proxy) (object)
+1. [developMiddleware](#advanced-proxying-with-developmiddleware) (function)
+1. [jsxRuntime](#jsxruntime) (string)
+1. [jsxImportSource](#jsximportsource) (string)
 
 ## siteMetadata
 
@@ -68,7 +71,7 @@ This way you can store it in one place, and pull it whenever you need it. If you
 
 See a full description and sample usage in [Gatsby.js Tutorial Part Four](/docs/tutorial/part-4/#data-in-gatsby).
 
-## Plugins
+## plugins
 
 Plugins are Node.js packages that implement Gatsby APIs. The config file accepts an array of plugins. Some plugins may need only to be listed by name, while others may take options (see the docs for individual plugins).
 
@@ -135,7 +138,7 @@ module.exports = {
 
 See more about [Plugins](/docs/plugins/) for more on utilizing plugins, and to see available official and community plugins.
 
-## Flags
+## flags
 
 Flags let sites enable experimental or upcoming changes that are still in testing or waiting for the next major release.
 
@@ -161,7 +164,17 @@ module.exports = {
 
 See more about [Adding a Path Prefix](/docs/how-to/previews-deploys-hosting/path-prefix/).
 
-## Polyfill
+## trailingSlash
+
+Configures the creation of URLs and whether to remove, append, or ignore trailing slashes.
+
+- `always`: Always add trailing slashes to each URL, e.g. `/x` to `/x/`.
+- `never`: Remove all trailing slashes on each URL, e.g. `/x/` to `/x`.
+- `ignore`: Don't automatically modify the URL
+
+Until Gatsby v4 it'll be set to `legacy` by default, in Gatsby v5 the default mode will be `always`.
+
+## polyfill
 
 Gatsby uses the ES6 Promise API. Because some browsers don't support this, Gatsby includes a Promise polyfill by default.
 

e2e-tests/trailing-slash/.gitignore

@@ -0,0 +1,13 @@
+# Project dependencies
+.cache
+node_modules
+yarn-error.log
+
+# Build assets
+/public
+.DS_Store
+/assets
+
+# Cypress output
+cypress/videos/
+cypress/screenshots/

e2e-tests/trailing-slash/README.md

@@ -0,0 +1,3 @@
+# trailing-slash E2E Test
+
+TODO

e2e-tests/trailing-slash/cypress.json

@@ -0,0 +1,3 @@
+{
+  "videoUploadOnPasses": false
+}

e2e-tests/trailing-slash/cypress/fixtures/example.json

@@ -0,0 +1,5 @@
+{
+  "name": "Using fixtures to represent data",
+  "email": "[email protected]",
+  "body": "Fixtures are a great way to mock data for responses to routes"
+}

e2e-tests/trailing-slash/cypress/integration/always.js

@@ -0,0 +1,71 @@
+describe(`always`, () => {
+  beforeEach(() => {
+    cy.visit(`/`).waitForRouteChange()
+  })
+ it(`page-creator without slash`, () => {
+  cy.getTestElement(`page-creator-without`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/page-2/`)
+ })
+ it(`page-creator with slash`, () => {
+  cy.getTestElement(`page-creator-with`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/page-2/`)
+ })
+ it(`create-page with slash`, () => {
+  cy.getTestElement(`create-page-with`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/create-page/with/`)
+ })
+ it(`create-page without slash`, () => {
+  cy.getTestElement(`create-page-without`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/create-page/without/`)
+ })
+ it(`fs-api with slash`, () => {
+  cy.getTestElement(`fs-api-with`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/fs-api/with/`)
+ })
+ it(`fs-api without slash`, () => {
+  cy.getTestElement(`fs-api-without`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/fs-api/without/`)
+ })
+ it(`hash`, () => {
+  cy.getTestElement(`hash`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/page-2/#anchor`)
+ })
+ it(`query-param`, () => {
+  cy.getTestElement(`query-param`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/page-2/?query_param=hello`)
+ })
+ it(`query-param-hash`, () => {
+  cy.getTestElement(`query-param-hash`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/page-2/?query_param=hello#anchor`)
+ })
+})
+
+if (Cypress.env(`IS_BUILD`)) {
+  describe(`always (direct visits)`, () => {
+    it(`page-creator`, () => {
+      cy.visit(`/page-2`).waitForRouteChange()
+        .assertRoute(`/page-2/`)
+    })
+    it(`create-page`, () => {
+      cy.visit(`/create-page/with/`).waitForRouteChange()
+        .assertRoute(`/create-page/with/`)
+      cy.visit(`/create-page/without`).waitForRouteChange()
+        .assertRoute(`/create-page/without/`)
+    })
+    it(`fs-api`, () => {
+      cy.visit(`/fs-api/with/`).waitForRouteChange()
+        .assertRoute(`/fs-api/with/`)
+      cy.visit(`/fs-api/without`).waitForRouteChange()
+        .assertRoute(`/fs-api/without/`)
+    })
+  })
+}

e2e-tests/trailing-slash/cypress/integration/ignore.js

@@ -0,0 +1,71 @@
+describe(`ignore`, () => {
+  beforeEach(() => {
+    cy.visit(`/`).waitForRouteChange()
+  })
+ it(`page-creator without slash`, () => {
+  cy.getTestElement(`page-creator-without`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/page-2/`)
+ })
+ it(`page-creator with slash`, () => {
+  cy.getTestElement(`page-creator-with`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/page-2/`)
+ })
+ it(`create-page with slash`, () => {
+  cy.getTestElement(`create-page-with`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/create-page/with/`)
+ })
+ it(`create-page without slash`, () => {
+  cy.getTestElement(`create-page-without`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/create-page/without`)
+ })
+ it(`fs-api with slash`, () => {
+  cy.getTestElement(`fs-api-with`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/fs-api/with/`)
+ })
+ it(`fs-api without slash`, () => {
+  cy.getTestElement(`fs-api-without`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/fs-api/without`)
+ })
+ it(`hash`, () => {
+  cy.getTestElement(`hash`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/page-2/#anchor`)
+ })
+ it(`query-param`, () => {
+  cy.getTestElement(`query-param`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/page-2/?query_param=hello`)
+ })
+ it(`query-param-hash`, () => {
+  cy.getTestElement(`query-param-hash`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/page-2/?query_param=hello#anchor`)
+ })
+})
+
+if (Cypress.env(`IS_BUILD`)) {
+  describe(`ignore (direct visits)`, () => {
+    it(`page-creator`, () => {
+      cy.visit(`/page-2`).waitForRouteChange()
+        .assertRoute(`/page-2/`)
+    })
+    it(`create-page`, () => {
+      cy.visit(`/create-page/with/`).waitForRouteChange()
+        .assertRoute(`/create-page/with/`)
+      cy.visit(`/create-page/without`).waitForRouteChange()
+        .assertRoute(`/create-page/without`)
+    })
+    it(`fs-api`, () => {
+      cy.visit(`/fs-api/with/`).waitForRouteChange()
+        .assertRoute(`/fs-api/with/`)
+      cy.visit(`/fs-api/without`).waitForRouteChange()
+        .assertRoute(`/fs-api/without`)
+    })
+  })
+}

e2e-tests/trailing-slash/cypress/integration/never.js

@@ -0,0 +1,71 @@
+describe(`never`, () => {
+  beforeEach(() => {
+    cy.visit(`/`).waitForRouteChange()
+  })
+ it(`page-creator without slash`, () => {
+  cy.getTestElement(`page-creator-without`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/page-2`)
+ })
+ it(`page-creator with slash`, () => {
+  cy.getTestElement(`page-creator-with`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/page-2`)
+ })
+ it(`create-page with slash`, () => {
+  cy.getTestElement(`create-page-with`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/create-page/with`)
+ })
+ it(`create-page without slash`, () => {
+  cy.getTestElement(`create-page-without`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/create-page/without`)
+ })
+ it(`fs-api with slash`, () => {
+  cy.getTestElement(`fs-api-with`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/fs-api/with`)
+ })
+ it(`fs-api without slash`, () => {
+  cy.getTestElement(`fs-api-without`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/fs-api/without`)
+ })
+ it(`hash`, () => {
+  cy.getTestElement(`hash`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/page-2#anchor`)
+ })
+ it(`query-param`, () => {
+  cy.getTestElement(`query-param`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/page-2?query_param=hello`)
+ })
+ it(`query-param-hash`, () => {
+  cy.getTestElement(`query-param-hash`).click()
+  cy.waitForRouteChange()
+    .assertRoute(`/page-2?query_param=hello#anchor`)
+ })
+})
+
+if (Cypress.env(`IS_BUILD`)) {
+  describe(`never (direct visits)`, () => {
+    it(`page-creator`, () => {
+      cy.visit(`/page-2`).waitForRouteChange()
+        .assertRoute(`/page-2`)
+    })
+    it(`create-page`, () => {
+      cy.visit(`/create-page/with/`).waitForRouteChange()
+        .assertRoute(`/create-page/with`)
+      cy.visit(`/create-page/without`).waitForRouteChange()
+        .assertRoute(`/create-page/without`)
+    })
+    it(`fs-api`, () => {
+      cy.visit(`/fs-api/with/`).waitForRouteChange()
+        .assertRoute(`/fs-api/with`)
+      cy.visit(`/fs-api/without`).waitForRouteChange()
+        .assertRoute(`/fs-api/without`)
+    })
+  })
+}

e2e-tests/trailing-slash/cypress/plugins/index.js

@@ -0,0 +1,17 @@
+// ***********************************************************
+// This example plugins/index.js can be used to load plugins
+//
+// You can change the location of this file or turn off loading
+// the plugins file with the 'pluginsFile' configuration option.
+//
+// You can read more here:
+// https://on.cypress.io/plugins-guide
+// ***********************************************************
+
+// This function is called when a project is opened or re-opened (e.g. due to
+// the project's config changing)
+
+module.exports = (on, config) => {
+  // `on` is used to hook into various events Cypress emits
+  // `config` is the resolved Cypress config
+}

e2e-tests/trailing-slash/cypress/support/commands.js

@@ -0,0 +1,3 @@
+Cypress.Commands.add(`assertRoute`, route => {
+  cy.url().should(`equal`, `${window.location.origin}${route}`)
+})

e2e-tests/trailing-slash/cypress/support/index.js

@@ -0,0 +1,2 @@
+import "gatsby-cypress"
+import "./commands"

e2e-tests/trailing-slash/gatsby-config.js

@@ -0,0 +1,11 @@
+console.log('env var', process.env.TRAILING_SLASH)
+
+module.exports = {
+  trailingSlash: process.env.TRAILING_SLASH || `legacy`,
+  siteMetadata: {
+    siteMetadata: {
+      siteUrl: `https://www.domain.tld`,
+      title: `Trailing Slash`,
+    },
+  },
+}