Evolve Framework
The Evolve Framework contains the shared backend logic of the platform:
GraphQL modules, resolvers, dataloaders, mappers, and the server runtime
they plug into. It lives in its own repository (evolve-framework) and is
published as @evolve-framework/* packages to the Evolve registry
(npm.registry.evolve-platform.com). Implementations depend on it like any
other library.
Every Evolve backend service used to ship with a complete copy of its GraphQL resolvers, schema definitions, dataloaders, mappers, and test infrastructure. A typical project contained hundreds of files and thousands of lines of code that was essentially identical across deployments. This created several problems:
- Upgrade friction: pulling in platform improvements meant manually diffing and merging hundreds of files
- Multiplied maintenance: a bug fix needed to be applied once per project instead of once
- Unclear boundaries: it was hard to tell which code was platform baseline and which was project-specific
Packages
Section titled “Packages”The framework repository contains 19 packages under packages/, all
published under the @evolve-framework scope.
Foundation and tooling
Section titled “Foundation and tooling”| Package | Description |
|---|---|
core |
The module system (Module, AbstractModule, CompositeModule), the DomainService runtime, cache, messaging, storage, HTTP client, and observability |
schemas |
GraphQL type definitions for every commerce domain, consumed by the implementation packages |
json-schema-to-zod |
Converts JSON Schema definitions into Zod validators |
packager |
Packages services into deployable artifacts (Docker, AWS Lambda, Azure Functions) |
Commercetools
Section titled “Commercetools”| Package | Description |
|---|---|
commercetools |
GraphQL modules, resolvers, dataloaders, mappers, factories, and test tooling for commercetools |
commercetools-adyen, commercetools-buckaroo, commercetools-invoice, commercetools-mollie, commercetools-paynl, commercetools-stripe |
Payment provider modules for the commercetools checkout, one package per provider |
| Package | Description |
|---|---|
contentful |
ContentfulModule with resolvers, a customizable mapper registry, and webhook handling |
storyblok |
StoryblokModule, interchangeable with the Contentful package at the subgraph level |
Other integrations
Section titled “Other integrations”| Package | Description |
|---|---|
sfcc |
Salesforce Commerce Cloud implementation modules (early stage) |
cloud-adapter-aws, cloud-adapter-azure, cloud-adapter-gcp |
Cloud-specific bindings for messaging and storage |
mcp-core |
Building blocks for MCP servers that expose GraphQL operations as AI tools |
user-notifications |
Queued user notification client and message contracts |
How implementations consume it
Section titled “How implementations consume it”Implementations point the @evolve-framework scope at the Evolve registry
in .npmrc and pin versions once, in the catalog: section of
pnpm-workspace.yaml. Individual package.json files use catalog: as
the version, so a framework upgrade is a one-line change.
New versions are published to the registry regularly; alongside stable
releases, snapshot versions (0.0.0-<sha>-<timestamp>, npm tag
snapshot) are published continuously, so unreleased work can be tested
in an implementation before it is formally released. You consume both the
same way: pin the version in your catalog:.
Framework versus implementation
Section titled “Framework versus implementation”The framework owns everything that is the same across projects: modules, resolvers, schemas, dataloaders, mappers, and the server runtime. Your implementation owns everything that is specific to your project: configuration loading, module composition, context wiring, custom REST routes, event handlers, and any resolvers or mappers you override or add. See Customization and extensibility for the extension points.
Frequently asked questions
Section titled “Frequently asked questions”Does the GraphQL API change when I upgrade? Not silently. The schema each service exposes is defined by the modules it composes; schema changes arrive through explicit version bumps and are documented in the package changelogs.
Can I stay on an older framework version?
Yes. Framework packages are versioned and pinned in your catalog:. You
upgrade on your own schedule.
When should I use a snapshot version? Only to validate unreleased framework changes against your implementation. Production deployments should pin released versions.