babel-plugin-fbt

1.0.0 verified Sat Apr 25 auth: no javascript

The main Babel transform plugin for Facebook's FBT (Facebook Translation) internationalization framework. Current stable version is 1.0.0, released with a regular cadence alongside the FBT ecosystem. It provides compile-time extraction and transformation of <fbt> elements and fbt() calls for localization. Key differentiators include React-integrated string interpolation with gender and number variations, and a hash-based string collection approach. Requires pairing with fbt-babel-plugin-runtime for runtime token resolution and @fbtjs/default-collection-transform for string collection outputs.

Common errors

error Error: Cannot find module '@fbtjs/default-collection-transform' ↓

cause Missing peer dependency after upgrading to v1.0.0.

fix

Run: npm install --save-dev @fbtjs/default-collection-transform

error TypeError: Cannot read properties of undefined (reading 'fbt') ↓

cause Runtime plugin is not installed or configured, or fbt runtime import is missing.

fix

Install babel-plugin-fbt-runtime and add it to babel.config.js after babel-plugin-fbt.

error SyntaxError: Unexpected token, expected "..." while parsing JSX with <fbt> ↓

cause Babel is not configured to parse JSX, or the plugin order is wrong.

fix

Ensure @babel/preset-react is included and that babel-plugin-fbt appears before the runtime plugin in the plugins array.

Warnings

breaking Version 1.0.0 changed peer dependency from fbt to @fbtjs/default-collection-transform. ↓

fix Install @fbtjs/default-collection-transform as a devDependency.

deprecated The fbtCommonPath and fbtEnumPath options are deprecated in favor of using the collection transform. ↓

fix Migrate to using @fbtjs/default-collection-transform and remove fbtCommonPath/fbtEnumPath from plugin options.

gotcha Plugin order matters: babel-plugin-fbt must come before babel-plugin-fbt-runtime in the plugins array. ↓

fix Ensure plugins are ordered correctly: first babel-plugin-fbt, then babel-plugin-fbt-runtime.

gotcha The fbt package must be installed as a runtime dependency, not devDependency, for the runtime plugin to work. ↓

fix Install fbt as a regular dependency: npm install fbt

Install

npm install babel-plugin-fbt

yarn add babel-plugin-fbt

pnpm add babel-plugin-fbt

Imports

default export (plugin)
wrong
```
import plugin from 'babel-plugin-fbt';
```
correct
```
module.exports = require('babel-plugin-fbt');
```
This is a Babel plugin, not a JS module for direct import. It's used in .babelrc or babel.config.js as 'babel-plugin-fbt'.
Babel config usage
wrong
```
plugins: [require('babel-plugin-fbt')]
```
correct
```
plugins: ['babel-plugin-fbt']
```
Babel resolves string plugin names automatically. Using require() works but is unnecessary and less portable.
TypeScript type import
```
import type { FbtPluginOptions } from 'babel-plugin-fbt';
```
The package does not ship TypeScript types; custom type definitions would need to be created.

Quickstart

Installs the FBT Babel plugin and runtime, configures them, and demonstrates basic usage with a React JSX component.

// Install dependencies
npm install --save-dev babel-plugin-fbt @fbtjs/default-collection-transform
npm install --save fbt babel-plugin-fbt-runtime

// babel.config.js
module.exports = {
  plugins: [
    ['babel-plugin-fbt', {
      fbtEnumPath: 'path/to/enums',
      fbtCommonPath: 'path/to/common-strings.json',
    }],
    'babel-plugin-fbt-runtime'
  ]
};

// Then in React code:
<fbt desc="example">Hello, <fbt:param name="name">{name}</fbt:param>!</fbt>