Web Components Repository

A growing collection of reusable, framework-agnostic web components built with modern technologies. This monorepo leverages Turborepo and PNPM Workspaces to efficiently manage multiple web component packages.

🎨 Web Components

This repository contains a collection of web components that can be used in any JavaScript framework or vanilla JavaScript. Currently available:

• @banegasn/m3-button - Material Design 3 Button component with 5 variants, accessibility support, and loading states
• @banegasn/m3-navigation-rail - Material Design 3 Navigation Rail component with collapsible functionality

🚀 More components coming soon! This repository will grow to include various web components for different use cases, not limited to Material Design 3.

📚 Documentation

• Publishing Guide - How to publish web component packages
• Web Components - List of available components
• Component Packages - Individual package documentation

🌐 Live Demo

The Angular demo app is automatically deployed to GitHub Pages: https://banegasn.github.io/components/

Every push to the main branch triggers an automatic deployment.

🏗️ Architecture

This monorepo is designed for building and distributing web components: - Framework-agnostic components: Built with Lit, Svelte, and other modern web component technologies - Universal compatibility: Components work in any JavaScript framework (Angular, React, Vue, etc.) or vanilla JavaScript - Efficient builds: Turborepo for intelligent build caching and parallelization - Workspace management: PNPM for fast, disk-efficient dependency management - Demo applications: Example apps showcasing component usage in different frameworks

📁 Project Structure

.
├── apps/                     # Demo applications
│   └── angular-app/          # Angular demo showcasing web components
├── packages/                 # Web component packages
│   ├── m3-button/            # Material Design 3 Button
│   └── m3-navigation-rail/   # Material Design 3 Navigation Rail
├── pnpm-workspace.yaml       # PNPM workspace configuration
├── turbo.json                # Turborepo configuration
└── tsconfig.json             # Shared TypeScript config

🚀 Quick Start

Prerequisites

• Node.js >= 18.0.0
• PNPM >= 9.0.0

Install PNPM if you haven't already:

npm install -g pnpm@9.12.1

Installation

# Clone the repository
git clone <repository-url>
cd components

# Install dependencies
pnpm install

# Build all packages and apps
pnpm build

# Run development servers
pnpm dev

🛠️ Development

Build Commands

# Build all packages and apps
pnpm build

# Build specific package
pnpm --filter @banegasn/m3-button build

# Build specific app
pnpm --filter angular-app build

Development Commands

# Run all dev servers
pnpm dev

# Run specific package in dev mode
cd packages/example-component
pnpm dev

# Run specific app
cd apps/angular-app
pnpm dev

The Angular app will be available at http://localhost:4200

Other Commands

# Run linters
pnpm lint

# Run tests
pnpm test

# Clean all build artifacts
pnpm clean

🎯 Demo Applications

angular-app

A demonstration Angular application showcasing how to use the web components in a real-world application.

Features: - Angular 18 with standalone components - Live examples of all available web components - Integration patterns and best practices - Deployed to GitHub Pages for live preview

Run:

cd apps/angular-app
pnpm dev

💡 Note: More demo apps (React, Vue, vanilla JS) may be added in the future to demonstrate cross-framework compatibility.

🔧 Turborepo Configuration

The turbo.json file defines the build pipeline:

• build: Builds all packages with dependency awareness
• dev: Runs all development servers
• lint: Runs linters across the monorepo
• test: Runs tests with proper dependencies
• clean: Cleans build artifacts

Key Features:

• Caching: Turborepo caches build outputs for faster rebuilds
• Parallelization: Runs independent tasks in parallel
• Dependency graph: Ensures packages build in the correct order

📝 Adding New Web Components

Add a new component package:

1. Create package directory:

mkdir -p packages/my-web-component/src

1. Create package.json:

{
  "name": "@banegasn/my-web-component",
  "version": "1.0.0",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch"
  }
}

1. Create your web component using Lit, Svelte, or vanilla JavaScript

2. Install dependencies from root:

pnpm install

Add a new demo app:

1. Create app directory:

mkdir -p apps/my-demo-app

1. Set up your framework (React, Vue, etc.)

2. Add workspace dependencies in package.json:

{
  "dependencies": {
    "@banegasn/m3-button": "workspace:*",
    "@banegasn/m3-navigation-rail": "workspace:*"
  }
}

🧪 Testing

Add test scripts to individual packages:

{
  "scripts": {
    "test": "vitest"
  }
}

Run all tests:

pnpm test

🚢 Building for Production

Build all packages and apps:

pnpm build

Turborepo will: 1. Build packages in dependency order 2. Cache successful builds 3. Only rebuild what changed

Build for GitHub Pages:

pnpm build:gh-pages

This builds all packages and the Angular app optimized for GitHub Pages deployment with the correct base href (/components/).

📤 Publishing Web Components

To publish web component packages to GitHub Packages (or npm):

# Bump version
pnpm version:patch  # or version:minor, version:major

# Publish all packages
pnpm publish:packages

All web components are published as individual npm packages that can be installed and used in any project.

See PUBLISHING.md for detailed publishing instructions and GitHub Actions setup.

📚 Best Practices for Web Components

1. Framework-agnostic: Design components to work in any framework or vanilla JavaScript
2. Use workspace protocol: Reference workspace packages with workspace:*
3. Shared configs: Extend root tsconfig.json for consistency
4. Custom elements: Follow web component standards and naming conventions (kebab-case)
5. Semantic versioning: Version packages independently
6. Documentation: Keep README files updated in each package with usage examples
7. Accessibility: Ensure components follow WCAG guidelines and support keyboard navigation

🔍 Troubleshooting

Clear all caches:

pnpm clean
rm -rf node_modules pnpm-lock.yaml
pnpm install

Clear Turborepo cache:

rm -rf .turbo

Reinstall dependencies:

pnpm install --force

📖 Resources

Web Components

• Web Components Standards
• Lit Documentation
• Svelte Documentation
• Material Design 3

Monorepo Tools

• Turborepo Documentation
• PNPM Workspaces

Framework Integration

• Angular Documentation
• Using Web Components in React
• Using Web Components in Vue

🤝 Contributing

1. Create a new branch
2. Make your changes
3. Run pnpm build and pnpm test
4. Submit a pull request

📄 License

MIT