Docusaurus 3.6.3: Typescript cannot find module @theme

[jackw]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

Updating docusaurus from 3.6.0 to 3.6.3 appears to break type aliasing (at least in our mono-repo). I cannot track this down but anything that imports from @theme doesn't resolve to what should be theme-classic types anymore. I can fix it by adding the following to tsconfig.json which seems a bit strange for a minor update.

  "compilerOptions": {
    "baseUrl": ".",
+    "types": ["@docusaurus/theme-classic"]
  },

I've tried bumping TS, removing global.d.ts, scaffolding a fresh docusaurus website with npx create-docusaurus@latest docusaurus-website classic --typescript and comparing files but I cannot figure it out.

Reproducible demo

grafana/plugin-tools#1312

Steps to reproduce

1. clone grafana/plugin-tools
2. check-out branch renovate/docusaurus-dependencies
3. run npm i to install deps
4. run npm typecheck
5. See lots of error TS2307: Cannot find module '@theme/*' or its corresponding type declarations. errors

Expected behavior

For the type aliases to resolve correctly.

Actual behavior

Type aliases don't resolve resulting in lots of error TS2307: Cannot find module '@theme/*' or its corresponding type declarations. errors.

Your environment

• Public source code: https://github.com/grafana/plugin-tools
• Public site URL: https://grafana.com/developers/plugin-tools/
• Docusaurus version used: 3.6.3
• Environment name and version (e.g. Chrome 89, Node.js 16.4): N/A
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): N/A

Self-service

• I'd be willing to fix this bug myself.

[ahnpnl]

I have the same issue

[slorber]

Thanks for reporting, this is related to #10694 (comment)

I'll study your Grafana tools repo and see if I can find a better setup that doesn't break sites.

@ahnpnl it can help if you also share a repro

[ahnpnl]

Hi, https://github.com/kulshekhar/ts-jest/tree/main/website you can use this repo and the failed PR is kulshekhar/ts-jest#4638

[jackw]

Thanks for reporting, this is related to #10694 (comment)

I'll study your Grafana tools repo and see if I can find a better setup that doesn't break sites.

Thanks for the info and the link @slorber. So the current workaround would be the following in the websites tsconfig (as that is how it was previously):

"types": [
  "node",
  "@docusaurus/module-type-aliases",
  "@docusaurus/theme-classic"
],

[slorber]

I still think the change we did was right: our base TS config shouldn't explicitly restrict types, and keep TS default behavior.

However, removing types made it break your sites. It's because of a specific reason: since nowhere in your code there is any import XYZ from '@docusaurus/theme-classic', then TS doesn't know that it has to load ambient theme types provided by this package.

There are multiple solutions, such as:

• adding a types field yourself (but this comes with the side-effect of whitelisting the types, not just including the ones we need)
• a triple-slash direct at the very top of a .d.ts: /// <reference types="@docusaurus/theme-classic" />
• an import of @docusaurus/theme-classic anywhere in your code

---

But to me the root of the problem is due to the half-typed setup of your sites, mostly because you use JS for your config files instead of TS.

By default, our init template imports theme/preset types automatically: https://github.com/facebook/docusaurus/blob/main/examples/classic-typescript/docusaurus.config.ts

In particular:

import type * as Preset from '@docusaurus/preset-classic';

As soon as you properly type your config file according to the preset you use, all the necessary ambient theme files will become available for typechecking.

I think we should keep the current base TS setup, and instead you should improve your site's typesafety. So unless there's a good reason, I'm going to close this issue. Please let me know if this works for you.

I thought about using typeRoots but it didn't really work as I expected. Also if we declared something like @docusaurus/** in typeRoots, we would possibly load ambient theme types of packages you don't even use, so I don't think it's a better option. Explicitly importing the types that you actually use is better.

[slorber]

Note, if you want to keep a JS config file, you can get the same benefit with JSDoc, that is now provided by default in our init template:

/** @type {import('@docusaurus/types').Config} */
const config = {
  ...generalConfig,
  url: 'https://grafana.com/',
  baseUrl: 'developers/plugin-tools/',
  plugins,
  presets: [
    [
      'classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          ...presetsDocs,
          routeBasePath: '/',
        },
        theme: presetsTheme,
        blog: false,
      }),
    ],
  ],
}

Important: make sure to wrap the option object with extra () otherwise the type doesn't get applied properly and the ambient types are not loaded.

[slorber]

@ahnpnl same for you. Your config is in TS, and you should rather import/use the preset type:

import type {Config} from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';

const config: Config = {
  title: 'My Site',
  presets: [
    [
      'classic',
      {
        docs: {
          
        },
        blog: {
          
        },
      } satisfies Preset.Options,
    ],
  ],
};

Somehow I think it's a feature that Docusaurus doesn't typecheck in your case: it's a sign that your TS setup is not ideal, not typechecking preset options 😄

[jackw]

I think we should keep the current base TS setup, and instead you should improve your site's typesafety. So unless there's a good reason, I'm going to close this issue. Please let me know if this works for you.

I see no reason not to move our configs to .ts files. @slorber thanks so much for taking the time to write up such a detailed reply with a selection of solutions to the problem. 👍