silgi

import { defineConfig } from "silgi" is for silgi.config.ts. The config guide is Configuration; this page lists the exports.

defineConfig

Returns the config unchanged. It exists so the editor checks the keys.

function defineConfig(config: SilgiConfig): SilgiConfig

import { defineConfig } from "silgi";

export default defineConfig({
  framework: "react",
  app: { baseURL: "/", head: { titleTemplate: "%s · Shop" } },
  runtimeConfig: { apiSecret: "", public: { apiBase: "/api" } },
  routeRules: { "/blog/**": { prerender: true } },
});

defineEnv

The default export of app/env.ts: returns the entries unchanged, typed. Each key is a variable name; the build reads the names, public and static from the file's text, so the object is written out as a literal.

function defineEnv<const T extends EnvSchema>(env: T): T

#silgi/env/private exports every name (server code only; client code that imports it fails the build), #silgi/env/public the public names that are not static, and a static name is read as import.meta.env.<NAME>, written into both bundles at build. Values are validated when the server starts (static ones when the build starts); a failure stops with Invalid environment variables: and one line per bad name, a private value reported only by its length.

// app/env.ts
import { defineEnv } from "silgi";

export default defineEnv({
  API_KEY: {},
  PORT: { schema: (raw) => Number(raw), default: "3000", description: "Port of the HTTP server" },
  GA_ID: { public: true },
  SHOW_DEBUG: { public: true, static: true, schema: (raw) => raw === "true", default: "false" },
});

EnvEntry, EnvSchema, EnvOutput

EnvEntry is one variable: { public?: boolean; static?: boolean; schema?: StandardSchemaV1 | ((raw: string | undefined) => unknown); default?: string; description?: string }. schema is a Standard Schema or a function that returns the value or throws; default replaces an unset value, not an empty one; static needs public. EnvSchema is Record<string, EnvEntry>. EnvOutput<E> is the type a variable reads as: the schema's output, the function's return type, else string.

SilgiConfig, SilgiConfigBlock, ResolvedConfig

SilgiConfigBlock is the type of an env override block ($development, $production, $test, $env.<mode>): a SilgiConfig without rootDir, extends, dev and the block keys.

SilgiConfig is what you write: every key is optional. ResolvedConfig is what Silgi reads after it merged your file, the layers in extends and the defaults: every key is set, paths are absolute, and layers is added. Modules and the build see the resolved one as silgi.options.

app.baseURL and app.buildAssetsDir get a leading and a trailing / ("docs" becomes "/docs/"); a baseURL with a scheme, a ? or a # is an error. The config is checked when it loads, and all problems are thrown together as Invalid config (silgi.config.ts): with one line each: booleans (ssr, components, build.minify, server.trustProxy, imports.autoImport, prerender.crawl, prerender.failOnError, devServer.prefetch, devServer.tasks), build.compressPublic (a boolean or an object with only the keys gzip, brotli and zstd, each a boolean), devServer.port (an integer from 0 to 65535, a string is not converted), build.assetsInlineLimit (a non-negative integer), build.importProtection.client.deny and build.importProtection.server.deny (arrays of strings and RegExps), server.maxBodySize, server.maxRequestBodySize and prerender.concurrency (positive integers), build.sourcemap, app.trailingSlash, prerender.routes and prerender.ignore, routeRules[...].redirect, routeRules[...].basicAuth, and a srcDir that does not exist. A top-level key that is neither a key above nor the configKey of a loaded module logs [silgi] Unknown config key "runtimeconfig" (did you mean "runtimeConfig"?) and the build goes on. A config that still sets build.target or experimental, which were removed, logs one line each and loads. A config file that fails to load is reported as Cannot load silgi.config.ts: with the file, line and column; a config that default-exports a function is an error, use defineConfig.

With build.sourcemap unset, a production build writes no client source maps and the server bundle is "linked"; set "external" or "linked" to publish the client maps.

A file that a stylesheet loads with url() (a font, an image) is a hashed file under app.buildAssetsDir when it is larger than build.assetsInlineLimit bytes (default 4096), so a change to the CSS does not make visitors download it again. A smaller file stays inline in the CSS as a data: URI, and 0 emits every file. A file that a script imports is always a hashed file.

