`preact/compat` is incompatible with `@types/react`

[remcohaszing]

• Check if updating to the latest Preact version resolves the issue

Describe the bug
The types of preact/compat conflict with React.

There are a couple of issues at play leading to type conflicts between React and Preact.

• React 19 removed the UMD bundle.
• Yet the for the types for the UMD bundle are preserved in version 19. (Not sure why my comment was marked off-topic.)
• Preact also declares types for the global React UMD bundle.
• The global UMD React namespaces from @types/react and preact/compat get merged.
• When you configure TypeScript with the jsx option set to preserve or react, it uses the JSX namespace defined by the jsxFactory option. The default value of React.createElement means you use the React.JSX namespace available in the file. This namespace can be made available globally, by importing React, or by declaring it locally.
  • If you set the jsx option to react-jsx, you use the JSX namespace of the automatic runtime. There are no problems.
• If you set the jsx option to preserve or react and import preact/compat anywhere in your project, you get this error for any JSX children.

  file.tsx:6:5 - error TS2322: Type 'Element' is not assignable to type 'ReactNode'.
    Property 'children' is missing in type 'VNode<any>' but required in type 'ReactPortal'.
  
  6     return (
        ~~~~~~
  
    node_modules/@types/react/index.d.ts:388:9
      388         children: ReactNode;
                  ~~~~~~~~
      'children' is declared here.

• If you set the the jsx option to react, you get the following additional error for all JSX elements. Resolving this error will also resolve the problem above

  file.tsx:7:10 - error TS2686: 'React' refers to a UMD global, but the current file is a module. Consider adding an import instead.
  
  7         <div>
             ~~~
  

I use Next.js and pulled in Preact as a transient dependency. Next.js (incorrectly) forces you to set jsx to preserve.

To Reproduce

If possible, please provide a link to a StackBlitz/CodeSandbox/Codepen project or a GitHub repository that demonstrates the issue. You can use the following template on StackBlitz to get started: https://stackblitz.com/edit/create-preact-starter

Steps to reproduce the behavior:

1. Clone https://github.com/remcohaszing/preact-typescript-issue
2. Run npm ci
3. Run npx tsx, or play around with an editor

Expected behavior
No type errors.

I would like to help think of a solution, but I first need to understand this need for augmentation. My gut feeling tells me 2 changes should be made:

1. VNode should specify children
2. preact/compat should not declare the React UMD namespace. It should augment react instead.

Refs vercel/next.js#83159

[rschristian]

You're not meant to use @types/react alongside preact/compat, the types are somewhat intentionally incompatible as they reflect real runtime differences. Use one or the other but never both at once.

We recommend setting tsconfig paths to help avoid @types/react ever being used.

VNode should specify children

This would be incorrect, Preact vnodes do not have a children property (it lives as props.children instead)

[remcohaszing]

My use case is that I pulled them in as a transient dependency. I don’t use Preact directly in this project.

What’s the point of declaring the global React UMD namespace if not for compatibility with React?

[rschristian]

What’s the point of declaring the global React UMD namespace if not for compatibility with React?

As I said, it's for correct compat. Unless you want the types to be blatantly wrong in some cases & lie to the dev, we need to own them? I don't see any other option anyhow. Module augmentation is still, unfortunately, far too limited in what it can offer.

[remcohaszing]

What do you mean by correct compat? React removed the UMD module at runtime in React 19, but the types remain. I consider this a React bug. Why does Preact need to deal with these types at all?

[rschristian]

React removed the UMD module at runtime in React 19

Okay, but that's not a change we've made, nor personally do I think it's one we need to mirror. It causes no problems that I'm aware of and increases our back-compat considerably for our users and the wider (p)react ecosystem.

Why does Preact need to deal with these types at all?

What types? Mirror @types/react in preact/compat? As I've mentioned twice now, augmenting React, as you suggest, doesn't cover the divergences in our types. For users that type-check libs, and those who use import ... from 'react'/import ... from 'react-dom' source code, these divergences could create problems as the types would be incorrect.

---

Evidently we're talking past each other but I really don't know how to make this any clearer, we're not doing all this extra work just for fun (I hope, if you have a better method I'd love to hear it). If you have a concrete PR in mind, feel free to open it and we can take a look there.

[remcohaszing]

What types?

I meant the global React UMD namespace, not the react users can import.

So this specific line:

export as namespace React;

---

Initially I though this was a bug. I used Preact at some point, but it has been a while. If I recall correctly, preact/compat could at some point be used together with @types/react, but I might be wrong. So this issue came as a surprise to me.

Since preact/compat was pulled in as a transient dependency, it was even more surprising to find these incompatibilities in a Next.js project. Nobody should ever use the React global, but Next.js forces users to. This is fixed in vercel/next.js#83159.

The issue is fixed in the problematic library in transloadit/uppy#5935. It no longer depends on preact/compat. I suppose libraries never should, at least for types.

I had my doubts about preact/compat declaring the global React namespace. It should not exist in @types/react. It should never be used. However, it does exist, so it is probably used in practice. Existing React libraries might provide components compatible with Preact, and they can use the global React namespace in their declaration files even if they shouldn’t. I think this is the reason Preact needs to declare the global React namespace.

The errors users get from this are really confusing, but I suppose there’s not really a solution. So I’m closing this.

[rschristian]

If I recall correctly, preact/compat could at some point be used together with @types/react

It didn't work well, most users would see a bunch of type errors, but you are absolutely correct. It used to be pretty common to see them used alongside each other.

I think it's been 3-ish years since we started discouraging this though as it was impossible for us to support.

---

Sorry this wasn't the outcome you were looking for but perhaps we can take another look at this in a couple years.