Configuration

Vesk projects are configured with `vesk.config.js` or `vesk.config.ts` in the project root. TypeScript configs are transpiled inline at startup — no separate build step needed.

Basic config

									
										import { defineConfig } from '@vesk/compiler'

export default defineConfig({
  appDir: './app',
  outDir: '.vesk',
  publicDir: './public',
  security: 'strict',
  md: {
    html: 'escape',
  },
})
									
								

Loading

• The CLI looks for `vesk.config.js` first, then `vesk.config.ts`; if neither exists, the app runs with defaults.
• TS configs are transpiled inline (`typescript.transpile`); `@vesk/compiler` imports are stripped, `defineConfig` / `definePlugin` / `preset` are injected via `globalThis.__vesk_inject`, the result is written to `.vesk/config.tmp.js`, imported, and the exports map makes the helpers available inside the config.
• The loaded object flows through `defineConfig` (normalization + security defaults) and then `validateConfig` (plugin contract checks) before any command runs.
• Environment files load before the config (`loadEnvFiles` runs first), so `process.env` is already populated when `vesk.config.ts` evaluates.

Config options

defineConfig

`defineConfig(config)` returns the config after normalizing it. It resolves `security` (preset string to object, `'off'`/`false` to `{}`, function to its return value) and then fills in guard defaults that apply on top of any preset.

• `security` may be a named preset (`'strict'`, `'default'`, `'minimal'`), `'off'` / `false`, a plain object, or a function `(preset) => VeskSecurity` that receives the `preset()` helper.
• Applying the defaults fills: `autoEscape: true`, `csrf: true` (same-origin check for unsafe methods), `xFrameOptions: 'DENY'`, the default Content-Security-Policy, and `redactLogs: true` — even when `security` was `false`/`'off'` (those only suppress the named-preset picks).
• The default CSP is `default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; frame-src 'self'; connect-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self'`.
• `routeDataCache` defaults to `0` when absent.
• `md.html` must be one of `escape` / `allow` / `allowlist` (anything else throws a config error); `md.allowTags` entries are lowercased and stripped to `[a-z0-9-]`.

Security presets

The named presets are built in `@vesk/compiler/src/config.ts`. `'default'` is defined as a shallow copy of `'strict'`. Presets only set the fields shown; the rate-limit / CORS / trust-proxy knobs live on `VeskSecurity` but are not part of any preset.

preset()

`preset(name, overrides?)` returns a security object for `'production'` (strict settings) or `'development'` (strict minus Content-Security-Policy). Unknown names throw, and `overrides` are merged last. It is normally reached through the `security` function form:

									
										import { defineConfig } from '@vesk/compiler'

export default defineConfig({
  security: (preset) =>
    preset('production', {
      contentSecurityPolicy: false,
    }),
})
									
								

Environment variables

• `vesk` loads `.env` then `.env.local` from the project root before anything else; because keys are only set when not already in `process.env`, `.env.local` wins over `.env`.
• Only `KEY=VAL` lines are read. Blank lines and `#` comments are skipped; surrounding quotes on values are stripped.
• Keys already present in `process.env` are never overridden by either file.
• Loaded before `vesk.config.ts` evaluates, so config files can read `process.env` at load time.

Platforms

`vesk build --platform <name>` picks the deployment artifact. Without the flag, the adapter auto-detects the platform from well-known CI/build environment variables and otherwise defaults to a standard Node server.

App events and server context

App-level lifecycle events live in one convention file: `app/_events.ts` (or `app/_events.js`), which exports optional `onStart`, `onRequest` and `onStop` handlers. The `_` prefix marks the file private — it is never routed. Both the events file and plugin `onStart`/`onStop` hooks receive a `ServerEventContext`.

									
										import type { ServerEventContext } from '@vesk/types'

export async function onStart(ctx: ServerEventContext) {
  ctx.set('bootedAt', Date.now())
}

export async function onRequest(ctx: ServerEventContext) {
  const hits = (ctx.get('hits') as number) || 0
  ctx.set('hits', hits + 1)
}
									
								

• `onStart` runs once when a dev/start server boots, before it begins listening; on serverless/edge targets it runs lazily once per isolate. Node servers additionally expose `server`, `port`, and `host`.
• `onRequest` runs for every request and receives the per-request `request`, `params`, `url`, `cookies` and `locals` in addition to the shared store.
• `onStop` runs on graceful shutdown (`SIGINT`/`SIGTERM`). Node dev/start servers only — serverless/edge targets have no shutdown lifecycle.
• `ctx.set(key, value)` / `ctx.get(key)` read and write the process-wide store exposed as `serverLocals`. Values set during `onStart` are pre-seeded into every request's `locals()`.
• Dev servers run the live handlers and reload them on HMR; production builds bake `app/_events.ts` into `server/events.js` at build time.

Component context (createContext)

`createContext` is a component-scoped runtime API (from `@vesk/runtime/src/context.ts`), not a config or plugin feature. It is auto-imported from `@vesk/runtime` whenever a `.vsk` component uses it. `createContext(defaultValue)` returns a `Context<T>`: `get()` walks up the active-component chain returning the nearest value set by an ancestor (falling back to the default), and `set(value)` stores a value for the currently rendering component (it throws `No active component found, cannot set context` outside a render). `getActiveComponent()` / `setActiveComponent()` are the runtime's lower-level hooks for tracking the active component and are used by renderer internals.

										
											component Theme {
  const Theme = createContext('light')
  Theme.set('dark')
  <p>{Theme.get()}</p>
}