fix(core): do not apply theme-init alias to user component

[Josh-Cena]

Motivation

This PR essentially reverts #3485.

#3485 makes user theme components have the @theme-init alias as well, however that's not the intention of this alias. That PR was only created because of the lack of knowledge of @theme-original at that time.

@theme-init is supposed to load the "initial version" of this component, when it's first provided. I made a contrived example to illustrate the bug (sorry for not filing an issue or creating a repro, but hope it's understandable enough):

1. Bootstrap a new website.
2. Install @docusaurus/theme-live-codeblock and add it to themes.
3. Create src/theme/CodeBlock.js and add:

import React from 'react'
import CodeBlock from '@theme-original/CodeBlock';

export default function CodeBlockEnhanced(props) {
  return (
    <>
      <div>Hey</div>
      <CodeBlock {...props} />
    </>
  )
}

4. Add a live codeblock to a page.

This turns into a blank screen with an error message Uncaught (in promise) ReferenceError: Cannot access '__WEBPACK_DEFAULT_EXPORT__' before initialization. The reason is that @theme-original/CodeBlock points to the live codeblock, but @theme-init/CodeBlock used in the live codeblock points to the user-swizzled one, causing a circular import.

I have a feeling that even the maintainers do not have a good understanding of what these aliases do, so I refactored the code a little and added some docs to clarify the internal details of aliasing.

This PR does not solve #4530 though, because Webpack aliases need to deterministically point to one file, so @theme-init has to point to the bottommost component. All plugins that try to enhance the same component would still receive the same, unenhanced component when importing from @theme-init. We can't "relay" the component from one theme to another.

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

In the Webpack alias test, I added another plugin to mimic my example above. This time @theme-init points to the first plugin, @theme-original points to the second, and @theme points to the user-swizzled one.

[netlify]

✔️ [V2]

🔨 Explore the source changes: 0040819

🔍 Inspect the deploy log: https://app.netlify.com/sites/docusaurus-2/deploys/61aa5796a35aeb0008042fee

😎 Browse the preview: https://deploy-preview-5983--docusaurus-2.netlify.app

[github-actions]

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🟠 Performance	67
🟢 Accessibility	98
🟢 Best practices	100
🟢 SEO	100
🟢 PWA	95

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

[github-actions]

Size Change: 0 B

Total Size: 656 kB

ℹ️ View Unchanged

Filename	Size
website/.docusaurus/globalData.json	40.1 kB
website/build/assets/css/styles.********.css	101 kB
website/build/assets/js/main.********.js	485 kB
website/build/index.html	29.5 kB

_{compressed-size-action}

[Josh-Cena]

/cc @lex111 Since you implemented this alias in the first place—I hope my understanding is correct?

[Josh-Cena]

PluginThemeComponentOverriddenByUser is no longer getting a @theme-init alias because it's not provided by two themes, only by the user and one theme.

[lex111]

@Josh-Cena yes, that's right. It really isn't the easiest/most obvious thing to understand and describe in words, so thank you for documenting it!

[slorber]

Thanks, LGTM 👍

The doc is clearer indeed :)

Added an empty theme/CodeBlock wrapper on our site to dogfood