How to use aliases to import custom components easily

[JEricaM]

Hi to everybody.
In my doc project I have some .md files with references of a custom component.
The references is:
import TcfPurposes from '../../src/components/TcfPurposes.tsx'

This works. The problem is that now I've translated my files to a new language so I have those .md files also under the i18n/languagecode/.... path.
If I build the documentation, an error occurs about the custom component path.
in this docusaurus doc page I've read about alias but I'm not able to find any information about how set them inside the project.
I've already checked the doc about the docusaurus.config.js.

How can I set aliases to use in my project? maybe an additional plugin should be added?
I already have

      "@docusaurus/core": "^3.2.1",
        "@docusaurus/preset-classic": "^3.2.1",
       "@docusaurus/module-type-aliases": "^3.2.1",
        "@tsconfig/docusaurus": "^1.0.4",

Thanks

[slorber]

@site alias is the root of your site so you can import things with @site/src/components/TcfPurposes and it should work even from files in i18n folder.

You can also use a plugin with configureWebpack to add your own Webpack aliases. In this case read the relevant Webpack doc regarding aliases.

I didn't try but something like this should work:

export default function MyAliasPlugin(context, options) {
  return {
    name: 'my-alias-plugin',
    configureWebpack() {
      return {
        resolve: {
          alias: {
            "@myAlias", "/my/aliased/path"
          },
        },
      };
    },
  };
}

[cglacet]

What if your components are in a parent folder?

For example if the structure look like this:

project
├── packages/app
│   └── someComponent.tsx
└── docs
    ├── docusaurus.config.ts
    ├── tsconfig.json
    └── docs
        └── file.md

I've tried editing tsconfig.json but it seems like it has no effect:

{
    // This file is not used in compilation. It is here just for a nice editor experience.
    "extends": "@docusaurus/tsconfig",
    "compilerOptions": {
        "baseUrl": ".",
        "paths": {
            "~/*": ["../../../packages/app/*"],
        }
    },
    "exclude": [".docusaurus", "build"]
}

I'm not sure what "This file" refers to, but I guess its not docusorus config and its instead the tsconfig?

I've tried the approach you suggest (explained in more details here) but it doesn't seem to work either (and I guess I would still have no auto-import/ts-check on these components so it doesn't look like a complete solution).

Am I'm missing something?

[slorber]

"this file" refers to the file the comment is on, so yes it's the tsconfig.json file

The TS config only impacts TypeScript typechecking and IDE errors, not Docusaurus build. The only way to register aliases for Docusaurus is through a plugin with configureWebpack(), as detailed above. If you also want TS support, you need to do both, but Docusaurus can work without TS too.

---

That's kind of outside the scope of Docusaurus to teach you that, aliases are a Webpack/Rspack feature and paths are a TS feature, and you should read their respective documentation.

However, if you provided a minimal https://docusauurs.new repro I could probably tell you what you did wrong.

[sporritt]

Regarding the comment @slorber made about writing an alias plugin, I can confirm that works nicely.

Specifically, I:

1. created an alias-plugin directory in the project root
2. Created alias-plugin/index.js and made this the contents:

export default function MyAliasPlugin(context, options) {
  return {
    name: 'my-alias-plugin',
    configureWebpack() {
      return {
        resolve: {
          alias: {
            "@myAlias": "/my/aliased/path"
          },
        },
      };
    },
  };
}

3. Added this plugin to the docusaurus config

plugins:[
      "./alias-plugin",
        ...
]

One cool thing I discovered is that aliases can be composed together (perhaps it says that in large letters in the webback docs; i dont know, I just copy-pasted slorber's code snippet). So I can start with a basic alias and build on top:

alias: {
  "@dc": "/docs-common",
  "@dcr": "@dc/reference",
  "@dcrc":"@dcr/components"
}

Aliases are very useful - I've got quite a few of them now. I use them throughout both the JS and MDX files.