Server settings: the one object that configures your worker

Every other post in this series points back here. The thesis calls it the Rosetta Stone: a Base worker is configured by one object, and the shape of that object is the shape of your worker. Turn on a capability by adding its key. Leave it off by leaving the key out. This post is the deep look at that object, the BaseSettings, because once you understand it, you understand how every feature in Base is reached.

Three things required, everything else optional

A worker needs almost nothing to exist. Three fields are required: a name, a title, and a version. That is the whole mandatory surface. Everything else, the router, the database, GraphQL, RPC, middleware, queues, scheduled work, durable objects, object storage, key-value storage, the event bus, every one of them is an optional key.

This is not a small detail. It is the architectural claim of the framework made concrete in a type. Base does not prescribe what your worker is. A worker with only a router is a REST service. A worker with only a GraphQL key is a GraphQL service. A worker with a router, a database, and a queue is a small application. You are not turning features off that came on by default; you are turning features on by naming them. The settings object is the proof that the framework hands you pieces already fitted, and lets you decide which ones to pick up.

A guided tour of the keys

The keys group naturally by what they do.

The identity keys are the required three: name, title, version. They say what this worker is.

The surface keys declare how the worker is reached: a router for HTTP routes, a graphql key for a GraphQL endpoint, an rpc key for RPC services, a webSocket key for socket connections. Add the ones that match how clients will call you.

The data keys declare what the worker stores and talks to: an orm key for the relational database, an objectStore key for R2 buckets, a keyValueStorage key for KV. Each is a connection declared once and reached by injection everywhere.

The work keys declare background and scheduled behavior: a queue key for producing and consuming queue messages, a scheduled key for cron-driven executables, an eventBus key for in-worker events and listeners.

The platform keys declare Cloudflare primitives the worker owns: durableObjects and containers, each a list of the stateful instances this worker manages.

The composition keys tie it together: modules pulls in self-contained units that bring their own slice of settings, providers registers classes into dependency injection, middleware registers the global and handler-level middleware pipelines, and delegate hooks into the worker lifecycle.

You do not need to memorize the list. You need the instinct: every capability in Base has a key, and adding the key is how you opt in.

Named configurations: more than one of a thing

Some keys are not a single setting but a named map, because a worker can have more than one of a thing. The clearest case is the database. Your orm key can declare a default connection and additional named ones, a primary database under one name and a second under another, each with its own adapter and entities. The same named-configuration shape applies to servers, so a worker can describe how it runs in more than one place.

The pattern is consistent: where you might need several of something, the key takes named entries, with a default entry as the common case. You reach a specific one by its name, and the default when you do not need to choose.

Settings change with where the worker runs

A worker does not run in only one environment, and its settings account for that. The settings carry a notion of which deploy environments they apply to, so the same worker can be described once and adapt to where it is deployed. Configuration that differs between development and production, a port here, a host there, a binding name, is expressed through the configuration system rather than scattered through your code. The settings object is the single place that knows how this worker is shaped, including how that shape shifts between environments.

The mental model to keep

The settings object is your worker, declared. Three fields are required, name, title, version, and every capability beyond that is an optional key you add to opt in. Surface keys say how you are reached, data keys say what you store, work keys say what happens in the background, platform keys say which stateful primitives you own, composition keys tie modules and middleware and providers together. Where you need several of something, the key takes named entries with a default. Read a worker's settings object and you have read the worker.