Skip to main content

Local development

Prerequisites​

  • Node.js 24+ (the repo's .tool-versions pins it)
  • Python 3.12+ (for packages/color-edit)
  • Firebase CLI 15.7.0 (ASDF_FIREBASE_VERSION=15.7.0 firebase --version)
  • gcloud authenticated against cpl-gen-ai-marketing (for ADC-based Vertex / Firestore / GCS access)

Install​

npm install

Backend​

# Genkit dev UI with hot reload (recommended)
npx nx dev server

# Plain Express server on :8080
npm start

In dev mode (NODE_ENV=development and USE_CLOUD_TASKS unset), pipeline-core/cloud-tasks.ts short-circuits the Cloud Tasks API and does direct fetch POSTs to localhost stage handlers. No Cloud Tasks queue or OIDC handshake required.

Frontend​

npx nx dev frontend

Vite dev server on :5173 with a proxy to backend :8080 (see packages/frontend/vite.config.ts for the route map).

MCP server​

npx nx serve mcp-server # Express on :8080

For local OAuth flow without Google credentials, set MCP_ALLOW_INSECURE_OIDC=1. This is only respected when NODE_ENV !== 'production'; production rejects insecure-mode hard.

Documentation site​

npx nx dev docs

Docusaurus dev server on :3000, hot reload on .md saves.

Build it locally:

npx nx build docs
npx nx serve docs # serves the built dist/ on :3000

Tests​

# Everything (lint + test + type-check across all packages)
npx nx run-many -t build lint test type-check --parallel=1

# Single package
npx nx test pipeline-core
npx nx test mcp-server
npx nx test color-edit

Tests for pipeline-core, mcp-server, server use the Firestore emulator (each on its own port to avoid collisions: 8085 / 8086 / 8087). nx.json sets parallel=false on the test target for this reason.

Useful environment overrides​

VariableDefaultWhen
FIRESTORE_DB_ID(default)Talk to a non-default Firestore database
GCS_BUCKET_NAMEcpl-gen-ai-marketing-imagesUse a personal sandbox bucket
USE_CLOUD_TASKSunsetForce real Cloud Tasks even in dev
MCP_ALLOW_INSECURE_OIDC0Skip Google ID token signature verification