How codecademy/gamut works
Project type and purpose
• This is a monorepo for a React component library & design system (“Gamut”) plus its documentation sandbox (Storybook styleguide).
• It also includes CI/CD pipelines (CircleCI / GitHub Actions) that build, test, and publish packages and deploy the styleguide.
Main components
A. Monorepo Root
• yarn workspace & Lerna config (package.json, lerna.json, nx.json)
• Top-level scripts: build, test, nx commands
B. Package Groups (packages/*)
1. Core UI packages
– @codecademy/gamut (React components)
– @codecademy/gamut-styles (styling utilities & SCSS assets)
2. Utility libraries
– @codecademy/variance (TypeScript CSS-in-JS helpers)
– @codecademy/gamut-tests (testing helpers)
– @codecademy/macros (Babel macros)
3. styleguide
– Storybook server & MDX docs (packages/styleguide)
4. scripts & tooling
– jest presets & transformers (script/jest)
– Babel configs at root and per-package
C. CI/CD Pipelines
• GitHub Actions & CircleCI workflows (in .github/ and .circleci/)
• Steps: lint → test → build → publish α / publish release → deploy styleguide
D. External Services
• GitHub (source & PR triggers)
• npm Registry (package publish & consume)
• Static hosting (Netlify or GitHub Pages for storybook)
• Slack / bots (PR comments from alpha deploys)
Relationships and data flows
• Developer → Git push/PR → GitHub triggers → CI jobs
• CI: installs dependencies (Yarn), bootstraps with Lerna, runs Nx task graph
• Each package: build → run tests → output to /dist
• On merge to main: automatic publish to npm (via CircleCI), automatic styleguide build & deploy
• Downstream application: installs @codecademy/gamut-kit (or individual packages) from npm; IDE intellisense via peerDependencies
Architectural patterns and principles
• Monorepo with coarse-grained package separation (single purpose per package)
• Lerna & Yarn workspaces for dependency linking and versioning
• Nx for caching, task orchestration, and incremental rebuilds
• Conventional commits & CI gating for automated changelog & semantic versioning
• Storybook MDX documentation co-located with code