Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

TypeScript refuses JSX because the jsx option is not set

ErrorCannot use JSX unless the '--jsx' flag is provided.

Short answer

TypeScript compiles JSX only when you name the file with a .tsx extension and enable the jsx compiler option. The error means the option is missing in the tsconfig that applies to the file. Set jsx to react-jsx for the modern React runtime, or preserve if a bundler transforms the JSX.

  • Applies to TypeScript 5.5, React 19, Vite 7
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the configuration TypeScript really uses, including values inherited with extends. If jsx is absent there, that is the cause.

    npx tsc --showConfig | grep -n jsx
  2. 2Match what you see, then jump to its fix

    1. 1npx tsc --showConfig shows no jsx lineThe jsx option is not setFix
    2. 2The error is reported in a .ts file that contains <Component /> tagsThe file has a .ts extensionFix

What does the error look like?

  • Cannot use JSX unless the '--jsx' flag is provided.
  • TS17004: Cannot use JSX unless the '--jsx' flag is provided.

Cause 1 of 2

The jsx option is not set

1Check

Look in tsconfig.json and in every file it extends. A project-references setup can have the option in one config and not in the one that covers your file.

grep -rn "\"jsx\"" tsconfig*.json

2Fix

Add jsx to compilerOptions. react-jsx emits the automatic-runtime calls and needs no React import in each file. preserve keeps the JSX for a later tool such as Babel or a bundler. react emits React.createElement.

{
  "compilerOptions": {
    "jsx": "react-jsx"
  }
}

3Verify

Restart the editor's TypeScript server and run the compiler.

npx tsc --noEmit

Confirmed by typescriptlang.org

Did this fix it?

Cause 2 of 2

The file has a .ts extension

1Check

TypeScript's JSX guide lists two requirements: the .tsx extension and the jsx option. A .ts file cannot hold JSX.

grep -rln "</\|/>" src --include=*.ts

2Fix

Rename the file to .tsx and update imports that name the extension, if any.

git mv src/Button.ts src/Button.tsx

3Verify

Type-check again; the error is gone.

npx tsc --noEmit

Confirmed by typescriptlang.org

Did this fix it?

How do I stop it coming back?

  • Start new projects from a maintained template that already has jsx set.
  • Set jsx in the base tsconfig that others extend, not in each child.
  • Use the same value your bundler expects: preserve when it transforms JSX itself.
  • Run tsc --noEmit in CI.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

TypeScript rejects MUI Data Grid columns that set a type

A TypeScript error inside a column's renderCell callback

A columns array declared without a type is inferred with type as a plain string, which the Data Grid's column type union does not accept.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.