feat(gatsby): display message about unfit flags found in config

packages/gatsby/src/bootstrap/load-config-and-plugins.ts

@@ -44,15 +44,19 @@ export async function loadConfigAndPlugins({
     // Setup flags
     if (config) {
       // Get flags
-      const { enabledConfigFlags, unknownFlagMessage, message } = handleFlags(
-        availableFlags,
-        config.flags
-      )
+      const {
+        enabledConfigFlags,
+        unknownFlagMessage,
+        unfitFlagMessage,
+        message,
+      } = handleFlags(availableFlags, config.flags)
 
       if (unknownFlagMessage !== ``) {
         reporter.warn(unknownFlagMessage)
       }
-
+      if (unfitFlagMessage !== ``) {
+        reporter.warn(unfitFlagMessage)
+      }
       //  set process.env for each flag
       enabledConfigFlags.forEach(flag => {
         process.env[flag.env] = `true`

packages/gatsby/src/utils/__tests__/__snapshots__/handle-flags.ts.snap

@@ -54,6 +54,7 @@ There are 2 other flags available that you might be interested in:
 - FAST_DEV · Enable all experiments aimed at improving develop server start time
 - YET_ANOTHER · (Umbrella Issue (test)) · test
 ",
+  "unfitFlagMessage": "",
   "unknownFlagMessage": "",
 }
 `;
@@ -101,6 +102,7 @@ There are 4 other flags available that you might be interested in:
 - ALL_COMMANDS · (Umbrella Issue (test)) · test
 - YET_ANOTHER · (Umbrella Issue (test)) · test
 ",
+  "unfitFlagMessage": "",
   "unknownFlagMessage": "",
 }
 `;
@@ -160,6 +162,7 @@ There are 3 other flags available that you might be interested in:
 - DEV_SSR · (Umbrella Issue (https://github.com/gatsbyjs/gatsby/discussions/28138)) · SSR pages on full reloads during develop. Helps you detect SSR bugs and fix them without needing to do full builds.
 - YET_ANOTHER · (Umbrella Issue (test)) · test
 ",
+  "unfitFlagMessage": "",
   "unknownFlagMessage": "The following flag(s) found in your gatsby-config.js are not known:
 - FASTLY_DEV (did you mean: FAST_DEV)
 - SUPER_COOL_FLAG",
@@ -256,6 +259,7 @@ The following flags were automatically enabled on your site:
 There is one other flag available that you might be interested in:
 - YET_ANOTHER · (Umbrella Issue (test)) · test
 ",
+  "unfitFlagMessage": "",
   "unknownFlagMessage": "",
 }
 `;

packages/gatsby/src/utils/__tests__/handle-flags.ts

@@ -145,6 +145,17 @@ describe(`handle flags`, () => {
         }
       },
     },
+    {
+      name: `LMDB_NODE14_ONLY`,
+      env: `GATSBY_LMDB`,
+      command: `all`,
+      description: `test`,
+      umbrellaIssue: `test`,
+      telemetryId: `test`,
+      experimental: false,
+      testFitness: (): fitnessEnum => false,
+      requires: `Requires Node 14.10+`,
+    },
   ]
 
   const configFlags = {
@@ -192,6 +203,24 @@ describe(`handle flags`, () => {
     expect(unknownConfigFlags).toMatchSnapshot()
   })
 
+  it(`returns a message about unfit flags in the config`, () => {
+    const unfitConfigFlags = handleFlags(
+      activeFlags,
+      { LMDB_NODE14_ONLY: true },
+      `develop`
+    )
+    expect(unfitConfigFlags.enabledConfigFlags).not.toContain(
+      expect.objectContaining({
+        name: `LMDB_NODE14_ONLY`,
+      })
+    )
+    expect(unfitConfigFlags.unfitFlagMessage).toMatchInlineSnapshot(`
+      "The following flag(s) found in your gatsby-config.js are not supported in your environment and will have no effect:
+      - LMDB_NODE14_ONLY: Requires Node 14.10+"
+    `)
+    expect(unfitConfigFlags.unknownFlagMessage).toEqual(``)
+  })
+
   it(`opts in sites to a flag if their site is selected for partial release`, () => {
     // Nothing is enabled in their config.
     const response = handleFlags(activeFlags, {}, `develop`)
@@ -226,6 +255,8 @@ describe(`handle flags`, () => {
       Object {
         "enabledConfigFlags": Array [],
         "message": "",
+        "unfitFlagMessage": "The following flag(s) found in your gatsby-config.js are not supported in your environment and will have no effect:
+      - PARTIAL_RELEASE_ONLY_VERY_OLD_LODASH",
         "unknownFlagMessage": "",
       }
     `)
@@ -377,6 +408,7 @@ describe(`handle flags`, () => {
           "message": "The following flags are active:
         - SOME_FLAG · (Umbrella Issue (test)) · test
         ",
+          "unfitFlagMessage": "",
           "unknownFlagMessage": "",
         }
       `)

packages/gatsby/src/utils/flags.ts

@@ -66,6 +66,13 @@ export interface IFlag {
    * (avoids showing unknown flag message and shows "no longer needed" message).
    */
   testFitness: (flag: IFlag) => fitnessEnum
+  /**
+   * Human-readable text explaining requirements for this feature to be available
+   * (e.g. requires Node 14+)
+   *
+   * It is shown to users when testFitness() returns `false` but flag is set in gatsby-config.js
+   */
+  requires?: string
   includedFlags?: Array<string>
   umbrellaIssue?: string
   noCI?: boolean
@@ -135,6 +142,7 @@ const activeFlags: Array<IFlag> = [
         return false
       }
     },
+    requires: `Requires gatsby-plugin-sharp@2.10.0 or above.`,
   },
   {
     name: `PRESERVE_WEBPACK_CACHE`,
@@ -198,6 +206,7 @@ const activeFlags: Array<IFlag> = [
       const [major, minor] = process.versions.node.split(`.`)
       return (Number(major) === 14 && Number(minor) >= 10) || Number(major) > 14
     },
+    requires: `Requires Node v14.10 or above.`,
   },
   {
     name: `PARALLEL_QUERY_RUNNING`,
@@ -212,6 +221,7 @@ const activeFlags: Array<IFlag> = [
       const [major, minor] = process.versions.node.split(`.`)
       return (Number(major) === 14 && Number(minor) >= 10) || Number(major) > 14
     },
+    requires: `Requires Node v14.10 or above.`,
   },
 ]
 

packages/gatsby/src/utils/handle-flags.ts

@@ -12,6 +12,7 @@ const handleFlags = (
 ): {
   enabledConfigFlags: Array<IFlag>
   unknownFlagMessage: string
+  unfitFlagMessage: string
   message: string
 } => {
   // Prepare config flags.
@@ -23,6 +24,7 @@ const handleFlags = (
 
   // Find unknown flags someone has in their config to warn them about.
   const unknownConfigFlags: Array<{ flag: string; didYouMean: string }> = []
+  const unfitConfigFlags: Array<{ flag: string; requires: string }> = []
   for (const flagName in configFlags) {
     if (availableFlags.has(flagName)) {
       continue
@@ -99,8 +101,23 @@ const handleFlags = (
     if (fitness === true || fitness === `OPT_IN`) {
       applicableFlags.set(flag.name, flag)
     }
+
+    if (fitness === false && enabledConfigFlags.includes(flag)) {
+      unfitConfigFlags.push({ flag: flag.name, requires: flag.requires ?? `` })
+    }
   })
 
+  let unfitFlagMessage = ``
+  if (unfitConfigFlags.length > 0) {
+    unfitFlagMessage =
+      `The following flag(s) found in your gatsby-config.js are not supported in your environment and will have no effect:\n` +
+      unfitConfigFlags
+        .map(
+          flag => `- ${flag.flag}${flag.requires ? `: ${flag.requires}` : ``}`
+        )
+        .join(`\n`)
+  }
+
   // Filter enabledConfigFlags against various tests
   enabledConfigFlags = enabledConfigFlags.filter(flag => {
     if (flag.command !== `all` && flag.command !== executingCommand) {
@@ -239,6 +256,7 @@ The following flags were automatically enabled on your site:`
     enabledConfigFlags,
     message,
     unknownFlagMessage,
+    unfitFlagMessage,
   }
 }