Registry / serialization / fluent-compiler

fluent-compiler

library0.1.0jsnpmunverified

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.

serialization web-framework

npm install fluent-compiler

github ↗package ↗

INSTALL

IMPORT

SIG · FLUENT-COMPILER

fluent-compiler

serializationjavascriptv0.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

compile

✓ import { compile } from 'fluent-compiler'

✗ const compile = require('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)

✓ import messages from './compiled.ftl.js'

✗ const messages = require('./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.

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'

Debug

Known issues

breakingRuntime 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.

affects: 0.1.0

gotchaThe 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.

affects: >=0.0.0

gotchaThe 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.

affects: >=0.0.0

gotchaThe `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.

affects: >=0.0.0

Errors

Common errors & fixes

Error: Cannot find module 'fluent-syntax'

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

fix

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

TypeError: locale is not a string or array

`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)`.

SyntaxError: Unexpected token 'export'

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.

ReferenceError: DATETIME is not defined

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.

Upgrade

Version history

0.1.0latest on npm

Audit

Dependencies

fluent-syntaxoptionalOptional dependency for parsing FTL strings into AST (e.g., if source is not yet a Resource object). Required only when passing string source to `compile()`.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/eemeli/fluent-compiler ↗

packagehttps://www.npmjs.com/package/fluent-compiler ↗