inlanginlang
Paraglide JS

Paraglide JS

Tool

CompilerOptions

CompilerOptions = object

Defined in: compiler-options.ts:51

Properties

additionalFiles?

optional additionalFiles: Record<string, string>

Defined in: compiler-options.ts:238

The additionalFiles option is an array of paths to additional files that should be copied to the output directory.

Example
await compile({
  project: "./project.inlang",
  outdir: "./src/paraglide",
  additionalFiles: [
+    "my-file.js": "console.log('hello')"
  ]
})

The output will look like this:

  - outdir/
    - messages/
+   - my-file.js
    - messages.js
    - runtime.js

cleanOutdir?

optional cleanOutdir: boolean

Defined in: compiler-options.ts:386

Whether to clean the output directory before writing the new files.

Default
true

cookieDomain?

optional cookieDomain: string

Defined in: compiler-options.ts:212

The host to which the cookie will be sent. If undefined or empty, the domain attribute is omitted from the cookie, scoping it to the exact current domain only (no subdomains). If specified, the cookie will be available to the specified domain and all its subdomains.

Use this when you need cookies to be shared across subdomains (e.g., between app.example.com and api.example.com). The default behavior (no domain) ensures better compatibility with server-side cookies that don't specify a domain attribute.

Example
// Default: exact domain only (compatible with server-side cookies)
cookieDomain: undefined // Cookie: "PARAGLIDE_LOCALE=en; path=/; max-age=34560000"

// Subdomain sharing: available across all subdomains
cookieDomain: "example.com" // Cookie: "PARAGLIDE_LOCALE=en; path=/; max-age=34560000; domain=example.com"
Default
"" (no domain attribute, exact domain only)

cookieMaxAge?

optional cookieMaxAge: number

Defined in: compiler-options.ts:192

The max-age in seconds of the cookie until it expires.

Default
60 * 60 * 24 * 400

cookieName?

optional cookieName: string

Defined in: compiler-options.ts:186

The name of the cookie to use for the cookie strategy.

Default
'PARAGLIDE_LOCALE'

disableAsyncLocalStorage?

optional disableAsyncLocalStorage: boolean

Defined in: compiler-options.ts:315

Replaces AsyncLocalStorage with a synchronous implementation.

Leave AsyncLocalStorage enabled by default. This option is a compatibility fallback for runtimes that do not provide AsyncLocalStorage or node:async_hooks.

⚠️ WARNING: Only use this option when your runtime also guarantees request isolation. Disabling AsyncLocalStorage in multi-request server environments risks cross-request pollution where state from one request could leak into another concurrent request.

emitGitIgnore?

optional emitGitIgnore: boolean

Defined in: compiler-options.ts:329

If emitGitIgnore is set to true a .gitignore file will be emitted in the output directory. Defaults to true.

  - outdir/
    - messages/
+   - .gitignore
    - messages.js
    - runtime.js
Default
true

emitPrettierIgnore?

optional emitPrettierIgnore: boolean

Defined in: compiler-options.ts:252

If emitPrettierIgnore is set to true a .prettierignore file will be emitted in the output directory. Defaults to true.

  - outdir/
    - messages/
+   - .prettierignore
    - messages.js
    - runtime.js
Default
true

emitReadme?

optional emitReadme: boolean

Defined in: compiler-options.ts:269

If emitReadme is set to true a README.md file will be emitted in the output directory. Defaults to true.

The README helps LLMs understand the compiled output. See https://llmstxt.org/ for format guidelines.

  - outdir/
    - messages/
+   - README.md
    - messages.js
    - runtime.js
Default
true

emitTsDeclarations?

optional emitTsDeclarations: boolean

Defined in: compiler-options.ts:292

Emit .d.ts files for the generated output using the TypeScript compiler.

Useful when allowJs: true cannot be set in your tsconfig.json (e.g., due to project constraints or conflicting compiler options).

Requires typescript to be resolvable in your toolchain.

