#Environment Variables
.env files, precedence, and process.env access.
Krate loads .env files at build and serve time and makes the resolved values
available to everything that runs server-side via process.env.
#File names and precedence
Krate reads, in increasing precedence:
| File | When loaded |
|---|---|
.env |
Always (base values) |
.env.<mode> |
Always, after .env |
.env.local |
Always, after .env.<mode> |
.env.<mode>.local |
Always, last (highest precedence) |
Later files override earlier ones. Values already present in the shell
environment always win over every file (dotenv override=false semantics),
which is how you override config at deploy time without editing files.
The mode depends on the command:
| Command | Mode |
|---|---|
krate dev |
development |
krate build |
production |
krate serve |
production |
NODE_ENV or KRATE_ENV overrides the default mode.
#Env files outside the project
By default the files are read from the project root. In a monorepo the shared
.env often sits at the repository root; point Krate at it with envDir:
// apps/web/krate.config.ts
export default defineConfig({ envDir: "../.." });envDir resolves against the project root, may be a parent directory, and must
exist. Every place that loads .env files uses it (dev, build, serve, start,
deploy, API routes, middleware, build-time evaluators, and krate.config.ts
itself, which sees the variables from envDir). The built server.mjs of
krate deploy --target node never reads .env files: set the variables in the
environment of the process (systemd EnvironmentFile=, docker run --env-file).
Files named .env.local and .env.*.local (your local, machine-specific
overrides) are listed in the .gitignore that create-krate-app generates so
secrets are not committed; add them to the .gitignore of an existing project. Keep non-secret defaults in committed .env files.
#File syntax
# A comment line
APP_NAME=krate-examples
export APP_MODE=production # optional `export ` prefix is stripped
SECRET="double quoted" # quotes are stripped
PATH_VAR=${BASE}/sub # $VAR / ${VAR} expansion
LITERAL='$HOME' # single-quoted: no expansion
INLINE=value # trailing comment after whitespaceKEY=VALUEonly; keys are trimmed of surrounding whitespace.#starts a comment on its own line; a#preceded by whitespace inside an unquoted value trims the rest of the line.$VARand${VAR}expand to the value ofVAR(in-file definitions are chained first, then the shell environment). Missing variables expand to the empty string.- Single-quoted values are literal - no expansion - matching dotenv.
See the krate-examples project for a working setup: examples/.env and
examples/.env.production, exercised by the src/api/env.ts route at
/api/env.
#Where variables are visible
.env values reach process.env in every server-side execution context:
- API routes -
src/api/*.ts(embedded QuickJS) andsrc/api/*.go(the Go sidecar subprocess). - Plugins - Go plugin hooks and JS/TS community plugins running in QuickJS.
- SSR / ISR / streaming pages - the renderer sidecar subprocess.
generateStaticParams- the embedded or bundled-runtime evaluation that computes statically generated params.
In every case, on every runtime (embedded QuickJS, Node, Bun, Deno) and in both
krate dev and krate serve, process.env holds the shell environment plus the
.env files, with the shell winning, and NODE_ENV set to "development" or
"production" when the shell does not set it. This also covers middleware and
the embedded generateStaticParams and metadata evaluation at build time.
FOO=bar krate serve therefore makes process.env.FOO readable in an API route
whichever runtime serves it. Shell variables never reach client output; only the
KRATE_PUBLIC_ rule below inlines values.
#Client-side variables
Variables whose name starts with KRATE_PUBLIC_ are inlined as string literals
at build time into both the statically rendered HTML and the browser
JavaScript, so a page can read them with either spelling:
<a href={import.meta.env.KRATE_PUBLIC_API_URL}>API</a>
const base = process.env.KRATE_PUBLIC_API_URL;Values come from the .env files described above and from the shell
environment (the shell wins). Changing one of them (or the mode) rebuilds the pages that
were built with the old value; the build cache does not replay them. These build constants are always available, with
no prefix: import.meta.env.MODE (the environment mode), DEV, PROD,
BASE_URL (the base path with a trailing slash) and SSR (always false in
client and static code); process.env.NODE_ENV is "development" or
"production".
Reading any other process.env.X or import.meta.env.X in a client component
or a statically rendered page is not possible: the value is never written to
output and the read is undefined. Krate reports it as warning
KR8310 with the file, line and column.
Server components, API routes, plugins and server actions keep full access to
process.env.
#Security
Environment values are build/serve-time only and are never emitted into
client HTML, JavaScript, or hydration payloads, except variables you opt in
with the KRATE_PUBLIC_ prefix. Do not put secrets in values
you render into a page component tree; only server-only contexts (API routes,
server components, plugins) may read them. Krate logs only that a given env
file was found/loaded - never its values.
#Compiler tuning variables
These are read from the shell environment (not .env) and tune robustness
limits. All are optional.
| Variable | Default | Effect |
|---|---|---|
KRATE_DEBUG |
unset | Re-throw internal panics with their original stack instead of reporting them as build errors. |
KRATE_EXEC_TIMEOUT |
unset | Fallback timeout for external processes without a specific override (Go duration, e.g. 90s). |
KRATE_API_TIMEOUT |
30s |
How long a JS/TS API route may take to return its response before it is answered with 504. A route's export const maxDuration overrides it. See API routes. |
KRATE_GOAPI_TIMEOUT |
15m |
Timeout for go build of the Go host (API routes + components). |
KRATE_GOAPI_TIDY_TIMEOUT |
10m |
Timeout for go mod tidy when go.tidy is enabled. |
KRATE_GIT_TIMEOUT |
60s |
Timeout for git reads used by lastUpdated/sitemap. |
KRATE_INSTALL_TIMEOUT |
30m |
Timeout for krate plugin add package installs. |
KRATE_JS_MEMORY_MB |
32 |
Embedded QuickJS heap limit. |
KRATE_JS_STACK_KB |
16 |
Embedded QuickJS stack limit, at most 32. The default allows about 16,000 nested calls; past the limit a call throws a catchable error. |
KRATE_JS_TIMEOUT |
30s |
Embedded QuickJS eval timeout. Build-time evaluations on Node or Bun use the same limit. |
KRATE_BUILD_JS |
auto | Engine for build-time JavaScript: generateMetadata and metadata, generateStaticParams, resource-hint renders and island server renders. node or bun runs it in a few long-lived worker processes, each evaluation in a fresh context; quickjs keeps it in the embedded engine. Unset, the build uses the project's runtime, ssr.ssrRuntime or ssr.apiRuntime when that is node or bun, else node, then bun, from PATH, and QuickJS when neither is installed. A worker that fails to start or dies hands the rest of the build to QuickJS. |
KRATE_BUILD_JS_WORKERS |
min(4, CPUs/3) |
Number of Node or Bun build workers. Without it, the memory budget also allows at most one worker per 2 GiB. |
KRATE_MAX_MEMORY |
3/4 of available memory | The most memory krate build and krate dev use, Node or Bun workers included: a size (6G, 4096M, 2.5GiB) or a percentage of the machine's or container's memory (50%). See Build memory. |
KRATE_PLUGIN_MAX_FILES |
10000 |
Max files a single plugin hook may emit. |
KRATE_PLUGIN_MAX_FILE_BYTES |
67108864 |
Max size of a single plugin-emitted file. |
KRATE_ALLOW_UNSAFE_OUTDIR |
unset | Allow an outDir that is a filesystem root or the project root (normally refused). |
Set a timeout to 0 (or off) to disable it. Other operational variables
include KRATE_NO_BUILD_CACHE (skip the disk build cache) and
KRATE_REQUIRE_E2E=1 (turn environment-missing test skips into failures).
Browser and performance gates:
| Variable | Default | Effect |
|---|---|---|
KRATE_BROWSER |
unset | Selects chromium, firefox, or webkit for browser conformance and the React differential. |
KRATE_HYDRATION_BUDGET_MS |
1500 |
Maximum island hydration time from navigation start in the browser conformance gate. CI uses 2500. |
KRATE_REACT_EXIT |
unset | Fail the React differential on any P0/P1 divergence (CI sets this). |
KRATE_REACTBROWSER_REPORT |
unset | Write the React differential report to this path. |
#Build memory
A build works within a memory budget: KRATE_MAX_MEMORY when set, otherwise
three quarters of the memory available when the build starts. Inside a
container (cgroup v2) the budget comes from the container's limit and what it
already uses, not from the host's memory.
The budget limits memory by slowing the build down, not by failing it:
- The Go heap gets a soft limit (unless
GOMEMLIMITis set): half of the budget, at least 4 GiB, and never more than the budget. The garbage collector works harder as the heap nears it instead of growing into swap. - Pages, esbuild calls and build-time JavaScript renders start only while memory allows. When the build's live data nears the budget, or the machine or container runs short of memory, each kind of work runs one job at a time until memory frees up. One job always runs, so the build always finishes.
- Node build workers get a V8 heap limit of a quarter of the budget, between 1 GiB and 4 GiB. A worker that runs out of heap stops, and the embedded engine runs the rest of the build, as for any worker failure.
krate build --profile prints the budget and how often memory pressure held
work back. To keep several builds on one machine within its memory, give each
one a share, for example KRATE_MAX_MEMORY=25% krate build.
Last updated: 2026-11-17
Contributors: Noinkin