Your code and ours

An Evolve project mixes two kinds of code. The commerce logic, the adapters, and the storefront features come from Evolve packages, and you update them through npm. Everything else is in your repository and is yours: your pages, your own modules, your configuration. How much an update costs you depends on how much of the first kind you have turned into the second.

flowchart TB
  npm[(Evolve registry)] -- pnpm install --> pkgs
  notes[Release note] -- a diff you apply --> markup
  subgraph repo[Your project]
    subgraph own[Yours to keep up to date]
      services[Services and your own modules]
      markup[Page markup]
      ejected[Ejected blocks]
    end
    pkgs["@evolve-framework/* and @evolve-storefront/*<br/>updated by raising versions"]
    own --> pkgs
  end

What Evolve owns and what you own

Code	Owned by	How changes reach you
@evolve-framework/* packages: modules, adapters, the contract	Evolve	You raise the version, and npm installs it
@evolve-storefront/* packages: feature logic, UI primitives	Evolve	You raise the version, and npm installs it
Optional contrib packages, such as the Medusa plugins	Evolve	You raise the version, and npm installs it
The GraphQL gateway image	Evolve	You change the image tag in your deploy config
The gateway’s router config	You	Compare it with the new image’s default when you change the tag
Page markup in your storefront	You	A diff you apply yourself
Code you ejected or took over	You	Only when you re-run the eject or copy the change
Your services, own modules, and configuration	You	Never; Evolve does not touch them

Packages carry the logic, so most fixes and features arrive with a version bump. This includes the hooks behind every storefront feature: they stay an npm dependency even when you take over a feature’s markup.

Page markup is the code that puts features on a page, in your frontend/site. A new Evolve release can change how the reference sites arrange a page, but that never reaches your pages by itself. When you want the change, apply it as a diff.

Ejected code is a copy that is now yours. A CMS block is ejected with the CMS package’s eject command, which copies the block’s code and Terraform into your project:

evolve --package @evolve-framework/contentful eject hero

To pick up a newer version of an ejected block, run the command again. It overwrites your copy, and you put your own changes back with git diff. A storefront component you took over is a plain copy, with no command to refresh it. See Customize a component for the levels of change, and what each one costs you on an update.

How Evolve versions its packages

Every package has its own version, and each version follows semver. Packages release independently: a fix in @evolve-framework/storyblok does not bump @evolve-framework/commercetools.

Most packages are still below 1.0.0, so Evolve uses the minor version for breaking changes:

Version step	What it can contain
Patch, such as 0.19.0 to 0.19.1	Fixes. Safe to take.
Minor, such as 0.19.1 to 0.20.0	New features, and possibly a breaking change

A breaking change ships as a minor version. Its release note starts with Breaking change: and says what you have to change in your project. Read the notes of every minor version you skip over.

@evolve-framework/core and @evolve-framework/mcp-core are past 1.0.0, and their breaking changes also ship as a minor version. A new major version of either is a deliberate decision of its own, never a side effect of a change.

Pin versions in your catalog

The reference sites pin every dependency in one place: the catalog: in pnpm-workspace.yaml. Each package.json refers to it with catalog:, so a package has exactly one version across your project.

catalog:
  "@evolve-framework/commercetools": 0.19.0
  "@evolve-framework/core": 1.7.0
  "@evolve-storefront/feature-cart": 0.12.0
  # ...
catalogMode: strict

"dependencies": {
  "@evolve-storefront/feature-cart": "catalog:"
}

catalogMode: strict makes pnpm refuse a version that is not in the catalog, so a package cannot drift to another version in one workspace. To update, change the version in the catalog and run pnpm install.

The reference sites also set minimumReleaseAge, which holds back any version published less than seven days ago. They exclude @evolve-framework/* and @evolve-storefront/* from it, so you can take an Evolve release on the day it comes out.

Where releases come from

The framework and storefront packages are released with changesets. Every change to a package comes with a short note, and the release collects those notes:

1. The release workflow keeps a pull request called “Release new version” open, with the new version and changelog of each package that changed.
2. When that pull request is merged, the packages are published to the Evolve registry, and each one gets a git tag such as @evolve-framework/commercetools@0.20.0.
3. For framework packages, the tags and a GitHub release per package, with that version’s notes, appear in the evolve-releases/evolve-framework repository on GitHub.

Every package also carries its notes in its own CHANGELOG.md.

Monthly highlights are not a version

The changelog has one page per month, labeled like 2026.8.0. That label names a summary of what changed across the packages that month. No package has that version, and you cannot install it. Your catalog always names package versions.

When a release asks you to change something in your project, it is listed in Upgrading.