Note: Enabling this option reduces compiler speed because TypeScript needs to generate declaration files for all output modules.

Example
await compile({
  project: "./project.inlang",
  outdir: "./src/paraglide",
  emitTsDeclarations: true,
});
Default
false

experimentalMiddlewareLocaleSplitting?

optional experimentalMiddlewareLocaleSplitting: boolean

Defined in: compiler-options.ts:127

Whether or not to use experimental middleware locale splitting.

⚠️ This feature is experimental and only works in SSR/SSG environment without client-side routing. Do not rely on this feature for production.

This feature is part of the exploration of per locale splitting. The issue is ongoing and can be followed here #88.

  • The client bundle will tree-shake all messages (have close to 0kb JS).
  • The server middleware will inject the used messages into the HTML.
  • The client will re-trieve the messages from the injected HTML.
Default
false

experimentalStaticLocale?

optional experimentalStaticLocale: string

Defined in: compiler-options.ts:180

Compile-time locale constant used for per-locale tree-shaking.

This is experimental and opt-in. It should be a JavaScript expression (not a quoted literal) that resolves to a locale or undefined at build time. You can pass a string literal (e.g. "de") for programmatic builds, or an injected env/define expression for bundler-driven builds.

High-level flow for per-locale builds:

client request (/) | v +----------------------+ | detect locale | | (cookie/Accept-L) | | pick build prefix | +----------------------+ | if "de" v serve dist/de/... <----> serve dist/en/... (HTML + assets) (HTML + assets)

See

https://github.com/opral/paraglide-js/issues/88#issuecomment-3634754638

Examples
// Vite define
  experimentalStaticLocale: "typeof __PARAGLIDE_STATIC_LOCALE__ === 'undefined' ? undefined : __PARAGLIDE_STATIC_LOCALE__"

// Programmatic compile (literal)
  experimentalStaticLocale: '"de"'

fs?

optional fs: any

Defined in: compiler-options.ts:393

The file system to use. Defaults to await import('node:fs').

Useful for testing the paraglide compiler by mocking the fs.

includeEslintDisableComment?

optional includeEslintDisableComment: boolean

Defined in: compiler-options.ts:302

Whether to include an eslint-disable comment at the top of each .js file.

Default
true

isServer?

optional isServer: string

Defined in: compiler-options.ts:146

Tree-shaking flag if the code is running on the server.

Dependent on the bundler, this flag must be adapted to enable tree-shaking.

Example
// vite
  isServer: "import.meta.env.SSR"
Default
typeof window === "undefined"

localStorageKey?

optional localStorageKey: string

Defined in: compiler-options.ts:133

The name of the localStorage key to use for the localStorage strategy.

Default
'PARAGLIDE_LOCALE'

outdir

outdir: string

Defined in: compiler-options.ts:75

The path to the output directory.

Example
await compile({
  project: "./project.inlang",
+ outdir: "./src/paraglide"
})

outputStructure?

optional outputStructure: "locale-modules" | "message-modules"

Defined in: compiler-options.ts:380

The outputStructure defines how modules are structured in the output.

  • message-modules - Each module is a message. This is the default.
  • locale-modules - Each module is a locale.

It is recommended to use locale-modules for development and message-modules for production. Bundlers speed up the dev mode by bypassing bundling which can lead to many http requests during the dev mode with message-modules. See https://github.com/opral/inlang-paraglide-js/issues/486.

message-modules

Messages have their own module which eases tree-shaking for bundlers.

  - outdir/
    - messages/
+   - blue_elephant_tree/
+     - index.js
+     - en.js
+     - fr.js
+   - sky_phone_bottle/
+     - index.js
+     - en.js
+     - fr.js
    - ...
  - messages.js
  - runtime.js

locale-modules

Messages are bundled in a per locale module. Bundlers often struggle with tree-shaking this structure, which can lead to more inefficient tree-shaking and larger bundle sizes compared to message-modules.

