React Native TypeScript Transformer

Common errors

• Error: Unable to resolve module `react-native-typescript-transformer`

  cause The package `react-native-typescript-transformer` is not installed or Metro cannot find it in your `node_modules`.
  fix Run `yarn add --dev react-native-typescript-transformer typescript` and ensure your `metro.config.js` or `rn-cli.config.js` correctly references the package.

• TypeError: Cannot read property 'babelTransformerPath' of undefined

  cause Your `metro.config.js` is malformed, or you are trying to use the newer `transformer.babelTransformerPath` syntax with an older React Native version that expects `getTransformModulePath()`.
  fix Check your `metro.config.js` for syntax errors. Verify your React Native version and use the corresponding configuration structure from the package documentation (e.g., for RN < 0.57, use `getTransformModulePath`).

• Type errors not reported in console during `react-native run-android/ios`

  cause The build process is using Babel (which only strips types) or the `noEmit: true` option in `tsconfig.json` prevents `tsc` from generating output, but you are not running `tsc` separately for type checking.
  fix Run `tsc --noEmit --watch` in a separate terminal during development, or integrate `tsc --noEmit` into your build script or CI/CD pipeline to perform type checking.

Warnings

• deprecated This package is largely deprecated. For new React Native projects or existing projects on RN 0.57+, it is recommended to use `react-native init MyProject --template typescript` which uses Babel for TypeScript transpilation, or follow Babel-based migration guides.
  Fix: For new projects, use `react-native init --template typescript`. For existing projects, migrate to Babel-based TypeScript setup as detailed in official React Native documentation or community gists (e.g., linked in the README).
• gotcha When using Babel for TypeScript transpilation (the recommended modern approach), Babel does not perform type checking. You must run the TypeScript compiler (`tsc --noEmit`) separately as a linter or for CI checks to catch type errors.
  Fix: Integrate `tsc --noEmit` into your development workflow (e.g., as a pre-commit hook or watch command) and CI/CD pipelines.
• gotcha Babel transpilation for TypeScript does not support certain advanced language features: namespaces, bracket-style type assertions (e.g., `<Foo>x`) when JSX is enabled, enums spanning multiple declarations (enum merging), and legacy import/export syntax (`import foo = require(...)`).
  Fix: Avoid these specific TypeScript features when using Babel for transpilation. For bracket-style assertions, use `x as Foo` instead. This transformer, if used, supports these features by compiling with `tsc`.
• gotcha The platform-specific entry files (e.g., `index.ios.js`, `index.android.js`, `index.js`) must remain JavaScript files (`.js`) and cannot be converted to TypeScript (`.ts` or `.tsx`).
  Fix: Keep your root entry point files as JavaScript. You can import TypeScript components from these files.
• breaking The configuration for this transformer in the React Native packager (Metro) changed significantly across different React Native versions. RN < 0.57 uses `getTransformModulePath()` and `getSourceExts()`, while RN >= 0.57 uses `transformer.babelTransformerPath`.
  Fix: Consult the package README for the correct `metro.config.js` or `rn-cli.config.js` structure corresponding to your specific React Native version.

Install

• npm install react-native-typescript-transformer npm
• yarn add react-native-typescript-transformer yarn
• pnpm add react-native-typescript-transformer pnpm

Imports

• transformer.babelTransformerPath
  wrong:

  import transformer from 'react-native-typescript-transformer'

  correct:

  module.exports = { transformer: { babelTransformerPath: require.resolve('react-native-typescript-transformer') } }

  This package is a Metro/packager transformer configured via `metro.config.js` or `rn-cli.config.js` and is not directly imported into application code. The primary interaction is via `require.resolve`.
• getTransformModulePath

  module.exports = { getTransformModulePath() { return require.resolve('react-native-typescript-transformer'); } }

  Used for React Native versions older than 0.57 in `rn-cli.config.js` configuration.
• getSourceExts

  module.exports = { getSourceExts() { return ['ts', 'tsx']; } }

  Often configured alongside `getTransformModulePath` for older React Native versions to ensure `.ts` and `.tsx` files are recognized by the packager.

Quickstart

This quickstart configures `tsconfig.json` and `metro.config.js` to enable TypeScript compilation for React Native >= 0.59 projects using this transformer, along with necessary dev dependencies.

{
  // tsconfig.json
  "compilerOptions": {
    "target": "es2015",
    "jsx": "react",
    "noEmit": true,
    "moduleResolution": "node",
    "importHelpers": true // Optional, for tslib
  },
  "exclude": [
    "node_modules"
  ]
}

// metro.config.js (for RN >= 0.59)
module.exports = {
  transformer: {
    babelTransformerPath: require.resolve('react-native-typescript-transformer')
  },
  resolver: {
    sourceExts: ['js', 'jsx', 'ts', 'tsx', 'json', 'node']
  }
};

// Add dev dependencies
// yarn add --dev react-native-typescript-transformer typescript @types/react @types/react-native