Skip to main content

Roadmap

Work in progress

The Evolve Framework is an ongoing, backwards-compatible refactoring. Not all services have been migrated yet, and APIs may still evolve. Everything described here is functional but should be considered pre-release.

The framework currently covers the five core commercetools services (account, catalog, checkout, order, quotes). This page outlines what comes next.

Gateway extraction​

The GraphQL gateway is currently implemented in full within each project, but roughly 90% of the code is identical across deployments. The plan is to extract it into @evolve-framework/gateway so that a project's gateway reduces to configuration.

What moves to the framework:

  • Federation gateway: Apollo Gateway with Fastify, supergraph loading (Hive CDN or local file)
  • Authentication: federated token plugin, @requiresSession directive, anonymous session creation
  • Data source: custom remote data source with store context header forwarding and IP propagation
  • Resilience: retry fetcher with exponential backoff on 502/503 errors
  • Observability: logging, error handling, Hive usage reporting
  • Trusted documents: persisted query support with LRU cache

What stays in your project:

  • supergraph.yaml defining which subgraphs to compose
  • Environment variables (CORS origins, JWT keys, Hive tokens)
  • Custom directives or plugins specific to your project

The target is a configuration-only gateway:

import { createGateway } from "@evolve-framework/gateway";

const gateway = createGateway({
  name: config.COMPONENT_NAME,
  port: config.HTTP_PORT,
  cors: config.CORS_ORIGIN,
  jwt: {
    issuer: config.JWT_ISSUER,
    audience: config.JWT_AUDIENCE,
  },
  accountServiceEndpoint: config.ACCOUNT_SERVICE_ENDPOINT,
  hive: {
    token: config.HIVE_TOKEN,
    cdnEndpoint: config.HIVE_CDN_ENDPOINT,
  },
  supergraph: config.HIVE_CDN_ENDPOINT
    ? "managed"
    : "./supergraph.generated.graphql",
});

Custom behavior plugs in through the same options:

const gateway = createGateway({
  // ...standard config
  plugins: [myCustomPlugin],
  directives: [myCustomDirective],
});

Additional implementation packages​

The same framework pattern will be applied to other SAAS integrations:

  • CMS: Contentful and Storyblok
  • Payments: Adyen, Stripe, Buckaroo, PayNL, Invoice
  • PIM: Bluestone
  • Commerce: Shopify, Salesforce

Each integration gets its own implementation package (for example, @evolve-framework/contentful or @evolve-framework/shopify), building on the same @evolve-framework/core and @evolve-framework/schemas layers.

Evolve CLI​

A command-line tool for scaffolding and maintaining Evolve projects:

create-evolve-app​

Scaffolds a new project with the right packages, configuration, and directory structure based on your choices:

$ npx create-evolve-app my-store

  ? Commerce backend     -> Commercetools
  ? CMS                  -> Contentful
  ? Payment providers    -> Stripe, Adyen
  ? Include B2B modules? -> Yes
  ? Deployment target    -> AWS

  Creating project in ./my-store...
  Done. Run `cd my-store && pnpm dev` to start.

Because the framework packages contain all standard logic, a new project starts with only the code that makes it unique. No resolvers to copy, no boilerplate to write.

evolve upgrade​

Handles framework version bumps, runs codemods for breaking changes, and validates configuration. This makes framework updates predictable and reduces the effort of staying current.

evolve add​

Adds first-party and community modules to a project:

$ evolve add loyalty

Modules plug into the existing GraphQLCompositeModule composition without conflicts.

Frontend framework​

The same extraction pattern will be applied to frontend components. Shared UI components, hooks, and utilities will move into framework packages so that storefronts carry only project-specific code.

npm publishing​

Framework packages are currently distributed as source code in the vendor/packages/ directory. The plan is to publish them to npm (public or private) so they can be versioned and installed like any other dependency, removing the need for the vendor/ directory in your workspace.