💥 Proposal

As more of the official packages are migrated to TS, I start to notice duplicated logic in the packing process, but not following this long process of compiling -> copying static assets -> double transpilation can cause some troubles.

The first one is less of a concern, although more likely to occur: when the theme folder contains .css files, they are not copied to the dist folder by tsc, you would either need to transpile by babel with allExtensions: true, or you would need to use the copyUntypedFiles script (which we use a lot—duplicated in every package). Neither is very convenient for a TS plugin developer. However, the plugin author cannot get away without using one of the two techniques, because missing .css files would make the code not run at all.

The second one can be more problematic. The TypeScript theme components are transpiled twice, once only with the types stripped and once to actual commonjs code. Now imagine the following case:

• The developer of a plugin writes the plugin in TS;
• Unaware of the double-transpile workflow, the plugin is only built with tsc and distributed;
• A user uses the plugin, and decided to swizzle a theme component, but uses the JS version;
• The user will receive an unreadable component.

This can go away unnoticed because for normal users who don't swizzle, the plugin runs correctly. The above case is very rare as of now, but can be likely in the future with a better plugin ecosystem. Also, many official plugins have their own theme components, and most of them are currently kept as JS to bypass this issue—still not optimal for TS-perfectionists like me. If we can expose a util to transpile the theme components to human-readable JS automatically, things would be a lot easier for the plugin authors.

I propose we have a docusaurus-plugin build command, meant to be used by plugin authors, which runs Babel and generates a nice directory structure automatically, maybe like this:

plugin
├── dist
│   ├── index.js
│   └── theme
│       └── Component.js
├── js-theme
│   └── Component.js
└── src
    ├── index.ts
    └── theme
        └── Component.ts

We can use this internally to reduce the logic duplication, so it's better if it gets into this repo.

We may even provide a docusaurus-plugin init utility to scaffold a plugin package, just like docusaurus init.

Have you read the Contributing Guidelines on issues?

Yes

Edit. Once #5816 lands, we don't need to transpile twice. Hence, the major focus of this tool shifts towards an ergonomic DX: hot reloading for CSS edits, type-checking integration, etc., than actually bundling & building.