Configuration & Environment Validation

Choosing the Validator: TypeBox + Ajv

We need a schema, a validator, and a URI-format check. The common instinct is to install zod or env-schema. However, both are new dependencies for a job the project can already do.

Fastify uses TypeBox to express JSON Schemas and Ajv to compile and run them. We have written TypeBox schemas for route bodies and responses since chapter 5, and Ajv has been validating every request all along. They are already in the dependency tree as transitive dependencies of Fastify. Instead of adding a new framework, we will promote the three packages we need to explicit dependencies.

Nothing new is downloaded. The @sinclair/typebox, ajv, and ajv-formats packages were already resolved transitively. This install just records them as direct dependencies so config.ts does not rely on hidden packages. The payoff is a single mental model: the same tools you use for routes now validate the environment.

Three Ajv options do the heavy lifting here:

• coerceTypes: true turns the always-string PORT="4000" into the number 4000 the schema declares.
• useDefaults: true fills in the schema's default values for any optional variable that is absent.
• allErrors: true collects every problem in one pass. A broken deploy reports all missing variables at once instead of requiring a restart for each fix.

The ajv-formats package adds format: "uri", which we use to reject a malformed DATABASE_URL or BASE_URL.

The Variables We Validate

The schema sets additionalProperties: true on purpose. A real server environment is full of variables we do not care about, like PATH, HOME, and TEST_DATABASE_URL. We validate the four we actually read and ignore the rest. We do not want to reject an environment just because it contains extra variables.

Step 1: The Failing Test (Red)

Check out the start branch:

The start branch includes __tests__/config.test.ts but no src/config.ts to satisfy it. The suite imports a module that does not exist yet, so it cannot load. The first test pins down the happy path. A valid environment should parse into the typed object, with PORT coerced from a string to a number:

Notice that loadConfig takes its environment as an argument instead of reading the global object. That single design choice makes the whole module testable. Every test passes a plain object and asserts on the result without any process-wide environment juggling. One test makes the rule explicit: loading config must never touch the real process.env:

The rest of the suite covers the failure modes that matter at boot. These include a missing DATABASE_URL, a malformed URI, a non-numeric PORT, an unknown NODE_ENV, and a multi-problem environment that must report every error in a single message.

Run the unit suite:

The config suite fails to run with Cannot find module '../src/config'. It shows as 1 suite failed of 14, while the other 13 suites and all 68 prior tests stay green. Running npm run typecheck fails for the same reason: the imported module does not exist yet. This is an honest failing test state. Nothing is broken; the implementation simply is not written.

Step 2: The Config Module (Green)

Switch to the finish branch:

The schema is plain TypeBox. The defaults live on the schema itself, so Ajv applies them automatically. This means there is exactly one place in the code that says PORT defaults to 3000:

The Static<typeof ConfigSchema> utility derives the TypeScript type straight from the schema. This is the same trick we use for route types. You define the shape once. The validator and the static type both come from it, so they can never drift apart.

Compiling the validator wires up the three Ajv options and the URI format:

Next is the loader. The detail that makes it safe is the copy step. Ajv's coerceTypes and useDefaults options mutate the object they validate in place, so we never want to hand it the caller's original object. We pull the four variables we care about into a fresh candidate object. We drop the keys that are absent so useDefaults can fill them, validate that copy, and freeze the result:

Three important decisions are packed in here:

• env defaults to process.env but can be injected. Production calls loadConfig() and reads the real environment. Tests call loadConfig(fixture) and read a plain object. It is the same function, with no globals to stub.
• We validate a copy, so process.env is never mutated. Coercion and defaults rewrite candidate while leaving the source untouched. This is exactly what the test asserts.
• The result is frozen. A config that the app reads everywhere should be immutable. Object.freeze turns an accidental config.PORT = … into a thrown error instead of a silent, app-wide surprise.

The error message is the part operators actually see, so it names each offending variable on its own line:

Because Ajv runs with allErrors: true, a deploy with three mistakes prints three lines. You can fix the whole environment in a single pass instead of restarting the server after each fix.

Read Once, Reuse: a Lazy Singleton

The app needs one config, not a fresh load per import. But an eager const config = loadConfig() at the module top level would call loadConfig() the instant anything imports config.ts. This would immediately read process.env. In the Docker-free unit tests, there is no DATABASE_URL in the plain shell. That eager load would throw an error and crash config.test.ts on import.

The fix is a lazy, memoized accessor. It loads on the first call, caches the result, and returns the cache forever after:

Now process.env is only read when something actually calls getConfig(). Only the server does this at startup. Unit tests import loadConfig, pass their own fixtures, and never trigger the singleton. The module is testable without a real environment, and the running app still gets a single shared config.

Fail Fast at the Boot Boundary

The server.ts file is the one place that turns a bad environment into a clean exit. It calls getConfig() before doing anything else. On failure, it prints the message and exits with a non-zero status code:

This is the main point of the chapter. A misconfigured deploy dies at the boot boundary with exit(1). This is the signal every orchestrator understands as "this container did not start, do not route traffic to it." A failed loadConfig() against a clean environment prints exactly what is wrong:

The hardcoded port: 3000 and the literal documentation URL are gone. The server.ts file now reads config.PORT and config.BASE_URL, which are the validated values.

Resolving the Chapter-19 Note: BASE_URL

Three routes built shortUrl from a hardcoded http://localhost:3000/${shortCode}. That string was correct in development and wrong in every other environment. This was the note we left for "later." Later is now. Each route takes a baseUrl and builds the URL from it:

The list.ts and stats.ts routes get the same treatment. The buildApp function accepts an optional baseUrl, falling back to the DEFAULT_BASE_URL constant, and passes it down to each route:

That fallback is what keeps the existing test suite green. The route tests assert the literal http://localhost:3000/..., and DEFAULT_BASE_URL is http://localhost:3000. This is the same constant the schema uses as its default. When a test calls buildApp() with no baseUrl, every shortUrl comes out identical to before, so not a single assertion changes. Production passes the validated config.BASE_URL from server.ts, while tests get the default. The fallback is a plain constant, not getConfig(). This ensures the unit tests stay Docker-free because they never load config or read process.env.

Why not route DATABASE_URL through config too? Prisma's datasource reads it from the environment directly, and the integration setup swaps in TEST_DATABASE_URL the same way. The config.ts file still validates that DATABASE_URL is present and well-formed at boot to keep the fail-fast guarantee. However, it deliberately does not change how Prisma reads it. Validating the contract and owning the plumbing are two different jobs.

Documenting the Environment: .env.example

A config module is only as useful as its documentation. The .env.example file is a committed, secret-free template. It tells a new developer exactly which variables exist, what they default to, and what each one means:

The real .env file stays gitignored. The .env.example file carries only safe local defaults and never a real secret. A teammate copies it to .env, adjusts what they need, and the validated config does the rest. Anyone who misspells a value learns at boot from the fail-fast message, not from a 2 a.m. page.

Step 3: Green Across the Board

Run both test suites:

Unit tests are at 14 suites and 78 tests. The new config.test.ts adds its 10 cases, and every prior test still passes because BASE_URL defaults to the old hardcoded value. Integration tests are unchanged at 10 suites and 28 tests. The routes serialize the same URLs they always did. Running npm run typecheck passes with no output. The service now reads its environment in one validated place, refuses to start when that environment is wrong, and builds public URLs from a configurable base instead of a hardcoded host.

What's Next

The service boots safely but stays mostly silent, and a SIGTERM signal kills it mid-request. Next, we will add structured logging and graceful shutdown. This includes JSON logs with request IDs, plus a clean drain-and-close routine when the server stops.