@saykit/config

@saykit/config exports the defineConfig helper, the underlying Zod schemas / types, and a small set of building blocks used by the CLI and plugins.

import { defineConfig } from '@saykit/config';
import type { Config, Bucket, Formatter, Transformer, Message } from '@saykit/config';

Most application code only ever uses defineConfig and the types. The other exports exist for plugin and transformer authors.

defineConfig(config)

Validate a SayKit configuration against the Zod schema and return the normalised result.

import { defineConfig } from '@saykit/config';
import po from '@saykit/format-po';
import js from '@saykit/transform-js';

export default defineConfig({
  locales: ['en', 'fr'],
  buckets: [
    {
      include: ['src/**/*.ts'],
      output: 'src/locales/{locale}.{extension}',
      formatter: po(),
      transformer: js(),
    },
  ],
});

Returns the parsed Config. Throws if validation fails (with a Zod error containing the path and reason).

Types

Config

Bucket

After parsing, each bucket also exposes match(id) and an output value with a match(id) helper. Plugin authors can use these to test whether a file belongs to a bucket:

config.buckets[0]!.match('src/app/page.tsx'); // true if matched by include
config.buckets[0]!.output.match('src/locales/en.po'); // true if it's a translation file

Formatter

Transformer

Message

Subpath exports

@saykit/config also exposes a few subpaths used by plugins and transformer authors.

@saykit/config/features/loader

import { resolveConfig } from '@saykit/config/features/loader';

resolveConfig(name?)

Search up from process.cwd() for saykit.config.{ts,mts,cts,js,mjs,cjs} (or ${name}.config.*), transpile it if necessary, and return the validated Config.

const config = resolveConfig(); // looks for saykit.config.*
const config = resolveConfig('my-tool'); // looks for my-tool.config.*

Used by:

• the saykit CLI
• unplugin-saykit
• babel-plugin-saykit

Transpiled TS configs are cached in node_modules/.cache/saykit/config/, keyed by the config file's mtime and the workspace's tsconfig.json mtimes.

@saykit/config/features/messages

import {
  generateHash,
  assignSequenceIdentifiers,
  CompositeMessage,
  LiteralMessage,
  ArgumentMessage,
  ChoiceMessage,
  ElementMessage,
} from '@saykit/config/features/messages';

The internal Message types used by transformers (different from the public catalogue Message shape), plus helpers:

• generateHash(text, context?), produces the same 6-character id SayKit uses elsewhere
• assignSequenceIdentifiers(message, { current: 0 }), numbers positional placeholders depth-first

These exist so that custom transformers can produce the same id and placeholder shape the built-in transformers do.

Next

• Configuration guide, how this schema is used in practice
• Custom formatter, implementing Formatter
• Custom transformer, implementing Transformer