[Flags] Better documentations and explanations on flags

[mwskwong]

Summary

Gatsby v3.4 release mentioned one of the flags PRESERVE_WEBPACK_CACHE, which may significantly improve DX. However, there are many flags that may help but are by default disabled, and there isn't seem to be a proper page documenting the flags.

The following is what I think should be included in the doc.

• Listing all available flags
• Briefly explain what each of them does
• The default value and available values of each flag.

e.g.
DEV_SSR
Description: EXPERIMENTAL: Server Side Render (SSR) pages on full reloads during development. Helps you detect SSR bugs and fix them without needing to do full builds.
Type: Boolean
Default: false

Motivation

Although the flags are experimental, it is beneficial for some of the development scenarios. Given the console mentioned the flags from time to time, I believe there should be an official page to document this information properly.

I may draft a doc and create a pull request if the core team agrees to add the page.

[KyleAMathews]

👍 this would be great! Ideally this would be a MDX page that just pulls in the flags from https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/utils/flags.ts so we don't have to remember to update the docs page when a flag changes stautus or description. We haven't yet made it so people can run the docs site locally easily but you could pull the doc file and the flag file into a seperate site perhaps to write the code and one of the core team can take it to the finish line.

[LekoArts]

I'm not sure if external contributors can actually make the needed changes to enable this.

[mwskwong]

I agree actually. There seems to have very little information about flags on the internet.

[LekoArts]

I'll try to implement it as automatic updating list of flags. At the minimum we'll add a new doc page linking to this :)