Config File

Overview

A Sigil config file is a TypeScript module that exports an Environment as its default export. Sigil dynamically imports this file at runtime using Bun’s native TypeScript support — no build step required.

File location

By default, Sigil looks for sigil.config.ts in the current working directory. Override with the --config flag:

sigil up --config ./configs/staging.config.ts

Structure

import { Environment, Postgres, Service } from "sigil";
import path from "path";

const root = import.meta.dir;

const env = new Environment("my-app");

// Add entities in dependency order
const db = env.add(new Postgres("db", { ... }));
env.add(new Service("api", { ... }));

// Must be the default export
export default env;

Key patterns

import.meta.dir

Use import.meta.dir to get the directory containing the config file. This makes paths work correctly regardless of where sigil up is run from:

const root = import.meta.dir;

new Postgres("db", {
  initSql: path.join(root, "db/schema.sql"),
});

new Service("api", {
  cwd: path.join(root, "backend"),
});

Dependency wiring

Entities that are added first start first. Use references to earlier entities to wire up dependencies:

const db = env.add(new Postgres("db", { ... }));

// db.connectionString is available immediately (computed from config)
env.add(new Service("api", {
  env: { DATABASE_URL: db.connectionString },
}));

Multiple configs

You can have multiple config files for different scenarios:

sigil.config.ts           # full stack
sigil.config.db-only.ts   # just the database
sigil.config.test.ts      # test environment with different ports

sigil up --config sigil.config.db-only.ts

What gets imported

Sigil does:

const mod = await import(configPath);
const env = mod.default; // must be an Environment

Side effects in your config file (like console.log) will execute when the config is imported.