core

@evolve-framework/core · v1.11.0

The runtime every Evolve service is built on: the application and its module system, the GraphQL and HTTP server, caching, an HTTP client, logging, tracing and metrics, and the ports for messaging and file storage.

When to use

Every Evolve service depends on it. You write or install modules, compose them into a CompositeModule and run them with createApplication; the commerce engines, CMS packages and payment adapters are all modules on top of this package. The cloud-specific implementations of messaging and storage live in the cloud-adapter-* packages, so this package stays the same on every cloud.

Get started

1. Install the package with the peer dependencies it needs. It comes from the Evolve registry, which needs a one-time sign-in.

   pnpm add @evolve-framework/core @opentelemetry/api fastify graphql graphql-yoga zod

   Requirements6

   @opentelemetry/api	^1.9.0
   @types/node	>=22optional
   fastify	>= 5.12.1 < 6.0.0
   graphql	>= 16.0.0 < 17.0.0
   graphql-yoga	>= 5.21.3 < 6.0.0
   zod	>= 4.4.0 < 5.0.0

For example:

import {
  CompositeModule,
  createApplication,
  HealthModule,
} from "@evolve-framework/core";

const app = await createApplication({
  name: "my-service",
  module: new CompositeModule([
    // your modules, e.g. new CartModule({ ... }) from a commerce engine
    new HealthModule({ name: "myService" }),
  ]),
  http: { address: { host: "0.0.0.0", port: 4000 } },
});

await app.start();

Application

Application	What it is	Required options
Application	Application composes a Module with its HTTP/GraphQL surface and runs it.	name, module, http

Modules

Module	Serves	Required options
AbstractModule	The base class of every module.	–
CompositeModule	Several modules served as one.	–
HealthModule	Reports this service's health as one field of a Health entity shared with every other service in the composition.	name

Adapters

Adapter	What it is	Required options
NoopPublisher	A no-op publisher that logs and discards every message.	–
RedisPublisher	Publishes internal events onto a Redis list, for local development, where startDevelopmentListener reads them back.	–
LocalStorageClient	Stores files on the local disk, as <path>/<bucket>/<key>, for development and tests.	–

Testing

Test helpers in /testing, /test-support, /test-support/contract. What they are for

Entry points

@evolve-framework/core	The application, the module system (Module, AbstractModule, CompositeModule), and health checks.11 exports
@evolve-framework/core/graphql/plugins	GraphQL server plugins for the client context and error logging.2 exports
@evolve-framework/core/messaging	The messaging port: the publisher and handler types, plus a Redis queue and a local development listener.8 exports
@evolve-framework/core/storage	The file storage port, the signed-URL port a browser uploads and downloads through, and a local-disk implementation for development.8 exports
@evolve-framework/core/service/graphql	The GraphQL request context, the store context and the session and authentication guards resolvers use.17 exports
@evolve-framework/core/service/http	The HTTP server underneath an application.3 exports
@evolve-framework/core/cache	The Redis-backed cache with its in-memory tier.9 exports
@evolve-framework/core/utils	Building blocks for per-request dataloaders, and file utilities for build scripts.7 exports
@evolve-framework/core/http/client	A fetch-based HTTP client with retries and error helpers.4 exports
@evolve-framework/core/observability	The logger, tracer and meter.10 exports
@evolve-framework/core/observability/configure	Start-up configuration for tracing, metrics, Sentry and event-loop monitoring.5 exports
@evolve-framework/core/observability/logging	Logging only: the logger, its destination and error reporting.10 exports
@evolve-framework/core/address	The city-lookup port an address-lookup provider implements, and officialCity, which an engine applies on an address write.3 exports
@evolve-framework/core/order-link	Signing a link that lets a buyer read one order until it expires, and reading one back.3 exports
@evolve-framework/core/site-revalidation	The sites' cache tags, and a signed purge that a CMS publish sends to each site's revalidate route.7 exports
@evolve-framework/core/testing	Helpers for running a module's GraphQL schema in tests.2 exports
@evolve-framework/core/test-support	A service for end-to-end suites that simulates back-office changes and removes test data, guarded to test environments.20 exports
@evolve-framework/core/test-support/contract	The request and response schemas of that service, for a test client that needs only the types.7 exports