ads-fe 0.0.1

package/skills/pnpm/references/best-practices-ci.md

@@ -0,0 +1,285 @@
+---
+name: pnpm-ci-cd-setup
+description: Optimizing pnpm for continuous integration and deployment workflows
+---
+
+# pnpm CI/CD Setup
+
+Best practices for using pnpm in CI/CD environments for fast, reliable builds.
+
+## GitHub Actions
+
+### Basic Setup
+
+```yaml
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+      
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+      
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm test
+      - run: pnpm build
+```
+
+### With Store Caching
+
+For larger projects, cache the pnpm store:
+
+```yaml
+- uses: pnpm/action-setup@v4
+  with:
+    version: 9
+
+- name: Get pnpm store directory
+  shell: bash
+  run: |
+    echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+
+- uses: actions/cache@v4
+  name: Setup pnpm cache
+  with:
+    path: ${{ env.STORE_PATH }}
+    key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+    restore-keys: |
+      ${{ runner.os }}-pnpm-store-
+
+- run: pnpm install --frozen-lockfile
+```
+
+### Matrix Testing
+
+```yaml
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        node: [18, 20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: 'pnpm'
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm test
+```
+
+## GitLab CI
+
+```yaml
+image: node:20
+
+stages:
+  - install
+  - test
+  - build
+
+variables:
+  PNPM_HOME: /root/.local/share/pnpm
+  PATH: $PNPM_HOME:$PATH
+
+before_script:
+  - corepack enable
+  - corepack prepare pnpm@latest --activate
+
+cache:
+  key: ${CI_COMMIT_REF_SLUG}
+  paths:
+    - .pnpm-store
+
+install:
+  stage: install
+  script:
+    - pnpm config set store-dir .pnpm-store
+    - pnpm install --frozen-lockfile
+
+test:
+  stage: test
+  script:
+    - pnpm test
+
+build:
+  stage: build
+  script:
+    - pnpm build
+```
+
+## Docker
+
+### Multi-Stage Build
+
+```dockerfile
+# Build stage
+FROM node:20-slim AS builder
+
+# Enable corepack for pnpm
+RUN corepack enable
+
+WORKDIR /app
+
+# Copy package files first for layer caching
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+COPY packages/*/package.json ./packages/
+
+# Install dependencies
+RUN pnpm install --frozen-lockfile
+
+# Copy source and build
+COPY . .
+RUN pnpm build
+
+# Production stage
+FROM node:20-slim AS runner
+
+RUN corepack enable
+WORKDIR /app
+
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/package.json ./
+COPY --from=builder /app/pnpm-lock.yaml ./
+
+# Production install
+RUN pnpm install --frozen-lockfile --prod
+
+CMD ["node", "dist/index.js"]
+```
+
+### Optimized for Monorepos
+
+```dockerfile
+FROM node:20-slim AS builder
+RUN corepack enable
+WORKDIR /app
+
+# Copy workspace config
+COPY pnpm-lock.yaml pnpm-workspace.yaml ./
+
+# Copy all package.json files maintaining structure
+COPY packages/core/package.json ./packages/core/
+COPY packages/api/package.json ./packages/api/
+
+# Install all dependencies
+RUN pnpm install --frozen-lockfile
+
+# Copy source
+COPY . .
+
+# Build specific package
+RUN pnpm --filter @myorg/api build
+```
+
+## Key CI Flags
+
+### --frozen-lockfile
+
+**Always use in CI.** Fails if `pnpm-lock.yaml` needs updates:
+
+```bash
+pnpm install --frozen-lockfile
+```
+
+### --prefer-offline
+
+Use cached packages when available:
+
+```bash
+pnpm install --frozen-lockfile --prefer-offline
+```
+
+### --ignore-scripts
+
+Skip lifecycle scripts for faster installs (use cautiously):
+
+```bash
+pnpm install --frozen-lockfile --ignore-scripts
+```
+
+## Corepack Integration
+
+Use Corepack to manage pnpm version:
+
+```json
+// package.json
+{
+  "packageManager": "pnpm@9.0.0"
+}
+```
+
+```yaml
+# GitHub Actions
+- run: corepack enable
+- run: pnpm install --frozen-lockfile
+```
+
+## Monorepo CI Strategies
+
+### Build Changed Packages Only
+
+```yaml
+- name: Build changed packages
+  run: |
+    pnpm --filter "...[origin/main]" build
+```
+
+### Parallel Jobs per Package
+
+```yaml
+jobs:
+  detect-changes:
+    runs-on: ubuntu-latest
+    outputs:
+      packages: ${{ steps.changes.outputs.packages }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - id: changes
+        run: |
+          echo "packages=$(pnpm --filter '...[origin/main]' list --json | jq -c '[.[].name]')" >> $GITHUB_OUTPUT
+
+  test:
+    needs: detect-changes
+    if: needs.detect-changes.outputs.packages != '[]'
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        package: ${{ fromJson(needs.detect-changes.outputs.packages) }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm --filter ${{ matrix.package }} test
+```
+
+## Best Practices Summary
+
+1. **Always use `--frozen-lockfile`** in CI
+2. **Cache the pnpm store** for faster installs
+3. **Use Corepack** for consistent pnpm versions
+4. **Specify `packageManager`** in package.json
+5. **Use `--filter`** in monorepos to build only what changed
+6. **Multi-stage Docker builds** for smaller images
+
+<!-- 
+Source references:
+- https://pnpm.io/continuous-integration
+- https://github.com/pnpm/action-setup
+-->