import type { SilgiConfig, ResolvedConfig } from "silgi";

export const config = { framework: "vue", ssr: false } satisfies SilgiConfig;

export function describe(resolved: ResolvedConfig): string {
  return `${resolved.framework} on ${resolved.preset}, output in ${resolved.outputDir}`;
}

ConfigHead, BuildConfig, KeyedComposable, PrerenderConfig, StorageMount

The types of app.head, of build, of one entry of build.keyedComposables, of prerender and of one value of storage, for a helper or a wrapper that builds that part of the config. ConfigHead is HeadInput with titleTemplate as a string only, because the config is serialized to the client.

A call of the adapter's three composables gets, whatever its arguments (the run time drops it when the call gave a key), and a call of an entry you add gets, when it has fewer than argumentLength arguments, { [Symbol.for("silgi.key")]: "$s<8 hex>" } as its last argument, in the server build, the client build and silgi dev; the hex is the start of the SHA-256 of <file relative to rootDir, with />:<line>:<column> of the call. Only a call of a name imported from its source counts (@silgi/<framework> for the three defaults). A module adds an entry with silgi.options.build.keyedComposables.push({ name, source, argumentLength }) in its setup; an entry with the name and source of a default replaces it. See State and Data.

const keyed: KeyedComposable = { name: "useCart", source: "~/cart", argumentLength: 1 }
const prerender: PrerenderConfig = { routes: ["/about"], crawl: true }
const mount: StorageMount = { driver: "memory" }

SilgiHooks, TsConfigFile

The build hooks as an interface of name to function. hooks in the config is { [name in keyof SilgiHooks]?: SilgiHooks[name] }, so a wrong name or a wrong signature is a type error. silgi/kit exports the same type.

SilgiModuleOptions

An empty interface that a module fills in to type its options. SilgiConfig gets one optional key for every key of it, so the options go under the module's configKey with type checking. silgi/kit exports the same type. See Modules.

import { defineConfig } from "silgi";

declare module "silgi" {
  interface SilgiModuleOptions {
    sitemap?: { hostname?: string };
  }
}

export default defineConfig({ modules: ["./modules/sitemap.ts"], sitemap: { hostname: "https://example.com" } });

HeadInput

The type that useHead takes: title, titleTemplate, meta, link, script, style, htmlAttrs and bodyAttrs; a tag may have a key. It is the same HeadInput that silgi/app exports. app.head in the config is typed by ConfigHead, the same shape with titleTemplate as a string only. See Head.

import { defineConfig } from "silgi";
import type { HeadInput } from "silgi";

const head = {
  title: "Silgi",
  titleTemplate: "%s · Silgi",
  meta: [{ name: "description", content: "A full-stack framework for Bun" }],
  link: [{ rel: "icon", href: "/favicon.svg" }],
} satisfies HeadInput;

export default defineConfig({ app: { head } });

RouteRule

One value of routeRules. Rules are matched by pattern and the more specific pattern wins. See Deploy and Storage and cache.

basicAuth asks for HTTP Basic credentials (see requireBasicAuth) for every path under the pattern, public files and prerendered pages included, before static files and routing; false lifts a less specific rule. Take the password from { runtimeConfig: "<key>" }: a literal in the config file warns at build, a key the config does not declare fails it. A CORS preflight passes without credentials when the same rule has cors. The rule covers paths, so a handler call (/_silgi/fn/<id>) is protected by defineMiddleware({ server: basicAuth(…) }) on the handler. A path that is a file stands for the route it serves, so a rule on /admin also guards /admin/index.html, and paths match exactly: /ADMIN is not /admin. On static the build fails; on vercel, netlify and cloudflare a prerendered page under the rule fails the build and a file of the output's public/ (including the /_silgi/ bundles under a /** rule) warns, since the platform serves them before the function.

import { defineConfig } from "silgi";
import type { RouteRule } from "silgi";

const docs: RouteRule = { prerender: true, headers: { "x-robots-tag": "all" } };
const legacy: RouteRule = { redirect: { to: "/docs", status: 301 } };

export default defineConfig({ routeRules: { "/docs/**": docs, "/old": legacy } });