The benefit are substantially fewer files which is needed in large projects.

  - outdir/
    - messages/
+     - de.js
+     - en.js
+     - fr.js
      - ...
  - messages.js
  - runtime.js
Default
"message-modules"

project

project: string

Defined in: compiler-options.ts:63

The path to the inlang project.

Example
await compile({
+ project: "./project.inlang",
  outdir: "./src/paraglide"
})

routeStrategies?

optional routeStrategies: RouteStrategy[]

Defined in: compiler-options.ts:111

Route-level strategy overrides.

Routes are matched in declaration order. The first matching rule wins. match uses URLPattern syntax.

  • strategy: Override locale resolution for the matched route.
  • exclude: true: Skip i18n middleware behavior for the matched route.
Example
routeStrategies: [
  { match: "/dashboard/:path(.*)?", strategy: ["cookie", "baseLocale"] },
  { match: "/api/:path(.*)?", exclude: true }
]

strategy?

optional strategy: Runtime["strategy"]

Defined in: compiler-options.ts:93

The strategy to use for getting the locale.

The order of the strategy defines the precedence of matches.

For example, in ['url', 'cookie', 'baseLocale'], the locale will be first tried to be detected in the url, then in a cookie, and finally fallback to the base locale.

The default ensures that the browser takes a cookie approach, server-side takes the globalVariable (because cookie is unavailable), whereas both fallback to the base locale if not available.

Custom strategies with the pattern custom-[A-Za-z0-9]+ are supported.

Default
["cookie", "globalVariable", "baseLocale"]

urlPatterns?

optional urlPatterns: Runtime["urlPatterns"]

Defined in: compiler-options.ts:296

https://inlang.com/m/gerre34r/library-inlang-paraglideJs/strategy#url

RouteStrategy

RouteStrategy = { exclude?: never; match: string; strategy: Runtime["strategy"]; } | { exclude: true; match: string; strategy?: never; }

Defined in: compiler-options.ts:3

Type Declaration

{ exclude?: never; match: string; strategy: Runtime["strategy"]; }

exclude?

optional exclude: never

Prevent mutually exclusive configuration (exclude + strategy).

match

match: string

URLPattern-compatible matcher.

strategy

strategy: Runtime["strategy"]

Strategy override for matching requests.

{ exclude: true; match: string; strategy?: never; }

exclude

exclude: true

Exclude matching requests from i18n middleware behavior.

match

match: string

URLPattern-compatible matcher.

strategy?

optional strategy: never

Prevent mutually exclusive configuration (exclude + strategy).

defaultCompilerOptions

const defaultCompilerOptions: object

Defined in: compiler-options.ts:33

Type Declaration

cleanOutdir

readonly cleanOutdir: true = true

cookieDomain

readonly cookieDomain: "" = ""

cookieMaxAge

readonly cookieMaxAge: number

cookieName

readonly cookieName: "PARAGLIDE_LOCALE" = "PARAGLIDE_LOCALE"

disableAsyncLocalStorage

readonly disableAsyncLocalStorage: false = false

emitGitIgnore

readonly emitGitIgnore: true = true

emitPrettierIgnore

readonly emitPrettierIgnore: true = true

emitReadme

readonly emitReadme: true = true

emitTsDeclarations

readonly emitTsDeclarations: false = false

experimentalMiddlewareLocaleSplitting

readonly experimentalMiddlewareLocaleSplitting: false = false

includeEslintDisableComment

readonly includeEslintDisableComment: true = true

isServer

readonly isServer: "typeof window === 'undefined'" = "typeof window === 'undefined'"

localStorageKey

readonly localStorageKey: "PARAGLIDE_LOCALE" = "PARAGLIDE_LOCALE"

outputStructure

readonly outputStructure: "message-modules" = "message-modules"

strategy

readonly strategy: ["cookie", "globalVariable", "baseLocale"]

Edit this page on GitHub