{"id":25597,"library":"fluent-compiler","title":"fluent-compiler","description":"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.","status":"active","version":"0.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/eemeli/fluent-compiler","tags":["javascript","localization","l10n","internationalization","i18n","ftl","ast","compiler","transpiler"],"install":[{"cmd":"npm install fluent-compiler","lang":"bash","label":"npm"},{"cmd":"yarn add fluent-compiler","lang":"bash","label":"yarn"},{"cmd":"pnpm add fluent-compiler","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Optional 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()`.","package":"fluent-syntax","optional":true}],"imports":[{"note":"The package is ESM-only and does not export a CommonJS default. In older Node.js or CJS environments, use dynamic import or transpile.","wrong":"const compile = require('fluent-compiler')","symbol":"compile","correct":"import { compile } from 'fluent-compiler'"},{"note":"The generated module uses ESM default export. If consumed from CJS, use dynamic import or compile with CommonJS output.","wrong":"const messages = require('./compiled.ftl.js')","symbol":"default export (compiled module)","correct":"import messages from './compiled.ftl.js'"},{"note":"Main package does not export types; runtime types may be available from the runtime path or `fluent` package.","wrong":"","symbol":"type imports (TypeScript)","correct":"import type { FluentBundle } from 'fluent-compiler/runtime'"}],"quickstart":{"code":"import { compile } from 'fluent-compiler'\nimport fs from 'fs'\n\n// Read FTL source\nconst ftlSource = fs.readFileSync('messages.it.ftl', 'utf8')\n\n// Compile to ES6 module string\nconst compiledJS = compile('it', ftlSource, {\n  runtimePath: 'fluent-compiler/runtime',\n  useIsolating: true,\n  withJunk: false\n})\n\n// Write output\nfs.writeFileSync('messages.it.js', compiledJS)\n\n// In application code:\nimport it from './messages.it.js'\n\nconsole.log(it.format('sync-signedout-account-title'))\n// Output: 'Connetti il tuo account Firefox'\n","lang":"typescript","description":"Shows end-to-end usage: compile FTL to JS, then import and use the pre-compiled bundle with format()."},"warnings":[{"fix":"Pin to exact version and test thoroughly before upgrading. Monitor Fluent.js PR #360 for API changes.","message":"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.","severity":"breaking","affected_versions":"0.1.0"},{"fix":"Always use `bundle.addResource(resource, { allowOverrides: true })` for adding compiled resources.","message":"The compiled module should not be used with `bundle.addMessages()`; use `bundle.addResource()` instead, as `addMessages` requires runtime compilation.","severity":"gotcha","affected_versions":">=0.0.0"},{"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.","message":"The compiled output is an ES6 module with a default export. It cannot be required via `require()` without transpilation or dynamic import.","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Install `fluent-syntax` as a dependency if you plan to pass string sources. Alternatively, parse with `fluent-syntax` yourself and pass the AST.","message":"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.","severity":"gotcha","affected_versions":">=0.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run `npm install fluent-syntax` or ensure it's listed in dependencies.","cause":"The `compile()` function with string source requires `fluent-syntax` for parsing.","error":"Error: Cannot find module 'fluent-syntax'"},{"fix":"Call `compile('it', source)` or `compile(['it', 'en'], source)` or `compile(undefined, source)`.","cause":"`compile()` first argument must be a locale string, string array, or undefined.","error":"TypeError: locale is not a string or array"},{"fix":"Use `import` statement or dynamic `import()`. If in Node.js CJS, rename file to .mjs or set type: module in package.json.","cause":"Attempting to `require()` the compiled module in a CommonJS environment.","error":"SyntaxError: Unexpected token 'export'"},{"fix":"Set `runtimeGlobals` option to include only those available, or provide polyfills.","cause":"The compiled module references runtime globals like DATETIME, NUMBER, which are expected to be provided by the runtime.","error":"ReferenceError: DATETIME is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}