Build an Arc application
You have a command, a read model, and the services they need. Before you expose them over HTTP, you need to collect them and check the wiring. The application builder does that once, creating the ArcServer you can run on its own or mount in a web framework. Choosing a host does not change your application artifacts.
Use an existing Arc project for these excerpts. If you are starting from an empty directory, follow Create an application for project setup first; the snippets here are not a standalone project.
Create, fill, and build
Section titled “Create, fill, and build”The Tasks entry point shows how an existing Arc project supplies discovery, service registration, and generated metadata. To see what the builder itself needs, start with an artifact that has no injected parameters:
import { field } from '@cratis/fundamentals';import { query, readModel } from '@cratis/arc.core';
@readModel()export class Status { @field(String) value = 'ready';
@query() static current(): Status { return new Status(); }}Status declares a read model and a query that returns it. Since current() takes no arguments, it needs no parameter bindings. This example uses explicit registration: add the class to the builder, then build and run the application. Folder discovery, described below, is an alternative way to collect the same artifacts, not an additional wiring step:
import { ArcApplication } from '@cratis/arc.core';import { Status } from './Status.js';
const builder = ArcApplication.createBuilder();builder.add(Status);export const app = await builder.build();await app.run({ port: Number(process.env.PORT ?? 3000) });build() returns an ArcApplication; app.server is the ArcServer inside it. app.run() starts the standalone Node listener, serving the query from the class you added. createBuilder accepts the configuration options (ArcOptions).
The Tasks command and queries do take parameters. In that bootstrap, useGeneratedMetadata(metadata) installs the bindings that arc-proxygenerator --metadata extracted from the source, so handle(tasks: Tasks) and a bare @query() need no token lists. Call it before discover() or add(). Without it, the sample’s artifacts would need explicit @inject(...) and @query(...) tokens, and build() rejects them as written. See Generate artifact metadata.
The Tasks sample’s Samples/Tasks/appsettings.json enables fixture providers with Cratis:Arc:Development; it does not select the runtime environment. The Yarn start script separately sets DOTNET_ENVIRONMENT=Development. Run the workspace command from the sample’s package directory (Yarn does this) so it reads that configuration file.
Before a listener opens, build() checks the declared graph: missing service registrations, dependency cycles, singletons that capture shorter-lived services, and decorators placed where they have no effect. It never runs a service factory to do this. A wiring error stops the build rather than waiting for the first request.
If you know Arc on .NET, this setup corresponds to standalone ArcApplication.CreateBuilder(args), builder.AddCratisArc(), builder.Build(), app.UseCratisArc(), app.RunAsync(). On Node, app.run() performs the standalone host step. For an Arc + Chronicle comparison, see Add event sourcing.
Discover artifacts from a folder
Section titled “Discover artifacts from a folder”Choose discovery when your artifacts live in a dedicated folder and you want to collect them without listing every class. discover(folderUrl, { rootNamespace? }) imports every exported decorated class below that folder, in deterministic path order.
- It accepts emitted
.jsfiles or loader-backed.tsfiles, not a mix of both. - It skips
dist,node_modules,given,for_*,index.*, declaration files, symbolic links, co-located*.proxy.ts/*.proxy.jsfiles, and React.tsxfiles. - It refuses a folder that contains the entry point, or an imported bootstrap that is itself calling discovery. Keep artifacts in a dedicated folder.
- It derives each artifact’s namespace from its path below the folder, and reports a class discovered under two different namespaces.
A folder rename changes the derived routes. Endpoint mapping shows how to pin a route.
Add artifacts explicitly
Section titled “Add artifacts explicitly”Choose explicit registration instead of discovery when you want to list the artifacts yourself. Bundled production builds often cannot import a folder at runtime, so pass the classes instead:
builder.add(RegisterTask, RegisterTaskValidator, TaskItem);add() rejects a class without an Arc decorator. Give explicitly added artifacts stable namespaces with @command({ namespace: 'Tasks.Registration' }) and @readModel({ namespace: 'Tasks.Listing' }). If you rely on class names in routes, configure the bundler to keep them (keepNames in esbuild), or set explicit namespaces and paths.
Besides commands, read models, and validators, add() and discover() recognize classes marked @queryRenderer(), @readModelInterceptor(), @commandResponseValueHandler(), @identityDetailsProvider(), and the lifetime decorators @singleton(), @scoped(), and @transient().
Register extension points
Section titled “Register extension points”Keep application service registration and pipeline extensions on the same builder, before build(). Use these methods when you need to change how a command or query runs:
| Builder method | Registers |
|---|---|
services.addSingleton / addScoped / addTransient |
An application service; see Dependency injection |
addAuthorizationPolicy(name, policy) |
A named policy; see Authorization policies |
addCommandResponseValueHandler(token) |
A handler for server-side return values; see Response value handlers |
addCommandKeyResolver(token) |
A rule that computes a command key; see Command context |
addCommandContextValuesProvider(token) |
Values attached to every command context |
addReadModelForCommandResolver(token) |
A source for commandReadModel(...) parameters |
addQueryRenderer(token) |
A renderer for provider-owned query results; see Query renderers |
addReadModelInterceptor(token) |
A read-model transform; see Read-model interception |
For a storage integration, import its package before calling builder.withMongoDB(...), builder.withDrizzle(...), or builder.withChronicle(...): the import adds the method to the builder. Each package also exports a function form, withX(builder, options). Configuration from appsettings.json is available to Chronicle and MongoDB, but you still provide model classes, clients, and authentication explicitly.
Run it, or mount it
Section titled “Run it, or mount it”With the application built, choose who owns the listener and its shutdown:
await app.run(...)orawait app.start(...)use the standalone Node host.expressApp.use(cratisArc(app)),await fastifyApp.register(cratisArc, { arc: app }), andhonoApp.use(cratisArc(app))hand the application to a web framework. ImportcratisArcfrom the matching adapter package. The host keeps listener ownership; callawait app.dispose()at shutdown. See Host adapters.app.fetch(request)returns an Arc response or 404 for foreign paths;app.handle(request)returnsnullfor fall-through. These Fetch methods alone do not establish edge-runtime compatibility: the core still imports Node runtime modules.
A caller-owned ServiceRegistry passed in the options cannot be combined with builder service registrations.