# @palamedes/config

[![npm version](https://img.shields.io/npm/v/%40palamedes%2Fconfig?logo=npm)](https://www.npmjs.com/package/@palamedes/config)
[![CI](https://github.com/sebastian-software/palamedes/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/sebastian-software/palamedes/actions/workflows/ci.yml)
[![Sponsored by Sebastian Software](https://img.shields.io/badge/Sponsored%20by-Sebastian%20Software-0f172a.svg)](https://oss.sebastian-software.com/)
[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-0f172a.svg)](https://github.com/sebastian-software/palamedes#license)

Lean config loading for Palamedes projects.

Use `@palamedes/config` when framework integrations need to load Palamedes
config files. It supports canonical `palamedes.yaml` files, secondary
`palamedes.yml`, `palamedes.json`, and `palamedes.toml` data files, and the
legacy `palamedes.config.ts/js/mjs/cjs` TypeScript/JavaScript formats.

## Minimal Example

```yaml
locales: [en, de]
source-locale: en
source-reference-root: git
catalogs:
  - path: src/locales/{locale}
    include: [src]
    po:
      line-breaks: "off"
```

PO output options are per catalog. In JavaScript or TypeScript configs, use
`po: { lineBreaks }`; data configs use the kebab-case spelling shown above.
Catalog order is not configurable — Ferrocat gives PO and FCL catalogs the
CLDR root order matching `Intl.Collator("en-US")`. The `po` object is invalid
for FCL catalogs.

## Exports

- `defineConfig(config)`
- `loadPalamedesConfig(options?)`
- `loadPalamedesConfigSync(options?)` — synchronous variant with the same
  options and return shape, for hosts that cannot await (e.g. synchronous
  loader hooks)
- `CONFIG_FILENAMES`
- `expandFallbackLocales(locales, fallbackLocales?)`
- `resolveCatalogPath(config, catalogPath, locale)`
- `resolveConfigPattern(config, pattern)`
- `PalamedesPluginDeclaration` (TypeScript)

## Configuration Notes

- `fallback-locales` defines the fallback chain for missing translations. It can
  be one shared array or a per-locale map.
- `pseudo-locale` marks a generated pseudo-locale used for layout and hardcoded
  string checks. Plugin integrations skip `failOnMissing` failures for that
  locale while keeping strict checks for real locales.
- `source-reference-root` controls the root used for catalog source references.
  The default is `"git"`, which emits paths relative to the nearest Git
  repository root and falls back to the config directory when no Git root is
  available. Use `"lingui"` or `"config"` for Lingui-compatible references
  relative to the config directory, or pass a custom path.
- `reference-scopes` defaults to `true`. Set it to `false` to skip stable
  component/function scope extraction and emit file-only PO and FCL references.
- `catalogs[].format` defaults to `"po"`. Set it to `"fcl"` to use Ferrocat
  Catalog Lines for canonical, merge-friendly generated catalog storage.
- `plugins` explicitly lists CLI plugin package specifiers or
  `[specifier, options]` pairs. Packages are never auto-discovered, and built-in
  CLI commands do not load them.
- `loadPalamedesConfig()` returns `sourceReferenceRoot` and the resolved
  `referenceScopes` boolean in addition to `configPath` and `rootDir`. Its
  `configDependencies` array contains real paths for the config and every local
  file imported by a legacy executable config. Framework integrations use this
  list for cache invalidation and file watching. Pass `skipValidation` only when
  inspecting a partially-authored config file.

See [Catalog formats](https://github.com/sebastian-software/palamedes/blob/main/docs/catalog-formats.md)
for the PO/FCL storage boundary.

See [Pseudo-localization and fallback locales](https://github.com/sebastian-software/palamedes/blob/main/docs/pseudo-localization.md)
for examples and the recommended development workflow.

<!-- ferramenta-family:start -->

**palamedes** is part of the [Ferramenta](https://ferramenta.dev) family — Rust-native developer tools that keep the APIs the ecosystem already knows.

Siblings: [ferroni](https://sebastian-software.github.io/ferroni/) · [ferriki](https://github.com/sebastian-software/ferriki) · [ferromark](https://sebastian-software.github.io/ferromark/) · [ferrolex](https://github.com/sebastian-software/ferrolex) · [ferrocat](https://ferrocat.dev) · [ferrovia](https://github.com/sebastian-software/ferrovia) · [ferralk](https://github.com/sebastian-software/ferralk) · [ferrugo](https://github.com/sebastian-software/ferrugo).
<!-- ferramenta-family:end -->

## License

[![Sebastian Software](https://sebastian-brand.vercel.app/sebastian-software/logo-software.svg)](https://oss.sebastian-software.com/)

MIT OR Apache-2.0 © 2026 Sebastian Software