fluent-compiler

0.1.0 verified Fri May 01 auth: no javascript

fluent-compiler (v0.1.0, stable pre-release) is a JavaScript transpiler for Project Fluent's FTL format. It compiles FTL messages into ES6 modules that export FluentBundle-compatible objects, shifting compilation from runtime to build time. Unlike the core `fluent` package (which ships a ~10kB runtime compiler), `fluent-compiler` outputs pre-compiled code with a ~1.2kB runtime dependency, reducing browser bundle size. It supports locale identifiers, optional AST input from `fluent-syntax`, configurable runtime imports, and Unicode isolation marks. Suitable for Node.js >=8.9.0 and build pipelines (Webpack, Rollup). Note: The runtime API is based on a draft PR (#360) and may change.

Common errors

error Error: Cannot find module 'fluent-syntax' ↓

cause The `compile()` function with string source requires `fluent-syntax` for parsing.

fix

Run npm install fluent-syntax or ensure it's listed in dependencies.

error TypeError: locale is not a string or array ↓

cause `compile()` first argument must be a locale string, string array, or undefined.

fix

Call compile('it', source) or compile(['it', 'en'], source) or compile(undefined, source).

error SyntaxError: Unexpected token 'export' ↓

cause Attempting to `require()` the compiled module in a CommonJS environment.

fix

Use import statement or dynamic import(). If in Node.js CJS, rename file to .mjs or set type: module in package.json.

error ReferenceError: DATETIME is not defined ↓

cause The compiled module references runtime globals like DATETIME, NUMBER, which are expected to be provided by the runtime.

fix

Set runtimeGlobals option to include only those available, or provide polyfills.

Warnings

breaking Runtime API is based on a draft PR (#360) and is subject to change. The current `format()`/`compound()` API may be revised in future releases. ↓

fix Pin to exact version and test thoroughly before upgrading. Monitor Fluent.js PR #360 for API changes.

gotcha The compiled module should not be used with `bundle.addMessages()`; use `bundle.addResource()` instead, as `addMessages` requires runtime compilation. ↓

fix Always use `bundle.addResource(resource, { allowOverrides: true })` for adding compiled resources.

gotcha The compiled output is an ES6 module with a default export. It cannot be required via `require()` without transpilation or dynamic import. ↓

fix Use `import` or `import()` to consume the generated module. If using CJS, compile with a tool like Babel or set up Node.js for ESM.

gotcha The `compile()` function accepts `source` as a string or a `Resource` AST object. When passing a string, ensure `fluent-syntax` is installed or provide a pre-parsed AST. ↓

fix Install `fluent-syntax` as a dependency if you plan to pass string sources. Alternatively, parse with `fluent-syntax` yourself and pass the AST.

Install

npm install fluent-compiler

yarn add fluent-compiler

pnpm add fluent-compiler

Imports

compile
wrong
```
const compile = require('fluent-compiler')
```
correct
```
import { compile } from 'fluent-compiler'
```
The package is ESM-only and does not export a CommonJS default. In older Node.js or CJS environments, use dynamic import or transpile.
default export (compiled module)
wrong
```
const messages = require('./compiled.ftl.js')
```
correct
```
import messages from './compiled.ftl.js'
```
The generated module uses ESM default export. If consumed from CJS, use dynamic import or compile with CommonJS output.
type imports (TypeScript)
```
import type { FluentBundle } from 'fluent-compiler/runtime'
```
Main package does not export types; runtime types may be available from the runtime path or `fluent` package.

Quickstart

Shows end-to-end usage: compile FTL to JS, then import and use the pre-compiled bundle with format().

import { compile } from 'fluent-compiler'
import fs from 'fs'

// Read FTL source
const ftlSource = fs.readFileSync('messages.it.ftl', 'utf8')

// Compile to ES6 module string
const compiledJS = compile('it', ftlSource, {
  runtimePath: 'fluent-compiler/runtime',
  useIsolating: true,
  withJunk: false
})

// Write output
fs.writeFileSync('messages.it.js', compiledJS)

// In application code:
import it from './messages.it.js'

console.log(it.format('sync-signedout-account-title'))
// Output: 'Connetti il tuo account Firefox'