Getting started

Evolve supports development on macOS, Windows (WSL), and Linux environments. This guide walks you through installation, environment setup, and running the platform locally.

Prerequisites

Tool	Purpose
Node.js 24+	JavaScript runtime
pnpm (via corepack)	Package manager
go-task	Task runner
1Password CLI	Environment variable management
Docker	Local development services

Installation

macOS

brew install node@24 go-task 1password-cli
corepack enable
pnpm install

Windows (WSL)

1. Install WSL 2 with the default Ubuntu distro:

   wsl --install

2. Install Homebrew, then install dependencies:

   brew install go-task nvm 1password-cli

3. Install Node.js 24 and enable corepack:

   nvm install 24
   corepack enable

Linux / Ubuntu

1. Install Node.js 24+ using a package manager of your choice.

2. Install 1Password CLI.

3. Install Task:

   snap install task --classic

Environment setup

Evolve uses 1Password to manage environment variables. A fully working .env file is available in the evolve-contributors vault:

task get-env

Running the development server

pnpm dev

Visit the storefront at http://localhost:3000.

Local development services

A Docker Compose file provides supporting services for local development:

Service	URL
Redis	—
Jaeger (OpenTelemetry)	http://localhost:16686
Mailpit (local SMTP)	http://localhost:8025

task docker:services    # start
docker compose down     # stop

Useful commands

Command	Description
pnpm dev	Start the full development environment
pnpm check	Run formatting, typechecking, linting, and Terraform checks
pnpm test	Run all tests
pnpm codegen	Generate GraphQL types and schema files
task get-env	Pull latest .env from 1Password
task docker:services	Start Redis, Jaeger, and Mailpit

API testing with Bruno

Example GraphQL Gateway API calls are included in the api-collection folder, meant to be used with the Bruno API Client:

1. Download and install Bruno.
2. Import the collection from the api-collection folder.
3. Select the correct environment (top right corner) and execute calls.

Next steps

• Learn about Evolve's architecture and how services are organized.
• Explore the technology stack to understand the frameworks and tools used.
• Read the frontend and backend development guides.

Relevant links

Documentation	Demo environments
GitHub	AWS / Commercetools / Storyblok
Storybook	GCP / Commercetools / Storyblok
Figma design system	Azure / Commercetools / Storyblok
Lab Digital engineering docs