React Refresh Transformer for TypeScript

Common errors

• Error: `module` must be `es2015` or later.

  cause The TypeScript `module` compiler option is set to `CommonJS` or an older value that is not compatible with Fast Refresh transformation.
  fix Change `compilerOptions.module` in your `tsconfig.json` to `es2015` or a newer ES module target.

• TypeError: (0 , react_refresh_typescript_1.refresh) is not a function

  cause Attempting to use `react-refresh-typescript` with a named import when it provides a default export.
  fix Change your import statement from `import { refresh } from 'react-refresh-typescript';` to `import refresh from 'react-refresh-typescript';`

Warnings

• breaking This transformer does not work with TypeScript `module` option set to `CommonJS`. It requires `es2015` or later.
  Fix: Ensure your `tsconfig.json` `compilerOptions.module` is set to `es2015`, `esnext`, `es2020`, `es2022`, or `nodenext`.
• gotcha The package is under 'on-demand maintenance', meaning updates to match the latest `react-refresh` runtime may not be immediate. It currently matches `react-refresh@0.19.*`.
  Fix: If you encounter issues with newer `react-refresh` versions, open an issue on the GitHub repository to prompt an update.
• gotcha When using `react-refresh-typescript` in Deno, you must provide a TypeScript instance either via an import map for 'typescript' or by passing `options.ts`.
  Fix: Configure an `import_map.json` in Deno to map `typescript` (e.g., to `https://esm.sh/typescript`) or import `dist-src/core.js` and provide `ts` in the options object directly.
• gotcha The `refresh()` function should typically be called without arguments when used as a `ts-loader` custom transformer, but it accepts an `Options` object for custom configurations.
  Fix: Pass an `Options` object to `refresh()` if you need to customize `refreshReg`, `refreshSig`, `emitFullSignatures`, `ts` instance, or `hashSignature`.

Install

• npm install react-refresh-typescript npm
• yarn add react-refresh-typescript yarn
• pnpm add react-refresh-typescript pnpm

Imports

• refresh
  wrong:

  import { refresh } from 'react-refresh-typescript';

  correct:

  import refresh from 'react-refresh-typescript';

  This package exports a default function. Named imports for the main transformer are incorrect.
• Options

  import type { Options } from 'react-refresh-typescript';

  Used for type hinting the configuration object for the transformer.
• require('react-refresh-typescript')

  require('react-refresh-typescript')

  CommonJS `require` for usage in bundler configurations like webpack's `ts-loader` options. The result is a function that should be called.

Quickstart

Demonstrates how to use react-refresh-typescript with TypeScript's `transpileModule` API to transform React JSX code for Fast Refresh.

import refresh from 'react-refresh-typescript';
import ts from 'typescript';

const sourceCode = `
const App = () => {
    const [count, setCount] = React.useState(0);
    return (
        <div>
            <h1>Hello Fast Refresh!</h1>
            <p>Count: {count}</p>
            <button onClick={() => setCount(c => c + 1)}>Increment</button>
        </div>
    );
};
export default App;
`;

const { outputText } = ts.transpileModule(sourceCode, {
    compilerOptions: {
        target: ts.ScriptTarget.ESNext,
        jsx: ts.JsxEmit.Preserve,
        module: ts.ModuleKind.ESNext, // Required for Fast Refresh
    },
    fileName: 'app.tsx',
    transformers: { before: [refresh()] },
});

console.log(outputText);