Configuration API

primate/config validates application configuration and returns the application facade exported by config/app.ts.

import config from "primate/config";

This page is a lookup for accepted keys, defaults, and validation. See the Configuration guide for deployment advice and examples, the Modules guide for writing extensions, and the AppFacade API for the returned value.

`config()`

function config<
  P extends EnvSchema = EnvSchema,
  const I extends I18NConfig | undefined = undefined,
  const T extends Record<string, string> = Record<string, string>,
  D extends DB = DB,
>(input?: ConfigInput<P, I, T, D>): AppFacade<P, I, D>;

Parameters: input is optional and defaults to {}. Pema validates it, applies defaults, and rejects invalid values. http.timeout is explicitly closed and rejects unknown members.

Returns: An AppFacade<P, I, D> preserving the inferred environment, localization, and migration-database types.

Throws: A Pema parse error for invalid configuration. Removed db.migrations.autoapply, client.groups, and numeric http.timeout forms produce migration diagnostics instead of being ignored.

// config/app.ts
import config from "primate/config";

export default config({
  http: { port: 8080 },
});

`ConfigInput`

ConfigInput is an inferred supporting type, not a named export from primate/config. The following expanded shape represents the current public input contract; generic refinements preserve partition, environment, i18n, and database inference.

type ConfigInput<P, I, T, D> = {
  build?: { external?: string[] };
  conditions?: string[];
  client?: {
    partitions: T;
    routes: Record<string, keyof NoInfer<T> & string>;
  };
  http?: {
    csp?: Record<string, string[]>;
    headers?: Record<string, string>;
    host?: string;
    port?: number;
    timeout?: {
      inactivity?: number;
      request?: number;
      headers?: number;
    };
    ssl?: { cert?: string; key?: string };
    static?: { root?: string };
  };
  livereload?: {
    exclude?: string[];
    host?: string;
    port?: number;
  };
  migrations?: { table: string; db: D };
  env?: { schema?: ObjectType<P> };
  i18n?: I;
  loaders?: Record<string, "file">;
  entrypoints?: Record<string, string>;
  modules?: Module[];
};

`input.build.external`

build?: { external?: string[] };

Packages or import paths excluded from the production server bundle. The default is []; duplicate entries are rejected. External packages must be available in the production installation.

`input.conditions`

conditions?: string[];

Additional package export conditions used by client and server builds. The default is []; duplicate entries are rejected.

`input.client`

client?: {
  partitions: Record<string, string>;
  routes: Record<string, string>;
};

Defines isolated client bundles and maps route prefixes to partition names. Both maps are required when client is present. Route values are constrained to inferred partitions keys. The complete prefix and isolation rules are in the Configuration guide.

`input.http.csp`

csp?: Record<string, string[]>;

Content-Security-Policy directives. No policy is emitted by default.

`input.http.headers`

headers?: Record<string, string>;

Default response headers added while rendering application views. The default is no additional headers.

`input.http.host`

host?: string;

Server host. Defaults to HOST from the environment, then "localhost".

`input.http.port`

port?: number;

Unsigned valid TCP port. Defaults to numeric PORT from the environment, then 6161.

`input.http.timeout`

timeout?: {
  inactivity?: number;
  request?: number;
  headers?: number;
};

Optional whole-millisecond network clocks. inactivity accepts 0 through 255000; request and headers accept 0 through 2147483647. Omitted members preserve runtime defaults. Runtime support and interactions are listed in the Configuration guide.

`input.http.ssl`

ssl?: { cert?: string; key?: string };

Certificate and private-key paths. HTTPS is active only when both are defined. Both values default to undefined.

`input.http.static.root`

static?: { root?: string };

URL root under which files from the application static directory are served. Defaults to "/".

`input.livereload`

livereload?: {
  exclude?: string[];
  host?: string;
  port?: number;
};

Development live-reload exclusions and endpoint overrides. host defaults to the configured HTTP host and port defaults to one less than the configured HTTP port when Primate resolves the live-reload endpoint.

`input.migrations`

migrations?: { table: string; db: DB };

Configures the application migration ledger and preserves db in the returned facade's migration declaration type. There is no default migration ledger; migrations are applied explicitly rather than at server startup.

`input.env.schema`

env?: { schema?: ObjectType<EnvSchema> };

Pema object schema for environment values. When present, values are parsed when the server facade is attached and app.env() becomes key- and result-typed. The default is no schema.

`input.i18n`

i18n?: I18NConfig;

Localization configuration. The default is undefined, which installs the missing-i18n facade. See the primate/i18n API and Internationalization guide.

`input.loaders`

loaders?: Record<string, "file">;

Maps file extensions to esbuild loaders. The only accepted value is "file". The default is no additional loader mapping.

`input.entrypoints`

entrypoints?: Record<string, string>;

Named files from client bundled for matching HTML template placeholders. The default is no named entrypoints. app, head, and body are reserved.

`input.modules`

modules?: Module[];

Extension modules initialized in array order. The default is []; module names must be unique. See the Module API.

Test Application

Module