Add support for @site/... imports in docusaurus.config.ts / builder

[SilasBerger]

@site/... imports work fine in React components and in .mdx files (thanks to intellij.config.js workaround for IntelliJ MDX plugin). However, they do not work in the docusaurus.config.ts and the whole builder part.

The @docusaurus/tsconfig file defines the @site path alias as follows:

"compilerOptions": {
  "paths": {
      "@site/*": ["./*"]
  },
}

It seems like that file doesn't apply to docusaurus.config.ts: Imports such as @site/src/builder/logger in docusaurus.config.ts are accepted (and even suggested) by the IDE, but during yarn run build, they yield the following error:

Cause: Cannot find module '@site/src/builder/logger'
Require stack:
- /Users/silas/repos/teaching-website/docusaurus.config.ts
    at loadFreshModule (/Users/silas/repos/teaching-website/node_modules/@docusaurus/utils/lib/moduleUtils.js:36:15)
    at loadSiteConfig (/Users/silas/repos/teaching-website/node_modules/@docusaurus/core/lib/server/config.js:35:62)
    ... 2 lines matching cause stack trace ...
    at async Command.start (/Users/silas/repos/teaching-website/node_modules/@docusaurus/core/lib/commands/start.js:44:19) {
  [cause]: Error: Cannot find module '@site/src/builder/logger'

Also note that the custom tsconfig.json file in the project root only applies for the IDE and is not used during compilation.

[SilasBerger]

What we know so far

• When auto-completing an import, IntelliJ always takes into account the tsconfig.json nearest to the current file. If that config defines an @site path alias, IntelliJ will create an @site import.
• Docusaurus does not use the custom tsconfig.json file in compilation (https://docusaurus.io/docs/typescript-support#setup).
• As far as I can tell, the @site alias works fine in all components, MDX pages, and generally in all the "web app" code. However, it doesn't work within the "CLI part": In the case of this project, this includes docusaurus.config.ts and its import tree.
• It appears that Docusaurus uses Babel to transpile TypeScript (rather than tsc).
• Points of interest for further research include Docusaurus' Babel and Webpack source.
• The current "root" directory where @site imports don't work is src/framework, plus docusaurus.config.ts.
• Here is an interesting discussion about what seems to be a similar issue: Support TypeScript in Docusaurus config facebook/docusaurus#7911 (comment).
• Most mentions of the @site alias in the Docusaurus documentation suggests that it is only intended for use within the "MDX world":
  • https://docusaurus.io/docs/advanced/routing#file-paths-and-url-paths
  • https://docusaurus.io/docs/markdown-features/react#importing-components
  • https://docusaurus.io/docs/versioning#use-absolute-import-within-the-docs
• Most likely, the best solution would be to fix the editor behavior, rather than the compiler settings. That is, prevent IntelliJ from using the @site alias when generating imports in files at the project rootor within the src/framework directory.
• One possible solution is to disable the @site alias at root level by adding a compiler option "paths": {} to the root-level tsconfig.json, then adding a lower-level tsconfig.json with a compiler option "paths": {"@site/*": ["./*"]} to every directory where @site imports are allowed, such as src/app. The caveat is that overriding the paths option means having to explicitl re-specify every path alias that we still want to be able to use, since we only want to disable @site (where applicable).
• With the workaround introduced in Rework directives and clean up src directory #28, this issue is now limited to docusaurus.config.ts. Within the src/framework directory, IntelliJ no longer auto-generates @site imports.