How brenoepics/vitepress-carbon works
Project Type and Purpose
• This is an open-source, multi-package monorepo offering:
• A “theme” library for VitePress (Vue-based static site generator)
• A “cli” tool (vpcar) to scaffold new VitePress-Carbon projects using JSON templates
• A “demo” VitePress site showcasing the theme in action
High-Level File/Package Structure
• Root: configuration (pnpm workspace, linting, build rules), CI/CD (GitHub workflows), changelogs, metadata.
• packages/theme: TypeScript + Vue components + styles → bundled library published to npm.
• packages/cli: Node.js + TS command-line app → reads templates, writes file tree, installs dependencies.
• packages/demo: VitePress site → markdown, config, public assets → uses the theme package.
• packages/templates: JSON template definitions consumed by the CLI.
Main Components
A. Monorepo Workspace
• Orchestrates: package.json workspaces, pnpm link, versioning, CI pipelines (GitHub Actions), lint/build tools.
B. Theme Package
• Source: src/theme/* (Vue components, composables, styles)
• Build: TS → ES modules, CSS assets
• Output: npm registry
C. CLI Package (vpcar)
• Entrypoint: bin/vpcar.mjs
• Commands: init, index, shared utilities (fs, templates, engines)
• Template Source: packages/templates/*.json
• Output: new project skeleton + installs theme dependency
D. Demo Site
• VitePress config & markdown
• Uses theme (imported via package alias)
• Dev server (Vite) → browser preview
E. External Services
• npm registry (publish/resolve)
• GitHub (source repo, Actions, Pages hosting demo)
• Developer Machine (CLI invocation, local builds)
Relationships & Data Flows
1. Developer → runs pnpm install at root → workspace links all packages
2. Developer → invokes vpcar init → CLI reads JSON templates → writes files → runs npm install in target directory (pulls in theme from registry or local workspace)
3. Developer → opens demo → VitePress (uses theme package) → renders documentation site
4. CI/CD → GitHub Actions → installs monorepo, runs tests/lints, builds packages, publishes theme & cli to npm
Architectural Patterns & Principles
• Monorepo with pnpm workspaces for atomic versioning, local linking, and unified CI.
• Modular separation: CLI (application), Theme (UI library), Demo (consumer app).
• Template-driven scaffolding: declarative JSON templates abstract file generation.
• Component-based UI: Vue single-file components & composables in theme.
Technologies & Frameworks
• Node.js + TypeScript for CLI & theme
• Vue 3 + VitePress for demo and theme components
• pnpm workspaces for package management
• GitHub Actions for CI, CodeQL, dependency review
• ESLint, Prettier, changelog tools (.changeset)