ads-fe 0.0.1

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

@@ -0,0 +1,284 @@
+---
+name: pnpm-performance-optimization
+description: Tips and tricks for faster installs and better performance
+---
+
+# pnpm Performance Optimization
+
+pnpm is fast by default, but these optimizations can make it even faster.
+
+## Install Optimizations
+
+### Use Frozen Lockfile
+
+Skip resolution when lockfile exists:
+
+```bash
+pnpm install --frozen-lockfile
+```
+
+This is faster because pnpm skips the resolution phase entirely.
+
+### Prefer Offline Mode
+
+Use cached packages when available:
+
+```bash
+pnpm install --prefer-offline
+```
+
+Or configure globally:
+```ini
+# .npmrc
+prefer-offline=true
+```
+
+### Skip Optional Dependencies
+
+If you don't need optional deps:
+
+```bash
+pnpm install --no-optional
+```
+
+### Skip Scripts
+
+For CI or when scripts aren't needed:
+
+```bash
+pnpm install --ignore-scripts
+```
+
+**Caution:** Some packages require postinstall scripts to work correctly.
+
+### Only Build Specific Dependencies
+
+Only run build scripts for specific packages:
+
+```ini
+# .npmrc
+onlyBuiltDependencies[]=esbuild
+onlyBuiltDependencies[]=sharp
+onlyBuiltDependencies[]=@swc/core
+```
+
+Or skip builds entirely for deps that don't need them:
+
+```json
+{
+  "pnpm": {
+    "neverBuiltDependencies": ["fsevents", "cpu-features"]
+  }
+}
+```
+
+## Store Optimizations
+
+### Side Effects Cache
+
+Cache native module build results:
+
+```ini
+# .npmrc
+side-effects-cache=true
+```
+
+This caches the results of postinstall scripts, speeding up subsequent installs.
+
+### Shared Store
+
+Use a single store for all projects (default behavior):
+
+```ini
+# .npmrc
+store-dir=~/.pnpm-store
+```
+
+Benefits:
+- Packages downloaded once for all projects
+- Hard links save disk space
+- Faster installs from cache
+
+### Store Maintenance
+
+Periodically clean unused packages:
+
+```bash
+# Remove unreferenced packages
+pnpm store prune
+
+# Check store integrity
+pnpm store status
+```
+
+## Workspace Optimizations
+
+### Parallel Execution
+
+Run workspace scripts in parallel:
+
+```bash
+pnpm -r --parallel run build
+```
+
+Control concurrency:
+```ini
+# .npmrc
+workspace-concurrency=8
+```
+
+### Stream Output
+
+See output in real-time:
+
+```bash
+pnpm -r --stream run build
+```
+
+### Filter to Changed Packages
+
+Only build what changed:
+
+```bash
+# Build packages changed since main branch
+pnpm --filter "...[origin/main]" run build
+```
+
+### Topological Order
+
+Build dependencies before dependents:
+
+```bash
+pnpm -r run build
+# Automatically runs in topological order
+```
+
+For explicit sequential builds:
+```bash
+pnpm -r --workspace-concurrency=1 run build
+```
+
+## Network Optimizations
+
+### Configure Registry
+
+Use closest/fastest registry:
+
+```ini
+# .npmrc
+registry=https://registry.npmmirror.com/
+```
+
+### HTTP Settings
+
+Tune network settings:
+
+```ini
+# .npmrc
+fetch-retries=3
+fetch-retry-mintimeout=10000
+fetch-retry-maxtimeout=60000
+network-concurrency=16
+```
+
+### Proxy Configuration
+
+```ini
+# .npmrc
+proxy=http://proxy.company.com:8080
+https-proxy=http://proxy.company.com:8080
+```
+
+## Lockfile Optimization
+
+### Single Lockfile (Monorepos)
+
+Use shared lockfile for all packages (default):
+
+```ini
+# .npmrc
+shared-workspace-lockfile=true
+```
+
+Benefits:
+- Single source of truth
+- Faster resolution
+- Consistent versions across workspace
+
+### Lockfile-only Mode
+
+Only update lockfile without installing:
+
+```bash
+pnpm install --lockfile-only
+```
+
+## Benchmarking
+
+### Compare Install Times
+
+```bash
+# Clean install
+rm -rf node_modules pnpm-lock.yaml
+time pnpm install
+
+# Cached install (with lockfile)
+rm -rf node_modules
+time pnpm install --frozen-lockfile
+
+# With store cache
+time pnpm install --frozen-lockfile --prefer-offline
+```
+
+### Profile Resolution
+
+Debug slow installs:
+
+```bash
+# Verbose logging
+pnpm install --reporter=append-only
+
+# Debug mode
+DEBUG=pnpm:* pnpm install
+```
+
+## Configuration Summary
+
+Optimized `.npmrc` for performance:
+
+```ini
+# Install behavior
+prefer-offline=true
+auto-install-peers=true
+
+# Build optimization  
+side-effects-cache=true
+# Only build what's necessary
+onlyBuiltDependencies[]=esbuild
+onlyBuiltDependencies[]=@swc/core
+
+# Network
+fetch-retries=3
+network-concurrency=16
+
+# Workspace
+workspace-concurrency=4
+```
+
+## Quick Reference
+
+| Scenario | Command/Setting |
+|----------|-----------------|
+| CI installs | `pnpm install --frozen-lockfile` |
+| Offline development | `--prefer-offline` |
+| Skip native builds | `neverBuiltDependencies` |
+| Parallel workspace | `pnpm -r --parallel run build` |
+| Build changed only | `pnpm --filter "...[origin/main]" build` |
+| Clean store | `pnpm store prune` |
+
+<!-- 
+Source references:
+- https://pnpm.io/npmrc
+- https://pnpm.io/cli/install
+- https://pnpm.io/filtering
+-->

