Skip to content

Monorepo Management

Overview

The ARG Global Design System (arg-gds-monorepo) uses pnpm workspaces for package management and Changesets for versioning.

Why Monorepo?

  • Unified versioning: Single source of truth for all design system components
  • Shared dependencies: Reduce duplication across packages
  • Atomic commits: Changes across packages stay in sync
  • Simplified CI/CD: Single pipeline for all packages
  • Easy cross-package development: Test changes immediately

Repository Structure

arg-gds-monorepo/
├── apps/                    # Consumer applications
│   ├── arc/                # ARC application
│   ├── design-system-app/  # Design system showcase
│   ├── emkan/              # Emkan application
│   ├── neoleap/            # Neoleap application
│   └── react/              # React demo app
├── packages/               # Shared packages
│   ├── design-tokens/      # Design tokens (@arg/gds-design-tokens)
│   ├── react-native/       # React Native components (@arg/gds-react-native)
│   └── web/
│       ├── core/           # Stencil web components (@arg/gds-web)
│       └── react/          # React wrappers (@arg/gds-react)
├── .changeset/             # Changeset configuration
├── .github/workflows/      # CI/CD pipelines
├── pnpm-workspace.yaml     # Workspace configuration
└── package.json            # Root package configuration

Workspace Management

Package Manager: pnpm 10.11.0

# Install all dependencies
pnpm install

# Install dependency in specific package
pnpm --filter @arg/gds-web add lodash

# Install dev dependency in root
pnpm add -D -w prettier

# Remove dependency
pnpm --filter @arg/gds-react remove unused-package

Workspace Configuration

pnpm-workspace.yaml: 

packages:
  - 'packages/*'
  - 'packages/web/*'
  - 'apps/*'

Packages reference each other using workspace:* protocol:

{
  "dependencies": {
    "@arg/gds-web": "workspace:*",
    "@arg/gds-design-tokens": "workspace:*"
  }
}

Dependency Flow

graph TD
    A[Design Tokens] --> B[Core Web Components]
    B --> C[React Wrappers]
    B --> D[React Native Components]
    C --> E[Apps: React/ARC/Emkan/Neoleap]
    D --> F[Apps: Design System App]

    style A fill:#e1f5ff
    style B fill:#fff3cd
    style C fill:#d4edda
    style D fill:#d4edda
    style E fill:#f8d7da
    style F fill:#f8d7da

Build Order (Critical)

  1. @arg/gds-design-tokens (no dependencies)
  2. @arg/gds-web (depends on tokens)
  3. @arg/gds-react (depends on web)
  4. @arg/gds-react-native (depends on tokens)

Adding New Packages/Apps

# Create new package
mkdir -p packages/new-package && cd packages/new-package && pnpm init

# Create new app
mkdir -p apps/new-app && cd apps/new-app && pnpm init

# Add workspace dependencies
pnpm add @arg/gds-design-tokens@workspace:*

Package.json essentials: - Packages: Include name, version, main, types - Apps: Set "private": true

Common Workflows

Daily Development

# 1. Pull and install
git pull origin develop && pnpm install

# 2. Build dependencies
pnpm build:tokens && pnpm build:core

# 3. Start development
pnpm start:react

Adding a Feature

# 1. Create branch
git checkout -b feature/new-component

# 2. Make changes and build
pnpm --filter @arg/gds-web build
pnpm --filter @arg/gds-web test

# 3. Test in consuming app
cd apps/react && pnpm dev

# 4. Create changeset
pnpm changeset
# Select packages, choose version bump (major/minor/patch), write summary

# 5. Commit and push
git add . && git commit -m "feat: add new component"
git push origin feature/new-component

Creating a Changeset

pnpm changeset

# Follow prompts:
# 1. Select changed packages (space to select)
# 2. Choose version bump:
#    - major: Breaking changes
#    - minor: New features
#    - patch: Bug fixes
# 3. Write summary

# Commit changeset
git add .changeset/ && git commit -m "chore: add changeset"

Releasing Versions

Automated via CI/CD: Create PR to main with changesets → CI checks → Version bump PR created → Review → Merge triggers release → Git tags created automatically

Working Across Packages

