feat(gatsby): trailingSlash config option

.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.
 

jest.config.js

@@ -46,6 +46,7 @@ module.exports = {
     "^weak-lru-cache$": `<rootDir>/node_modules/weak-lru-cache/dist/index.cjs`,
     "^ordered-binary$": `<rootDir>/node_modules/ordered-binary/dist/index.cjs`,
     "^msgpackr$": `<rootDir>/node_modules/msgpackr/dist/node.cjs`,
+    "^gatsby-page-utils/(.*)$": `gatsby-page-utils/dist/$1`, // Workaround for https://github.com/facebook/jest/issues/9771
   },
   snapshotSerializers: [`jest-serializer-path`],
   collectCoverageFrom: coverageDirs,

packages/gatsby-link/package.json

@@ -9,6 +9,7 @@
   "dependencies": {
     "@babel/runtime": "^7.15.4",
     "@types/reach__router": "^1.3.9",
+    "gatsby-page-utils": "^2.5.0-next.0",
     "prop-types": "^15.7.2"
   },
   "devDependencies": {

packages/gatsby-link/src/__tests__/rewrite-link-path.js

@@ -0,0 +1,57 @@
+import { rewriteLinkPath } from "../rewrite-link-path"
+
+beforeEach(() => {
+  global.__TRAILING_SLASH__ = ``
+})
+
+const getRewriteLinkPath = (option = `legacy`) => {
+  global.__TRAILING_SLASH__ = option
+  return rewriteLinkPath
+}
+
+describe(`rewriteLinkPath`, () => {
+  it(`handles legacy option`, () => {
+    expect(getRewriteLinkPath()(`/path`, `/`)).toBe(`/path`)
+    expect(getRewriteLinkPath()(`/path/`, `/`)).toBe(`/path/`)
+    expect(getRewriteLinkPath()(`/path#hash`, `/`)).toBe(`/path#hash`)
+    expect(getRewriteLinkPath()(`/path?query_param=hello`, `/`)).toBe(
+      `/path?query_param=hello`
+    )
+    expect(getRewriteLinkPath()(`/path?query_param=hello#anchor`, `/`)).toBe(
+      `/path?query_param=hello#anchor`
+    )
+  })
+  it(`handles always option`, () => {
+    expect(getRewriteLinkPath(`always`)(`/path`, `/`)).toBe(`/path/`)
+    expect(getRewriteLinkPath(`always`)(`/path/`, `/`)).toBe(`/path/`)
+    expect(getRewriteLinkPath(`always`)(`/path#hash`, `/`)).toBe(`/path/#hash`)
+    expect(getRewriteLinkPath(`always`)(`/path?query_param=hello`, `/`)).toBe(
+      `/path/?query_param=hello`
+    )
+    expect(
+      getRewriteLinkPath(`always`)(`/path?query_param=hello#anchor`, `/`)
+    ).toBe(`/path/?query_param=hello#anchor`)
+  })
+  it(`handles never option`, () => {
+    expect(getRewriteLinkPath(`never`)(`/path`, `/`)).toBe(`/path`)
+    expect(getRewriteLinkPath(`never`)(`/path/`, `/`)).toBe(`/path`)
+    expect(getRewriteLinkPath(`never`)(`/path/#hash`, `/`)).toBe(`/path#hash`)
+    expect(getRewriteLinkPath(`never`)(`/path/?query_param=hello`, `/`)).toBe(
+      `/path?query_param=hello`
+    )
+    expect(
+      getRewriteLinkPath(`never`)(`/path/?query_param=hello#anchor`, `/`)
+    ).toBe(`/path?query_param=hello#anchor`)
+  })
+  it(`handles ignore option`, () => {
+    expect(getRewriteLinkPath(`ignore`)(`/path`, `/`)).toBe(`/path`)
+    expect(getRewriteLinkPath(`ignore`)(`/path/`, `/`)).toBe(`/path/`)
+    expect(getRewriteLinkPath(`ignore`)(`/path#hash`, `/`)).toBe(`/path#hash`)
+    expect(getRewriteLinkPath(`ignore`)(`/path?query_param=hello`, `/`)).toBe(
+      `/path?query_param=hello`
+    )
+    expect(
+      getRewriteLinkPath(`ignore`)(`/path?query_param=hello#anchor`, `/`)
+    ).toBe(`/path?query_param=hello#anchor`)
+  })
+})

packages/gatsby-link/src/index.js

@@ -1,14 +1,12 @@
 import PropTypes from "prop-types"
 import React from "react"
 import { Link, Location } from "@gatsbyjs/reach-router"
-import { resolve } from "@gatsbyjs/reach-router/lib/utils"
-
 import { parsePath } from "./parse-path"
+import { isLocalLink } from "./is-local-link"
+import { rewriteLinkPath } from "./rewrite-link-path"
 
 export { parsePath }
 
-const isAbsolutePath = path => path?.startsWith(`/`)
-
 export function withPrefix(path, prefix = getGlobalBasePrefix()) {
   if (!isLocalLink(path)) {
     return path
@@ -39,34 +37,10 @@ const getGlobalBasePrefix = () =>
       : undefined
     : __BASE_PATH__
 
-const isLocalLink = path =>
-  path &&
-  !path.startsWith(`http://`) &&
-  !path.startsWith(`https://`) &&
-  !path.startsWith(`//`)
-
 export function withAssetPrefix(path) {
   return withPrefix(path, getGlobalPathPrefix())
 }
 
-function absolutify(path, current) {
-  // If it's already absolute, return as-is
-  if (isAbsolutePath(path)) {
-    return path
-  }
-  return resolve(path, current)
-}
-
-const rewriteLinkPath = (path, relativeTo) => {
-  if (typeof path === `number`) {
-    return path
-  }
-  if (!isLocalLink(path)) {
-    return path
-  }
-  return isAbsolutePath(path) ? withPrefix(path) : absolutify(path, relativeTo)
-}
-
 const NavLinkPropTypes = {
   activeClassName: PropTypes.string,
   activeStyle: PropTypes.object,

packages/gatsby-link/src/is-local-link.js

@@ -0,0 +1,5 @@
+export const isLocalLink = path =>
+  path &&
+  !path.startsWith(`http://`) &&
+  !path.startsWith(`https://`) &&
+  !path.startsWith(`//`)

packages/gatsby-link/src/rewrite-link-path.js

@@ -0,0 +1,45 @@
+import { resolve } from "@gatsbyjs/reach-router/lib/utils"
+// Specific import to treeshake Node.js stuff
+import { applyTrailingSlashOption } from "gatsby-page-utils/apply-trailing-slash-option"
+import { parsePath } from "./parse-path"
+import { isLocalLink } from "./is-local-link"
+import { withPrefix } from "."
+
+const isAbsolutePath = path => path?.startsWith(`/`)
+
+const getGlobalTrailingSlash = () =>
+  process.env.NODE_ENV !== `production`
+    ? typeof __TRAILING_SLASH__ !== `undefined`
+      ? __TRAILING_SLASH__
+      : undefined
+    : __TRAILING_SLASH__
+
+function absolutify(path, current) {
+  // If it's already absolute, return as-is
+  if (isAbsolutePath(path)) {
+    return path
+  }
+  return resolve(path, current)
+}
+
+export const rewriteLinkPath = (path, relativeTo) => {
+  const { pathname, search, hash } = parsePath(path)
+  const option = getGlobalTrailingSlash()
+  let adjustedPath = path
+
+  if (typeof path === `number`) {
+    return path
+  }
+  if (!isLocalLink(path)) {
+    return path
+  }
+
+  if (option === `always` || option === `never`) {
+    const output = applyTrailingSlashOption(pathname, option)
+    adjustedPath = `${output}${search}${hash}`
+  }
+
+  return isAbsolutePath(adjustedPath)
+    ? withPrefix(adjustedPath)
+    : absolutify(adjustedPath, relativeTo)
+}

packages/gatsby-page-utils/package.json

@@ -4,6 +4,10 @@
   "description": "Gatsby library that helps creating pages",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./*": "./dist/*.js"
+  },
   "scripts": {
     "build": "babel src --out-dir dist/ --ignore \"**/__tests__\" --extensions \".ts\"",
     "typegen": "rimraf \"dist/**/*.d.ts\" && tsc --emitDeclarationOnly --declaration --declarationDir dist/",

packages/gatsby-page-utils/src/__tests__/apply-trailing-slash-option.ts

@@ -0,0 +1,50 @@
+import { applyTrailingSlashOption } from "../apply-trailing-slash-option"
+
+describe(`applyTrailingSlashOption`, () => {
+  const indexPage = `/`
+  const withoutSlash = `/nested/path`
+  const withSlash = `/nested/path/`
+
+  it(`returns / for root index page`, () => {
+    expect(applyTrailingSlashOption(indexPage)).toEqual(indexPage)
+  })
+  describe(`always`, () => {
+    it(`should add trailing slash`, () => {
+      expect(applyTrailingSlashOption(withoutSlash, `always`)).toEqual(
+        withSlash
+      )
+    })
+    it(`should leave existing slash`, () => {
+      expect(applyTrailingSlashOption(withSlash, `always`)).toEqual(withSlash)
+    })
+  })
+  describe(`never`, () => {
+    it(`should leave root index`, () => {
+      expect(applyTrailingSlashOption(indexPage, `never`)).toEqual(indexPage)
+    })
+    it(`should remove trailing slashes`, () => {
+      expect(applyTrailingSlashOption(withSlash, `never`)).toEqual(withoutSlash)
+    })
+    it(`should leave non-trailing paths`, () => {
+      expect(applyTrailingSlashOption(withoutSlash, `never`)).toEqual(
+        withoutSlash
+      )
+    })
+  })
+  describe(`ignore`, () => {
+    it(`should return input (trailing)`, () => {
+      expect(applyTrailingSlashOption(withSlash, `ignore`)).toEqual(withSlash)
+    })
+    it(`should return input (non-trailing)`, () => {
+      expect(applyTrailingSlashOption(withoutSlash, `ignore`)).toEqual(
+        withoutSlash
+      )
+    })
+  })
+  describe(`legacy`, () => {
+    it(`should do nothing`, () => {
+      expect(applyTrailingSlashOption(withSlash)).toEqual(withSlash)
+      expect(applyTrailingSlashOption(withoutSlash)).toEqual(withoutSlash)
+    })
+  })
+})

packages/gatsby-page-utils/src/__tests__/create-path.ts

@@ -1,9 +1,39 @@
 import { createPath } from "../create-path"
 
+const withoutSlash = `/nested/path`
+const withSlash = `/nested/path/`
+
 describe(`create-path`, () => {
   it(`should create unix paths`, () => {
     const paths = [`b/c/de`, `bee`, `b/d/c/`]
 
     expect(paths.map(p => createPath(p))).toMatchSnapshot()
   })
+  it(`should handle index page`, () => {
+    expect(createPath(`/index/`)).toEqual(`/`)
+    expect(createPath(`/index`)).toEqual(`/`)
+  })
+  it(`should output with trailing slash in legacy mode`, () => {
+    expect(createPath(withoutSlash)).toEqual(withSlash)
+    expect(createPath(`/index/`)).toEqual(`/`)
+    expect(createPath(`/index`)).toEqual(`/`)
+  })
+  it(`should add trailing slash with always mode`, () => {
+    expect(createPath(withoutSlash, `always`)).toEqual(withSlash)
+    expect(createPath(withSlash, `always`)).toEqual(withSlash)
+    expect(createPath(`/index/`, `always`)).toEqual(`/`)
+    expect(createPath(`/index`, `always`)).toEqual(`/`)
+  })
+  it(`should not add trailing slash with never mode`, () => {
+    expect(createPath(withSlash, `never`)).toEqual(withoutSlash)
+    expect(createPath(withoutSlash, `never`)).toEqual(withoutSlash)
+    expect(createPath(`/index/`, `never`)).toEqual(`/`)
+    expect(createPath(`/index`, `never`)).toEqual(`/`)
+  })
+  it(`should not change anything in ignore mode`, () => {
+    expect(createPath(withSlash, `ignore`)).toEqual(withSlash)
+    expect(createPath(withoutSlash, `ignore`)).toEqual(withoutSlash)
+    expect(createPath(`/index/`, `ignore`)).toEqual(`/`)
+    expect(createPath(`/index`, `ignore`)).toEqual(`/`)
+  })
 })

packages/gatsby-page-utils/src/apply-trailing-slash-option.ts

@@ -0,0 +1,21 @@
+// TODO(v5): Remove legacy setting and default to "always"
+export type TrailingSlash = "always" | "never" | "ignore" | "legacy"
+
+export const applyTrailingSlashOption = (
+  input: string,
+  option: TrailingSlash = `legacy`
+): string => {
+  const hasHtmlSuffix = input.endsWith(`.html`)
+  if (input === `/`) return input
+  if (hasHtmlSuffix) {
+    option = `never`
+  }
+  if (option === `always`) {
+    return input.endsWith(`/`) ? input : `${input}/`
+  }
+  if (option === `never`) {
+    return input.endsWith(`/`) ? input.slice(0, -1) : input
+  }
+
+  return input
+}

packages/gatsby-page-utils/src/create-path.ts

@@ -1,8 +1,26 @@
 import { parse, posix } from "path"
+import {
+  applyTrailingSlashOption,
+  TrailingSlash,
+} from "./apply-trailing-slash-option"
 
-export function createPath(filePath: string): string {
+export function createPath(
+  filePath: string,
+  option: TrailingSlash = `legacy`
+): string {
   const { dir, name } = parse(filePath)
   const parsedName = name === `index` ? `` : name
+  const hasHtmlSuffix = parsedName.endsWith(`.html`)
 
-  return posix.join(`/`, dir, parsedName, `/`)
+  if (hasHtmlSuffix) {
+    option = `never`
+  }
+
+  const hasTrailing = filePath.endsWith(`/`)
+  const parsedNameWithSlash = `${parsedName}${
+    option === `legacy` || hasTrailing ? `/` : ``
+  }`
+  const postfix = applyTrailingSlashOption(parsedNameWithSlash, option)
+
+  return posix.join(`/`, dir, postfix)
 }