MDX and React instructions don't work for TypeScript projects

[kaycebasques]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Description

After following these instructions: https://docusaurus.io/docs/markdown-features/react#importing-components

Docusaurus would tell me that the page crashed and that React is undefined.

I eventually had a hunch that it was because I had initialized my Docusaurus project with TypeScript. Perhaps it's obvious to seasoned TS developers but I'm still new to it.

I think I can take on this documentation update myself but I'm creating this issue in case I get sidetracked.

Self-service

• I'd be willing to address this documentation request myself.

[Josh-Cena]

@kaycebasques Do you have a reproduction? If anything goes against the documentation you'd better give something so we can investigate, as I'm sure not everyone's running into this.

[kaycebasques]

Repro

1. Generate project with following command as instructed in scaffold project website

npx create-docusaurus@latest my-website classic --typescript

2. Create Highlight component as instructed in MDX and React

// /src/components/Highlight.js
export default function Highlight({children, color}) {
  return (
    <span
      style={{
        backgroundColor: color,
        borderRadius: '2px',
        color: '#fff',
        padding: '0.2rem',
      }}>
      {children}
    </span>
  );
}

(Note there is no TypeScript information in that guide)

3. Rename /docs/intro.md to /docs/intro.mdx
4. Add following code to the top of /docs/intro.mdx (below the front matter) to import and use Highlight component as instructed in MDX and React

---
sidebar_position: 1
---

import Highlight from '@site/src/components/Highlight';

<Highlight color="#25c2a0">Docusaurus green</Highlight>

5. npm run start

Result

Fix

Follow the example of the HomePageFeatures component that is included in the starting code:

• Rename /src/components/Highlight.js to /src/components/Highlight/index.tsx
• Add import React from 'react' to the top of index.tsx
• Add type goodness to index.tsx

(This fix sections summarizes the changes I'm proposing to MDX and React... there should probably be an H3 section after importing components dedicated to the TS workflow)

[Josh-Cena]

Hi, you need to import React from "react" whenever you use JSX—this is standard React practice. For some explanation, you can see https://www.chakshunyu.com/blog/why-did-and-dont-you-need-to-import-react/ This has nothing to do with TS, because you have to add that import either in JS or TS.

There are many ways to enforce this, for example, there's the ESLint rule: https://github.com/yannickcr/eslint-plugin-react/blob/HEAD/docs/rules/react-in-jsx-scope.md When you use TS, TS will also warn you about React not being in scope when using JSX. Since this is only about JSX and not about Docusaurus, I will close this.

[kaycebasques]

Thanks for taking the extra time to link to those docs and explain. Since I'm new to React I understand I may not be your target audience but perhaps a fix here is to just add the import statement to the top of the /src/components/Highlight.js code in the importing components section to reduce the likelihood of another newbie like me opening this issue again on your repo? Or ellipsis (...) to indicate that the Highlight.js code is incomplete. Happy to put in that PR. But I also understand that sometimes it's best to keep the code samples minimal.

[Josh-Cena]

Oh, I just realized our docs don't add that import statement 🤦‍♂️ Happy to have a PR that adds import React for that!