package/skills/pnpm/references/best-practices-migration.md

@@ -0,0 +1,291 @@
+---
+name: migration-to-pnpm
+description: Migrating from npm or Yarn to pnpm with minimal friction
+---
+
+# Migration to pnpm
+
+Guide for migrating existing projects from npm or Yarn to pnpm.
+
+## Quick Migration
+
+### From npm
+
+```bash
+# Remove npm lockfile and node_modules
+rm -rf node_modules package-lock.json
+
+# Install with pnpm
+pnpm install
+```
+
+### From Yarn
+
+```bash
+# Remove yarn lockfile and node_modules
+rm -rf node_modules yarn.lock
+
+# Install with pnpm
+pnpm install
+```
+
+### Import Existing Lockfile
+
+pnpm can import existing lockfiles:
+
+```bash
+# Import from npm or yarn lockfile
+pnpm import
+
+# This creates pnpm-lock.yaml from:
+# - package-lock.json (npm)
+# - yarn.lock (yarn)
+# - npm-shrinkwrap.json (npm)
+```
+
+## Handling Common Issues
+
+### Phantom Dependencies
+
+pnpm is strict about dependencies. If code imports a package not in `package.json`, it will fail.
+
+**Problem:**
+```js
+// Works with npm (hoisted), fails with pnpm
+import lodash from 'lodash' // Not in dependencies, installed by another package
+```
+
+**Solution:** Add missing dependencies explicitly:
+```bash
+pnpm add lodash
+```
+
+### Missing Peer Dependencies
+
+pnpm reports peer dependency issues by default.
+
+**Option 1:** Let pnpm auto-install:
+```ini
+# .npmrc (default in pnpm v8+)
+auto-install-peers=true
+```
+
+**Option 2:** Install manually:
+```bash
+pnpm add react react-dom
+```
+
+**Option 3:** Suppress warnings if acceptable:
+```json
+{
+  "pnpm": {
+    "peerDependencyRules": {
+      "ignoreMissing": ["react"]
+    }
+  }
+}
+```
+
+### Symlink Issues
+
+Some tools don't work with symlinks. Use hoisted mode:
+
+```ini
+# .npmrc
+node-linker=hoisted
+```
+
+Or hoist specific packages:
+
+```ini
+public-hoist-pattern[]=*eslint*
+public-hoist-pattern[]=*babel*
+```
+
+### Native Module Rebuilds
+
+If native modules fail, try:
+
+```bash
+# Rebuild all native modules
+pnpm rebuild
+
+# Or reinstall
+rm -rf node_modules
+pnpm install
+```
+
+## Monorepo Migration
+
+### From npm Workspaces
+
+1. Create `pnpm-workspace.yaml`:
+   ```yaml
+   packages:
+     - 'packages/*'
+   ```
+
+2. Update internal dependencies to use workspace protocol:
+   ```json
+   {
+     "dependencies": {
+       "@myorg/utils": "workspace:^"
+     }
+   }
+   ```
+
+3. Install:
+   ```bash
+   rm -rf node_modules packages/*/node_modules package-lock.json
+   pnpm install
+   ```
+
+### From Yarn Workspaces
+
+1. Remove Yarn-specific files:
+   ```bash
+   rm yarn.lock .yarnrc.yml
+   rm -rf .yarn
+   ```
+
+2. Create `pnpm-workspace.yaml` matching `workspaces` in package.json:
+   ```yaml
+   packages:
+     - 'packages/*'
+   ```
+
+3. Update `package.json` - remove Yarn workspace config if not needed:
+   ```json
+   {
+     // Remove "workspaces" field (optional, pnpm uses pnpm-workspace.yaml)
+   }
+   ```
+
+4. Convert workspace references:
+   ```json
+   // From Yarn
+   "@myorg/utils": "*"
+   
+   // To pnpm
+   "@myorg/utils": "workspace:*"
+   ```
+
+### From Lerna
+
+pnpm can replace Lerna for most use cases:
+
+```bash
+# Lerna: run script in all packages
+lerna run build
+
+# pnpm equivalent
+pnpm -r run build
+
+# Lerna: run in specific package
+lerna run build --scope=@myorg/app
+
+# pnpm equivalent  
+pnpm --filter @myorg/app run build
+
+# Lerna: publish
+lerna publish
+
+# pnpm: use changesets instead
+pnpm add -Dw @changesets/cli
+pnpm changeset
+pnpm changeset version
+pnpm publish -r
+```
+
+## Configuration Migration
+
+### .npmrc Settings
+
+Most npm/Yarn settings work in pnpm's `.npmrc`:
+
+```ini
+# Registry settings (same as npm)
+registry=https://registry.npmjs.org/
+@myorg:registry=https://npm.myorg.com/
+
+# Auth tokens (same as npm)
+//registry.npmjs.org/:_authToken=${NPM_TOKEN}
+
+# pnpm-specific additions
+auto-install-peers=true
+strict-peer-dependencies=false
+```
+
+### Scripts Migration
+
+Most scripts work unchanged. Update pnpm-specific patterns:
+
+```json
+{
+  "scripts": {
+    // npm: recursive scripts
+    "build:all": "npm run build --workspaces",
+    // pnpm: use -r flag
+    "build:all": "pnpm -r run build",
+    
+    // npm: run in specific workspace  
+    "dev:app": "npm run dev -w packages/app",
+    // pnpm: use --filter
+    "dev:app": "pnpm --filter @myorg/app run dev"
+  }
+}
+```
+
+## CI/CD Migration
+
+Update CI configuration:
+
+```yaml
+# Before (npm)
+- run: npm ci
+
+# After (pnpm)
+- uses: pnpm/action-setup@v4
+- run: pnpm install --frozen-lockfile
+```
+
+Add to `package.json` for Corepack:
+```json
+{
+  "packageManager": "pnpm@9.0.0"
+}
+```
+
+## Gradual Migration
+
+For large projects, migrate gradually:
+
+1. **Start with CI**: Use pnpm in CI, keep npm/yarn locally
+2. **Add pnpm-lock.yaml**: Run `pnpm import` to create lockfile
+3. **Test thoroughly**: Ensure builds work with pnpm
+4. **Update documentation**: Update README, CONTRIBUTING
+5. **Remove old files**: Delete old lockfiles after team adoption
+
+## Rollback Plan
+
+If migration causes issues:
+
+```bash
+# Remove pnpm files
+rm -rf node_modules pnpm-lock.yaml pnpm-workspace.yaml
+
+# Restore npm
+npm install
+
+# Or restore Yarn
+yarn install
+```
+
+Keep old lockfile in git history for easy rollback.
+
+<!-- 
+Source references:
+- https://pnpm.io/installation
+- https://pnpm.io/cli/import
+- https://pnpm.io/limitations
+-->