# Build in core, immediately available in apps (workspace:*)
cd packages/web/core && pnpm build
cd ../../../apps/react && pnpm dev

Build and Test Commands

# Build all packages
pnpm build

# Build specific packages in order
pnpm build:tokens           # Design tokens
pnpm build:core             # Core web components
pnpm build:react            # React wrappers
pnpm build:react-native     # React Native

# Start development servers
pnpm start:core             # Stencil dev server
pnpm start:react            # React demo app

# Testing
pnpm test                   # Run all tests
pnpm test:coverage          # Run with coverage
pnpm check-tests            # Check coverage requirements
pnpm --filter @arg/gds-web test  # Test specific package

# Quality checks
pnpm lint                   # Lint all packages
pnpm format                 # Format code
pnpm format:check           # Check formatting

CI/CD Essentials

Pipeline (.github/workflows/main.yml): Runs on PRs to main/develop - Jobs: format-lint, test, version-bump

Checks: pnpm lint, pnpm format:check, pnpm check-tests, pnpm -r test

Pre-commit: Husky + lint-staged runs Prettier automatically

Best Practices: Always commit changesets, run tests locally, check CI before review, don't skip hooks

Troubleshooting

Installation Issues

# Clear and reinstall
rm -rf node_modules
find . -name "node_modules" -type d -prune -exec rm -rf {} +
pnpm install

# Clear pnpm cache
pnpm store prune && pnpm install

Build Failures

# Build in dependency order
pnpm build:tokens && pnpm build:core && pnpm build:react

# Check circular dependencies
pnpm why <package-name>

# Verify workspace links
pnpm list --depth 0

Version Conflicts

# Check mismatches
pnpm outdated

# Update all
pnpm update -r

# Ensure workspace protocol in package.json:
# "@arg/gds-web": "workspace:*"

Test Coverage Failures

# Check what's missing
pnpm check-tests

# Stencil components need both:
# - component-name.spec.ts (unit tests)
# - component-name.e2e.ts (e2e tests)

Workspace Not Found

# Verify pnpm-workspace.yaml includes path
packages:
  - 'packages/*'
  - 'packages/web/*'  # For nested packages
  - 'apps/*'

# Reinstall
pnpm install

Best Practices

Package Organization

  • packages/: Reusable, publishable packages
  • apps/: Consumer applications (private)
  • One responsibility per package
  • Shared configs in root

Dependency Management

  • Use workspace:* for internal dependencies
  • Pin external versions in root
  • Avoid duplicate dependencies
  • Keep devDependencies in root when possible

Versioning

  • Follow semantic versioning
  • Always create changesets
  • Write clear changelog entries
  • Group related changes

Testing

  • All packages need test script
  • All components need unit + e2e tests
  • Run pnpm check-tests before pushing
  • Maintain >80% code coverage

Git Workflow

  • Branch from develop for features
  • PR to develop for development
  • PR to main for releases
  • Use conventional commits
  • Include changeset in PR

Performance

  • Build only what changed during development
  • Use --filter to target specific packages
  • Cache dependencies in CI
  • Keep package boundaries clear

Quick Reference

# Installation
pnpm install                          # Install all dependencies
pnpm --filter <pkg> add <dep>        # Add dependency to package
pnpm add -D -w <dep>                 # Add dev dependency to root

# Building
pnpm build                            # Build all packages
pnpm build:tokens                     # Build design tokens only
pnpm --filter <pkg> build            # Build specific package

# Testing
pnpm test                             # Run all tests
pnpm check-tests                      # Verify test coverage
pnpm --filter <pkg> test             # Test specific package

# Quality
pnpm lint                             # Lint all packages
pnpm format                           # Format all files
pnpm format:check                     # Check formatting

# Versioning
pnpm changeset                        # Create changeset
pnpm version-packages                 # Apply version bumps
pnpm release                          # Publish packages

# Development
pnpm start:core                       # Start Stencil dev server
pnpm start:react                      # Start React demo app
pnpm list-packages                    # List all packages

# Workspace Management
pnpm list --depth 0                   # List installed packages
pnpm why <package>                    # Check why package is installed
pnpm outdated                         # Check for outdated packages
pnpm update -r                        # Update all packages recursively

References