New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Generate CLI docs as a Docusaurus plugin #6218
base: master
Are you sure you want to change the base?
Conversation
39f992e
to
c833f23
Compare
d0e62d4
to
ef0d749
Compare
Got hot rebuild to work, using But the deploy preview is failing now, will investigate. |
ef0d749
to
6344f7f
Compare
Looks like using |
Re: Also investigated caching to improve warm start, but that does not give a significant perf boost compared to the complexity increase. The limiting factor is probably somewhere else. |
const loader = jiti(__filename, { | ||
cache: true, | ||
requireCache: false, | ||
}); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What is this for? I see you mentioned jiti in the PR's comment, but that you also intended to remove it
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
jiti
is a library to create loader functions that are drop-in replacements for require
with on-the-fly TS compilation, used by Docusaurus itself (e.g. to require docusaurus.config.ts
).
I want the CLI doc plugin to do hot reload. That is, if I change a command's metadata while the dev server is running, I want the change to reflect on the page without restarting the dev server. The problem with that is the cli-docs.ts
is compiled by Docusaurus's internal jiti
loader instance, so any import
or require
I use will just be intercepted. But that jiti
instance has an internal, hidden cache, so it will just load the cached stale instance of the changed command file, breaking hot reload. To get around that, I needed to create a separate jiti
loader instance which properly recompile every time it is called.
The trouble comes when I tried to integrate our own on-the-fly TS compilation pipeline (scripts/setup-ts-execution
) into that jiti
loader instance. Turns out jiti
and esbuild
have some subtle incompatibilities, so I just removed the esbuild
integration and use jiti
with its built-in babel-based compilation pipeline. The intention was never to remove jiti
.
What's the problem this PR addresses?
The current method of CLI docs generation is very inefficient because it is synchronously blocking and memory-intensive. It can easily take up 40% of the time needed to start the dev server.
How did you fix it?
Created a Docusaurus plugin that generates the CLI docs. This has a number of advantages over the existing method:
Performance
Index pages
I have also taken the opportunity to take the
@yarnpkg/cli
index page and adapted it to the other binariesUnfortunately, generating the CLI docs as a separate plugin makes the original URL scheme conflict with the main docs plugin, so we either have to
/cli
)I have opted to move everything under
/cli
Other Changes
The change causes a few visual changes to existing stuff:
yarn
invocation, and thus is properly styledFuture work
This PR is ready, but I am still experimenting with a few things that may or may not make it into the PR.
I'm trying whether it is possible to use Docusaurus's watch mechanism to hot rebuild the pages.Also, as you can see, there are practically no difference in warm and cold startup time. Maybe checking mtimes can avoid some work?Checklist