diff --git a/packages/gatsby/src/bootstrap/load-config-and-plugins.ts b/packages/gatsby/src/bootstrap/load-config-and-plugins.ts index f59929b103556..05aa5bd02902d 100644 --- a/packages/gatsby/src/bootstrap/load-config-and-plugins.ts +++ b/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` diff --git a/packages/gatsby/src/utils/__tests__/__snapshots__/handle-flags.ts.snap b/packages/gatsby/src/utils/__tests__/__snapshots__/handle-flags.ts.snap index 226519fc0323b..733641bdc3f60 100644 --- a/packages/gatsby/src/utils/__tests__/__snapshots__/handle-flags.ts.snap +++ b/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": "", } `; diff --git a/packages/gatsby/src/utils/__tests__/handle-flags.ts b/packages/gatsby/src/utils/__tests__/handle-flags.ts index a4c74f2091fdd..59eb724461fa7 100644 --- a/packages/gatsby/src/utils/__tests__/handle-flags.ts +++ b/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": "", } `) diff --git a/packages/gatsby/src/utils/flags.ts b/packages/gatsby/src/utils/flags.ts index 89fc214fea05d..d35c5690e3bcf 100644 --- a/packages/gatsby/src/utils/flags.ts +++ b/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 umbrellaIssue?: string noCI?: boolean @@ -135,6 +142,7 @@ const activeFlags: Array = [ return false } }, + requires: `Requires gatsby-plugin-sharp@2.10.0 or above.`, }, { name: `PRESERVE_WEBPACK_CACHE`, @@ -198,6 +206,7 @@ const activeFlags: Array = [ 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 = [ const [major, minor] = process.versions.node.split(`.`) return (Number(major) === 14 && Number(minor) >= 10) || Number(major) > 14 }, + requires: `Requires Node v14.10 or above.`, }, ] diff --git a/packages/gatsby/src/utils/handle-flags.ts b/packages/gatsby/src/utils/handle-flags.ts index 6b0b9ffc00f9e..d4022339e5ca6 100644 --- a/packages/gatsby/src/utils/handle-flags.ts +++ b/packages/gatsby/src/utils/handle-flags.ts @@ -12,6 +12,7 @@ const handleFlags = ( ): { enabledConfigFlags: Array 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, } }