diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile new file mode 100644 index 00000000000..419aabe0133 --- /dev/null +++ b/.devcontainer/Dockerfile @@ -0,0 +1,27 @@ +# Build stage for installing dependencies +FROM node:22-bookworm + +# Install essential packages +RUN apt-get update && apt-get install -y \ + git \ + && rm -rf /var/lib/apt/lists/* + +# Enable corepack and pnpm +RUN corepack enable && corepack prepare pnpm@10.18.1 --activate + +# Configure pnpm +ENV PNPM_HOME="/pnpm" +ENV PATH="$PNPM_HOME:$PATH" + +# Set up workspace directory +WORKDIR /workspace + +# Create node user with proper permissions if it doesn't exist +RUN id -u node &>/dev/null || (groupadd --gid 1000 node && \ + useradd --uid 1000 --gid node --shell /bin/bash --create-home node) + +# Ensure node user owns workspace +RUN chown -R node:node /workspace + +# Switch to node user for all subsequent operations +USER node diff --git a/.devcontainer/README.md b/.devcontainer/README.md index f8bfcb754d8..28d1c4b7fce 100644 --- a/.devcontainer/README.md +++ b/.devcontainer/README.md @@ -1,6 +1,6 @@ # Devcontainer Configuration -This directory contains the configuration for GitHub Codespaces and VS Code Dev Containers. +This directory contains the configuration for GitHub Codespaces and VS Code Dev Containers, optimized for pnpm monorepo development. ## Quick Start @@ -18,21 +18,50 @@ With prebuilds enabled, your codespace will be ready in ~30 seconds instead of 5 2. Open the repository in VS Code 3. Press `F1` and select "Dev Containers: Reopen in Container" +## Architecture + +### Custom Dockerfile + +Following [pnpm Docker best practices](https://pnpm.io/docker), we use a custom Dockerfile that: + +- Uses Node.js 22 (matching `.nvmrc` and `package.json` engines) +- Enables pnpm 10.18.1 via corepack (matching `packageManager` in `package.json`) +- Runs as the `node` user to avoid permission issues +- Includes git and essential development tools + +### pnpm Store Caching + +The devcontainer uses a Docker volume (`ui-kit-pnpm-store`) to persist the pnpm store across container rebuilds. This significantly speeds up dependency installation: + +- First install: Downloads all dependencies +- Subsequent installs: Reuses cached packages from the volume + +### Optimized Lifecycle + +The devcontainer uses GitHub Codespaces prebuild lifecycle: + +1. **`updateContentCommand`** - Runs during prebuild (slow operations) + - Installs all dependencies with frozen lockfile + - Builds all packages in the monorepo + +2. **`postStartCommand`** - Runs every time the codespace starts + - Displays a welcome message with quick start commands + +This separation ensures expensive operations are cached in the prebuild, while codespace startup remains fast. + ## What's Included ### Pre-installed Tools -- Node.js 22 -- pnpm (via corepack) +- Node.js 22.17.1 +- pnpm 10.18.1 +- git - GitHub CLI -- All dependencies installed (`pnpm install --frozen-lockfile`) -- Full project build completed (`pnpm run build`) ### VS Code Extensions The following extensions are automatically installed: - Biome (formatter and linter) - Code Spell Checker -- GitHub Copilot -- GitHub Copilot Chat +- GitHub Copilot & Copilot Chat - Lit Plugin - MDX Language Support - Playwright Test Runner @@ -45,24 +74,6 @@ The following extensions are automatically installed: - Auto-organize imports: Enabled - LF line endings enforced -## Lifecycle Commands - -The devcontainer uses an optimized lifecycle for GitHub Codespaces prebuilds: - -1. **`updateContentCommand`** - Runs during prebuild (slow operations) - - Enables pnpm via corepack - - Installs all dependencies with frozen lockfile - - Builds all packages - -2. **`postCreateCommand`** - Runs after prebuild (fast operations) - - Ensures pnpm is enabled - -3. **`postStartCommand`** - Runs every time the codespace starts - - Displays a welcome message - -This separation ensures that expensive operations (install & build) are cached in the prebuild, -while codespace creation and startup remain fast. - ## GitHub Codespaces Prebuilds Prebuilds must be configured in the repository settings: @@ -75,49 +86,46 @@ Prebuilds must be configured in the repository settings: - **Trigger**: On push to main branch 4. Click **Create** -Once configured, prebuilds will be created automatically: -- On every push to `main` branch -- On schedule (configurable, recommended: daily or weekly) -- When devcontainer configuration or dependencies change - ### Benefits of Prebuilds - Reduces codespace creation from ~5 minutes to ~30 seconds -- Pre-installs all dependencies (1.6GB of node_modules) -- Pre-builds all 36 packages in the monorepo +- Pre-installs all dependencies +- Pre-builds all packages in the monorepo - Ensures consistent developer environment -## Customization +## Development Workflow -To customize the devcontainer: -1. Edit `devcontainer.json` -2. Test locally with VS Code Dev Containers -3. Commit and push to trigger a new prebuild +Once your codespace is ready: -## Benefits +```bash +# Start development with hot reload +pnpm run dev:atomic -### Before Optimization -- Codespace creation: ~5 minutes -- Manual dependency installation and build -- No pre-configured VS Code extensions -- Inconsistent developer environment +# Run tests +pnpm test -### After Optimization -- Codespace creation: ~30 seconds (with prebuild) -- Dependencies and build pre-cached -- All recommended extensions auto-installed -- Consistent, production-ready environment +# Run linting +pnpm run lint:check + +# Build all packages +pnpm run build +``` ## Troubleshooting ### Codespace takes a long time to start - Check if prebuilds are enabled in repository settings - Verify the prebuild workflow ran successfully -- Consider manually triggering the prebuild workflow +- Consider manually triggering a new prebuild + +### pnpm install fails +- Ensure `pnpm-lock.yaml` is up to date +- Try deleting the pnpm store volume: `docker volume rm ui-kit-pnpm-store` +- Rebuild the container: "Dev Containers: Rebuild Container" -### Build failures in prebuild -- Check the prebuild logs in the Codespaces section of the repository settings -- Ensure `pnpm install --frozen-lockfile` and `pnpm run build` work locally -- Verify all dependencies are correctly specified in `pnpm-lock.yaml` +### Permission errors +- The container runs as the `node` user (UID 1000, GID 1000) +- If you see permission errors, ensure your host files are accessible +- On Linux, you may need to adjust file ownership ### Extensions not installing - Check VS Code output panel for extension installation logs @@ -126,6 +134,7 @@ To customize the devcontainer: ## Resources +- [pnpm Docker Guide](https://pnpm.io/docker) - [GitHub Codespaces Documentation](https://docs.github.com/en/codespaces) - [Dev Containers Specification](https://containers.dev/) - [Prebuild Configuration Guide](https://docs.github.com/en/codespaces/prebuilding-your-codespaces/configuring-prebuilds) diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index cff77eff8d9..6f10ec330b6 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -1,36 +1,28 @@ -// For format details, see https://aka.ms/devcontainer.json. For config options, see the -// README at: https://github.com/devcontainers/templates/tree/main/src/typescript-node { - "name": "Node.js & TypeScript", - // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile - "image": "mcr.microsoft.com/devcontainers/typescript-node:2-22-bookworm", + "name": "UI Kit (pnpm)", + "build": { + "dockerfile": "Dockerfile", + "context": ".." + }, - // Features to add to the dev container. More info: https://containers.dev/features. + // Features to add to the dev container "features": { "ghcr.io/devcontainers/features/github-cli:1": {} }, - // Use 'forwardPorts' to make a list of ports inside the container available locally. - // "forwardPorts": [], - - // Lifecycle commands optimized for GitHub Codespaces prebuilds - // See: https://docs.github.com/en/codespaces/prebuilding-your-codespaces/configuring-prebuilds - - // postCreateCommand runs AFTER prebuild (fast for users) - // Used for quick setup tasks after a codespace is created + // Mount the pnpm store as a volume for better caching + "mounts": ["source=ui-kit-pnpm-store,target=/pnpm/store,type=volume"], - // updateContentCommand runs DURING prebuild (slow but cached) - // This is where expensive operations like install and build should go - "updateContentCommand": "bash -c 'CI=true corepack enable pnpm && pnpm install --frozen-lockfile && pnpm run build'", + // Lifecycle commands optimized for GitHub Codespaces + // updateContentCommand runs during prebuild (expensive operations cached) + "updateContentCommand": "pnpm install --frozen-lockfile && pnpm run build", // postStartCommand runs every time the codespace starts - // Keep this minimal for fast startup - "postStartCommand": "echo 'Codespace ready! Run pnpm run dev to start development.'", + "postStartCommand": "echo '✓ Codespace ready! Run pnpm run dev:atomic to start development.'", - // Configure tool-specific properties. + // Configure tool-specific properties "customizations": { "vscode": { - // Extensions that will be automatically installed "extensions": [ "biomejs.biome", "streetsidesoftware.code-spell-checker", @@ -42,7 +34,6 @@ "bradlc.vscode-tailwindcss", "vitest.explorer" ], - // VS Code settings for better developer experience "settings": { "editor.defaultFormatter": "biomejs.biome", "editor.formatOnSave": true, @@ -56,9 +47,6 @@ } }, - // User configuration - explicitly set to 'node' user to avoid permission issues - // The base image uses 'node' user by default, but explicit configuration - // helps VS Code properly initialize home directory and config files "remoteUser": "node", "containerUser": "node" } diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 00000000000..93eb754163b --- /dev/null +++ b/.dockerignore @@ -0,0 +1,55 @@ +# Git +.git +.gitignore +.github + +# Dependencies +node_modules + +# Build outputs +dist +reports +sarifs + +# IDE +.vscode +.idea + +# Dev tools +.devcontainer +.husky + +# Logs +npm-debug.log +*.log + +# Cache +.turbo +.dccache +.cspellcache +.nx + +# Test files +**/*.spec.* +**/*.test.* +**/*.cy.ts +**.cy.ts.mp4 + +# Storybook +**/*.stories.tsx +.storybook + +# Documentation +internal-docs + +# Temporary files +.size-snapshot.json +topology.json +topology-raw.json +.git-message +packages/atomic/custom-elements.json +scripts/translation-gpt/temporary.json + +# Environment +.env +.env.local