@secundus-studio/stift-generator

Bundler-agnostic build core: config loading/validation, namespace discovery, pack compiler, and typegen.

What it is

The shared build engine behind @secundus-studio/stift-cli and @secundus-studio/stift-vite-plugin: config loading and validation (stift.config.ts), locale/namespace discovery, message-shape extraction, the pack compiler (.dat packs plus catalog.json and per-locale shards), and Register typegen (stift.gen.d.ts). Most users meet it through the CLI or the Vite plugin and never install it directly — reach for it when you need the pipeline programmatically (custom scripts, tests, or your own tooling).

pnpm add @secundus-studio/stift-generator

Quick start

import { Generator } from '@secundus-studio/stift-generator'

const generator = new Generator({ root: process.cwd() })

// Load stift.config.ts, discover locales/<locale>/<namespace>.json,
// extract param shapes, diff locales, emit src/stift.gen.d.ts.
await generator.generateAsync()

// Compile every (locale, namespace) into packs + catalog.json + shards.
await generator.compileAsync({ outDir: 'dist/packs' })

stift.config.ts is authored with the defineConfig helper and resolved with loadConfig / findConfigFile.

API

• Generator — one-shot pipeline: generateAsync() (config → discovery → extraction → diff → stift.gen.d.ts) and compileAsync() (packs + catalog + shards, written to outDir or returned in memory).
• DEFAULT_OUTPUT_REL — default relative output path for the generated declaration file.
• compileAll — compile every (locale, namespace) source into pack bytes, the catalog index, and one shard per locale.
• compileNamespace — compile a single namespace message map into pack bytes.
• resolveCompileSecurity — resolve the effective compiler security config from a loaded config (with static-key fallback).
• loadConfig / findConfigFile — resolve and schema-validate stift.config.ts.
• defineConfig — typed helper for authoring stift.config.ts.
• discoverConvention — walk locales/<locale>/<namespace>.json (nested namespaces supported) into a stable discovery result.
• generateTypegen — emit the stift.gen.d.ts Register declaration from config plus extraction.
• extractShapes / deriveLocaleShape — infer union-across-locale param shapes from message sources.
• diffLocales — diff key coverage across supported locales against the default locale.
• parseMessage / collectFunctions — ICU message parsing and function collection (re-exported from core).
• configSchema — schema the loaded config is validated against.
• Type-only: GenerateOptions, GenerateResult, CompileOptions, CompileResult, CompileAllOptions, CompileAllResult, CompileNamespaceOptions, CompiledNamespaceOutput, CompiledNamespaceCacheEntry, CompiledCache, LocaleShardOutput, CompileSecurityConfig, StiftConfig, ParamsConfig, ContextParamConfig, NamespacesConfig, DetectionConfig, LoadConfigOptions, LoadedConfig, DiscoveredNamespace, DiscoveryResult, ExtractResult, KeyShape, KeyLocaleShape, MessageSourceInput, ParamType, DiffResult, MissingDiffIssue, GenerateTypegenOptions, IcuNode, IcuOption, ParseResult.

Docs

• Config file: https://stift.secundus.studio/docs/latest/vanilla/configuration/config-file
• Build pipeline: https://stift.secundus.studio/docs/latest/vanilla/tooling/build
• Authoring messages: https://stift.secundus.studio/docs/latest/vanilla/authoring/messages