Document how to load ambient types for non-preset plugins

[Clarity-89]

Have you read the Contributing Guidelines on issues?

• [X] I have read the Contributing Guidelines on issues.

Prerequisites

• [X] I'm using the latest version of Docusaurus.
• [X] I have tried the npm run clear or yarn clear command.
• [X] 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

import {type Props} from '@theme/Playground'; fails with the error: TS2307: Cannot find module '@theme/Playground' or its corresponding type declarations. The same imports work for @sites, @docusaurus and even @theme/CodeBlock, so this is not an issue with the TS setup. I see that the @theme/Playground module is declared in theme-live-codeblock.d.ts but it has no effect.

Reproducible demo

https://stackblitz.com/edit/github-muqq2c?file=src%2Fcomponents%2FHomepageFeatures%2Findex.tsx

Steps to reproduce

Add import {type Props} from '@theme/Playground'; to any tsx file in the sandbox and see the error.

Expected behavior

The imports from @theme/Playground should work correctly.

Actual behavior

TypeScript error.

Your environment

• Public source code:
• Public site URL:
• Docusaurus version used:
• Environment name and version (e.g. Chrome 89, Node.js 16.4):
• Operating system and version (e.g. Ubuntu 20.04.2 LTS):

Self-service

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

[slorber]

Hey

Not sure how to handle this properly because of our modular architecture but it's probably just a documentation issue.

By default @theme/Playground does not exist (on purpose) because TypeScript doesn't know you use this optional plugin.

BTW first you'd need to add the plugin in dependencies: in your repro it's not.

Then there are multiple ways to tell TypeScript you are using it.

// tsconfig.json

{
  "extends": "@tsconfig/docusaurus/tsconfig.json",
  "compilerOptions": {
    "baseUrl": ".",
    "types": ["@docusaurus/theme-live-codeblock"]
  }
}

// types.d.ts

/// <reference types="@docusaurus/theme-live-codeblock" />

// index.tsx

import '@docusaurus/theme-live-codeblock';

By default our preset only bias toward declaring types for theme classic and core types, and all other types have to be "found" by TypeScript by other means, sometimes involving an explicit declaration.

We probably need to document this better although it's a typical TS behavior and does not just apply to Docusaurus

[Clarity-89]

Adding "types": ["@docusaurus/theme-live-codeblock"] to the tsconfig.json fixes the error, thank you for the help! 🎉

[kwennB]

Hello @slorber. I would love to fix this issue on the Docs. Is it available?

Could you clarify if the required edits go to the TypeScript support or the Preset section of Using Plugins? Thank you.

[slorber]

@kwennB sure, but I don't know what's best actually 😅 You'll have to make a proposal and we'll see if it's good and consistent.

@Josh-Cena any opinion on how we should document this? Or could we even simplify our TS setup to not have to document it?

[Josh-Cena]

The fix is as easy as adding it to tsconfig or a .d.ts triple slash reference, as you have already pointed out. We should probably add it to TypeScript support.