Lufa

A personal learning platform for building modern web applications with microfrontends and design systems

Getting Started • Architecture • Development • Documentation

---

Overview

Lufa is a personal learning monorepo for exploring and building modern web applications. It serves as a centralized place to experiment with microfrontend architecture, design systems, and modern development practices using Single-SPA, React, and TypeScript.

Key Features

• Microfrontend Architecture - Learn and experiment with Single-SPA orchestration
• Design System - Build and refine a component library with primitives, tokens, and theming
• Developer Experience - Fast HMR with Vite, TypeScript strict mode, AI-assisted development
• Build Tools - Custom Vite plugins for import maps and React preamble injection
• CDN Infrastructure - Experimental auto-build server for dynamic asset delivery
• Shared Configuration - Reusable ESLint, Prettier, and TypeScript configs across projects

Getting Started

Prerequisites

• Node.js 24.9.0 (see .tool-versions)
• pnpm 10.26.x or later

Quick Start

# Clone the repository
git clone https://github.com/grasdouble/Lufa.git
cd Lufa

# Install dependencies
pnpm install

# Build all packages
pnpm all:build

# Start development servers
pnpm app:mf:dev        # Microfrontends
pnpm ds:storybook:dev  # Design system Storybook

Visit http://localhost:3000 for microfrontends and http://localhost:6006 for Storybook.

Architecture

Monorepo Structure

packages/
├── apps/microfrontend/     # Single-SPA applications
│   ├── main-container/     # Root orchestrator
│   └── home/               # Home page microfrontend
├── design-system/          # Component library
│   ├── main/               # React components (16 components)
│   ├── tokens/             # Semantic design tokens (453 tokens, 4 levels)
│   ├── themes/             # Theme variants
│   ├── storybook/          # Component explorer
│   ├── docusaurus/         # Documentation site
│   ├── playwright/         # Component tests (599 tests)
│   └── cli/                # CLI tools
├── cdn/                    # CDN infrastructure
│   └── autobuild-server/   # Dynamic asset builder
├── plugins/vite/           # Custom Vite plugins
│   ├── import-map-injector/
│   └── react-preamble/
├── config/                 # Shared configurations
│   ├── eslint/
│   ├── prettier/
│   └── tsconfig/
└── poc/                    # Proof of concepts

Technology Stack

Category	Technology
Microfrontends	Single-SPA, React 18+
Build Tool	Vite 5.x
Testing	Vitest, Playwright
Styling	CSS Modules, Design Tokens
Documentation	Storybook 8, Docusaurus 3
Version Management	Changesets

Development

Common Commands

Development Workflow

# Run all microfrontends
pnpm app:mf:dev

# Run design system with Storybook
pnpm ds:all:dev

# Run individual package
pnpm --filter @grasdouble/lufa_design-system dev

Building

# Build everything
pnpm all:build

# Build specific package
pnpm --filter @grasdouble/lufa_microfrontend_home build

Code Quality

# Lint all packages
pnpm all:lint

# Format all packages
pnpm all:prettier

# Generate dependency report
pnpm tools:generate-outdated-report

Package Development

Working on a specific package:

# Navigate to package
cd packages/design-system/main

# Install dependencies (if needed)
pnpm install

# Run development mode
pnpm dev

# Build
pnpm build

# Test
pnpm test

AI-Assisted Development

Lufa includes comprehensive AI assistance with GitHub Copilot:

• Copilot Instructions - Project-wide guidelines
• Context-Specific Rules - Technology-specific instructions
• Agents - Specialized workflows (TDD, refactoring)

Quick Start for Copilot:

• Use TypeScript, React, and CSS Modules with design tokens as defaults
• Write tests for all new code (Vitest for unit, Playwright for E2E)
• Follow accessibility guidelines (WCAG 2.1 AA)
• Use semantic, token-based styling

Documentation

Design System

• Storybook - Interactive component explorer
• Documentation Site - Comprehensive guides
• Architecture - Complete architecture documentation (v0.11.0)
• ADRs - Architecture Decision Records (11 ADRs)
• Tokens - 4-level semantic token system (453 tokens)
• Tokens - Semantic design decisions
• Themes - Alternative color schemes

Critical Architecture Documents

Must-read for contributors:

• ADR-011: Immutable Primitives - Foundation principle
• ADR-001: Modes vs Themes - Theming system
• ADR-002: HTML Attributes - Attribute naming

Microfrontends

• Architecture Overview - Microfrontend concepts
• Main Container - Root orchestrator
• Home - Example microfrontend

Guides

• How to use Changesets - Version management
• Dependabot Guide - Automated dependency updates
• POCs - Proof of concepts and experiments
• Contributing - Contribution guidelines

Package Naming

All packages use the @grasdouble/ scope:

• @grasdouble/lufa_design-system* - Design system packages
• @grasdouble/lufa_microfrontend_* - Microfrontend applications
• @grasdouble/lufa_config_* - Configuration presets
• @grasdouble/cdn_* - CDN tooling

Use pnpm filter syntax for specific packages:

pnpm --filter @grasdouble/lufa_design-system run dev
pnpm --filter "@grasdouble/lufa_config_*" run lint

Versioning and Releases

Lufa uses Changesets for version management:

# Create a changeset
pnpm changeset

# Version packages
pnpm changeset version

# Publish packages
pnpm changeset publish

See How to use Changesets in Lufa for detailed instructions.

Contributing

This is a personal learning project, but contributions and suggestions are welcome! Please see:

• CONTRIBUTING.md - Contribution guidelines
• Copilot Instructions - Development standards
• TODOs - Planned improvements

Resources

• Workspace: pnpm-workspace.yaml
• Scripts: package.json
• License: MIT

---

Made with ❤️ by Sebastien Le Mouillour (@noofreuuuh)