rollup-plugin-formatjs

3.0.0 verified Mon Apr 27 auth: no javascript

A Rollup and Vite plugin that applies formatjs (react-intl) message extraction and translation transforms during the build process. Version 3.0.0 is the latest stable release, with monthly updates. It seamlessly integrates with the formatjs ecosystem, supporting both Rollup (^3) and Vite via plugin-compat. Unlike manual extraction, this automates the pipeline from source code to compiled messages, reducing configuration overhead. Ships TypeScript definitions.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/rollup-plugin-formatjs/dist/index.js from /path/to/project/rollup.config.js not supported. ↓

cause Using CommonJS require() with package set to type: module or ESM-only dist.

fix

Switch to ESM imports (import formatjs from 'rollup-plugin-formatjs') or rename config to .mjs.

error TypeError: (0 , _rollupPluginFormatjs.default) is not a function ↓

cause Named import instead of default import.

fix

Use import formatjs from 'rollup-plugin-formatjs' instead of import { formatjs } from 'rollup-plugin-formatjs'.

error Error: Cannot find module '@formatjs/icu-messageformat-parser' ↓

cause Transitive dependency not installed (e.g., using npm 6 with no dedupe).

fix

Run npm install or explicitly add @formatjs/icu-messageformat-parser to your dependencies.

error Error: [object Object] is not a PostCSS plugin (or similar message when used with other tools) ↓

cause Incorrect plugin ordering; formatjs plugin placed before CSS-related plugins in Rollup array.

fix

Ensure formatjs plugin comes after CSS plugins or is configured only for JS files with include/exclude.

Warnings

breaking v3 dropped support for Rollup <3.0.0. ↓

fix Upgrade Rollup to ^3.0.0.

gotcha Default export must be imported directly; named destructuring fails silently with undefined or error. ↓

fix Use default import: import formatjs from 'rollup-plugin-formatjs'

gotcha Option 'extractFromFormatMessageCall' defaults to false; without it, message extraction does not cover formatMessage calls, only <FormattedMessage> components. ↓

fix Set extractFromFormatMessageCall: true in plugin options.

gotcha Plugin may fail silently if source code contains invalid ICU messages; no runtime error is thrown. ↓

fix Validate messages with @formatjs/cli extract command before building.

gotcha TypeScript type 'FormatjsOptions' is exported but not listed in package.json exports field; some bundlers may not resolve it. ↓

fix Use @ts-ignore or import via explicit path to types: import type { FormatjsOptions } from 'rollup-plugin-formatjs/lib/types'

Install

npm install rollup-plugin-formatjs

yarn add rollup-plugin-formatjs

pnpm add rollup-plugin-formatjs

Imports

formatjs

wrong

import { formatjs } from 'rollup-plugin-formatjs'

correct

import formatjs from 'rollup-plugin-formatjs'

Default export; named import breaks in v3+.

formatjs

wrong

const { formatjs } = require('rollup-plugin-formatjs')

correct

const formatjs = require('rollup-plugin-formatjs')

CommonJS default import; destructuring fails.

FormatjsOptions

import type { FormatjsOptions } from 'rollup-plugin-formatjs'

TypeScript type import for configuration object.

Quickstart

Basic Rollup config that applies formatjs transforms to source files, generating compiled message IDs and optimizations.

import formatjs from 'rollup-plugin-formatjs';
import { defineConfig } from 'rollup';

export default defineConfig({
  input: 'src/index.js',
  plugins: [
    formatjs({
      idInterpolationPattern: '[sha512:contenthash:base64:6]',
      ast: true,
      extractFromFormatMessageCall: true,
      additionalFunctionNames: [],
      additionalComponentNames: [],
      removeDefaultMessage: false,
      overrideIdFn: undefined,
      sourceMaps: false,
      include: '**/*.{js,ts,jsx,tsx}',
      exclude: 'node_modules/**'
    })
  ],
  output: { file: 'dist/bundle.js', format: 'es' }
});