feat(v2): add --config option to CLI

[longlho]

Motivation

We're trying to get docusaurus to play nicer with bazel, which relies heavily on explicit IO. Currently docusaurus makes a lot of assumptions on folder structure based on siteDir (e.g .docusaurus temp folder & docusaurus.config.js). The new CLI options allow user to control:

• --config controls the path to docusaurus.config.js.
• --generated-files-dir controls the path to .docusaurus folder which is used for deployment.
• Fixes deployment issue where it needs generated files dir but in reality it just needs a tmpdir. This prevents issue where generated files dir is read-only (in bazel scenario).

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

Upstream bazel setup: https://github.com/formatjs/formatjs/blob/main/website/BUILD#L50

Related PRs

[netlify]

[V1] Deploy preview success

Built with commit 9d67ddc

https://deploy-preview-4308--docusaurus-1.netlify.app

[netlify]

Deploy preview for docusaurus-2 ready!

Built with commit 9d67ddc

https://deploy-preview-4308--docusaurus-2.netlify.app

[github-actions]

Size Change: 0 B

Total Size: 532 kB

ℹ️ View Unchanged

Filename	Size	Change
website/build/assets/css/styles.********.css	87.1 kB	0 B
website/build/assets/js/main.********.js	359 kB	0 B
website/build/blog/2017/12/14/introducing-docusaurus/index.html	60.3 kB	0 B
website/build/docs/introduction/index.html	235 B	0 B
website/build/index.html	25.4 kB	0 B

_{compressed-size-action}

[github-actions]

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🟠 Performance	51
🟢 Accessibility	96
🟢 Best practices	100
🟢 SEO	100
🟢 PWA	95

Lighthouse ran on https://deploy-preview-4308--docusaurus-2.netlify.app/classic/

[longlho]

@slorber if u can review that'd be great! Thanks!

[slorber]

Thanks, will take a deeper look tomorrow but that looks nice.

Just wondering if having 2 new cli options for a quite niche use-case isn't going to clutter a bit our API?
Could it make sense to keep using env variables instead and document these differently than widely used cli options?
Could we use only --config and configure the .docusaurus folder through the config file instead?

I don't have strong opinions, just wondering what's the best public API choice for this.

[longlho]

yeah that works too I'm fine w/ either option. LMK and I'll change it :)

[slorber]

Note: we could basically have a need to allow customizing all these constants:

packages/docusaurus/src/constants.ts

export const BABEL_CONFIG_FILE_NAME = 'babel.config.js';
export const BUILD_DIR_NAME = 'build';
export const CONFIG_FILE_NAME = 'docusaurus.config.js';
export const GENERATED_FILES_DIR_NAME = '.docusaurus';
export const SRC_DIR_NAME = 'src';
export const STATIC_DIR_NAME = 'static';
export const OUTPUT_STATIC_ASSETS_DIR_NAME = 'assets'; // files handled by webpack, hashed (can be cached aggressively)
export const THEME_PATH = `${SRC_DIR_NAME}/theme`;
export const DEFAULT_PORT = 3000;
export const DEFAULT_PLUGIN_ID = 'default';

At least it has been requested already the ability to customize STATIC_DIR_NAME.

My point is that I would find it odd if we would end up with many start/build options, most of them are barely used by anyone.

[longlho]

Although the bigger question would be, is generatedFilesDir just a tmpdir or is there some significance to it? I saw it being used in webpack to resolve @generated but those get inlined after packaging. How about the server side? If it's only used as tmp I'd just switch to mkdtemp and have the consistency basically.

[slorber]

Honnestly I don't know too much the impact of changing .docusaurus to a tmp folder. I think we could do that technically, but having this folder in the site can be useful for debugging.

And we could later leverage some kind of image resizing or Webpack 5 build caching inside it so we should be able to read from the .docusaurus folder of the previous build (ie it should be constant across builds). Will have to double-check that to be sure, but would rather delay this change after we upgrade to Webpack 5 just in case.

[longlho]

ok gotcha. Yeah I don't really mind 1 way or the other as long as there's a way to customize it (env var, param, config file...)

[slorber]

So, I see a few use-cases where --config can be useful as a cli option.

For .docusaurus I'd say it can stay as an env variable to avoid cluttering the cli API. Note neither Gatsby or Next do allow to customize .cache or .next/cache btw.

Going to edit a bit your PR and merge it asap, thanks

[slorber]

@longlho have you tested this with .docusaurus being replaced by an absolute path outside of the monorepo?

I'm trying this and it fails:

DOCUSAURUS_GENERATED_FILES_DIR_NAME=/tmp/test-docu yarn workspace docusaurus-2-website build:blogOnly

This is somehow expected as this tmp folder does not have any node_modules to read, and the generated files contain require/import calls to import React.

[slorber]

Note I tested to revert my local changes and it does not work either.

yarn workspace docusaurus-2-website build:blogOnly => OK
yarn workspace docusaurus-2-website build:blogOnly --generated-files-dir /tmp/test-docu => KO with a similar error

[longlho]

hmm gotcha I'll take a look. What's the server bundling btw?

[slorber]

hmm gotcha I'll take a look.

I don't mind merging a way to customize the .docusaurus folder, but would this actually solve your usecase if you can't use /tmp/.docusaurus-123 ? The current limitation is that this folder should be able to read the node_modules of your site, so rather be a subfolder of your site (or at least subfolder of the monorepo). That's probably why Gatsby/Next don't allow to customize this.

What's the server bundling btw?

What do you mean? Webpack?

[longlho]

@slorber yes subfolder of the monorepo is what I'm looking for. For context bazel creates a sandbox for every build and symlink dependencies in, including node_modules. I'm actually ok w/ dropping the generatedFilesDir config param for now since it's not blocking me anymore.

By server bundling I mean I don't know what the server component of docusaurus is since I only use the client bundle and throw it on GH pages.

[slorber]

So, just pushed my update.

As a summary, this works:

yarn workspace docusaurus-2-website build:blogOnly

DOCUSAURUS_GENERATED_FILES_DIR_NAME=/Users/sebastienlorber/Desktop/projects/docusaurus/website/.docusaurus-test-gendir yarn workspace docusaurus-2-website build:blogOnly

But this won't work, and afaik it's not a problem for your use-case:

DOCUSAURUS_GENERATED_FILES_DIR_NAME=/tmp/test-docu yarn workspace docusaurus-2-website build:blogOnly