{"id":15212,"library":"react-refresh-typescript","title":"React Refresh Transformer for TypeScript","description":"react-refresh-typescript is a TypeScript transformer that integrates React Fast Refresh (Hot Module Replacement) into React applications. It specifically handles the necessary transformations for TypeScript codebases to enable live editing of React components without losing their state. The package is currently under on-demand maintenance, meaning updates typically occur when issues are opened to track upstream changes in `react-refresh`. It currently matches `react-refresh@0.19.*` (React 19). Its primary audience includes bundler plugin developers, such as those building integrations for webpack, Rollup, or esbuild. Key differentiators include its direct integration as a TypeScript custom transformer, which allows it to operate early in the compilation pipeline, and its support for Deno environments. This package is essential for enabling a smooth developer experience with hot reloading in TypeScript-based React projects.","status":"maintenance","version":"2.0.12","language":"javascript","source_language":"en","source_url":"https://github.com/Jack-Works/react-refresh-transformer","tags":["javascript","react","refresh","transformer","typescript"],"install":[{"cmd":"npm install react-refresh-typescript","lang":"bash","label":"npm"},{"cmd":"yarn add react-refresh-typescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-refresh-typescript","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime peer dependency for React Fast Refresh functionality.","package":"react-refresh","optional":false},{"reason":"Compiler peer dependency required for transformation.","package":"typescript","optional":false}],"imports":[{"note":"This package exports a default function. Named imports for the main transformer are incorrect.","wrong":"import { refresh } from 'react-refresh-typescript';","symbol":"refresh","correct":"import refresh from 'react-refresh-typescript';"},{"note":"Used for type hinting the configuration object for the transformer.","symbol":"Options","correct":"import type { Options } from 'react-refresh-typescript';"},{"note":"CommonJS `require` for usage in bundler configurations like webpack's `ts-loader` options. The result is a function that should be called.","symbol":"require('react-refresh-typescript')","correct":"require('react-refresh-typescript')"}],"quickstart":{"code":"import refresh from 'react-refresh-typescript';\nimport ts from 'typescript';\n\nconst sourceCode = `\nconst App = () => {\n    const [count, setCount] = React.useState(0);\n    return (\n        <div>\n            <h1>Hello Fast Refresh!</h1>\n            <p>Count: {count}</p>\n            <button onClick={() => setCount(c => c + 1)}>Increment</button>\n        </div>\n    );\n};\nexport default App;\n`;\n\nconst { outputText } = ts.transpileModule(sourceCode, {\n    compilerOptions: {\n        target: ts.ScriptTarget.ESNext,\n        jsx: ts.JsxEmit.Preserve,\n        module: ts.ModuleKind.ESNext, // Required for Fast Refresh\n    },\n    fileName: 'app.tsx',\n    transformers: { before: [refresh()] },\n});\n\nconsole.log(outputText);","lang":"typescript","description":"Demonstrates how to use react-refresh-typescript with TypeScript's `transpileModule` API to transform React JSX code for Fast Refresh."},"warnings":[{"fix":"Ensure your `tsconfig.json` `compilerOptions.module` is set to `es2015`, `esnext`, `es2020`, `es2022`, or `nodenext`.","message":"This transformer does not work with TypeScript `module` option set to `CommonJS`. It requires `es2015` or later.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"If you encounter issues with newer `react-refresh` versions, open an issue on the GitHub repository to prompt an update.","message":"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.*`.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Pass an `Options` object to `refresh()` if you need to customize `refreshReg`, `refreshSig`, `emitFullSignatures`, `ts` instance, or `hashSignature`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Change `compilerOptions.module` in your `tsconfig.json` to `es2015` or a newer ES module target.","cause":"The TypeScript `module` compiler option is set to `CommonJS` or an older value that is not compatible with Fast Refresh transformation.","error":"Error: `module` must be `es2015` or later."},{"fix":"Change your import statement from `import { refresh } from 'react-refresh-typescript';` to `import refresh from 'react-refresh-typescript';`","cause":"Attempting to use `react-refresh-typescript` with a named import when it provides a default export.","error":"TypeError: (0 , react_refresh_typescript_1.refresh) is not a function"}],"ecosystem":"npm"}