How vtex/shoreline works
Project Type and Purpose
• This is a monorepo hosting Shoreline, a React-based design system and toolkit for building VTEX Admin apps.
• It comprises multiple npm packages (component library, CSS tokens, utility functions, test utilities, table package, documentation site), orchestrated by pnpm, Lerna, and Turborepo.
File Structure Analysis
• Top-level files and folders:
• pnpm-workspace.yaml, lerna.json, turbo.json → workspace orchestration and fast build.
• .github/workflows → CI pipelines for PR checks, tests, publishing.
• .husky, commitlint.config.js → Git hooks & commit standards.
• storybook/, vite.config.ts → Storybook config for live component previews.
• scripts/, plopfile.js → scaffolding and maintenance scripts.
• packages/ → each subfolder is an independent published module:
• css → design tokens, generation of CSS bundles (tsup, build scripts).
• shoreline → the core React component library with stories, tests, theming.
• docs → Next.js + MDX site for API reference, guides, and live examples.
• test-utils → shared testing utilities (Vitest, React helpers).
• ts-table → specialized table component package.
• utils → shared TypeScript utilities.
• Dependencies flow:
utils + css → shoreline + ts-table → docs + storybook. test-utils serves shoreline and ts-table tests.
a. Main Components
• Developer Workstation (CLI tools: pnpm, plop)
• Monorepo Orchestrator (pnpm/Lerna/Turbo)
• Package Modules: css, utils, test-utils, ts-table, shoreline
• Documentation Site (Next.js/MDX)
• Storybook Server (Vite/React)
• CI/CD (GitHub Actions)
• npm Registry (publishing target)
• External Consumers (VTEX Admin Apps)
b. Relationships & Data Flow
• Developer invokes build/dev commands via pnpm CLI → Orchestrator schedules builds across packages.
• css builds design tokens → shoreline & ts-table import CSS bundles.
• utils provides shared functions → all code packages import it.
• test-utils supplies test helpers → shoreline & ts-table tests import.
• shoreline & ts-table exports → Storybook for live component rendering & Next.js docs site for examples/docs.
• CI triggers on push/PR → runs tests, lint, build, then publishes to npm and deploys docs.
• External VTEX Admin apps fetch published packages from npm.
c. Architectural Patterns & Principles
• Monorepo with package isolation and sharing.
• Workspace dependency graph for incremental builds (Turborepo).
• Micro-library decomposition: each concern (styling, components, utilities, docs) is a separate package.
• CI/CD as code via GitHub Actions.
• Component-driven development with Storybook.
d. Key Technologies
• pnpm, Lerna, Turborepo for workspace management and incremental builds.
• TypeScript, React, MDX/Next.js for code and docs.
• Vite & Storybook for live component preview.
• tsup for bundling.
• Vitest for testing.
• GitHub Actions for CI/CD.
Essential Details to Capture
• Monorepo orchestrator at root controlling per-package lifecycle.
• Package boundary and reuse: css → shoreline, utils → all, test-utils → tests, ts-table → standalone table.
• Two developer-facing servers: Storybook for components and Next.js for docs.
• CI/CD flow from GitHub Actions to npm Registry and docs deployment.
• External consumption by VTEX Admin applications.