React Support

tsdown provides first-class support for building React component libraries. As Rolldown natively supports bundling JSX/TSX files, you don't need any additional plugins to get started.

Quick Start

For the fastest way to get started, use the React component starter template. This starter project comes pre-configured for React library development, so you can focus on building components right away.

npx create-tsdown@latest -t react

To use React Compiler, you can quickly set up a project with the dedicated template:

npx create-tsdown@latest -t react-compiler

Minimal Example

To configure tsdown for a React library, you can just use a standard tsdown.config.ts:

tsdown.config.ts

import { defineConfig } from 'tsdown'

export default defineConfig({
  entry: ['./src/index.ts'],
  platform: 'neutral',
  dts: true,
})

Create your typical React component:

MyButton.tsx

import React from 'react'

interface MyButtonProps {
  type?: 'primary'
}

export const MyButton: React.FC<MyButtonProps> = ({ type }) => {
  return <button className="my-button">my button: type {type}</button>
}

And export it in your entry file:

index.ts

export { MyButton } from './MyButton'

WARNING

There are 2 ways of transforming JSX/TSX files in tsdown:

• classic
• automatic (default)

If you need to use classic JSX transformation, you can configure Rolldown's transform.jsx option in your configuration file:

tsdown.config.ts

import { defineConfig } from 'tsdown'

export default defineConfig({
  inputOptions: {
    transform: {
      jsx: 'react', // Use classic JSX transformation
    },
  },
})

Enabling React Compiler

React Compiler is an innovative build-time tool that automatically memoizes React components and hooks. React recommends that library authors use React Compiler to precompile their code for improved performance.

There are two ways to use it in tsdown: the stable Babel-based integration, and the new experimental native Oxc support.

Babel preset

React Compiler is distributed as a Babel plugin. @vitejs/plugin-react exports a reactCompilerPreset helper that configures babel-plugin-react-compiler for you. Combine it with @rolldown/plugin-babel to use it in tsdown:

pnpm add -D @rolldown/plugin-babel @vitejs/plugin-react babel-plugin-react-compiler

tsdown.config.ts

import pluginBabel from '@rolldown/plugin-babel'
import { reactCompilerPreset } from '@vitejs/plugin-react'
import { defineConfig } from 'tsdown'

export default defineConfig({
  plugins: [
    pluginBabel({
      presets: [reactCompilerPreset()],
    }),
  ],
})

Native Oxc support (experimental)

Since @vitejs/plugin-react 6.1.0, React Compiler is also available in a native form through the standalone oxc-transform-react package, which bundles the Rust port of the React Compiler. Install it and enable the experimental compiler option:

pnpm add -D @vitejs/plugin-react oxc-transform-react

tsdown.config.ts

import react from '@vitejs/plugin-react'
import { defineConfig } from 'tsdown'

export default defineConfig({
  entry: ['./src/index.ts'],
  platform: 'neutral',
  dts: true,
  plugins: [
    react({
      compiler: true,
      // Only needed when `dts: true`: prevent the plugin from
      // transforming the generated .d.ts files
      exclude: [/node_modules/, /\.d\.ts$/],
    }),
  ],
})

The exclude is only required when dts: true — the plugin's default filter also matches generated declaration files, which breaks the build. Without dts, react({ compiler: true }) is all you need.

The compiler runs on the original source before any other transform and is enabled by default with a React 19 target. Pass compiler options to target other versions:

react({
  compiler: {
    target: '18', // '17' | '18' | '19'
  },
})

React 19 ships the compiler runtime in react; targets 17 and 18 require the react-compiler-runtime package. Files whose filename contains node_modules are skipped by default — provide a sources allowlist in the compiler options to opt dependencies back in.

WARNING

The native React Compiler support is experimental and under active development. Options and behavior may change, so review the generated output before using it in production.