package/skills/pnpm/references/core-cli.md

@@ -0,0 +1,229 @@
+---
+name: pnpm-cli-commands
+description: Essential pnpm commands for package management, running scripts, and workspace operations
+---
+
+# pnpm CLI Commands
+
+pnpm provides a comprehensive CLI for package management with commands similar to npm/yarn but with unique features.
+
+## Installation Commands
+
+### Install all dependencies
+```bash
+pnpm install
+# or
+pnpm i
+```
+
+### Add a dependency
+```bash
+# Production dependency
+pnpm add <pkg>
+
+# Dev dependency
+pnpm add -D <pkg>
+pnpm add --save-dev <pkg>
+
+# Optional dependency
+pnpm add -O <pkg>
+
+# Global package
+pnpm add -g <pkg>
+
+# Specific version
+pnpm add <pkg>@<version>
+pnpm add <pkg>@next
+pnpm add <pkg>@^1.0.0
+```
+
+### Remove a dependency
+```bash
+pnpm remove <pkg>
+pnpm rm <pkg>
+pnpm uninstall <pkg>
+pnpm un <pkg>
+```
+
+### Update dependencies
+```bash
+# Update all
+pnpm update
+pnpm up
+
+# Update specific package
+pnpm update <pkg>
+
+# Update to latest (ignore semver)
+pnpm update --latest
+pnpm up -L
+
+# Interactive update
+pnpm update --interactive
+pnpm up -i
+```
+
+## Script Commands
+
+### Run scripts
+```bash
+pnpm run <script>
+# or shorthand
+pnpm <script>
+
+# Pass arguments to script
+pnpm run build -- --watch
+
+# Run script if exists (no error if missing)
+pnpm run --if-present build
+```
+
+### Execute binaries
+```bash
+# Run local binary
+pnpm exec <command>
+
+# Example
+pnpm exec eslint .
+```
+
+### dlx - Run without installing
+```bash
+# Like npx but for pnpm
+pnpm dlx <pkg>
+
+# Examples
+pnpm dlx create-vite my-app
+pnpm dlx degit user/repo my-project
+```
+
+## Workspace Commands
+
+### Run in all packages
+```bash
+# Run script in all workspace packages
+pnpm -r run <script>
+pnpm --recursive run <script>
+
+# Run in specific packages
+pnpm --filter <pattern> run <script>
+
+# Examples
+pnpm --filter "./packages/**" run build
+pnpm --filter "!./packages/internal/**" run test
+pnpm --filter "@myorg/*" run lint
+```
+
+### Filter patterns
+```bash
+# By package name
+pnpm --filter <pkg-name> <command>
+pnpm --filter "@scope/pkg" build
+
+# By directory
+pnpm --filter "./packages/core" test
+
+# Dependencies of a package
+pnpm --filter "...@scope/app" build
+
+# Dependents of a package
+pnpm --filter "@scope/core..." test
+
+# Changed packages since commit/branch
+pnpm --filter "...[origin/main]" build
+```
+
+## Other Useful Commands
+
+### Link packages
+```bash
+# Link global package
+pnpm link --global
+pnpm link -g
+
+# Use linked package
+pnpm link --global <pkg>
+```
+
+### Patch packages
+```bash
+# Create patch for a package
+pnpm patch <pkg>@<version>
+
+# After editing, commit the patch
+pnpm patch-commit <path>
+
+# Remove a patch
+pnpm patch-remove <pkg>
+```
+
+### Store management
+```bash
+# Show store path
+pnpm store path
+
+# Remove unreferenced packages
+pnpm store prune
+
+# Check store integrity
+pnpm store status
+```
+
+### Other commands
+```bash
+# Clean install (like npm ci)
+pnpm install --frozen-lockfile
+
+# List installed packages
+pnpm list
+pnpm ls
+
+# Why is package installed?
+pnpm why <pkg>
+
+# Outdated packages
+pnpm outdated
+
+# Audit for vulnerabilities
+pnpm audit
+
+# Rebuild native modules
+pnpm rebuild
+
+# Import from npm/yarn lockfile
+pnpm import
+
+# Create tarball
+pnpm pack
+
+# Publish package
+pnpm publish
+```
+
+## Useful Flags
+
+```bash
+# Ignore scripts
+pnpm install --ignore-scripts
+
+# Prefer offline (use cache)
+pnpm install --prefer-offline
+
+# Strict peer dependencies
+pnpm install --strict-peer-dependencies
+
+# Production only
+pnpm install --prod
+pnpm install -P
+
+# No optional dependencies
+pnpm install --no-optional
+```
+
+<!-- 
+Source references:
+- https://pnpm.io/cli/install
+- https://pnpm.io/cli/add
+- https://pnpm.io/cli/run
+- https://pnpm.io/filtering
+-->

package/skills/pnpm/references/core-config.md

@@ -0,0 +1,188 @@
+---
+name: pnpm-configuration
+description: Configuration options via pnpm-workspace.yaml and .npmrc settings
+---
+
+# pnpm Configuration
+
+pnpm uses two main configuration files: `pnpm-workspace.yaml` for workspace and pnpm-specific settings, and `.npmrc` for npm-compatible and pnpm-specific settings.
+
+## pnpm-workspace.yaml
+
+The recommended location for pnpm-specific configurations. Place at project root.
+
+```yaml
+# Define workspace packages
+packages:
+  - 'packages/*'
+  - 'apps/*'
+  - '!**/test/**'  # Exclude pattern
+
+# Catalog for shared dependency versions
+catalog:
+  react: ^18.2.0
+  typescript: ~5.3.0
+
+# Named catalogs for different dependency groups
+catalogs:
+  react17:
+    react: ^17.0.2
+    react-dom: ^17.0.2
+  react18:
+    react: ^18.2.0
+    react-dom: ^18.2.0
+
+# Override resolutions (preferred location)
+overrides:
+  lodash: ^4.17.21
+  'foo@^1.0.0>bar': ^2.0.0
+
+# pnpm settings (alternative to .npmrc)
+settings:
+  auto-install-peers: true
+  strict-peer-dependencies: false
+  link-workspace-packages: true
+  prefer-workspace-packages: true
+  shared-workspace-lockfile: true
+```
+
+## .npmrc Settings
+
+pnpm reads settings from `.npmrc` files. Create at project root or user home.
+
+### Common pnpm Settings
+
+```ini
+# Automatically install peer dependencies
+auto-install-peers=true
+
+# Fail on peer dependency issues
+strict-peer-dependencies=false
+
+# Hoist patterns for dependencies
+public-hoist-pattern[]=*types*
+public-hoist-pattern[]=*eslint*
+shamefully-hoist=false
+
+# Store location
+store-dir=~/.pnpm-store
+
+# Virtual store location  
+virtual-store-dir=node_modules/.pnpm
+
+# Lockfile settings
+lockfile=true
+prefer-frozen-lockfile=true
+
+# Side effects cache (speeds up rebuilds)
+side-effects-cache=true
+
+# Registry settings
+registry=https://registry.npmjs.org/
+@myorg:registry=https://npm.myorg.com/
+```
+
+### Workspace Settings
+
+```ini
+# Link workspace packages
+link-workspace-packages=true
+
+# Prefer workspace packages over registry
+prefer-workspace-packages=true
+
+# Single lockfile for all packages
+shared-workspace-lockfile=true
+
+# Save prefix for workspace dependencies
+save-workspace-protocol=rolling
+```
+
+### Node.js Settings
+
+```ini
+# Use specific Node.js version
+use-node-version=20.10.0
+
+# Node.js version file
+node-version-file=.nvmrc
+
+# Manage Node.js versions
+manage-package-manager-versions=true
+```
+
+### Security Settings
+
+```ini
+# Ignore specific scripts
+ignore-scripts=false
+
+# Allow specific build scripts
+onlyBuiltDependencies[]=esbuild
+onlyBuiltDependencies[]=sharp
+
+# Package extensions for missing peer deps
+package-extensions[foo@1].peerDependencies.bar=*
+```
+
+## Configuration Hierarchy
+
+Settings are read in order (later overrides earlier):
+
+1. `/etc/npmrc` - Global config
+2. `~/.npmrc` - User config  
+3. `<project>/.npmrc` - Project config
+4. Environment variables: `npm_config_<key>=<value>`
+5. `pnpm-workspace.yaml` settings field
+
+## Environment Variables
+
+```bash
+# Set config via env
+npm_config_registry=https://registry.npmjs.org/
+
+# pnpm-specific env vars
+PNPM_HOME=~/.local/share/pnpm
+```
+
+## Package.json Fields
+
+pnpm reads specific fields from `package.json`:
+
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "lodash": "^4.17.21"
+    },
+    "peerDependencyRules": {
+      "ignoreMissing": ["@babel/*"],
+      "allowedVersions": {
+        "react": "17 || 18"
+      }
+    },
+    "neverBuiltDependencies": ["fsevents"],
+    "onlyBuiltDependencies": ["esbuild"],
+    "allowedDeprecatedVersions": {
+      "request": "*"
+    },
+    "patchedDependencies": {
+      "express@4.18.2": "patches/express@4.18.2.patch"
+    }
+  }
+}
+```
+
+## Key Differences from npm/yarn
+
+1. **Strict by default**: No phantom dependencies
+2. **Workspace protocol**: `workspace:*` for local packages
+3. **Catalogs**: Centralized version management
+4. **Content-addressable store**: Shared across projects
+
+<!-- 
+Source references:
+- https://pnpm.io/pnpm-workspace_yaml
+- https://pnpm.io/npmrc
+- https://pnpm.io/package_json
+-->