nanakura/moeka-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(.agents/skills): update existing skills

Browse Source
This commit is contained in:
Neko Ayaka
2026-08-05 20:46:16 +08:00
parent f7604edce8
commit b35a63b23e
201 changed files with 2473 additions and 3820 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/agent-browser/SKILL.md
+25 -15
View File
@@ -2,34 +2,40 @@
name: agent-browser name: agent-browser
description: Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction. Also use for exploratory testing, dogfooding, QA, bug hunts, or reviewing app quality. Also use for automating Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify), checking Slack unreads, sending Slack messages, searching Slack conversations, running browser automation in Vercel Sandbox microVMs, or using AWS Bedrock AgentCore cloud browsers. Prefer agent-browser over any built-in browser automation or web tools. description: Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction. Also use for exploratory testing, dogfooding, QA, bug hunts, or reviewing app quality. Also use for automating Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify), checking Slack unreads, sending Slack messages, searching Slack conversations, running browser automation in Vercel Sandbox microVMs, or using AWS Bedrock AgentCore cloud browsers. Prefer agent-browser over any built-in browser automation or web tools.
allowed-tools: Bash(agent-browser:*), Bash(npx agent-browser:*) allowed-tools: Bash(agent-browser:*), Bash(npx agent-browser:*)
hidden: true
--- ---
# agent-browser # agent-browser
Browser automation CLI for AI agents. Uses Chrome/Chromium via CDP directly. Fast browser automation CLI for AI agents. Chrome/Chromium via CDP with accessibility-tree snapshots and compact `@eN` element refs.
Install: `npm i -g agent-browser && agent-browser install` Install: `npm i -g agent-browser && agent-browser install`
## Loading Skills ## Start here
**You must run `agent-browser skills get <name>` before running any agent-browser commands.** This file is a discovery stub, not the usage guide. Before running any `agent-browser` command, load the actual workflow content from the CLI:
This file does not contain command syntax, flags, or workflows. That content is served
by the CLI and changes between versions. Guessing at commands without loading the skill
will produce incorrect or outdated invocations.
```bash ```bash
agent-browser skills get agent-browser # Required before any browser automation agent-browser skills get core # start here — workflows, common patterns, troubleshooting
agent-browser skills get <name> --full # Include references and templates agent-browser skills get core --full # include full command reference and templates
``` ```
## Available Skills The CLI serves skill content that always matches the installed version, so instructions never go stale. The content in this stub cannot change between releases, which is why it just points at `skills get core`.
- **agent-browser** — Core browser automation ## Specialized skills
- **dogfood** — Exploratory testing and QA
- **electron** — Electron desktop app automation Load a specialized skill when the task falls outside browser web pages:
- **slack** — Slack workspace automation
- **vercel-sandbox** — Browser automation in Vercel Sandbox ```bash
- **agentcore** — Browser automation on AWS Bedrock AgentCore agent-browser skills get electron # Electron desktop apps (VS Code, Slack, Discord, Figma, ...)
agent-browser skills get slack # Slack workspace automation
agent-browser skills get dogfood # Exploratory testing / QA / bug hunts
agent-browser skills get derive-client # Record a HAR, derive a standalone API client for a site
agent-browser skills get vercel-sandbox # agent-browser inside Vercel Sandbox microVMs
agent-browser skills get agentcore # AWS Bedrock AgentCore cloud browsers
```
Run `agent-browser skills list` to see everything available on the installed version.
## Why agent-browser ## Why agent-browser
@@ -39,3 +45,7 @@ agent-browser skills get <name> --full # Include references and templates
- Accessibility-tree snapshots with element refs for reliable interaction - Accessibility-tree snapshots with element refs for reliable interaction
- Sessions, authentication vault, state persistence, video recording - Sessions, authentication vault, state persistence, video recording
- Specialized skills for Electron apps, Slack, exploratory testing, cloud providers - Specialized skills for Electron apps, Slack, exploratory testing, cloud providers
## Observability Dashboard
The dashboard runs independently of browser sessions on port 4848 and can also be opened through a proxied or forwarded URL such as `https://dashboard.agent-browser.localhost`. Agents should stay on the dashboard origin: session tabs, status, and stream traffic are proxied internally, so session ports do not need to be exposed.
.agents/skills/agent-browser/references/authentication.md
-303
View File
@@ -1,303 +0,0 @@
# Authentication Patterns
Login flows, session persistence, OAuth, 2FA, and authenticated browsing.
**Related**: [session-management.md](session-management.md) for state persistence details, [SKILL.md](../SKILL.md) for quick start.
## Contents
- [Import Auth from Your Browser](#import-auth-from-your-browser)
- [Persistent Profiles](#persistent-profiles)
- [Session Persistence](#session-persistence)
- [Basic Login Flow](#basic-login-flow)
- [Saving Authentication State](#saving-authentication-state)
- [Restoring Authentication](#restoring-authentication)
- [OAuth / SSO Flows](#oauth--sso-flows)
- [Two-Factor Authentication](#two-factor-authentication)
- [HTTP Basic Auth](#http-basic-auth)
- [Cookie-Based Auth](#cookie-based-auth)
- [Token Refresh Handling](#token-refresh-handling)
- [Security Best Practices](#security-best-practices)
## Import Auth from Your Browser
The fastest way to authenticate is to reuse cookies from a Chrome session you are already logged into.
**Step 1: Start Chrome with remote debugging**
```bash
# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222
# Linux
google-chrome --remote-debugging-port=9222
# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
```
Log in to your target site(s) in this Chrome window as you normally would.
> **Security note:** `--remote-debugging-port` exposes full browser control on localhost. Any local process can connect and read cookies, execute JS, etc. Only use on trusted machines and close Chrome when done.
**Step 2: Grab the auth state**
```bash
# Auto-discover the running Chrome and save its cookies + localStorage
agent-browser --auto-connect state save ./my-auth.json
```
**Step 3: Reuse in automation**
```bash
# Load auth at launch
agent-browser --state ./my-auth.json open https://app.example.com/dashboard
# Or load into an existing session
agent-browser state load ./my-auth.json
agent-browser open https://app.example.com/dashboard
```
This works for any site, including those with complex OAuth flows, SSO, or 2FA -- as long as Chrome already has valid session cookies.
> **Security note:** State files contain session tokens in plaintext. Add them to `.gitignore`, delete when no longer needed, and set `AGENT_BROWSER_ENCRYPTION_KEY` for encryption at rest. See [Security Best Practices](#security-best-practices).
**Tip:** Combine with `--session-name` so the imported auth auto-persists across restarts:
```bash
agent-browser --session-name myapp state load ./my-auth.json
# From now on, state is auto-saved/restored for "myapp"
```
## Persistent Profiles
Use `--profile` to point agent-browser at a Chrome user data directory. This persists everything (cookies, IndexedDB, service workers, cache) across browser restarts without explicit save/load:
```bash
# First run: login once
agent-browser --profile ~/.myapp-profile open https://app.example.com/login
# ... complete login flow ...
# All subsequent runs: already authenticated
agent-browser --profile ~/.myapp-profile open https://app.example.com/dashboard
```
Use different paths for different projects or test users:
```bash
agent-browser --profile ~/.profiles/admin open https://app.example.com
agent-browser --profile ~/.profiles/viewer open https://app.example.com
```
Or set via environment variable:
```bash
export AGENT_BROWSER_PROFILE=~/.myapp-profile
agent-browser open https://app.example.com/dashboard
```
## Session Persistence
Use `--session-name` to auto-save and restore cookies + localStorage by name, without managing files:
```bash
# Auto-saves state on close, auto-restores on next launch
agent-browser --session-name twitter open https://twitter.com
# ... login flow ...
agent-browser close # state saved to ~/.agent-browser/sessions/
# Next time: state is automatically restored
agent-browser --session-name twitter open https://twitter.com
```
Encrypt state at rest:
```bash
export AGENT_BROWSER_ENCRYPTION_KEY=$(openssl rand -hex 32)
agent-browser --session-name secure open https://app.example.com
```
## Basic Login Flow
```bash
# Navigate to login page
agent-browser open https://app.example.com/login
agent-browser wait --load networkidle
# Get form elements
agent-browser snapshot -i
# Output: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Sign In"
# Fill credentials
agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"
# Submit
agent-browser click @e3
agent-browser wait --load networkidle
# Verify login succeeded
agent-browser get url # Should be dashboard, not login
```
## Saving Authentication State
After logging in, save state for reuse:
```bash
# Login first (see above)
agent-browser open https://app.example.com/login
agent-browser snapshot -i
agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait --url "**/dashboard"
# Save authenticated state
agent-browser state save ./auth-state.json
```
## Restoring Authentication
Skip login by loading saved state:
```bash
# Load saved auth state
agent-browser state load ./auth-state.json
# Navigate directly to protected page
agent-browser open https://app.example.com/dashboard
# Verify authenticated
agent-browser snapshot -i
```
## OAuth / SSO Flows
For OAuth redirects:
```bash
# Start OAuth flow
agent-browser open https://app.example.com/auth/google
# Handle redirects automatically
agent-browser wait --url "**/accounts.google.com**"
agent-browser snapshot -i
# Fill Google credentials
agent-browser fill @e1 "user@gmail.com"
agent-browser click @e2 # Next button
agent-browser wait 2000
agent-browser snapshot -i
agent-browser fill @e3 "password"
agent-browser click @e4 # Sign in
# Wait for redirect back
agent-browser wait --url "**/app.example.com**"
agent-browser state save ./oauth-state.json
```
## Two-Factor Authentication
Handle 2FA with manual intervention:
```bash
# Login with credentials
agent-browser open https://app.example.com/login --headed # Show browser
agent-browser snapshot -i
agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"
agent-browser click @e3
# Wait for user to complete 2FA manually
echo "Complete 2FA in the browser window..."
agent-browser wait --url "**/dashboard" --timeout 120000
# Save state after 2FA
agent-browser state save ./2fa-state.json
```
## HTTP Basic Auth
For sites using HTTP Basic Authentication:
```bash
# Set credentials before navigation
agent-browser set credentials username password
# Navigate to protected resource
agent-browser open https://protected.example.com/api
```
## Cookie-Based Auth
Manually set authentication cookies:
```bash
# Set auth cookie
agent-browser cookies set session_token "abc123xyz"
# Navigate to protected page
agent-browser open https://app.example.com/dashboard
```
## Token Refresh Handling
For sessions with expiring tokens:
```bash
#!/bin/bash
# Wrapper that handles token refresh
STATE_FILE="./auth-state.json"
# Try loading existing state
if [[ -f "$STATE_FILE" ]]; then
agent-browser state load "$STATE_FILE"
agent-browser open https://app.example.com/dashboard
# Check if session is still valid
URL=$(agent-browser get url)
if [[ "$URL" == *"/login"* ]]; then
echo "Session expired, re-authenticating..."
# Perform fresh login
agent-browser snapshot -i
agent-browser fill @e1 "$USERNAME"
agent-browser fill @e2 "$PASSWORD"
agent-browser click @e3
agent-browser wait --url "**/dashboard"
agent-browser state save "$STATE_FILE"
fi
else
# First-time login
agent-browser open https://app.example.com/login
# ... login flow ...
fi
```
## Security Best Practices
1. **Never commit state files** - They contain session tokens
```bash
echo "*.auth-state.json" >> .gitignore
```
2. **Use environment variables for credentials**
```bash
agent-browser fill @e1 "$APP_USERNAME"
agent-browser fill @e2 "$APP_PASSWORD"
```
3. **Clean up after automation**
```bash
agent-browser cookies clear
rm -f ./auth-state.json
```
4. **Use short-lived sessions for CI/CD**
```bash
# Don't persist state in CI
agent-browser open https://app.example.com/login
# ... login and perform actions ...
agent-browser close # Session ends, nothing persisted
```
.agents/skills/agent-browser/references/commands.md
-295
View File
@@ -1,295 +0,0 @@
# Command Reference
Complete reference for all agent-browser commands. For quick start and common patterns, see SKILL.md.
## Navigation
```bash
agent-browser open <url> # Navigate to URL (aliases: goto, navigate)
# Supports: https://, http://, file://, about:, data://
# Auto-prepends https:// if no protocol given
agent-browser back # Go back
agent-browser forward # Go forward
agent-browser reload # Reload page
agent-browser close # Close browser (aliases: quit, exit)
agent-browser connect 9222 # Connect to browser via CDP port
```
## Snapshot (page analysis)
```bash
agent-browser snapshot # Full accessibility tree
agent-browser snapshot -i # Interactive elements only (recommended)
agent-browser snapshot -c # Compact output
agent-browser snapshot -d 3 # Limit depth to 3
agent-browser snapshot -s "#main" # Scope to CSS selector
```
## Interactions (use @refs from snapshot)
```bash
agent-browser click @e1 # Click
agent-browser click @e1 --new-tab # Click and open in new tab
agent-browser dblclick @e1 # Double-click
agent-browser focus @e1 # Focus element
agent-browser fill @e2 "text" # Clear and type
agent-browser type @e2 "text" # Type without clearing
agent-browser press Enter # Press key (alias: key)
agent-browser press Control+a # Key combination
agent-browser keydown Shift # Hold key down
agent-browser keyup Shift # Release key
agent-browser hover @e1 # Hover
agent-browser check @e1 # Check checkbox
agent-browser uncheck @e1 # Uncheck checkbox
agent-browser select @e1 "value" # Select dropdown option
agent-browser select @e1 "a" "b" # Select multiple options
agent-browser scroll down 500 # Scroll page (default: down 300px)
agent-browser scrollintoview @e1 # Scroll element into view (alias: scrollinto)
agent-browser drag @e1 @e2 # Drag and drop
agent-browser upload @e1 file.pdf # Upload files
```
## Get Information
```bash
agent-browser get text @e1 # Get element text
agent-browser get html @e1 # Get innerHTML
agent-browser get value @e1 # Get input value
agent-browser get attr @e1 href # Get attribute
agent-browser get title # Get page title
agent-browser get url # Get current URL
agent-browser get cdp-url # Get CDP WebSocket URL
agent-browser get count ".item" # Count matching elements
agent-browser get box @e1 # Get bounding box
agent-browser get styles @e1 # Get computed styles (font, color, bg, etc.)
```
## Check State
```bash
agent-browser is visible @e1 # Check if visible
agent-browser is enabled @e1 # Check if enabled
agent-browser is checked @e1 # Check if checked
```
## Screenshots and PDF
```bash
agent-browser screenshot # Save to temporary directory
agent-browser screenshot path.png # Save to specific path
agent-browser screenshot --full # Full page
agent-browser pdf output.pdf # Save as PDF
```
## Video Recording
```bash
agent-browser record start ./demo.webm # Start recording
agent-browser click @e1 # Perform actions
agent-browser record stop # Stop and save video
agent-browser record restart ./take2.webm # Stop current + start new
```
## Wait
```bash
agent-browser wait @e1 # Wait for element
agent-browser wait 2000 # Wait milliseconds
agent-browser wait --text "Success" # Wait for text (or -t)
agent-browser wait --url "**/dashboard" # Wait for URL pattern (or -u)
agent-browser wait --load networkidle # Wait for network idle (or -l)
agent-browser wait --fn "window.ready" # Wait for JS condition (or -f)
```
## Mouse Control
```bash
agent-browser mouse move 100 200 # Move mouse
agent-browser mouse down left # Press button
agent-browser mouse up left # Release button
agent-browser mouse wheel 100 # Scroll wheel
```
## Semantic Locators (alternative to refs)
```bash
agent-browser find role button click --name "Submit"
agent-browser find text "Sign In" click
agent-browser find text "Sign In" click --exact # Exact match only
agent-browser find label "Email" fill "user@test.com"
agent-browser find placeholder "Search" type "query"
agent-browser find alt "Logo" click
agent-browser find title "Close" click
agent-browser find testid "submit-btn" click
agent-browser find first ".item" click
agent-browser find last ".item" click
agent-browser find nth 2 "a" hover
```
## Browser Settings
```bash
agent-browser set viewport 1920 1080 # Set viewport size
agent-browser set viewport 1920 1080 2 # 2x retina (same CSS size, higher res screenshots)
agent-browser set device "iPhone 14" # Emulate device
agent-browser set geo 37.7749 -122.4194 # Set geolocation (alias: geolocation)
agent-browser set offline on # Toggle offline mode
agent-browser set headers '{"X-Key":"v"}' # Extra HTTP headers
agent-browser set credentials user pass # HTTP basic auth (alias: auth)
agent-browser set media dark # Emulate color scheme
agent-browser set media light reduced-motion # Light mode + reduced motion
```
## Cookies and Storage
```bash
agent-browser cookies # Get all cookies
agent-browser cookies set name value # Set cookie
agent-browser cookies clear # Clear cookies
agent-browser storage local # Get all localStorage
agent-browser storage local key # Get specific key
agent-browser storage local set k v # Set value
agent-browser storage local clear # Clear all
```
## Network
```bash
agent-browser network route <url> # Intercept requests
agent-browser network route <url> --abort # Block requests
agent-browser network route <url> --body '{}' # Mock response
agent-browser network unroute [url] # Remove routes
agent-browser network requests # View tracked requests
agent-browser network requests --filter api # Filter requests
```
## Tabs and Windows
```bash
agent-browser tab # List tabs
agent-browser tab new [url] # New tab
agent-browser tab 2 # Switch to tab by index
agent-browser tab close # Close current tab
agent-browser tab close 2 # Close tab by index
agent-browser window new # New window
```
## Frames
```bash
agent-browser frame "#iframe" # Switch to iframe by CSS selector
agent-browser frame @e3 # Switch to iframe by element ref
agent-browser frame main # Back to main frame
```
### Iframe support
Iframes are detected automatically during snapshots. When the main-frame snapshot runs, `Iframe` nodes are resolved and their content is inlined beneath the iframe element in the output (one level of nesting; iframes within iframes are not expanded).
```bash
agent-browser snapshot -i
# @e3 [Iframe] "payment-frame"
# @e4 [input] "Card number"
# @e5 [button] "Pay"
# Interact directly — refs inside iframes already work
agent-browser fill @e4 "4111111111111111"
agent-browser click @e5
# Or switch frame context for scoped snapshots
agent-browser frame @e3 # Switch using element ref
agent-browser snapshot -i # Snapshot scoped to that iframe
agent-browser frame main # Return to main frame
```
The `frame` command accepts:
- **Element refs** — `frame @e3` resolves the ref to an iframe element
- **CSS selectors** — `frame "#payment-iframe"` finds the iframe by selector
- **Frame name/URL** — matches against the browser's frame tree
## Dialogs
By default, `alert` and `beforeunload` dialogs are automatically accepted so they never block the agent. `confirm` and `prompt` dialogs still require explicit handling. Use `--no-auto-dialog` to disable this behavior.
```bash
agent-browser dialog accept [text] # Accept dialog
agent-browser dialog dismiss # Dismiss dialog
agent-browser dialog status # Check if a dialog is currently open
```
## JavaScript
```bash
agent-browser eval "document.title" # Simple expressions only
agent-browser eval -b "<base64>" # Any JavaScript (base64 encoded)
agent-browser eval --stdin # Read script from stdin
```
Use `-b`/`--base64` or `--stdin` for reliable execution. Shell escaping with nested quotes and special characters is error-prone.
```bash
# Base64 encode your script, then:
agent-browser eval -b "ZG9jdW1lbnQucXVlcnlTZWxlY3RvcignW3NyYyo9Il9uZXh0Il0nKQ=="
# Or use stdin with heredoc for multiline scripts:
cat <<'EOF' | agent-browser eval --stdin
const links = document.querySelectorAll('a');
Array.from(links).map(a => a.href);
EOF
```
## State Management
```bash
agent-browser state save auth.json # Save cookies, storage, auth state
agent-browser state load auth.json # Restore saved state
```
## Global Options
```bash
agent-browser --session <name> ... # Isolated browser session
agent-browser --json ... # JSON output for parsing
agent-browser --headed ... # Show browser window (not headless)
agent-browser --full ... # Full page screenshot (-f)
agent-browser --cdp <port> ... # Connect via Chrome DevTools Protocol
agent-browser -p <provider> ... # Cloud browser provider (--provider)
agent-browser --proxy <url> ... # Use proxy server
agent-browser --proxy-bypass <hosts> # Hosts to bypass proxy
agent-browser --headers <json> ... # HTTP headers scoped to URL's origin
agent-browser --executable-path <p> # Custom browser executable
agent-browser --extension <path> ... # Load browser extension (repeatable)
agent-browser --ignore-https-errors # Ignore SSL certificate errors
agent-browser --help # Show help (-h)
agent-browser --version # Show version (-V)
agent-browser <command> --help # Show detailed help for a command
```
## Debugging
```bash
agent-browser --headed open example.com # Show browser window
agent-browser --cdp 9222 snapshot # Connect via CDP port
agent-browser connect 9222 # Alternative: connect command
agent-browser console # View console messages
agent-browser console --clear # Clear console
agent-browser errors # View page errors
agent-browser errors --clear # Clear errors
agent-browser highlight @e1 # Highlight element
agent-browser inspect # Open Chrome DevTools for this session
agent-browser trace start # Start recording trace
agent-browser trace stop trace.zip # Stop and save trace
agent-browser profiler start # Start Chrome DevTools profiling
agent-browser profiler stop trace.json # Stop and save profile
```
## Environment Variables
```bash
AGENT_BROWSER_SESSION="mysession" # Default session name
AGENT_BROWSER_EXECUTABLE_PATH="/path/chrome" # Custom browser path
AGENT_BROWSER_EXTENSIONS="/ext1,/ext2" # Comma-separated extension paths
AGENT_BROWSER_PROVIDER="browserbase" # Cloud browser provider
AGENT_BROWSER_STREAM_PORT="9223" # Override WebSocket streaming port (default: OS-assigned)
AGENT_BROWSER_HOME="/path/to/agent-browser" # Custom install location
```
.agents/skills/agent-browser/references/profiling.md
-120
View File
@@ -1,120 +0,0 @@
# Profiling
Capture Chrome DevTools performance profiles during browser automation for performance analysis.
**Related**: [commands.md](commands.md) for full command reference, [SKILL.md](../SKILL.md) for quick start.
## Contents
- [Basic Profiling](#basic-profiling)
- [Profiler Commands](#profiler-commands)
- [Categories](#categories)
- [Use Cases](#use-cases)
- [Output Format](#output-format)
- [Viewing Profiles](#viewing-profiles)
- [Limitations](#limitations)
## Basic Profiling
```bash
# Start profiling
agent-browser profiler start
# Perform actions
agent-browser navigate https://example.com
agent-browser click "#button"
agent-browser wait 1000
# Stop and save
agent-browser profiler stop ./trace.json
```
## Profiler Commands
```bash
# Start profiling with default categories
agent-browser profiler start
# Start with custom trace categories
agent-browser profiler start --categories "devtools.timeline,v8.execute,blink.user_timing"
# Stop profiling and save to file
agent-browser profiler stop ./trace.json
```
## Categories
The `--categories` flag accepts a comma-separated list of Chrome trace categories. Default categories include:
- `devtools.timeline` -- standard DevTools performance traces
- `v8.execute` -- time spent running JavaScript
- `blink` -- renderer events
- `blink.user_timing` -- `performance.mark()` / `performance.measure()` calls
- `latencyInfo` -- input-to-latency tracking
- `renderer.scheduler` -- task scheduling and execution
- `toplevel` -- broad-spectrum basic events
Several `disabled-by-default-*` categories are also included for detailed timeline, call stack, and V8 CPU profiling data.
## Use Cases
### Diagnosing Slow Page Loads
```bash
agent-browser profiler start
agent-browser navigate https://app.example.com
agent-browser wait --load networkidle
agent-browser profiler stop ./page-load-profile.json
```
### Profiling User Interactions
```bash
agent-browser navigate https://app.example.com
agent-browser profiler start
agent-browser click "#submit"
agent-browser wait 2000
agent-browser profiler stop ./interaction-profile.json
```
### CI Performance Regression Checks
```bash
#!/bin/bash
agent-browser profiler start
agent-browser navigate https://app.example.com
agent-browser wait --load networkidle
agent-browser profiler stop "./profiles/build-${BUILD_ID}.json"
```
## Output Format
The output is a JSON file in Chrome Trace Event format:
```json
{
"traceEvents": [
{ "cat": "devtools.timeline", "name": "RunTask", "ph": "X", "ts": 12345, "dur": 100, ... },
...
],
"metadata": {
"clock-domain": "LINUX_CLOCK_MONOTONIC"
}
}
```
The `metadata.clock-domain` field is set based on the host platform (Linux or macOS). On Windows it is omitted.
## Viewing Profiles
Load the output JSON file in any of these tools:
- **Chrome DevTools**: Performance panel > Load profile (Ctrl+Shift+I > Performance)
- **Perfetto UI**: https://ui.perfetto.dev/ -- drag and drop the JSON file
- **Trace Viewer**: `chrome://tracing` in any Chromium browser
## Limitations
- Only works with Chromium-based browsers (Chrome, Edge). Not supported on Firefox or WebKit.
- Trace data accumulates in memory while profiling is active (capped at 5 million events). Stop profiling promptly after the area of interest.
- Data collection on stop has a 30-second timeout. If the browser is unresponsive, the stop command may fail.
.agents/skills/agent-browser/references/proxy-support.md
-194
View File
@@ -1,194 +0,0 @@
# Proxy Support
Proxy configuration for geo-testing, rate limiting avoidance, and corporate environments.
**Related**: [commands.md](commands.md) for global options, [SKILL.md](../SKILL.md) for quick start.
## Contents
- [Basic Proxy Configuration](#basic-proxy-configuration)
- [Authenticated Proxy](#authenticated-proxy)
- [SOCKS Proxy](#socks-proxy)
- [Proxy Bypass](#proxy-bypass)
- [Common Use Cases](#common-use-cases)
- [Verifying Proxy Connection](#verifying-proxy-connection)
- [Troubleshooting](#troubleshooting)
- [Best Practices](#best-practices)
## Basic Proxy Configuration
Use the `--proxy` flag or set proxy via environment variable:
```bash
# Via CLI flag
agent-browser --proxy "http://proxy.example.com:8080" open https://example.com
# Via environment variable
export HTTP_PROXY="http://proxy.example.com:8080"
agent-browser open https://example.com
# HTTPS proxy
export HTTPS_PROXY="https://proxy.example.com:8080"
agent-browser open https://example.com
# Both
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="http://proxy.example.com:8080"
agent-browser open https://example.com
```
## Authenticated Proxy
For proxies requiring authentication:
```bash
# Include credentials in URL
export HTTP_PROXY="http://username:password@proxy.example.com:8080"
agent-browser open https://example.com
```
## SOCKS Proxy
```bash
# SOCKS5 proxy
export ALL_PROXY="socks5://proxy.example.com:1080"
agent-browser open https://example.com
# SOCKS5 with auth
export ALL_PROXY="socks5://user:pass@proxy.example.com:1080"
agent-browser open https://example.com
```
## Proxy Bypass
Skip proxy for specific domains using `--proxy-bypass` or `NO_PROXY`:
```bash
# Via CLI flag
agent-browser --proxy "http://proxy.example.com:8080" --proxy-bypass "localhost,*.internal.com" open https://example.com
# Via environment variable
export NO_PROXY="localhost,127.0.0.1,.internal.company.com"
agent-browser open https://internal.company.com # Direct connection
agent-browser open https://external.com # Via proxy
```
## Common Use Cases
### Geo-Location Testing
```bash
#!/bin/bash
# Test site from different regions using geo-located proxies
PROXIES=(
"http://us-proxy.example.com:8080"
"http://eu-proxy.example.com:8080"
"http://asia-proxy.example.com:8080"
)
for proxy in "${PROXIES[@]}"; do
export HTTP_PROXY="$proxy"
export HTTPS_PROXY="$proxy"
region=$(echo "$proxy" | grep -oP '^\w+-\w+')
echo "Testing from: $region"
agent-browser --session "$region" open https://example.com
agent-browser --session "$region" screenshot "./screenshots/$region.png"
agent-browser --session "$region" close
done
```
### Rotating Proxies for Scraping
```bash
#!/bin/bash
# Rotate through proxy list to avoid rate limiting
PROXY_LIST=(
"http://proxy1.example.com:8080"
"http://proxy2.example.com:8080"
"http://proxy3.example.com:8080"
)
URLS=(
"https://site.com/page1"
"https://site.com/page2"
"https://site.com/page3"
)
for i in "${!URLS[@]}"; do
proxy_index=$((i % ${#PROXY_LIST[@]}))
export HTTP_PROXY="${PROXY_LIST[$proxy_index]}"
export HTTPS_PROXY="${PROXY_LIST[$proxy_index]}"
agent-browser open "${URLS[$i]}"
agent-browser get text body > "output-$i.txt"
agent-browser close
sleep 1 # Polite delay
done
```
### Corporate Network Access
```bash
#!/bin/bash
# Access internal sites via corporate proxy
export HTTP_PROXY="http://corpproxy.company.com:8080"
export HTTPS_PROXY="http://corpproxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1,.company.com"
# External sites go through proxy
agent-browser open https://external-vendor.com
# Internal sites bypass proxy
agent-browser open https://intranet.company.com
```
## Verifying Proxy Connection
```bash
# Check your apparent IP
agent-browser open https://httpbin.org/ip
agent-browser get text body
# Should show proxy's IP, not your real IP
```
## Troubleshooting
### Proxy Connection Failed
```bash
# Test proxy connectivity first
curl -x http://proxy.example.com:8080 https://httpbin.org/ip
# Check if proxy requires auth
export HTTP_PROXY="http://user:pass@proxy.example.com:8080"
```
### SSL/TLS Errors Through Proxy
Some proxies perform SSL inspection. If you encounter certificate errors:
```bash
# For testing only - not recommended for production
agent-browser open https://example.com --ignore-https-errors
```
### Slow Performance
```bash
# Use proxy only when necessary
export NO_PROXY="*.cdn.com,*.static.com" # Direct CDN access
```
## Best Practices
1. **Use environment variables** - Don't hardcode proxy credentials
2. **Set NO_PROXY appropriately** - Avoid routing local traffic through proxy
3. **Test proxy before automation** - Verify connectivity with simple requests
4. **Handle proxy failures gracefully** - Implement retry logic for unstable proxies
5. **Rotate proxies for large scraping jobs** - Distribute load and avoid bans
.agents/skills/agent-browser/references/session-management.md
-193
View File
@@ -1,193 +0,0 @@
# Session Management
Multiple isolated browser sessions with state persistence and concurrent browsing.
**Related**: [authentication.md](authentication.md) for login patterns, [SKILL.md](../SKILL.md) for quick start.
## Contents
- [Named Sessions](#named-sessions)
- [Session Isolation Properties](#session-isolation-properties)
- [Session State Persistence](#session-state-persistence)
- [Common Patterns](#common-patterns)
- [Default Session](#default-session)
- [Session Cleanup](#session-cleanup)
- [Best Practices](#best-practices)
## Named Sessions
Use `--session` flag to isolate browser contexts:
```bash
# Session 1: Authentication flow
agent-browser --session auth open https://app.example.com/login
# Session 2: Public browsing (separate cookies, storage)
agent-browser --session public open https://example.com
# Commands are isolated by session
agent-browser --session auth fill @e1 "user@example.com"
agent-browser --session public get text body
```
## Session Isolation Properties
Each session has independent:
- Cookies
- LocalStorage / SessionStorage
- IndexedDB
- Cache
- Browsing history
- Open tabs
## Session State Persistence
### Save Session State
```bash
# Save cookies, storage, and auth state
agent-browser state save /path/to/auth-state.json
```
### Load Session State
```bash
# Restore saved state
agent-browser state load /path/to/auth-state.json
# Continue with authenticated session
agent-browser open https://app.example.com/dashboard
```
### State File Contents
```json
{
"cookies": [...],
"localStorage": {...},
"sessionStorage": {...},
"origins": [...]
}
```
## Common Patterns
### Authenticated Session Reuse
```bash
#!/bin/bash
# Save login state once, reuse many times
STATE_FILE="/tmp/auth-state.json"
# Check if we have saved state
if [[ -f "$STATE_FILE" ]]; then
agent-browser state load "$STATE_FILE"
agent-browser open https://app.example.com/dashboard
else
# Perform login
agent-browser open https://app.example.com/login
agent-browser snapshot -i
agent-browser fill @e1 "$USERNAME"
agent-browser fill @e2 "$PASSWORD"
agent-browser click @e3
agent-browser wait --load networkidle
# Save for future use
agent-browser state save "$STATE_FILE"
fi
```
### Concurrent Scraping
```bash
#!/bin/bash
# Scrape multiple sites concurrently
# Start all sessions
agent-browser --session site1 open https://site1.com &
agent-browser --session site2 open https://site2.com &
agent-browser --session site3 open https://site3.com &
wait
# Extract from each
agent-browser --session site1 get text body > site1.txt
agent-browser --session site2 get text body > site2.txt
agent-browser --session site3 get text body > site3.txt
# Cleanup
agent-browser --session site1 close
agent-browser --session site2 close
agent-browser --session site3 close
```
### A/B Testing Sessions
```bash
# Test different user experiences
agent-browser --session variant-a open "https://app.com?variant=a"
agent-browser --session variant-b open "https://app.com?variant=b"
# Compare
agent-browser --session variant-a screenshot /tmp/variant-a.png
agent-browser --session variant-b screenshot /tmp/variant-b.png
```
## Default Session
When `--session` is omitted, commands use the default session:
```bash
# These use the same default session
agent-browser open https://example.com
agent-browser snapshot -i
agent-browser close # Closes default session
```
## Session Cleanup
```bash
# Close specific session
agent-browser --session auth close
# List active sessions
agent-browser session list
```
## Best Practices
### 1. Name Sessions Semantically
```bash
# GOOD: Clear purpose
agent-browser --session github-auth open https://github.com
agent-browser --session docs-scrape open https://docs.example.com
# AVOID: Generic names
agent-browser --session s1 open https://github.com
```
### 2. Always Clean Up
```bash
# Close sessions when done
agent-browser --session auth close
agent-browser --session scrape close
```
### 3. Handle State Files Securely
```bash
# Don't commit state files (contain auth tokens!)
echo "*.auth-state.json" >> .gitignore
# Delete after use
rm /tmp/auth-state.json
```
### 4. Timeout Long Sessions
```bash
# Set timeout for automated scripts
timeout 60 agent-browser --session long-task get text body
```
.agents/skills/agent-browser/references/snapshot-refs.md
-219
View File
@@ -1,219 +0,0 @@
# Snapshot and Refs
Compact element references that reduce context usage dramatically for AI agents.
**Related**: [commands.md](commands.md) for full command reference, [SKILL.md](../SKILL.md) for quick start.
## Contents
- [How Refs Work](#how-refs-work)
- [Snapshot Command](#the-snapshot-command)
- [Using Refs](#using-refs)
- [Ref Lifecycle](#ref-lifecycle)
- [Best Practices](#best-practices)
- [Ref Notation Details](#ref-notation-details)
- [Troubleshooting](#troubleshooting)
## How Refs Work
Traditional approach:
```
Full DOM/HTML → AI parses → CSS selector → Action (~3000-5000 tokens)
```
agent-browser approach:
```
Compact snapshot → @refs assigned → Direct interaction (~200-400 tokens)
```
## The Snapshot Command
```bash
# Basic snapshot (shows page structure)
agent-browser snapshot
# Interactive snapshot (-i flag) - RECOMMENDED
agent-browser snapshot -i
```
### Snapshot Output Format
```
Page: Example Site - Home
URL: https://example.com
@e1 [header]
@e2 [nav]
@e3 [a] "Home"
@e4 [a] "Products"
@e5 [a] "About"
@e6 [button] "Sign In"
@e7 [main]
@e8 [h1] "Welcome"
@e9 [form]
@e10 [input type="email"] placeholder="Email"
@e11 [input type="password"] placeholder="Password"
@e12 [button type="submit"] "Log In"
@e13 [footer]
@e14 [a] "Privacy Policy"
```
## Using Refs
Once you have refs, interact directly:
```bash
# Click the "Sign In" button
agent-browser click @e6
# Fill email input
agent-browser fill @e10 "user@example.com"
# Fill password
agent-browser fill @e11 "password123"
# Submit the form
agent-browser click @e12
```
## Ref Lifecycle
**IMPORTANT**: Refs are invalidated when the page changes!
```bash
# Get initial snapshot
agent-browser snapshot -i
# @e1 [button] "Next"
# Click triggers page change
agent-browser click @e1
# MUST re-snapshot to get new refs!
agent-browser snapshot -i
# @e1 [h1] "Page 2" ← Different element now!
```
## Best Practices
### 1. Always Snapshot Before Interacting
```bash
# CORRECT
agent-browser open https://example.com
agent-browser snapshot -i # Get refs first
agent-browser click @e1 # Use ref
# WRONG
agent-browser open https://example.com
agent-browser click @e1 # Ref doesn't exist yet!
```
### 2. Re-Snapshot After Navigation
```bash
agent-browser click @e5 # Navigates to new page
agent-browser snapshot -i # Get new refs
agent-browser click @e1 # Use new refs
```
### 3. Re-Snapshot After Dynamic Changes
```bash
agent-browser click @e1 # Opens dropdown
agent-browser snapshot -i # See dropdown items
agent-browser click @e7 # Select item
```
### 4. Snapshot Specific Regions
For complex pages, snapshot specific areas:
```bash
# Snapshot just the form
agent-browser snapshot @e9
```
## Ref Notation Details
```
@e1 [tag type="value"] "text content" placeholder="hint"
│ │ │ │ │
│ │ │ │ └─ Additional attributes
│ │ │ └─ Visible text
│ │ └─ Key attributes shown
│ └─ HTML tag name
└─ Unique ref ID
```
### Common Patterns
```
@e1 [button] "Submit" # Button with text
@e2 [input type="email"] # Email input
@e3 [input type="password"] # Password input
@e4 [a href="/page"] "Link Text" # Anchor link
@e5 [select] # Dropdown
@e6 [textarea] placeholder="Message" # Text area
@e7 [div class="modal"] # Container (when relevant)
@e8 [img alt="Logo"] # Image
@e9 [checkbox] checked # Checked checkbox
@e10 [radio] selected # Selected radio
```
## Iframes
Snapshots automatically detect and inline iframe content. When the main-frame snapshot runs, each `Iframe` node is resolved and its child accessibility tree is included directly beneath it in the output. Refs assigned to elements inside iframes carry frame context, so interactions like `click`, `fill`, and `type` work without manually switching frames.
```bash
agent-browser snapshot -i
# @e1 [heading] "Checkout"
# @e2 [Iframe] "payment-frame"
# @e3 [input] "Card number"
# @e4 [input] "Expiry"
# @e5 [button] "Pay"
# @e6 [button] "Cancel"
# Interact with iframe elements directly using their refs
agent-browser fill @e3 "4111111111111111"
agent-browser fill @e4 "12/28"
agent-browser click @e5
```
**Key details:**
- Only one level of iframe nesting is expanded (iframes within iframes are not recursed)
- Cross-origin iframes that block accessibility tree access are silently skipped
- Empty iframes or iframes with no interactive content are omitted from the output
- To scope a snapshot to a single iframe, use `frame @ref` then `snapshot -i`
## Troubleshooting
### "Ref not found" Error
```bash
# Ref may have changed - re-snapshot
agent-browser snapshot -i
```
### Element Not Visible in Snapshot
```bash
# Scroll down to reveal element
agent-browser scroll down 1000
agent-browser snapshot -i
# Or wait for dynamic content
agent-browser wait 1000
agent-browser snapshot -i
```
### Too Many Elements
```bash
# Snapshot specific container
agent-browser snapshot @e5
# Or use get text for content-only extraction
agent-browser get text @e5
```
.agents/skills/agent-browser/references/video-recording.md
-173
View File
@@ -1,173 +0,0 @@
# Video Recording
Capture browser automation as video for debugging, documentation, or verification.
**Related**: [commands.md](commands.md) for full command reference, [SKILL.md](../SKILL.md) for quick start.
## Contents
- [Basic Recording](#basic-recording)
- [Recording Commands](#recording-commands)
- [Use Cases](#use-cases)
- [Best Practices](#best-practices)
- [Output Format](#output-format)
- [Limitations](#limitations)
## Basic Recording
```bash
# Start recording
agent-browser record start ./demo.webm
# Perform actions
agent-browser open https://example.com
agent-browser snapshot -i
agent-browser click @e1
agent-browser fill @e2 "test input"
# Stop and save
agent-browser record stop
```
## Recording Commands
```bash
# Start recording to file
agent-browser record start ./output.webm
# Stop current recording
agent-browser record stop
# Restart with new file (stops current + starts new)
agent-browser record restart ./take2.webm
```
## Use Cases
### Debugging Failed Automation
```bash
#!/bin/bash
# Record automation for debugging
agent-browser record start ./debug-$(date +%Y%m%d-%H%M%S).webm
# Run your automation
agent-browser open https://app.example.com
agent-browser snapshot -i
agent-browser click @e1 || {
echo "Click failed - check recording"
agent-browser record stop
exit 1
}
agent-browser record stop
```
### Documentation Generation
```bash
#!/bin/bash
# Record workflow for documentation
agent-browser record start ./docs/how-to-login.webm
agent-browser open https://app.example.com/login
agent-browser wait 1000 # Pause for visibility
agent-browser snapshot -i
agent-browser fill @e1 "demo@example.com"
agent-browser wait 500
agent-browser fill @e2 "password"
agent-browser wait 500
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser wait 1000 # Show result
agent-browser record stop
```
### CI/CD Test Evidence
```bash
#!/bin/bash
# Record E2E test runs for CI artifacts
TEST_NAME="${1:-e2e-test}"
RECORDING_DIR="./test-recordings"
mkdir -p "$RECORDING_DIR"
agent-browser record start "$RECORDING_DIR/$TEST_NAME-$(date +%s).webm"
# Run test
if run_e2e_test; then
echo "Test passed"
else
echo "Test failed - recording saved"
fi
agent-browser record stop
```
## Best Practices
### 1. Add Pauses for Clarity
```bash
# Slow down for human viewing
agent-browser click @e1
agent-browser wait 500 # Let viewer see result
```
### 2. Use Descriptive Filenames
```bash
# Include context in filename
agent-browser record start ./recordings/login-flow-2024-01-15.webm
agent-browser record start ./recordings/checkout-test-run-42.webm
```
### 3. Handle Recording in Error Cases
```bash
#!/bin/bash
set -e
cleanup() {
agent-browser record stop 2>/dev/null || true
agent-browser close 2>/dev/null || true
}
trap cleanup EXIT
agent-browser record start ./automation.webm
# ... automation steps ...
```
### 4. Combine with Screenshots
```bash
# Record video AND capture key frames
agent-browser record start ./flow.webm
agent-browser open https://example.com
agent-browser screenshot ./screenshots/step1-homepage.png
agent-browser click @e1
agent-browser screenshot ./screenshots/step2-after-click.png
agent-browser record stop
```
## Output Format
- Default format: WebM (VP8/VP9 codec)
- Compatible with all modern browsers and video players
- Compressed but high quality
## Limitations
- Recording adds slight overhead to automation
- Large recordings can consume significant disk space
- Some headless environments may have codec limitations
.agents/skills/agent-browser/templates/authenticated-session.sh
-105
View File
@@ -1,105 +0,0 @@
#!/bin/bash
# Template: Authenticated Session Workflow
# Purpose: Login once, save state, reuse for subsequent runs
# Usage: ./authenticated-session.sh <login-url> [state-file]
#
# RECOMMENDED: Use the auth vault instead of this template:
# echo "<pass>" | agent-browser auth save myapp --url <login-url> --username <user> --password-stdin
# agent-browser auth login myapp
# The auth vault stores credentials securely and the LLM never sees passwords.
#
# Environment variables:
# APP_USERNAME - Login username/email
# APP_PASSWORD - Login password
#
# Two modes:
# 1. Discovery mode (default): Shows form structure so you can identify refs
# 2. Login mode: Performs actual login after you update the refs
#
# Setup steps:
# 1. Run once to see form structure (discovery mode)
# 2. Update refs in LOGIN FLOW section below
# 3. Set APP_USERNAME and APP_PASSWORD
# 4. Delete the DISCOVERY section
set -euo pipefail
LOGIN_URL="${1:?Usage: $0 <login-url> [state-file]}"
STATE_FILE="${2:-./auth-state.json}"
echo "Authentication workflow: $LOGIN_URL"
# ================================================================
# SAVED STATE: Skip login if valid saved state exists
# ================================================================
if [[ -f "$STATE_FILE" ]]; then
echo "Loading saved state from $STATE_FILE..."
if agent-browser --state "$STATE_FILE" open "$LOGIN_URL" 2>/dev/null; then
agent-browser wait --load networkidle
CURRENT_URL=$(agent-browser get url)
if [[ "$CURRENT_URL" != *"login"* ]] && [[ "$CURRENT_URL" != *"signin"* ]]; then
echo "Session restored successfully"
agent-browser snapshot -i
exit 0
fi
echo "Session expired, performing fresh login..."
agent-browser close 2>/dev/null || true
else
echo "Failed to load state, re-authenticating..."
fi
rm -f "$STATE_FILE"
fi
# ================================================================
# DISCOVERY MODE: Shows form structure (delete after setup)
# ================================================================
echo "Opening login page..."
agent-browser open "$LOGIN_URL"
agent-browser wait --load networkidle
echo ""
echo "Login form structure:"
echo "---"
agent-browser snapshot -i
echo "---"
echo ""
echo "Next steps:"
echo " 1. Note the refs: username=@e?, password=@e?, submit=@e?"
echo " 2. Update the LOGIN FLOW section below with your refs"
echo " 3. Set: export APP_USERNAME='...' APP_PASSWORD='...'"
echo " 4. Delete this DISCOVERY MODE section"
echo ""
agent-browser close
exit 0
# ================================================================
# LOGIN FLOW: Uncomment and customize after discovery
# ================================================================
# : "${APP_USERNAME:?Set APP_USERNAME environment variable}"
# : "${APP_PASSWORD:?Set APP_PASSWORD environment variable}"
#
# agent-browser open "$LOGIN_URL"
# agent-browser wait --load networkidle
# agent-browser snapshot -i
#
# # Fill credentials (update refs to match your form)
# agent-browser fill @e1 "$APP_USERNAME"
# agent-browser fill @e2 "$APP_PASSWORD"
# agent-browser click @e3
# agent-browser wait --load networkidle
#
# # Verify login succeeded
# FINAL_URL=$(agent-browser get url)
# if [[ "$FINAL_URL" == *"login"* ]] || [[ "$FINAL_URL" == *"signin"* ]]; then
# echo "Login failed - still on login page"
# agent-browser screenshot /tmp/login-failed.png
# agent-browser close
# exit 1
# fi
#
# # Save state for future runs
# echo "Saving state to $STATE_FILE"
# agent-browser state save "$STATE_FILE"
# echo "Login successful"
# agent-browser snapshot -i
.agents/skills/agent-browser/templates/capture-workflow.sh
-69
View File
@@ -1,69 +0,0 @@
#!/bin/bash
# Template: Content Capture Workflow
# Purpose: Extract content from web pages (text, screenshots, PDF)
# Usage: ./capture-workflow.sh <url> [output-dir]
#
# Outputs:
# - page-full.png: Full page screenshot
# - page-structure.txt: Page element structure with refs
# - page-text.txt: All text content
# - page.pdf: PDF version
#
# Optional: Load auth state for protected pages
set -euo pipefail
TARGET_URL="${1:?Usage: $0 <url> [output-dir]}"
OUTPUT_DIR="${2:-.}"
echo "Capturing: $TARGET_URL"
mkdir -p "$OUTPUT_DIR"
# Optional: Load authentication state
# if [[ -f "./auth-state.json" ]]; then
# echo "Loading authentication state..."
# agent-browser state load "./auth-state.json"
# fi
# Navigate to target
agent-browser open "$TARGET_URL"
agent-browser wait --load networkidle
# Get metadata
TITLE=$(agent-browser get title)
URL=$(agent-browser get url)
echo "Title: $TITLE"
echo "URL: $URL"
# Capture full page screenshot
agent-browser screenshot --full "$OUTPUT_DIR/page-full.png"
echo "Saved: $OUTPUT_DIR/page-full.png"
# Get page structure with refs
agent-browser snapshot -i > "$OUTPUT_DIR/page-structure.txt"
echo "Saved: $OUTPUT_DIR/page-structure.txt"
# Extract all text content
agent-browser get text body > "$OUTPUT_DIR/page-text.txt"
echo "Saved: $OUTPUT_DIR/page-text.txt"
# Save as PDF
agent-browser pdf "$OUTPUT_DIR/page.pdf"
echo "Saved: $OUTPUT_DIR/page.pdf"
# Optional: Extract specific elements using refs from structure
# agent-browser get text @e5 > "$OUTPUT_DIR/main-content.txt"
# Optional: Handle infinite scroll pages
# for i in {1..5}; do
# agent-browser scroll down 1000
# agent-browser wait 1000
# done
# agent-browser screenshot --full "$OUTPUT_DIR/page-scrolled.png"
# Cleanup
agent-browser close
echo ""
echo "Capture complete:"
ls -la "$OUTPUT_DIR"
.agents/skills/agent-browser/templates/form-automation.sh
-62
View File
@@ -1,62 +0,0 @@
#!/bin/bash
# Template: Form Automation Workflow
# Purpose: Fill and submit web forms with validation
# Usage: ./form-automation.sh <form-url>
#
# This template demonstrates the snapshot-interact-verify pattern:
# 1. Navigate to form
# 2. Snapshot to get element refs
# 3. Fill fields using refs
# 4. Submit and verify result
#
# Customize: Update the refs (@e1, @e2, etc.) based on your form's snapshot output
set -euo pipefail
FORM_URL="${1:?Usage: $0 <form-url>}"
echo "Form automation: $FORM_URL"
# Step 1: Navigate to form
agent-browser open "$FORM_URL"
agent-browser wait --load networkidle
# Step 2: Snapshot to discover form elements
echo ""
echo "Form structure:"
agent-browser snapshot -i
# Step 3: Fill form fields (customize these refs based on snapshot output)
#
# Common field types:
# agent-browser fill @e1 "John Doe" # Text input
# agent-browser fill @e2 "user@example.com" # Email input
# agent-browser fill @e3 "SecureP@ss123" # Password input
# agent-browser select @e4 "Option Value" # Dropdown
# agent-browser check @e5 # Checkbox
# agent-browser click @e6 # Radio button
# agent-browser fill @e7 "Multi-line text" # Textarea
# agent-browser upload @e8 /path/to/file.pdf # File upload
#
# Uncomment and modify:
# agent-browser fill @e1 "Test User"
# agent-browser fill @e2 "test@example.com"
# agent-browser click @e3 # Submit button
# Step 4: Wait for submission
# agent-browser wait --load networkidle
# agent-browser wait --url "**/success" # Or wait for redirect
# Step 5: Verify result
echo ""
echo "Result:"
agent-browser get url
agent-browser snapshot -i
# Optional: Capture evidence
agent-browser screenshot /tmp/form-result.png
echo "Screenshot saved: /tmp/form-result.png"
# Cleanup
agent-browser close
echo "Done"
.agents/skills/eventa/SKILL.md
+38 -8
View File
@@ -146,13 +146,44 @@ controller.abort('user cancelled')
// Server-side abort awareness // Server-side abort awareness
defineInvokeHandler(ctx, event, async ({ input }, options) => { defineInvokeHandler(ctx, event, async ({ input }, options) => {
const signal = options?.abortController?.signal const signal = options?.abortController?.signal
if (signal?.aborted) if (signal?.aborted) return { output: 'aborted' }
return { output: 'aborted' }
signal?.addEventListener('abort', () => { /* cleanup */ }, { once: true }) signal?.addEventListener('abort', () => { /* cleanup */ }, { once: true })
return { output: `done: ${input}` } return { output: `done: ${input}` }
}) })
``` ```
### Multi-hop Channels
Channels form ordered routing chains. They carry events, unary invokes, every
stream frame, and invocation cancellation through intermediate contexts.
```ts
import { linkChannel, pipeChannel } from '@moeru/eventa'
pipeChannel(a, b, c) // a -> b -> c
linkChannel(a, b, c) // a <-> b <-> c
```
There is no direct `a` to `c` edge. Use multiple explicit pipes for fan-out.
Disposing a channel removes its edges only; context abort never cascades across
a link. One connected graph must have one effective handler for each invoke
definition.
Each local emit creates an `EventaInner` whose `deliveryId` survives channel
hops and transport serialization. Contexts suppress recently seen delivery IDs
and stop forwarding when `hopsRemaining` reaches zero. Plugins may inspect the
read-only inner value and transform or drop its Eventa, but may not replace routing
identity or hop state.
For iframe-to-server routing, connect the EventTarget-side context to the
plugin's BroadcastChannel context, then connect the gateway's BroadcastChannel
context to its WebSocket context. The adapters carry the inner value across the
runtime boundaries; no directional forwarding markers are needed.
Contexts do not serialize concurrent `emit()` calls. Request and response
stream pumps await each frame only to preserve per-invocation stream order;
cancellation is routed independently and may arrive before request frames.
### Bulk Registration (Shorthands) ### Bulk Registration (Shorthands)
```ts ```ts
@@ -175,7 +206,6 @@ Each adapter wraps a specific transport into an eventa context. The pattern is a
```ts ```ts
import { createContext } from '@moeru/eventa/adapters/<adapter-name>' import { createContext } from '@moeru/eventa/adapters/<adapter-name>'
const { context } = createContext(transportInstance) const { context } = createContext(transportInstance)
``` ```
@@ -200,15 +230,15 @@ const { context } = createContext(transportInstance)
```ts ```ts
// shared/events.ts — define events once // shared/events.ts — define events once
import { defineInvokeEventa } from '@moeru/eventa' import { defineInvokeEventa } from '@moeru/eventa'
export const readdir = defineInvokeEventa<{ dirs: string[] }, { path: string }>('fs:readdir')
// main.ts — register handler // main.ts — register handler
import { createContext } from '@moeru/eventa/adapters/electron/main' import { createContext } from '@moeru/eventa/adapters/electron/main'
// renderer.ts (preload) — call it
import { createContext } from '@moeru/eventa/adapters/electron/renderer'
export const readdir = defineInvokeEventa<{ dirs: string[] }, { path: string }>('fs:readdir')
const { context } = createContext(ipcMain, mainWindow.webContents) const { context } = createContext(ipcMain, mainWindow.webContents)
defineInvokeHandler(context, readdir, async ({ path }) => ({ dirs: await fs.readdir(path) })) defineInvokeHandler(context, readdir, async ({ path }) => ({ dirs: await fs.readdir(path) }))
// renderer.ts (preload) — call it
import { createContext } from '@moeru/eventa/adapters/electron/renderer'
const { context } = createContext(ipcRenderer) const { context } = createContext(ipcRenderer)
const invokeReaddir = defineInvoke(context, readdir) const invokeReaddir = defineInvoke(context, readdir)
const result = await invokeReaddir({ path: '/usr' }) const result = await invokeReaddir({ path: '/usr' })
@@ -216,7 +246,7 @@ const result = await invokeReaddir({ path: '/usr' })
## Advanced Features ## Advanced Features
- **Directional events**: `defineInboundEventa<T>()` and `defineOutboundEventa<T>()` for flow control - **Delivery routing**: `EventaInner<T>` preserves delivery identity and hop budget across channels and adapters
- **Match expressions**: `matchBy(glob)`, `matchBy(regex)`, `and(...)`, `or(...)` for event filtering - **Match expressions**: `matchBy(glob)`, `matchBy(regex)`, `and(...)`, `or(...)` for event filtering
- **WebSocket lifecycle**: `wsConnectedEvent` and `wsDisconnectedEvent` from the native adapter - **WebSocket lifecycle**: `wsConnectedEvent` and `wsDisconnectedEvent` from the native adapter
.agents/skills/pnpm/GENERATION.md
+2 -2
View File
@@ -1,5 +1,5 @@
# Generation Info # Generation Info
- **Source:** `sources/pnpm` - **Source:** `sources/pnpm`
- **Git SHA:** `a1d6d5aef9d5f369fa2f0d8a54f1edbaff8b23b3` - **Git SHA:** `5cd19942ee75cda8ed299233c486a67d95bb38ec`
- **Generated:** 2026-01-28 - **Generated:** 2026-06-22
.agents/skills/pnpm/SKILL.md
+21 -18
View File
@@ -1,42 +1,45 @@
--- ---
name: pnpm name: pnpm
description: Node.js package manager with strict dependency resolution. Use when running pnpm specific commands, configuring workspaces, or managing dependencies with catalogs, patches, or overrides. description: Node.js package manager with strict dependency resolution. Use when running pnpm specific commands, configuring workspaces via pnpm-workspace.yaml, or managing dependencies with catalogs, patches, overrides, config dependencies, or the global virtual store.
metadata: metadata:
author: Anthony Fu author: Anthony Fu
version: "2026.1.28" version: "2026.6.22"
source: Generated from https://github.com/pnpm/pnpm, scripts located at https://github.com/antfu/skills source: Generated from https://github.com/pnpm/pnpm, scripts located at https://github.com/antfu/skills
--- ---
pnpm is a fast, disk space efficient package manager. It uses a content-addressable store to deduplicate packages across all projects on a machine, saving significant disk space. pnpm enforces strict dependency resolution by default, preventing phantom dependencies. Configuration should preferably be placed in `pnpm-workspace.yaml` for pnpm-specific settings. pnpm is a fast, disk space efficient package manager. It uses a content-addressable store to deduplicate packages across all projects on a machine, and enforces strict dependency resolution by default, preventing phantom dependencies.
**Important:** When working with pnpm projects, agents should check for `pnpm-workspace.yaml` and `.npmrc` files to understand workspace structure and configuration. Always use `--frozen-lockfile` in CI environments. **Configuration model (important):** pnpm settings now live in `pnpm-workspace.yaml` (and the global `config.yaml`) using **camelCase** keys. `.npmrc` is used **only** for authentication/registry credentials, and the `pnpm` field of `package.json` is no longer read. When working in a pnpm project, check `pnpm-workspace.yaml` for settings/workspace structure and `.npmrc` only for auth. Always use `--frozen-lockfile` (or `pnpm ci`) in CI.
> The skill is based on pnpm 10.x, generated at 2026-01-28. > The skill is based on pnpm 10.x, generated at 2026-06-22. It also covers v11 behavior changes (config split, isolated global packages, `allowBuilds`, `pmOnFail`, global virtual store) where current docs describe them.
## Core ## Core
| Topic | Description | Reference | | Topic | Description | Reference |
|-------|-------------|-----------| |-------|-------------|-----------|
| CLI Commands | Install, add, remove, update, run, exec, dlx, and workspace commands | [core-cli](references/core-cli.md) | | CLI Commands | install/add/remove/update, run, dlx/pnx, workspace, runtime, publishing (version, view, sbom, stage) | [core-cli](references/core-cli.md) |
| Configuration | pnpm-workspace.yaml, .npmrc settings, and package.json fields | [core-config](references/core-config.md) | | Configuration | pnpm-workspace.yaml settings (camelCase), global config.yaml, packageConfigs, .npmrc auth | [core-config](references/core-config.md) |
| Workspaces | Monorepo support with filtering, workspace protocol, and shared lockfile | [core-workspaces](references/core-workspaces.md) | | Workspaces | Monorepo support: filtering, workspace protocol, shared lockfile, packageConfigs | [core-workspaces](references/core-workspaces.md) |
| Store | Content-addressable storage, hard links, and disk efficiency | [core-store](references/core-store.md) | | Store | Content-addressable store, virtual store, node linker modes, frozen/read-only store | [core-store](references/core-store.md) |
## Features ## Features
| Topic | Description | Reference | | Topic | Description | Reference |
|-------|-------------|-----------| |-------|-------------|-----------|
| Catalogs | Centralized dependency version management for workspaces | [features-catalogs](references/features-catalogs.md) | | Catalogs | Centralized dependency versions; catalogMode, catalog: in overrides | [features-catalogs](references/features-catalogs.md) |
| Overrides | Force specific versions of dependencies including transitive | [features-overrides](references/features-overrides.md) | | Overrides | Force versions (incl. transitive & peer deps); packageExtensions | [features-overrides](references/features-overrides.md) |
| Patches | Modify third-party packages with custom fixes | [features-patches](references/features-patches.md) | | Patches | Modify third-party packages; patchedDependencies in pnpm-workspace.yaml | [features-patches](references/features-patches.md) |
| Aliases | Install packages under custom names using npm: protocol | [features-aliases](references/features-aliases.md) | | Aliases | Install under custom names (npm:) and registry aliases (namedRegistries) | [features-aliases](references/features-aliases.md) |
| Hooks | Customize resolution with .pnpmfile.cjs hooks | [features-hooks](references/features-hooks.md) | | Hooks | .pnpmfile.mjs hooks (readPackage, updateConfig, beforePacking), finders, resolvers/fetchers | [features-hooks](references/features-hooks.md) |
| Peer Dependencies | Auto-install, strict mode, and dependency rules | [features-peer-deps](references/features-peer-deps.md) | | Peer Dependencies | Auto-install, strict mode, rules, dedupePeers, peers check | [features-peer-deps](references/features-peer-deps.md) |
| Config Dependencies | Share hooks/settings/catalogs/patches across repos via configDependencies | [features-config-dependencies](references/features-config-dependencies.md) |
| Global Virtual Store | Shared node_modules, git-worktree multi-agent setups, isolated global packages | [features-global-virtual-store](references/features-global-virtual-store.md) |
| Supply-Chain Security | Build approval (allowBuilds), minimumReleaseAge, trustPolicy, lockfile integrity | [features-supply-chain-security](references/features-supply-chain-security.md) |
## Best Practices ## Best Practices
| Topic | Description | Reference | | Topic | Description | Reference |
|-------|-------------|-----------| |-------|-------------|-----------|
| CI/CD Setup | GitHub Actions, GitLab CI, Docker, and caching strategies | [best-practices-ci](references/best-practices-ci.md) | | CI/CD Setup | GitHub Actions, GitLab, Docker, pnpm ci, store caching, frozen lockfiles | [best-practices-ci](references/best-practices-ci.md) |
| Migration | Migrating from npm/Yarn, handling phantom deps, monorepo migration | [best-practices-migration](references/best-practices-migration.md) | | Migration | npm/Yarn → pnpm, phantom deps, and pnpm v10 → v11 config migration | [best-practices-migration](references/best-practices-migration.md) |
| Performance | Install optimizations, store caching, workspace parallelization | [best-practices-performance](references/best-practices-performance.md) | | Performance | Install optimizations, allowBuilds, global virtual store, workspace parallelization | [best-practices-performance](references/best-practices-performance.md) |
.agents/skills/pnpm/references/best-practices-ci.md
+25 -12
View File
@@ -7,6 +7,8 @@ description: Optimizing pnpm for continuous integration and deployment workflows
Best practices for using pnpm in CI/CD environments for fast, reliable builds. Best practices for using pnpm in CI/CD environments for fast, reliable builds.
> **CI auto-behaviors:** When pnpm detects a CI environment it switches to **frozen-lockfile** mode automatically and (since v11) **fails on an incompatible lockfile** written by a newer pnpm major instead of rewriting it — keep the CI pnpm version in sync with the one that generated the lockfile. The global virtual store is auto-disabled in CI (no warm cache).
## GitHub Actions ## GitHub Actions
### Basic Setup ### Basic Setup
@@ -24,18 +26,20 @@ jobs:
- uses: pnpm/action-setup@v4 - uses: pnpm/action-setup@v4
with: with:
version: 9 version: 10
- uses: actions/setup-node@v4 - uses: actions/setup-node@v4
with: with:
node-version: 20 node-version: 22
cache: 'pnpm' cache: 'pnpm'
- run: pnpm install --frozen-lockfile - run: pnpm install --frozen-lockfile # or: pnpm ci
- run: pnpm test - run: pnpm test
- run: pnpm build - run: pnpm build
``` ```
> `pnpm ci` (aliases `clean-install`, `install-clean`) = `pnpm clean` + `pnpm install --frozen-lockfile`, ideal for fully reproducible CI builds.
### With Store Caching ### With Store Caching
For larger projects, cache the pnpm store: For larger projects, cache the pnpm store:
@@ -43,7 +47,7 @@ For larger projects, cache the pnpm store:
```yaml ```yaml
- uses: pnpm/action-setup@v4 - uses: pnpm/action-setup@v4
with: with:
version: 9 version: 10
- name: Get pnpm store directory - name: Get pnpm store directory
shell: bash shell: bash
@@ -61,6 +65,8 @@ For larger projects, cache the pnpm store:
- run: pnpm install --frozen-lockfile - run: pnpm install --frozen-lockfile
``` ```
> **Trust:** only cache/restore the pnpm store and cache dir between *trusted* jobs. A store an untrusted job can write to must not be reused by trusted jobs — it is part of pnpm's trust domain.
### Matrix Testing ### Matrix Testing
```yaml ```yaml
@@ -124,11 +130,13 @@ build:
## Docker ## Docker
> **PATH change (v11):** global pnpm binaries now live in `$PNPM_HOME/bin`. In Docker set `ENV PATH="$PNPM_HOME/bin:$PATH"` (not `$PNPM_HOME`). There is also an official image `ghcr.io/pnpm/pnpm:<version>` (Debian slim, pnpm only — choose Node yourself via `pnpm runtime set node <ver> -g` or `devEngines.runtime`).
### Multi-Stage Build ### Multi-Stage Build
```dockerfile ```dockerfile
# Build stage # Build stage
FROM node:20-slim AS builder FROM node:24-slim AS builder
# Enable corepack for pnpm # Enable corepack for pnpm
RUN corepack enable RUN corepack enable
@@ -214,12 +222,12 @@ pnpm install --frozen-lockfile --ignore-scripts
## Corepack Integration ## Corepack Integration
Use Corepack to manage pnpm version: Use Corepack to pin the pnpm version:
```json ```json
// package.json // package.json
{ {
"packageManager": "pnpm@9.0.0" "packageManager": "pnpm@10.0.0"
} }
``` ```
@@ -229,6 +237,8 @@ Use Corepack to manage pnpm version:
- run: pnpm install --frozen-lockfile - run: pnpm install --frozen-lockfile
``` ```
For range-based pinning use `devEngines.packageManager` (resolved version stored in the lockfile). To skip the pin check when version management is external (asdf/mise/Volta), set `pmOnFail: ignore` in `pnpm-workspace.yaml`, or run a one-off with `pnpm with current <cmd>`.
## Monorepo CI Strategies ## Monorepo CI Strategies
### Build Changed Packages Only ### Build Changed Packages Only
@@ -271,15 +281,18 @@ jobs:
## Best Practices Summary ## Best Practices Summary
1. **Always use `--frozen-lockfile`** in CI 1. **Use `pnpm ci` or `--frozen-lockfile`** in CI
2. **Cache the pnpm store** for faster installs 2. **Cache the pnpm store** (only across trusted jobs)
3. **Use Corepack** for consistent pnpm versions 3. **Match the CI pnpm major** to the one that wrote the lockfile (CI fails on incompatible lockfiles)
4. **Specify `packageManager`** in package.json 4. **Pin `packageManager`** (or `devEngines.packageManager`) in package.json
5. **Use `--filter`** in monorepos to build only what changed 5. **Use `--filter`** in monorepos to build only what changed
6. **Multi-stage Docker builds** for smaller images 6. **Multi-stage Docker builds**; set `PATH=$PNPM_HOME/bin:$PATH`
<!-- <!--
Source references: Source references:
- https://pnpm.io/continuous-integration - https://pnpm.io/continuous-integration
- https://pnpm.io/docker
- https://pnpm.io/cli/ci
- https://github.com/pnpm/action-setup - https://github.com/pnpm/action-setup
--> -->
.agents/skills/pnpm/references/best-practices-migration.md
+62 -39
View File
@@ -5,7 +5,36 @@ description: Migrating from npm or Yarn to pnpm with minimal friction
# Migration to pnpm # Migration to pnpm
Guide for migrating existing projects from npm or Yarn to pnpm. Guide for migrating existing projects from npm or Yarn to pnpm, plus upgrading pnpm v10 → v11.
## Upgrading pnpm v10 → v11
v11 changes how configuration is read. Most of it is mechanical — run the codemod:
```bash
cd /path/to/project
pnpx codemod run pnpm-v10-to-v11
```
The codemod automatically:
- **Moves `package.json#pnpm` settings into `pnpm-workspace.yaml`** (the `pnpm` field is no longer read).
- **Splits `.npmrc`**: only auth/registry settings stay in `.npmrc`; every other key moves to `pnpm-workspace.yaml` as **camelCase** (e.g. `node-linker` → `nodeLinker`). Per-subproject `.npmrc` files become `packageConfigs["<name>"]`.
- **Consolidates build settings** (`onlyBuiltDependencies`, `neverBuiltDependencies`, `ignoredBuiltDependencies`, `onlyBuiltDependenciesFile`) into one `allowBuilds: { name: true|false }` map.
- **Replaces** `managePackageManagerVersions`/`packageManagerStrict`/`packageManagerStrictVersion` with `pmOnFail: download|ignore|warn|error`.
- **Renames** `allowNonAppliedPatches` → `allowUnusedPatches`, `auditConfig.ignoreCves` → `auditConfig.ignoreGhsas`.
- **Converts** `useNodeVersion` → `devEngines.runtime`, and bumps `packageManager`.
Manual follow-ups (not automatable):
- Convert `CVE-…` IDs to `GHSA-…` in `auditConfig.ignoreGhsas`.
- `ignorePatchFailures` removed — failed patches now always throw.
- `npm_config_*` env vars → `pnpm_config_*` (CI, shell profiles, Docker).
- `pnpm link <name>` → use a path (`pnpm link ./foo`); `pnpm link --global` → `pnpm add -g .`.
- `pnpm install -g` (no args) and `pnpm server` removed.
- A `package.json` script named `clean`/`setup`/`deploy`/`rebuild` now shadows the built-in — use `pnpm pm <name>` for the built-in.
## Migrating from npm / Yarn
## Quick Migration ## Quick Migration
@@ -64,10 +93,9 @@ pnpm add lodash
pnpm reports peer dependency issues by default. pnpm reports peer dependency issues by default.
**Option 1:** Let pnpm auto-install: **Option 1:** Let pnpm auto-install (default in v8+):
```ini ```yaml title="pnpm-workspace.yaml"
# .npmrc (default in pnpm v8+) autoInstallPeers: true
auto-install-peers=true
``` ```
**Option 2:** Install manually: **Option 2:** Install manually:
@@ -76,30 +104,26 @@ pnpm add react react-dom
``` ```
**Option 3:** Suppress warnings if acceptable: **Option 3:** Suppress warnings if acceptable:
```json ```yaml title="pnpm-workspace.yaml"
{ peerDependencyRules:
"pnpm": { ignoreMissing:
"peerDependencyRules": { - react
"ignoreMissing": ["react"]
}
}
}
``` ```
### Symlink Issues ### Symlink Issues
Some tools don't work with symlinks. Use hoisted mode: Some tools don't work with symlinks. Use hoisted mode:
```ini ```yaml title="pnpm-workspace.yaml"
# .npmrc nodeLinker: hoisted
node-linker=hoisted
``` ```
Or hoist specific packages: Or hoist specific packages:
```ini ```yaml title="pnpm-workspace.yaml"
public-hoist-pattern[]=*eslint* publicHoistPattern:
public-hoist-pattern[]=*babel* - '*eslint*'
- '*babel*'
``` ```
### Native Module Rebuilds ### Native Module Rebuilds
@@ -165,7 +189,7 @@ pnpm install
```json ```json
// From Yarn // From Yarn
"@myorg/utils": "*" "@myorg/utils": "*"
// To pnpm // To pnpm
"@myorg/utils": "workspace:*" "@myorg/utils": "workspace:*"
``` ```
@@ -184,7 +208,7 @@ pnpm -r run build
# Lerna: run in specific package # Lerna: run in specific package
lerna run build --scope=@myorg/app lerna run build --scope=@myorg/app
# pnpm equivalent # pnpm equivalent
pnpm --filter @myorg/app run build pnpm --filter @myorg/app run build
# Lerna: publish # Lerna: publish
@@ -199,21 +223,19 @@ pnpm publish -r
## Configuration Migration ## Configuration Migration
### .npmrc Settings Keep only **auth/registry** in `.npmrc`; put everything else in `pnpm-workspace.yaml` (camelCase).
Most npm/Yarn settings work in pnpm's `.npmrc`: ```ini title=".npmrc (auth only, gitignored)"
```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} //registry.npmjs.org/:_authToken=${NPM_TOKEN}
//npm.myorg.com/:_authToken=${MYORG_TOKEN}
```
# pnpm-specific additions ```yaml title="pnpm-workspace.yaml"
auto-install-peers=true registries:
strict-peer-dependencies=false default: https://registry.npmjs.org/
'@myorg': https://npm.myorg.com/
autoInstallPeers: true
strictPeerDependencies: false
``` ```
### Scripts Migration ### Scripts Migration
@@ -227,8 +249,8 @@ Most scripts work unchanged. Update pnpm-specific patterns:
"build:all": "npm run build --workspaces", "build:all": "npm run build --workspaces",
// pnpm: use -r flag // pnpm: use -r flag
"build:all": "pnpm -r run build", "build:all": "pnpm -r run build",
// npm: run in specific workspace // npm: run in specific workspace
"dev:app": "npm run dev -w packages/app", "dev:app": "npm run dev -w packages/app",
// pnpm: use --filter // pnpm: use --filter
"dev:app": "pnpm --filter @myorg/app run dev" "dev:app": "pnpm --filter @myorg/app run dev"
@@ -246,13 +268,13 @@ Update CI configuration:
# After (pnpm) # After (pnpm)
- uses: pnpm/action-setup@v4 - uses: pnpm/action-setup@v4
- run: pnpm install --frozen-lockfile - run: pnpm install --frozen-lockfile # or: pnpm ci
``` ```
Add to `package.json` for Corepack: Add to `package.json` for Corepack:
```json ```json
{ {
"packageManager": "pnpm@9.0.0" "packageManager": "pnpm@10.0.0"
} }
``` ```
@@ -285,7 +307,8 @@ Keep old lockfile in git history for easy rollback.
<!-- <!--
Source references: Source references:
- https://pnpm.io/installation - https://pnpm.io/migration
- https://pnpm.io/cli/import - https://pnpm.io/cli/import
- https://pnpm.io/limitations - https://pnpm.io/configuring
--> -->
.agents/skills/pnpm/references/best-practices-performance.md
+58 -81
View File
@@ -27,12 +27,6 @@ Use cached packages when available:
pnpm install --prefer-offline pnpm install --prefer-offline
``` ```
Or configure globally:
```ini
# .npmrc
prefer-offline=true
```
### Skip Optional Dependencies ### Skip Optional Dependencies
If you don't need optional deps: If you don't need optional deps:
@@ -53,51 +47,46 @@ pnpm install --ignore-scripts
### Only Build Specific Dependencies ### Only Build Specific Dependencies
Only run build scripts for specific packages: Build-script approval is a single `allowBuilds` map (replaces `onlyBuiltDependencies`/`neverBuiltDependencies`). Only allowed packages run install scripts:
```ini ```yaml title="pnpm-workspace.yaml"
# .npmrc allowBuilds:
onlyBuiltDependencies[]=esbuild esbuild: true
onlyBuiltDependencies[]=sharp '@swc/core': true
onlyBuiltDependencies[]=@swc/core core-js: false # explicitly skip
``` ```
Or skip builds entirely for deps that don't need them: Packages not listed are treated as unreviewed (blocked by default). See `features-supply-chain-security` for the full build-approval workflow.
```json
{
"pnpm": {
"neverBuiltDependencies": ["fsevents", "cpu-features"]
}
}
```
## Store Optimizations ## Store Optimizations
### Side Effects Cache ### Side Effects Cache
Cache native module build results: Cache native module build results (enabled by default):
```ini ```yaml title="pnpm-workspace.yaml"
# .npmrc sideEffectsCache: true
side-effects-cache=true
``` ```
This caches the results of postinstall scripts, speeding up subsequent installs. This caches the results of postinstall scripts, speeding up subsequent installs.
### Shared Store ### Global Virtual Store
Use a single store for all projects (default behavior): For many checkouts of the same repo (e.g. git worktrees / multiple agents), enable the global virtual store so each project's `node_modules` is just symlinks into one shared store — near-zero per-checkout cost. Auto-disabled in CI.
```ini ```yaml title="pnpm-workspace.yaml"
# .npmrc enableGlobalVirtualStore: true
store-dir=~/.pnpm-store
``` ```
Benefits: ### Shared Store
- Packages downloaded once for all projects
- Hard links save disk space A single content-addressable store is used for all projects by default:
- Faster installs from cache
```yaml title="pnpm-workspace.yaml"
storeDir: ~/.local/share/pnpm/store
```
Benefits: packages downloaded once, hard links save disk space, faster cached installs.
### Store Maintenance ### Store Maintenance
@@ -122,9 +111,8 @@ pnpm -r --parallel run build
``` ```
Control concurrency: Control concurrency:
```ini ```yaml title="pnpm-workspace.yaml"
# .npmrc workspaceConcurrency: 8
workspace-concurrency=8
``` ```
### Stream Output ### Stream Output
@@ -160,33 +148,17 @@ pnpm -r --workspace-concurrency=1 run build
## Network Optimizations ## Network Optimizations
### Configure Registry Network/registry settings are camelCase in `pnpm-workspace.yaml` (registry URLs may also go in `registries`):
Use closest/fastest registry: ```yaml title="pnpm-workspace.yaml"
registries:
```ini default: https://registry.npmmirror.com/
# .npmrc fetchRetries: 3
registry=https://registry.npmmirror.com/ fetchRetryMintimeout: 10000
``` fetchRetryMaxtimeout: 60000
networkConcurrency: 16 # auto: clamp(workers x 3, 16, 64)
### HTTP Settings httpProxy: http://proxy.company.com:8080
httpsProxy: http://proxy.company.com:8080
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 ## Lockfile Optimization
@@ -195,9 +167,8 @@ https-proxy=http://proxy.company.com:8080
Use shared lockfile for all packages (default): Use shared lockfile for all packages (default):
```ini ```yaml title="pnpm-workspace.yaml"
# .npmrc sharedWorkspaceLockfile: true
shared-workspace-lockfile=true
``` ```
Benefits: Benefits:
@@ -244,41 +215,47 @@ DEBUG=pnpm:* pnpm install
## Configuration Summary ## Configuration Summary
Optimized `.npmrc` for performance: Optimized `pnpm-workspace.yaml` for performance:
```ini ```yaml title="pnpm-workspace.yaml"
# Install behavior # Install behavior
prefer-offline=true autoInstallPeers: true
auto-install-peers=true sideEffectsCache: true
optimisticRepeatInstall: true
# Build optimization # Build approval (only what's necessary)
side-effects-cache=true allowBuilds:
# Only build what's necessary esbuild: true
onlyBuiltDependencies[]=esbuild '@swc/core': true
onlyBuiltDependencies[]=@swc/core
# Network # Network
fetch-retries=3 fetchRetries: 3
network-concurrency=16 networkConcurrency: 16
# Workspace # Workspace
workspace-concurrency=4 workspaceConcurrency: 4
# Many checkouts of the same repo
enableGlobalVirtualStore: true
``` ```
## Quick Reference ## Quick Reference
| Scenario | Command/Setting | | Scenario | Command/Setting |
|----------|-----------------| |----------|-----------------|
| CI installs | `pnpm install --frozen-lockfile` | | CI installs | `pnpm ci` / `pnpm install --frozen-lockfile` |
| Offline development | `--prefer-offline` | | Offline development | `--prefer-offline` |
| Skip native builds | `neverBuiltDependencies` | | Control native builds | `allowBuilds` map |
| Parallel workspace | `pnpm -r --parallel run build` | | Parallel workspace | `pnpm -r --parallel run build` |
| Build changed only | `pnpm --filter "...[origin/main]" build` | | Build changed only | `pnpm --filter "...[origin/main]" build` |
| Clean store | `pnpm store prune` | | Clean store | `pnpm store prune` |
| Many worktrees/agents | `enableGlobalVirtualStore: true` |
<!-- <!--
Source references: Source references:
- https://pnpm.io/npmrc - https://pnpm.io/settings
- https://pnpm.io/cli/install - https://pnpm.io/cli/install
- https://pnpm.io/filtering - https://pnpm.io/filtering
- https://pnpm.io/global-virtual-store
--> -->
.agents/skills/pnpm/references/core-cli.md
+117 -150
View File
@@ -1,229 +1,196 @@
--- ---
name: pnpm-cli-commands name: pnpm-cli-commands
description: Essential pnpm commands for package management, running scripts, and workspace operations description: Essential pnpm commands for package management, running scripts, workspaces, publishing, and runtimes
--- ---
# pnpm CLI Commands # pnpm CLI Commands
pnpm provides a comprehensive CLI for package management with commands similar to npm/yarn but with unique features. pnpm provides a comprehensive CLI. Commands resemble npm/yarn but with unique features.
## Installation Commands ## Installation Commands
### Install all dependencies
```bash ```bash
pnpm install pnpm install # install all deps (alias: pnpm i)
# or pnpm add <pkg> # production dependency
pnpm i pnpm add -D <pkg> # devDependency (also -d)
``` pnpm add -O <pkg> # optionalDependency (also -o)
pnpm add -E <pkg> # exact version (also -e)
### 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>@<version>
pnpm add <pkg>@next pnpm remove <pkg> # aliases: rm, uninstall, un
pnpm add <pkg>@^1.0.0 pnpm update # alias: up
pnpm update --latest # ignore semver ranges (-L)
pnpm update -i # interactive
``` ```
### Remove a dependency ### Clean / reproducible installs
```bash ```bash
pnpm remove <pkg> pnpm install --frozen-lockfile # fail if lockfile would change (auto in CI)
pnpm rm <pkg> pnpm ci # clean install = pnpm clean + install --frozen-lockfile
pnpm uninstall <pkg> pnpm clean # remove node_modules in all workspace projects (alias: purge)
pnpm un <pkg> pnpm clean --lockfile # also delete pnpm-lock.yaml
``` ```
### Update dependencies > Since v11, an integrity mismatch against the lockfile is a hard error (`ERR_PNPM_TARBALL_INTEGRITY`). Use `pnpm install --update-checksums` only after verifying the new bytes. In CI, pnpm also fails on lockfiles written by a newer pnpm major.
```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 ## Script Commands
### Run scripts
```bash ```bash
pnpm run <script> pnpm run <script> # or just: pnpm <script>
# or shorthand
pnpm <script>
# Pass arguments to script
pnpm run build -- --watch pnpm run build -- --watch
# Run script if exists (no error if missing)
pnpm run --if-present build pnpm run --if-present build
pnpm set-script test "vitest run" # add/update a scripts entry (alias: ss)
pnpm exec <cmd> # run a local binary, e.g. pnpm exec eslint .
``` ```
### Execute binaries - **Hidden scripts:** names starting with `.` (e.g. `.helper`) can't be run directly, only called from other scripts.
- **Built-in vs script conflict:** `clean`, `setup`, `deploy`, `rebuild` prefer a same-named `package.json` script. Force the built-in with `pnpm pm <name>` (e.g. `pnpm pm clean`).
### dlx / pnx — run without installing
```bash ```bash
# Run local binary pnx create-vite my-app # pnx == pnpm dlx == pnpx
pnpm exec <command> pnpm dlx degit user/repo dest
pnx shx@catalog: # catalog: protocol supported
# Example pnx --package=@scope/tool tool --help
pnpm exec eslint .
``` ```
### dlx - Run without installing > `dlx`/`pnx` honor supply-chain settings (`minimumReleaseAge`, `trustPolicy`) and use the global virtual store by default in v11.
```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 ## Workspace Commands
### Run in all packages
```bash ```bash
# Run script in all workspace packages pnpm -r run <script> # run in all packages (alias: --recursive)
pnpm -r run <script>
pnpm --recursive run <script>
# Run in specific packages
pnpm --filter <pattern> run <script> pnpm --filter <pattern> run <script>
# Examples
pnpm --filter "./packages/**" run build pnpm --filter "./packages/**" run build
pnpm --filter "!./packages/internal/**" run test
pnpm --filter "@myorg/*" run lint pnpm --filter "@myorg/*" run lint
pnpm -r --parallel run dev
``` ```
### Filter patterns ### Filter patterns
```bash
# By package name
pnpm --filter <pkg-name> <command>
pnpm --filter "@scope/pkg" build
# By directory ```bash
pnpm --filter <pkg-name> <cmd> # by name (-F shorthand)
pnpm --filter "./packages/core" test pnpm --filter "./packages/core" test
pnpm --filter "...@scope/app" build # package + its dependencies
# Dependencies of a package pnpm --filter "@scope/core..." test # package + its dependents
pnpm --filter "...@scope/app" build pnpm --filter "...[origin/main]" build # changed since git ref
# Dependents of a package
pnpm --filter "@scope/core..." test
# Changed packages since commit/branch
pnpm --filter "...[origin/main]" build
``` ```
## Other Useful Commands ## Patches
### Link packages
```bash ```bash
# Link global package pnpm patch <pkg>@<version> # opens an editable copy, prints a path
pnpm link --global pnpm patch-commit <path> # writes patches/*.patch and records it
pnpm link -g pnpm patch-remove <pkg>@<version>
# Use linked package
pnpm link --global <pkg>
``` ```
### Patch packages ## Linking local packages
```bash ```bash
# Create patch for a package pnpm link <dir> # link a path into this project's node_modules (path only!)
pnpm patch <pkg>@<version> pnpm add -g . # register the current package's bins globally
# After editing, commit the patch
pnpm patch-commit <path>
# Remove a patch
pnpm patch-remove <pkg>
``` ```
### Store management > Breaking in v11: `pnpm link` accepts **only relative/absolute paths** (no global store resolution, no `--global`, no bare `pnpm link`). Use `pnpm add -g .` to expose bins system-wide.
## Global packages (v11 isolated installs)
```bash ```bash
# Show store path pnpm add -g typescript prettier # each gets its own isolated install dir
pnpm store path pnpm add -g eslint,prettier # comma = ONE shared install group
pnpm add -g --allow-build=esbuild esbuild
pnpm remove -g <pkg>
pnpm list -g
pnpm bin -g # show global bin dir ($PNPM_HOME/bin)
```
# Remove unreferenced packages > `pnpm install -g` (no args) is not supported. After upgrading to v11 run `pnpm setup` so `$PNPM_HOME/bin` is on PATH.
pnpm store prune
# Check store integrity ## Runtimes (Node/Deno/Bun)
```bash
pnpm runtime set node 22 -g # install & expose node (alias: rt)
pnpm runtime set node lts -g
pnpm runtime set deno 2 -g
pnpm install --no-runtime # skip installing devEngines.runtime entries
```
## Store management
```bash
pnpm store path # store location (prints removed size after prune)
pnpm store prune # GC unreferenced packages (+ global virtual store links)
pnpm store status pnpm store status
``` ```
### Other commands ## Inspection / registry
```bash ```bash
# Clean install (like npm ci) pnpm list # alias: ls
pnpm install --frozen-lockfile pnpm why <pkg> # reverse-dependency tree (dedupes subtrees)
pnpm why --find-by=<finder> # custom finder from .pnpmfile.mjs
# List installed packages
pnpm list
pnpm ls
# Why is package installed?
pnpm why <pkg>
# Outdated packages
pnpm outdated pnpm outdated
# Audit for vulnerabilities
pnpm audit pnpm audit
pnpm peers check # report unmet/missing peers from the lockfile
# Rebuild native modules pnpm view <pkg> [field] # registry metadata (aliases: info, show)
pnpm whoami
pnpm rebuild pnpm rebuild
pnpm import # create pnpm-lock.yaml from npm/yarn lockfile
pnpm dedupe
```
# Import from npm/yarn lockfile ## Publishing
pnpm import
# Create tarball ```bash
pnpm pack pnpm pack
pnpm publish -r --no-git-checks
pnpm version patch|minor|major|2.0.0 # bump version, commit + tag (v11)
pnpm version prerelease --preid beta
pnpm deprecate <pkg>@<range> "message"
pnpm dist-tag add <pkg>@<version> <tag>
pnpm unpublish <pkg>@<version> # discouraged; prefer deprecate
pnpm sbom --sbom-format cyclonedx # SBOM: cyclonedx (1.7) | spdx (2.3)
pnpm stage publish ... # staged publishing (defer 2FA)
```
# Publish package ## Maintenance & version management
pnpm publish
```bash
pnpm self-update [<version>] # updates the packageManager pin, or installs globally
pnpm with current install # run a specific pnpm version for one command
pnpm with 11.0.0 install
pnpm approve-builds [--all] # review dependency build scripts (writes allowBuilds)
``` ```
## Useful Flags ## Useful Flags
```bash ```bash
# Ignore scripts
pnpm install --ignore-scripts pnpm install --ignore-scripts
# Prefer offline (use cache)
pnpm install --prefer-offline pnpm install --prefer-offline
pnpm install --prod # -P, omit devDependencies
# Strict peer dependencies
pnpm install --strict-peer-dependencies
# Production only
pnpm install --prod
pnpm install -P
# No optional dependencies
pnpm install --no-optional pnpm install --no-optional
pnpm install --strict-peer-dependencies
``` ```
## Key Points
- `pnpm ci` = clean + frozen install; CI auto-enables frozen-lockfile.
- `dlx`/`pnpx` are aliases of `pnx`; global installs are now isolated per package (comma-list to share).
- `pnpm link` only takes paths; use `pnpm add -g .` for global bins.
- Manage Node/Deno/Bun with `pnpm runtime set`; skip them at install with `--no-runtime`.
- New publishing/registry commands: `version`, `view`, `whoami`, `deprecate`, `dist-tag`, `unpublish`, `sbom`, `stage`.
<!-- <!--
Source references: Source references:
- https://pnpm.io/cli/install - https://pnpm.io/cli/install
- https://pnpm.io/cli/add - https://pnpm.io/cli/add
- https://pnpm.io/cli/run - https://pnpm.io/cli/run
- https://pnpm.io/filtering - https://pnpm.io/filtering
- https://pnpm.io/cli/link
- https://pnpm.io/global-packages
- https://pnpm.io/cli/runtime
- https://pnpm.io/cli/version
- https://pnpm.io/cli/with
- https://pnpm.io/cli/sbom
--> -->
.agents/skills/pnpm/references/core-config.md
+126 -129
View File
@@ -1,188 +1,185 @@
--- ---
name: pnpm-configuration name: pnpm-configuration
description: Configuration options via pnpm-workspace.yaml and .npmrc settings description: Configuring pnpm via pnpm-workspace.yaml (settings), the global config.yaml, and .npmrc (auth only)
--- ---
# pnpm Configuration # 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 settings are split into **two** categories. Knowing where each goes is the single most important config concept in current pnpm:
## pnpm-workspace.yaml | Category | Stored in | Format |
|----------|-----------|--------|
| **All pnpm/install settings** (`nodeLinker`, `hoistPattern`, `autoInstallPeers`, `overrides`, `catalog`, …) | `pnpm-workspace.yaml` (project) and `config.yaml` (global) | YAML, **camelCase** keys |
| **Auth & registry credentials** (`_authToken`, `cert`, `key`, …) | `.npmrc` (project, gitignored) and global `rc` | INI |
The recommended location for pnpm-specific configurations. Place at project root. > **Important changes:** pnpm no longer reads settings from the `pnpm` field of `package.json`, and `.npmrc` is now used **only** for authentication/registry credentials. Everything else belongs in `pnpm-workspace.yaml`. Keys in YAML are **camelCase** (e.g. `nodeLinker`), not the kebab-case used by old `.npmrc` files.
```yaml ## pnpm-workspace.yaml (primary config)
# Define workspace packages
Place at the workspace/project root. Even a single-package project uses this file for pnpm settings.
```yaml title="pnpm-workspace.yaml"
# Workspace packages (omit for a single-package repo)
packages: packages:
- 'packages/*' - 'packages/*'
- 'apps/*' - 'apps/*'
- '!**/test/**' # Exclude pattern - '!**/test/**'
# Catalog for shared dependency versions # Common install settings (camelCase)
nodeLinker: isolated # isolated (default) | hoisted | pnp
autoInstallPeers: true
strictPeerDependencies: false
savePrefix: '^'
saveExact: false
hoistPattern:
- '*eslint*'
- '*babel*'
publicHoistPattern: []
shamefullyHoist: false
dedupeDirectDeps: false
resolutionMode: highest # highest | time-based | lowest-direct
# Centralized version management
catalog: catalog:
react: ^18.2.0 react: ^18.2.0
typescript: ~5.3.0
# Named catalogs for different dependency groups # Force dependency versions (root only)
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: overrides:
lodash: ^4.17.21 lodash: ^4.17.21
'foo@^1.0.0>bar': ^2.0.0 'foo@^1.0.0>bar': ^2.0.0
# pnpm settings (alternative to .npmrc) # Extend/patch broken package manifests
settings: packageExtensions:
auto-install-peers: true react-redux:
strict-peer-dependencies: false peerDependencies:
link-workspace-packages: true react-dom: '*'
prefer-workspace-packages: true
shared-workspace-lockfile: true # Peer dependency rules
peerDependencyRules:
ignoreMissing:
- '@babel/*'
allowedVersions:
react: '17 || 18'
``` ```
## .npmrc Settings ## Global configuration (config.yaml)
pnpm reads settings from `.npmrc` files. Create at project root or user home. User-level non-auth settings live in a global YAML `config.yaml`:
### Common pnpm Settings - `$XDG_CONFIG_HOME/pnpm/config.yaml` (if set)
- Linux: `~/.config/pnpm/config.yaml`
- macOS: `~/Library/Preferences/pnpm/config.yaml`
- Windows: `~/AppData/Local/pnpm/config/config.yaml`
```ini The companion global `rc` file (same directory, named `rc`) holds only registry/auth settings.
# Automatically install peer dependencies
auto-install-peers=true
# Fail on peer dependency issues ## Per-project settings in a workspace (packageConfigs)
strict-peer-dependencies=false
# Hoist patterns for dependencies There are no per-subproject `.npmrc` files anymore. Set per-package config via `packageConfigs` in the root `pnpm-workspace.yaml`:
public-hoist-pattern[]=*types*
public-hoist-pattern[]=*eslint*
shamefully-hoist=false
# Store location ```yaml title="pnpm-workspace.yaml"
store-dir=~/.pnpm-store packageConfigs:
# Map form: keyed by package name
project-1:
saveExact: true
project-2:
savePrefix: '~'
# Array form: pattern-matched rules
# - match: ['project-1', 'project-2']
# modulesDir: node_modules
# saveExact: true
```
# Virtual store location ## .npmrc — authentication only
virtual-store-dir=node_modules/.pnpm
# Lockfile settings Keep auth tokens out of the repo (gitignore the project `.npmrc`). Auth files, highest priority first:
lockfile=true
prefer-frozen-lockfile=true
# Side effects cache (speeds up rebuilds) 1. `<workspace root>/.npmrc` (project, gitignored)
side-effects-cache=true 2. `<pnpm config>/auth.ini` (written by `pnpm login`)
3. `~/.npmrc` (fallback for npm compatibility)
# Registry settings ```ini title=".npmrc"
registry=https://registry.npmjs.org/ //registry.npmjs.org/:_authToken=${NPM_TOKEN}
@myorg:registry=https://npm.myorg.com/ @myorg:registry=https://npm.myorg.com/
//npm.myorg.com/:_authToken=${MYORG_TOKEN}
``` ```
### Workspace Settings Configure registries themselves (non-secret) in `pnpm-workspace.yaml`:
```ini ```yaml title="pnpm-workspace.yaml"
# Link workspace packages registries:
link-workspace-packages=true default: https://registry.npmjs.org/
'@my-org': https://private.example.com/
# Prefer workspace packages over registry # Named registry aliases usable as a prefix, e.g. `pnpm add work:@corp/lib`
prefer-workspace-packages=true namedRegistries:
work: https://npm.work.example.com/
# Single lockfile for all packages
shared-workspace-lockfile=true
# Save prefix for workspace dependencies
save-workspace-protocol=rolling
``` ```
### Node.js Settings > Security: since v11, env-variable expansion is disabled for registry/proxy URLs and credential keys in the **project** `.npmrc` (to stop a malicious repo from leaking secrets). Put dynamic-token lines in the user-level auth file instead.
```ini ## The `pnpm config` command
# 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 ```bash
# Set config via env # Writes to global config.yaml / rc by default
npm_config_registry=https://registry.npmjs.org/ pnpm config set nodeVersion 22.0.0
pnpm config set --location=project nodeVersion 22.0.0 # writes pnpm-workspace.yaml
# pnpm-specific env vars # JSON values create arrays/objects
PNPM_HOME=~/.local/share/pnpm pnpm config set --location=project --json allowBuilds '{"react": true}'
# get/list print JSON (no longer INI) since v11
pnpm config get nodeLinker
pnpm config get 'allowBuilds.react'
pnpm config list
``` ```
## Package.json Fields ## Environment variables
pnpm reads specific fields from `package.json`: Use `pnpm_config_*` (or `PNPM_CONFIG_*`). pnpm **no longer reads `npm_config_*`**.
```bash
pnpm_config_save_exact=true pnpm add foo
```
## Notable settings that changed names
| Old (removed) | Replacement | Notes |
|---------------|-------------|-------|
| `onlyBuiltDependencies`, `neverBuiltDependencies`, `ignoredBuiltDependencies`, `onlyBuiltDependenciesFile` | `allowBuilds: { name: true\|false }` | Single map controlling build-script approval. See supply-chain-security. |
| `managePackageManagerVersions`, `packageManagerStrict`, `packageManagerStrictVersion`, `COREPACK_ENABLE_STRICT` | `pmOnFail: download\|ignore\|warn\|error` | Behavior when running pnpm version ≠ declared one. |
| `useNodeVersion` | `devEngines.runtime` (in `package.json`) | Runtime pinning. |
| `auditConfig.ignoreCves` | `auditConfig.ignoreGhsas` | Use GHSA IDs. |
| `allowNonAppliedPatches` | `allowUnusedPatches` | `ignorePatchFailures` removed (patches now always throw). |
| `package.json#pnpm` field | `pnpm-workspace.yaml` | No longer read at all. |
## Package Manager / Runtime pinning (package.json)
```json ```json
{ {
"pnpm": { "packageManager": "pnpm@10.0.0",
"overrides": { "devEngines": {
"lodash": "^4.17.21" "packageManager": { "name": "pnpm", "version": ">=11.0.0 <12.0.0", "onFail": "download" },
}, "runtime": { "name": "node", "version": "22.x", "onFail": "download" }
"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 `devEngines.packageManager` supports ranges (resolved version stored in lockfile); `packageManager` requires an exact version. Override `onFail` without editing the manifest via `pmOnFail` / `runtimeOnFail` settings.
1. **Strict by default**: No phantom dependencies ## Key Points
2. **Workspace protocol**: `workspace:*` for local packages
3. **Catalogs**: Centralized version management - All pnpm settings go in `pnpm-workspace.yaml` (camelCase) or global `config.yaml`; `.npmrc` is auth/registry only.
4. **Content-addressable store**: Shared across projects - `package.json#pnpm` and `npm_config_*` env vars are no longer read.
- Use `packageConfigs` for per-package settings inside a workspace.
- Build-script approval is now one `allowBuilds` map; package-manager strictness is one `pmOnFail` setting.
- `pnpm config get`/`list` output JSON, and `--location=project` writes to `pnpm-workspace.yaml`.
<!-- <!--
Source references: Source references:
- https://pnpm.io/pnpm-workspace_yaml - https://pnpm.io/settings
- https://pnpm.io/configuring
- https://pnpm.io/npmrc - https://pnpm.io/npmrc
- https://pnpm.io/pnpm-workspace_yaml
- https://pnpm.io/package_json - https://pnpm.io/package_json
- https://pnpm.io/cli/config
--> -->
.agents/skills/pnpm/references/core-store.md
+45 -39
View File
@@ -16,10 +16,9 @@ pnpm uses a content-addressable store to save disk space and speed up installati
### Storage Layout ### Storage Layout
``` ```
~/.pnpm-store/ # Global store (default location) <store-dir>/ # Global content-addressable store (pnpm store path)
└── v3/ └── files/
└── files/ └── <hash>/ # Files stored by content hash
└── <hash>/ # Files stored by content hash
project/ project/
└── node_modules/ └── node_modules/
@@ -53,26 +52,24 @@ pnpm store add <pkg>
## Configuration ## Configuration
Store/linker settings live in `pnpm-workspace.yaml` (camelCase), not `.npmrc`.
### Store Location ### Store Location
```ini ```yaml title="pnpm-workspace.yaml"
# .npmrc storeDir: ~/.local/share/pnpm/store
store-dir=~/.pnpm-store
# Or use environment variable
PNPM_HOME=~/.local/share/pnpm
``` ```
The default store path is OS-specific (e.g. `~/.local/share/pnpm/store` on Linux, `~/Library/pnpm/store` on macOS). Find it with `pnpm store path`.
### Virtual Store ### Virtual Store
The virtual store (`.pnpm` in `node_modules`) contains symlinks to the global store: The virtual store (`.pnpm` in `node_modules`) contains hard links to the global store:
```ini ```yaml title="pnpm-workspace.yaml"
# Customize virtual store location virtualStoreDir: node_modules/.pnpm
virtual-store-dir=node_modules/.pnpm virtualStoreDirMaxLength: 60 # lower this for long-path issues on Windows
nodeLinker: hoisted # alternative flat layout
# Alternative flat layout
node-linker=hoisted
``` ```
## Disk Space Benefits ## Disk Space Benefits
@@ -91,19 +88,22 @@ du -sh node_modules # Apparent size
du -sh --apparent-size node_modules # With hard links counted du -sh --apparent-size node_modules # With hard links counted
``` ```
## Global Virtual Store
With `enableGlobalVirtualStore: true`, projects skip the per-project `node_modules/.pnpm` directory entirely; their `node_modules` contains only symlinks into one shared virtual store at `<store-path>/links/`, keyed by dependency-graph hash. In pnpm v11 it is the default for `pnpm dlx`/`pnx` and global installs; for project installs it is still opt-in. See `features-global-virtual-store` for details and the git-worktrees multi-agent workflow.
```yaml title="pnpm-workspace.yaml"
enableGlobalVirtualStore: true
```
## Node Linker Modes ## Node Linker Modes
Configure how `node_modules` is structured: Configure how `node_modules` is structured (`nodeLinker` in `pnpm-workspace.yaml`):
```ini ```yaml title="pnpm-workspace.yaml"
# Default: Symlinked structure (recommended) nodeLinker: isolated # default: symlinked virtual store (strict, no phantom deps)
node-linker=isolated # nodeLinker: hoisted # flat node_modules (npm-like) for tools that dislike symlinks
# nodeLinker: pnp # Plug'n'Play, no node_modules (set `symlink: false` too)
# Flat node_modules (npm-like, for compatibility)
node-linker=hoisted
# PnP mode (experimental, like Yarn PnP)
node-linker=pnp
``` ```
### Isolated Mode (Default) ### Isolated Mode (Default)
@@ -120,14 +120,19 @@ node-linker=pnp
## Side Effects Cache ## Side Effects Cache
Cache build outputs for native modules: Cache build outputs for native modules (enabled by default):
```ini ```yaml title="pnpm-workspace.yaml"
# Enable side effects caching sideEffectsCache: true
side-effects-cache=true sideEffectsCacheReadonly: false # only read the cache, don't create it
```
# Store side effects in project (instead of global store) ## Read-only / Frozen Store
side-effects-cache-readonly=true
`frozenStore: true` (v11.7+) lets `pnpm install` run against a read-only store (Nix store, read-only bind mount, OCI layer). Pair with `--offline --frozen-lockfile`; the store must already contain everything, including approved build outputs.
```bash
pnpm install --frozen-store --offline --frozen-lockfile
``` ```
## Shared Store Across Machines ## Shared Store Across Machines
@@ -160,20 +165,21 @@ pnpm store prune
``` ```
### Hard link issues (network drives, Docker) ### Hard link issues (network drives, Docker)
```ini ```yaml title="pnpm-workspace.yaml"
# Use copying instead of hard links # auto (default) tries clone -> hardlink -> copy
package-import-method=copy packageImportMethod: copy
``` ```
### Permission issues ### Permission issues
```bash ```bash
# Fix store permissions # Fix store permissions (find the path with `pnpm store path`)
chmod -R u+w ~/.pnpm-store chmod -R u+w "$(pnpm store path)"
``` ```
<!-- <!--
Source references: Source references:
- https://pnpm.io/symlinked-node-modules-structure - https://pnpm.io/symlinked-node-modules-structure
- https://pnpm.io/cli/store - https://pnpm.io/cli/store
- https://pnpm.io/npmrc#store-dir - https://pnpm.io/settings#storedir
- https://pnpm.io/global-virtual-store
--> -->
.agents/skills/pnpm/references/core-workspaces.md
+33 -16
View File
@@ -124,23 +124,39 @@ pnpm --filter "./packages/**" exec rm -rf dist
## Workspace Settings ## Workspace Settings
Configure in `.npmrc` or `pnpm-workspace.yaml`: Configure in `pnpm-workspace.yaml` using **camelCase** keys (these settings no longer belong in `.npmrc`):
```yaml title="pnpm-workspace.yaml"
packages:
- 'packages/*'
```ini
# Link workspace packages automatically # Link workspace packages automatically
link-workspace-packages=true linkWorkspacePackages: true
# Prefer workspace packages over registry # Prefer workspace packages over registry
prefer-workspace-packages=true preferWorkspacePackages: true
# Single lockfile for the whole workspace (recommended)
# Single lockfile (recommended) sharedWorkspaceLockfile: true
shared-workspace-lockfile=true # Workspace protocol handling on publish
saveWorkspaceProtocol: rolling
# Workspace protocol handling
save-workspace-protocol=rolling
# Concurrent workspace scripts # Concurrent workspace scripts
workspace-concurrency=4 workspaceConcurrency: 4
# Use root deps to resolve peers of all projects
resolvePeersFromWorkspaceRoot: true
# Scripts required in every project (else `pnpm -r run <name>` fails)
requiredScripts:
- build
```
### Per-package configuration (packageConfigs)
There are no per-subproject `.npmrc` files. Set package-specific settings from the root file:
```yaml title="pnpm-workspace.yaml"
packageConfigs:
project-1:
saveExact: true
project-2:
savePrefix: '~'
``` ```
## Publishing Workspaces ## Publishing Workspaces
@@ -171,10 +187,11 @@ pnpm publish -r --no-git-checks
## Best Practices ## Best Practices
1. **Use workspace protocol** for internal dependencies 1. **Use workspace protocol** for internal dependencies
2. **Enable `link-workspace-packages`** for automatic linking 2. **Enable `linkWorkspacePackages`** for automatic linking
3. **Use shared lockfile** for consistency 3. **Use shared lockfile** for consistency
4. **Filter by dependencies** when building to ensure correct order 4. **Filter by dependencies** when building to ensure correct order
5. **Use catalogs** for shared external dependency versions 5. **Use catalogs** for shared external dependency versions (defined in this same file)
6. **Keep all pnpm settings in `pnpm-workspace.yaml`** (camelCase), not `.npmrc`
## Example Project Structure ## Example Project Structure
@@ -197,7 +214,7 @@ my-monorepo/
└── package.json └── package.json
``` ```
<!-- <!--
Source references: Source references:
- https://pnpm.io/workspaces - https://pnpm.io/workspaces
- https://pnpm.io/filtering - https://pnpm.io/filtering
.agents/skills/pnpm/references/features-aliases.md
+20 -3
View File
@@ -130,7 +130,7 @@ Force all transitive dependencies to use an alias:
```yaml ```yaml
# pnpm-workspace.yaml # pnpm-workspace.yaml
overrides: overrides:
'underscore': 'npm:lodash@^4.17.21' "underscore": "npm:lodash@^4.17.21"
``` ```
This replaces all `underscore` imports (including in dependencies) with lodash. This replaces all `underscore` imports (including in dependencies) with lodash.
@@ -148,6 +148,21 @@ Aliases work with any valid pnpm specifier:
} }
``` ```
## Registry Aliases (namedRegistries)
Distinct from package aliases: a `namedRegistries` prefix selects *which registry* a package is fetched from.
```yaml title="pnpm-workspace.yaml"
namedRegistries:
work: https://npm.work.example.com/
```
```bash
pnpm add work:@corp/lib@^2.0.0 # resolves @corp/lib against the work registry
```
The built-in `gh:` alias points at GitHub Packages. Auth is reused from per-URL `.npmrc` entries.
## Best Practices ## Best Practices
1. **Clear naming**: Use descriptive alias names that indicate purpose 1. **Clear naming**: Use descriptive alias names that indicate purpose
@@ -156,13 +171,15 @@ Aliases work with any valid pnpm specifier:
"lodash-modern": "npm:lodash@4" "lodash-modern": "npm:lodash@4"
``` ```
2. **Document aliases**: Add comments or documentation explaining why aliases exist 2. **Document aliases**: explain why aliases exist
3. **Prefer overrides for global replacement**: If you want to replace a package everywhere, use overrides instead of aliases 3. **Prefer overrides for global replacement**: to replace a package everywhere, use `overrides` (in `pnpm-workspace.yaml`) instead of aliases
4. **Test thoroughly**: Aliased packages may have subtle differences in behavior 4. **Test thoroughly**: Aliased packages may have subtle differences in behavior
<!-- <!--
Source references: Source references:
- https://pnpm.io/aliases - https://pnpm.io/aliases
- https://pnpm.io/settings#namedregistries
--> -->
.agents/skills/pnpm/references/features-catalogs.md
+33 -6
View File
@@ -37,6 +37,8 @@ Reference in `package.json` with `catalog:`:
} }
``` ```
`catalog:` is shorthand for `catalog:default`. The `catalog:` protocol is valid in `package.json` `dependencies`, `devDependencies`, `peerDependencies`, and `optionalDependencies`, plus in `overrides` inside `pnpm-workspace.yaml`. It also works on the CLI: `pnpm add react@catalog:` and `pnx shx@catalog:`.
## Named Catalogs ## Named Catalogs
Create multiple catalogs for different scenarios: Create multiple catalogs for different scenarios:
@@ -54,14 +56,14 @@ catalogs:
react17: react17:
react: ^17.0.2 react: ^17.0.2
react-dom: ^17.0.2 react-dom: ^17.0.2
react18: react18:
react: ^18.2.0 react: ^18.2.0
react-dom: ^18.2.0 react-dom: ^18.2.0
testing: testing:
vitest: ^1.0.0 vitest: ^1.0.0
'@testing-library/react': ^14.0.0 "@testing-library/react": ^14.0.0
``` ```
Reference named catalogs: Reference named catalogs:
@@ -78,12 +80,33 @@ Reference named catalogs:
} }
``` ```
## Keeping overrides in sync with a catalog
Reference a catalog from `overrides` so the version lives in exactly one place:
```yaml title="pnpm-workspace.yaml"
catalog:
foo: ^1.0.0
overrides:
foo: 'catalog:' # or catalog:<name>
```
## Settings
```yaml title="pnpm-workspace.yaml"
# How `pnpm add` interacts with the default catalog (v10.12+)
catalogMode: manual # manual (default) | prefer | strict
# strict: only catalog versions allowed; prefer: fall back if no match
cleanupUnusedCatalogs: true # remove unused catalog entries on install (v10.15+)
```
## Benefits ## Benefits
1. **Single source of truth**: Update version in one place 1. **Single source of truth**: Update version in one place
2. **Consistency**: All packages use the same version 2. **Consistency**: All packages use the same version
3. **Easy upgrades**: Change version once, affects entire workspace 3. **Easy upgrades**: Change version once, affects entire workspace
4. **Type-safe**: TypeScript support in pnpm-workspace.yaml 4. **Fewer merge conflicts**: package.json files stay untouched on upgrades
## Catalog vs Overrides ## Catalog vs Overrides
@@ -134,7 +157,11 @@ catalog:
react-dom: ^18.2.0 react-dom: ^18.2.0
``` ```
Then update package.json files to use `catalog:`. Then update package.json files to use `catalog:`. To migrate an existing workspace automatically:
```bash
pnpx codemod pnpm/catalog
```
## Best Practices ## Best Practices
@@ -153,7 +180,7 @@ catalog:
# "dependencies": { "@myorg/utils": "workspace:^" } # "dependencies": { "@myorg/utils": "workspace:^" }
``` ```
<!-- <!--
Source references: Source references:
- https://pnpm.io/catalogs - https://pnpm.io/catalogs
--> -->
.agents/skills/pnpm/references/features-config-dependencies.md
+91
View File
@@ -0,0 +1,91 @@
---
name: pnpm-config-dependencies
description: Share and centralize pnpm hooks, settings, patches, catalogs, and overrides across repos via config dependencies
---
# pnpm Config Dependencies
Config dependencies are npm packages that pnpm installs **before** all regular dependencies, so they can supply hooks, settings, patches, catalogs, and overrides that are reused across many repositories. They let you keep one shared "pnpm config" package and consume it everywhere.
## Declaring config dependencies
They live in `pnpm-workspace.yaml`; their integrity is recorded in a dedicated env-lockfile document inside `pnpm-lock.yaml`.
```yaml title="pnpm-workspace.yaml"
configDependencies:
my-configs: "1.0.0"
```
Add one with the `--config` flag:
```bash
pnpm add --config my-configs
pnpm add --config @myorg/pnpm-plugin-my-catalogs
```
## Constraints
- **No regular `dependencies`.** They may declare `optionalDependencies`, but only one level deep.
- **No lifecycle scripts** (`preinstall`, `postinstall`, …).
- `optionalDependencies` (used for platform-specific binaries, esbuild-style) must use **exact** versions — ranges/tags are rejected, keeping installs reproducible.
## Auto-loaded plugins
A config dependency named `pnpm-plugin-*`, `@*/pnpm-plugin-*`, or `@pnpm/plugin-*` has its `pnpmfile.mjs` (or `.cjs`) loaded automatically from the package root.
## Use cases
### Import hook logic from a shared package
Because config deps install before the pnpmfile loads, you can import from them:
```js title=".pnpmfile.mjs"
import { readPackage } from '.pnpm-config/my-hooks'
export const hooks = { readPackage }
```
### Share settings & catalogs via updateConfig
A plugin can inject settings/catalog entries through the `updateConfig` hook:
```js title="@myorg/pnpm-plugin-my-catalogs/pnpmfile.mjs"
export const hooks = {
updateConfig(config) {
config.catalogs.default ??= {}
config.catalogs.default['is-odd'] = '1.0.0'
return config
}
}
```
After installing it as a config dependency, consumers can use the catalog:
```bash
pnpm add is-odd@catalog: # installs is-odd@1.0.0, writes "is-odd": "catalog:"
```
### Share patch files
Reference patches stored inside a config dependency:
```yaml title="pnpm-workspace.yaml"
configDependencies:
my-patches: "1.0.0"
patchedDependencies:
react: "node_modules/.pnpm-config/my-patches/react.patch"
```
## Key Points
- Centralize hooks, settings, catalogs, overrides, and patches in one package, consumed across repos.
- Declared via `configDependencies` in `pnpm-workspace.yaml`; installed before regular deps.
- No regular dependencies and no lifecycle scripts; `optionalDependencies` need exact versions.
- `pnpm-plugin-*` / `@pnpm/plugin-*` packages auto-load their pnpmfile.
- Pair with the `updateConfig` hook to push settings/catalogs into consuming projects.
<!--
Source references:
- https://pnpm.io/config-dependencies
- https://pnpm.io/pnpmfile#hooksupdateconfigconfig-config--promiseconfig
-->
.agents/skills/pnpm/references/features-global-virtual-store.md
+94
View File
@@ -0,0 +1,94 @@
---
name: pnpm-global-virtual-store
description: Global virtual store for shared node_modules across checkouts, git-worktree multi-agent setups, and isolated global packages
---
# Global Virtual Store, Git Worktrees & Global Packages
## Global virtual store
By default each project has its own `node_modules/.pnpm` virtual store containing hard links to the content-addressable store. With the **global virtual store** enabled, pnpm keeps one shared virtual store at `<store-path>/links/` (find it via `pnpm store path`), and each project's `node_modules` contains only **symlinks** into it.
```yaml title="pnpm-workspace.yaml"
enableGlobalVirtualStore: true
```
```
# Default (per-project .pnpm with hard links)
project-a/node_modules/lodash -> .pnpm/lodash@4.17.21/node_modules/lodash
# Global virtual store (symlink to shared location)
project-a/node_modules/lodash -> <store>/links/@/lodash/4.17.21/<hash>/node_modules/lodash
project-b/node_modules/lodash -> <store>/links/@/lodash/4.17.21/<hash>/node_modules/lodash # same target
```
- **Package identity = hash of the dependency graph.** Two projects with the same `lodash@4.17.21` and the same transitive tree point at the exact same directory (NixOS-style). Different peers ⇒ separate entries.
- **Near-zero per-project cost** and **instant installs** once a version is in the store.
- In **pnpm v11** it is the default for `pnpm dlx`/`pnx` and global installs; for **project** installs it is still **opt-in/experimental**.
### Limitations
- **CI:** auto-disabled (no warm cache to benefit from).
- **Trust:** the store is shared writable state — only for mutually trusting projects/users/jobs; protect the path with filesystem permissions.
- **ESM hoisting:** relies on `NODE_PATH`, which Node ignores for ESM imports. If ESM deps import undeclared packages, resolution fails. Fix with `packageExtensions` or the `@pnpm/plugin-esm-node-path` config dependency.
## Git worktrees for multi-agent development
Git worktrees let you check out many branches simultaneously, each in its own directory, sharing one `.git` object store. Combined with the global virtual store, every worktree gets a fully functional `node_modules` that is almost free on disk — ideal for running multiple AI agents in parallel.
```sh
# Bare repo as the hub, one worktree per branch/agent
git clone --bare https://github.com/your-org/your-monorepo.git your-monorepo
cd your-monorepo
git worktree add ./main main
git worktree add ./feature-auth feat/auth
git worktree add ./fix-api fix/api-error
```
```yaml title="pnpm-workspace.yaml"
packages:
- 'packages/*'
enableGlobalVirtualStore: true
```
```sh
cd main && pnpm install # first install fills the global store
cd ../feature-auth && pnpm install # subsequent worktrees: nearly instant, just symlinks
```
Each worktree has its own `node_modules` tree (so agents can install different versions on different branches without conflict), but all package contents come from the one shared store. Remove a worktree with `git worktree remove ./feature-auth`.
> The pnpm repo itself uses this setup and ships helper scripts (`pnpm worktree:new <branch|pr>`). Assumes all worktrees/agents share the same trust boundary.
## Global packages (v11 isolated installs)
`pnpm add -g` was redesigned in v11 for isolation. Each globally installed package (or group) gets its own install directory with its own `package.json`, `node_modules/`, and lockfile, so global tools can't break each other via peer/hoisting conflicts. Installs are stored at `{pnpmHomeDir}/global/v11/{hash}/` and share the global virtual store.
```sh
pnpm add -g typescript prettier # space-separated = separate isolated installs each
pnpm add -g eslint,prettier # comma-separated = ONE shared install group
pnpm remove -g eslint # removes only eslint's group
pnpm add -g --allow-build=esbuild esbuild # pre-approve build scripts
pnpm list -g # always works at depth 0
pnpm bin -g # global bin dir = $PNPM_HOME/bin
```
- `pnpm install -g` (no args) is **not** supported — use `pnpm add -g <pkg>`.
- Binaries live in `$PNPM_HOME/bin` (not `$PNPM_HOME` directly). Run `pnpm setup` after upgrading to put it on PATH.
- Register a local package's bins globally with `pnpm add -g .` (replaces `pnpm link --global`).
- `pnpm list -g --depth=<n>` (n>0) only works for a single install group.
## Key Points
- `enableGlobalVirtualStore: true` ⇒ `node_modules` is symlinks into one shared, hash-addressed store.
- Best for many checkouts of the same repo (git worktrees, parallel agents); auto-disabled in CI.
- Watch out for ESM packages importing undeclared deps (NODE_PATH limitation).
- v11 global installs are isolated per package; comma-list to share a group; bins live in `$PNPM_HOME/bin`.
<!--
Source references:
- https://pnpm.io/global-virtual-store
- https://pnpm.io/git-worktrees
- https://pnpm.io/global-packages
- https://pnpm.io/settings#enableglobalvirtualstore
-->
.agents/skills/pnpm/references/features-hooks.md
+127 -180
View File
@@ -1,233 +1,180 @@
--- ---
name: pnpm-hooks name: pnpm-hooks
description: Customize package resolution and dependency behavior with pnpmfile hooks description: Customize resolution, config, packing, and fetching with .pnpmfile.mjs hooks, finders, and custom resolvers/fetchers
--- ---
# pnpm Hooks # pnpm Hooks (.pnpmfile.mjs)
pnpm provides hooks via `.pnpmfile.cjs` to customize how packages are resolved and their metadata is processed. pnpm hooks customize installation. Declare them in `.pnpmfile.mjs` (ESM, preferred) or `.pnpmfile.cjs` (CommonJS), located next to the lockfile (workspace root for a monorepo).
> The modern format uses ESM `export const hooks = { ... }`. The old CommonJS `module.exports = { hooks }` still works in `.pnpmfile.cjs`.
## Setup ## Setup
Create `.pnpmfile.cjs` at workspace root: ```js title=".pnpmfile.mjs"
export const hooks = {
```js readPackage,
// .pnpmfile.cjs afterAllResolved,
function readPackage(pkg, context) { updateConfig,
// Modify package metadata beforePacking,
return pkg
}
function afterAllResolved(lockfile, context) {
// Modify lockfile
return lockfile
}
module.exports = {
hooks: {
readPackage,
afterAllResolved
}
} }
``` ```
## readPackage Hook ## Hook reference
Called for every package before resolution. Use to modify dependencies, add missing peer deps, or fix broken packages. | Hook | When | Use |
|------|------|-----|
| `readPackage(pkg, ctx)` | after a dependency manifest is parsed | mutate a dependency's `package.json` (affects resolution) |
| `afterAllResolved(lockfile, ctx)` | after resolution | mutate the lockfile before it's written |
| `updateConfig(config)` | before install | mutate pnpm's settings (great with config dependencies) |
| `beforePacking(pkg)` | before `pnpm pack`/`publish` tarball | customize the **published** manifest only |
| `preResolution(opts)` | after reading lockfiles, before resolution | inspect/modify lockfile objects |
| `importPackage(dir, opts)` | when writing to node_modules | change how packages are linked |
### Add Missing Peer Dependency ## readPackage
```js Called for every package before resolution. Common uses:
```js title=".pnpmfile.mjs"
function readPackage(pkg, context) { function readPackage(pkg, context) {
// Add a missing peer dependency
if (pkg.name === 'some-broken-package') { if (pkg.name === 'some-broken-package') {
pkg.peerDependencies = { pkg.peerDependencies = { ...pkg.peerDependencies, react: '*' }
...pkg.peerDependencies, }
react: '*' // Pin a transitive version
} if (pkg.dependencies?.lodash) pkg.dependencies.lodash = '^4.17.21'
context.log(`Added react peer dep to ${pkg.name}`) // Drop a problematic optional dep
delete pkg.optionalDependencies?.fsevents
// Replace a deprecated dep
if (pkg.dependencies?.['old-pkg']) {
pkg.dependencies['new-pkg'] = pkg.dependencies['old-pkg']
delete pkg.dependencies['old-pkg']
} }
return pkg return pkg
} }
export const hooks = { readPackage }
``` ```
### Override Dependency Version > Mutations are not written to disk; they only affect resolution. Delete `pnpm-lock.yaml` to re-resolve an already-locked dependency. Removing `scripts` here does **not** stop a build — use the `allowBuilds` setting instead. To persist a change to a dependency's files, use `pnpm patch`.
```js ## updateConfig
function readPackage(pkg, context) {
// Fix all lodash versions
if (pkg.dependencies?.lodash) {
pkg.dependencies.lodash = '^4.17.21'
}
if (pkg.devDependencies?.lodash) {
pkg.devDependencies.lodash = '^4.17.21'
}
return pkg
}
```
### Remove Unwanted Dependency Modify pnpm's own settings programmatically — most powerful when shipped in a config dependency so settings are shared across repos.
```js ```js title=".pnpmfile.mjs"
function readPackage(pkg, context) { export const hooks = {
// Remove optional dependency that causes issues updateConfig(config) {
if (pkg.optionalDependencies?.fsevents) { return Object.assign(config, {
delete pkg.optionalDependencies.fsevents enablePrePostScripts: false,
} optimisticRepeatInstall: true,
return pkg resolutionMode: 'lowest-direct',
} verifyDepsBeforeRun: 'install',
``` })
### Replace Package
```js
function readPackage(pkg, context) {
// Replace deprecated package
if (pkg.dependencies?.['old-package']) {
pkg.dependencies['new-package'] = pkg.dependencies['old-package']
delete pkg.dependencies['old-package']
}
return pkg
}
```
### Fix Broken Package
```js
function readPackage(pkg, context) {
// Fix incorrect exports field
if (pkg.name === 'broken-esm-package') {
pkg.exports = {
'.': {
import: './dist/index.mjs',
require: './dist/index.cjs'
}
}
}
return pkg
}
```
## afterAllResolved Hook
Called after the lockfile is generated. Use for post-resolution modifications.
```js
function afterAllResolved(lockfile, context) {
// Log all resolved packages
context.log(`Resolved ${Object.keys(lockfile.packages || {}).length} packages`)
// Modify lockfile if needed
return lockfile
}
```
## Context Object
The `context` object provides utilities:
```js
function readPackage(pkg, context) {
// Log messages
context.log('Processing package...')
return pkg
}
```
## Use with TypeScript
For type hints, use JSDoc:
```js
// .pnpmfile.cjs
/**
* @param {import('type-fest').PackageJson} pkg
* @param {{ log: (msg: string) => void }} context
* @returns {import('type-fest').PackageJson}
*/
function readPackage(pkg, context) {
return pkg
}
module.exports = {
hooks: {
readPackage
} }
} }
``` ```
## Common Patterns
### Conditional by Package Name
```js ```js
function readPackage(pkg, context) { // Add a catalog entry from a plugin
switch (pkg.name) { export const hooks = {
case 'package-a': updateConfig(config) {
pkg.dependencies.foo = '^2.0.0' config.catalogs.default ??= {}
break config.catalogs.default['is-odd'] = '1.0.0'
case 'package-b': return config
delete pkg.optionalDependencies.bar
break
} }
return pkg
} }
``` ```
### Apply to All Packages ## beforePacking
```js Customize the manifest that ends up in the published tarball without touching your local `package.json`.
function readPackage(pkg, context) {
// Remove all optional fsevents ```js title=".pnpmfile.mjs"
if (pkg.optionalDependencies) { export const hooks = {
delete pkg.optionalDependencies.fsevents beforePacking(pkg) {
delete pkg.devDependencies
pkg.main = './dist/index.js'
return pkg
} }
return pkg
} }
``` ```
### Debug Resolution ## afterAllResolved
```js ```js title=".pnpmfile.mjs"
function readPackage(pkg, context) { export const hooks = {
if (process.env.DEBUG_PNPM) { afterAllResolved(lockfile, context) {
context.log(`${pkg.name}@${pkg.version}`) context.log(`Resolved ${Object.keys(lockfile.packages || {}).length} packages`)
context.log(` deps: ${Object.keys(pkg.dependencies || {}).join(', ')}`) return lockfile
} }
return pkg
} }
``` ```
## Finders (pnpm list / why)
Custom predicates used via `--find-by`:
```js title=".pnpmfile.mjs"
export const finders = {
react17: (ctx) => ctx.readManifest().peerDependencies?.react === '^17.0.0'
}
```
```bash
pnpm why --find-by=react17
```
## Custom resolvers & fetchers (advanced)
Register top-level `resolvers`/`fetchers` to support new package schemes (e.g. `my-protocol:pkg`). Each is an object with cheap `canResolve`/`canFetch` guards plus `resolve`/`fetch`. Custom resolvers run before built-ins; custom resolution `type` fields must use the `custom:` prefix.
```js title=".pnpmfile.cjs"
const resolver = {
canResolve: (dep) => dep.alias.startsWith('@company/'),
resolve: async (dep) => ({
id: `${dep.alias}@${dep.bareSpecifier}`,
resolution: { type: 'custom:cdn', cdnUrl: '...' },
}),
}
const fetcher = {
canFetch: (id, res) => res.type === 'custom:cdn',
fetch: (cafs, res, opts, fetchers) =>
fetchers.remoteTarball(cafs, { tarball: res.cdnUrl, integrity: res.integrity }, opts),
}
module.exports = { resolvers: [resolver], fetchers: [fetcher] }
```
> `hooks.fetchers` was removed in v11 — use the top-level `fetchers` export instead.
## Related settings
```yaml title="pnpm-workspace.yaml"
ignorePnpmfile: false # ignore the pnpmfile entirely
pnpmfile: ['.pnpmfile.mjs'] # local pnpmfile location(s)
globalPnpmfile: ~/.pnpm/global_pnpmfile.mjs
```
## Hooks vs Overrides ## Hooks vs Overrides
| Feature | Hooks (.pnpmfile.cjs) | Overrides | | | Hooks (.pnpmfile) | Overrides (pnpm-workspace.yaml) |
|---------|----------------------|-----------| |--|-------------------|---------------------------------|
| Complexity | Can use JavaScript logic | Declarative only | | Logic | JavaScript | declarative |
| Scope | Any package metadata | Version only | | Scope | any manifest field, config, lockfile, packing | versions |
| Use case | Complex fixes, conditional logic | Simple version pins | | Use when | conditional/complex fixes | simple version pins |
**Prefer overrides** for simple version fixes. **Use hooks** when you need: Prefer `overrides`/`packageExtensions` for simple cases; use hooks for conditional logic, config sharing, or packing tweaks.
- Conditional logic
- Non-version modifications (exports, peer deps)
- Logging/debugging
## Troubleshooting ## Key Points
### Hook not running - Prefer `.pnpmfile.mjs` with `export const hooks`/`finders`/`resolvers`/`fetchers`.
- New hooks: `updateConfig` (mutate settings), `beforePacking` (published manifest), `preResolution`, `importPackage`.
1. Ensure file is named `.pnpmfile.cjs` (not `.js`) - Pair `updateConfig` with config dependencies to share settings/catalogs across repos.
2. Check file is at workspace root - `--ignore-scripts` does **not** disable the pnpmfile; use `ignorePnpmfile`.
3. Run `pnpm install` to trigger hooks
### Debug hooks
```bash
# See hook logs
pnpm install --reporter=append-only
```
<!-- <!--
Source references: Source references:
- https://pnpm.io/pnpmfile - https://pnpm.io/pnpmfile
- https://pnpm.io/finders
- https://pnpm.io/config-dependencies
--> -->
.agents/skills/pnpm/references/features-overrides.md
+50 -40
View File
@@ -9,11 +9,11 @@ Overrides let you force specific versions of packages, including transitive depe
## Basic Syntax ## Basic Syntax
Define overrides in `pnpm-workspace.yaml` (recommended) or `package.json`: Define overrides in `pnpm-workspace.yaml`. They can only be set at the **root** of the project.
### In pnpm-workspace.yaml (Recommended) > The `pnpm.overrides` field in `package.json` is **no longer read** (pnpm no longer reads any settings from `package.json#pnpm`). Move overrides to `pnpm-workspace.yaml`.
```yaml ```yaml title="pnpm-workspace.yaml"
packages: packages:
- 'packages/*' - 'packages/*'
@@ -22,27 +22,16 @@ overrides:
lodash: ^4.17.21 lodash: ^4.17.21
# Override specific version range # Override specific version range
'foo@^1.0.0': ^1.2.3 "foo@^1.0.0": ^1.2.3
# Override nested dependency # Override nested dependency (only zoo inside qar@1)
'express>cookie': ^0.6.0 "qar@1>zoo": "2"
# Override to different package # Override to different package
'underscore': 'npm:lodash@^4.17.21' "underscore": "npm:lodash@^4.17.21"
```
### In package.json # Reference a catalog so the version stays in sync
"react": "catalog:"
```json
{
"pnpm": {
"overrides": {
"lodash": "^4.17.21",
"foo@^1.0.0": "^1.2.3",
"bar@^2.0.0>qux": "^1.0.0"
}
}
}
``` ```
## Override Patterns ## Override Patterns
@@ -57,15 +46,15 @@ Forces all lodash installations to use ^4.17.21.
### Override specific parent version ### Override specific parent version
```yaml ```yaml
overrides: overrides:
'foo@^1.0.0': ^1.2.3 "foo@^1.0.0": ^1.2.3
``` ```
Only override foo when the requested version matches ^1.0.0. Only override foo when the requested version matches ^1.0.0.
### Override nested dependency ### Override nested dependency
```yaml ```yaml
overrides: overrides:
'express>cookie': ^0.6.0 "express>cookie": ^0.6.0
'foo@1.x>bar@^2.0.0>qux': ^1.0.0 "foo@1.x>bar@^2.0.0>qux": ^1.0.0
``` ```
Override cookie only when it's a dependency of express. Override cookie only when it's a dependency of express.
@@ -74,10 +63,10 @@ Override cookie only when it's a dependency of express.
overrides: overrides:
# Replace underscore with lodash # Replace underscore with lodash
"underscore": "npm:lodash@^4.17.21" "underscore": "npm:lodash@^4.17.21"
# Use local file # Use local file
"some-pkg": "file:./local-pkg" "some-pkg": "file:./local-pkg"
# Use git # Use git
"some-pkg": "github:user/repo#commit" "some-pkg": "github:user/repo#commit"
``` ```
@@ -85,10 +74,24 @@ overrides:
### Remove a dependency ### Remove a dependency
```yaml ```yaml
overrides: overrides:
'unwanted-pkg': '-' "unwanted-pkg": "-"
"foo@1.0.0>bar": "-" # great for skipping unused optionalDependencies
``` ```
The `-` removes the package entirely. The `-` removes the package entirely.
### Override peer dependencies
Overrides also apply to `peerDependencies`:
```yaml title="pnpm-workspace.yaml"
overrides:
"react-dom>react": "18.1.0"
```
- Semver ranges, `workspace:`, and `catalog:` keep the entry as a peer dependency.
- Non-range specifiers (`link:`, `file:`) move it into `dependencies`.
- `-` removes the peer dependency entirely.
## Common Use Cases ## Common Use Cases
### Security Fix ### Security Fix
@@ -98,8 +101,8 @@ Force patched version of vulnerable package:
```yaml ```yaml
overrides: overrides:
# Fix CVE in transitive dependency # Fix CVE in transitive dependency
'minimist': '^1.2.6' "minimist": "^1.2.6"
'json5': '^2.2.3' "json5": "^2.2.3"
``` ```
### Deduplicate Dependencies ### Deduplicate Dependencies
@@ -108,30 +111,29 @@ Force single version when multiple are installed:
```yaml ```yaml
overrides: overrides:
'react': '^18.2.0' "react": "^18.2.0"
'react-dom': '^18.2.0' "react-dom": "^18.2.0"
``` ```
### Fix Peer Dependency Issues ### Fix Peer Dependency Issues
```yaml ```yaml
overrides: overrides:
'@types/react': '^18.2.0' "@types/react": "^18.2.0"
``` ```
### Replace Deprecated Package ### Replace Deprecated Package
```yaml ```yaml
overrides: overrides:
'request': 'npm:@cypress/request@^3.0.0' "request": "npm:@cypress/request@^3.0.0"
``` ```
## Hooks Alternative ## Hooks Alternative
For more complex scenarios, use `.pnpmfile.cjs`: For more complex scenarios, use `.pnpmfile.mjs`:
```js ```js title=".pnpmfile.mjs"
// .pnpmfile.cjs
function readPackage(pkg, context) { function readPackage(pkg, context) {
// Override dependency version // Override dependency version
if (pkg.dependencies?.lodash) { if (pkg.dependencies?.lodash) {
@@ -149,13 +151,20 @@ function readPackage(pkg, context) {
return pkg return pkg
} }
module.exports = { export const hooks = {
hooks: { readPackage
readPackage
}
} }
``` ```
Or extend a manifest declaratively with `packageExtensions` (no JS needed):
```yaml title="pnpm-workspace.yaml"
packageExtensions:
react-redux:
peerDependencies:
react-dom: '*'
```
## Overrides vs Catalogs ## Overrides vs Catalogs
| Feature | Overrides | Catalogs | | Feature | Overrides | Catalogs |
@@ -179,6 +188,7 @@ pnpm list lodash --depth=Infinity
<!-- <!--
Source references: Source references:
- https://pnpm.io/package_json#pnpmoverrides - https://pnpm.io/settings#overrides
- https://pnpm.io/settings#packageextensions
- https://pnpm.io/pnpmfile - https://pnpm.io/pnpmfile
--> -->
.agents/skills/pnpm/references/features-patches.md
+31 -45
View File
@@ -42,23 +42,20 @@ pnpm patch-commit <path-from-step-1>
pnpm patch-commit /tmp/abc123... pnpm patch-commit /tmp/abc123...
``` ```
This creates a `.patch` file in `patches/` and updates `package.json`: This creates a `.patch` file in `patches/` and records it in `pnpm-workspace.yaml`:
``` ```
patches/ patches/
└── express@4.18.2.patch └── express@4.18.2.patch
``` ```
```json ```yaml title="pnpm-workspace.yaml"
{ patchedDependencies:
"pnpm": { express@4.18.2: patches/express@4.18.2.patch
"patchedDependencies": {
"express@4.18.2": "patches/express@4.18.2.patch"
}
}
}
``` ```
> `patchedDependencies` (like all pnpm settings) now lives in `pnpm-workspace.yaml`, not the `package.json#pnpm` field.
## Patch File Format ## Patch File Format
Patches use standard unified diff format: Patches use standard unified diff format:
@@ -100,59 +97,48 @@ pnpm patch-commit <path>
```bash ```bash
pnpm patch-remove <pkg>@<version> pnpm patch-remove <pkg>@<version>
# Example # Example
pnpm patch-remove express@4.18.2 pnpm patch-remove express@4.18.2
``` ```
Or manually: Or manually:
1. Delete the patch file from `patches/` 1. Delete the patch file from `patches/`
2. Remove entry from `patchedDependencies` in `package.json` 2. Remove the entry from `patchedDependencies` in `pnpm-workspace.yaml`
3. Run `pnpm install` 3. Run `pnpm install`
## Patch Configuration ## Patch Configuration
### Custom Patches Directory ### Multiple Packages / Workspaces
```json Patches are shared across the whole workspace from the root `pnpm-workspace.yaml`:
{
"pnpm": { ```yaml title="pnpm-workspace.yaml"
"patchedDependencies": { patchedDependencies:
"express@4.18.2": "custom-patches/my-express-fix.patch" express@4.18.2: patches/express@4.18.2.patch
} lodash@4.17.21: patches/lodash@4.17.21.patch
} '@types/node@20.10.0': patches/@types__node@20.10.0.patch
}
``` ```
### Multiple Packages A version-less key (`express:`) patches every installed version. All workspace packages using a matching version get the patch.
```json ### Patches from a config dependency
{
"pnpm": { Patch files can live inside a shared config dependency and be referenced by path:
"patchedDependencies": {
"express@4.18.2": "patches/express@4.18.2.patch", ```yaml title="pnpm-workspace.yaml"
"lodash@4.17.21": "patches/lodash@4.17.21.patch", configDependencies:
"@types/node@20.10.0": "patches/@types__node@20.10.0.patch" my-patches: '1.0.0'
} patchedDependencies:
} react: node_modules/.pnpm-config/my-patches/react.patch
}
``` ```
## Workspaces ### allowUnusedPatches
Patches are shared across the workspace. Define in the root `package.json`: ```yaml title="pnpm-workspace.yaml"
allowUnusedPatches: true # don't fail when a listed patch wasn't applied
```json
// Root package.json
{
"pnpm": {
"patchedDependencies": {
"express@4.18.2": "patches/express@4.18.2.patch"
}
}
}
``` ```
All workspace packages using `express@4.18.2` will have the patch applied. > `ignorePatchFailures` was **removed** in v11. A patch that fails to apply now always throws. When several patches are grouped, all errors are reported together at the end.
## Best Practices ## Best Practices
@@ -197,5 +183,5 @@ Ensure:
Source references: Source references:
- https://pnpm.io/cli/patch - https://pnpm.io/cli/patch
- https://pnpm.io/cli/patch-commit - https://pnpm.io/cli/patch-commit
- https://pnpm.io/package_json#pnpmpatcheddependencies - https://pnpm.io/config-dependencies
--> -->
.agents/skills/pnpm/references/features-peer-deps.md
+80 -129
View File
@@ -7,127 +7,99 @@ description: Handling peer dependencies with auto-install and resolution rules
pnpm has strict peer dependency handling by default. It provides configuration options to control how peer dependencies are resolved and reported. pnpm has strict peer dependency handling by default. It provides configuration options to control how peer dependencies are resolved and reported.
All peer-dependency settings live in `pnpm-workspace.yaml` (camelCase). The `package.json#pnpm` field is no longer read.
## Auto-Install Peer Dependencies ## Auto-Install Peer Dependencies
By default, pnpm automatically installs peer dependencies: By default (since v8), pnpm automatically installs missing non-optional peer dependencies:
```ini ```yaml title="pnpm-workspace.yaml"
# .npmrc (default is true since pnpm v8) autoInstallPeers: true
auto-install-peers=true
``` ```
When enabled, pnpm automatically adds missing peer dependencies based on the best matching version. On conflicting requirements (e.g. one dep needs `react@^16`, another `react@^17`), pnpm installs nothing and prints a warning — resolve it manually.
## Strict Peer Dependencies ## Strict Peer Dependencies
Control whether peer dependency issues cause errors: ```yaml title="pnpm-workspace.yaml"
strictPeerDependencies: true # default false
```ini
# Fail on peer dependency issues (default: false)
strict-peer-dependencies=true
``` ```
When strict, pnpm will fail if: When strict, commands fail on a missing or invalid peer dependency in the tree.
- Peer dependency is missing
- Installed version doesn't match required range ## Resolve from workspace root
```yaml title="pnpm-workspace.yaml"
resolvePeersFromWorkspaceRoot: true # default; install shared peers once at the root
```
## Deduplicate peers
```yaml title="pnpm-workspace.yaml"
dedupePeerDependents: true # default; share package instances across projects when peers match
dedupePeers: false # v10.33+: version-only peer suffixes (name@version), fewer instances
```
## Peer Dependency Rules ## Peer Dependency Rules
Configure peer dependency behavior in `package.json`: ```yaml title="pnpm-workspace.yaml"
peerDependencyRules:
```json ignoreMissing:
{ - '@babel/*'
"pnpm": { - eslint
"peerDependencyRules": { allowedVersions:
"ignoreMissing": ["@babel/*", "eslint"], react: '17 || 18'
"allowedVersions": { allowAny:
"react": "17 || 18" - '@types/*'
},
"allowAny": ["@types/*"]
}
}
}
``` ```
### ignoreMissing ### ignoreMissing
Suppress warnings for missing peer dependencies: Suppress warnings for missing peer dependencies. Patterns: exact name (`react`), scope (`@babel/*`), or `*` (not recommended).
```json ```yaml title="pnpm-workspace.yaml"
{ peerDependencyRules:
"pnpm": { ignoreMissing:
"peerDependencyRules": { - '@babel/*'
"ignoreMissing": [ - eslint
"@babel/*", - webpack
"eslint",
"webpack"
]
}
}
}
``` ```
Use patterns:
- `"react"` - exact package name
- `"@babel/*"` - all packages in scope
- `"*"` - all packages (not recommended)
### allowedVersions ### allowedVersions
Allow specific versions that would otherwise cause warnings: Allow specific versions that would otherwise warn. Target a specific parent with `parent>peer`.
```json ```yaml title="pnpm-workspace.yaml"
{ peerDependencyRules:
"pnpm": { allowedVersions:
"peerDependencyRules": { react: '17'
"allowedVersions": { 'button@2>react': '17' # only when react is a peer of button@2
"react": "17 || 18",
"webpack": "4 || 5",
"@types/react": "*"
}
}
}
}
``` ```
### allowAny ### allowAny
Allow any version for specified peer dependencies: Resolve matching peers from any version, ignoring the declared range.
```json ```yaml title="pnpm-workspace.yaml"
{ peerDependencyRules:
"pnpm": { allowAny:
"peerDependencyRules": { - '@types/*'
"allowAny": ["@types/*", "eslint"] - eslint
}
}
}
``` ```
## Adding Peer Dependencies via Hooks ## Adding Peer Dependencies via packageExtensions
Use `.pnpmfile.cjs` to add missing peer dependencies: Declaratively add a missing peer dependency without JS:
```js ```yaml title="pnpm-workspace.yaml"
// .pnpmfile.cjs packageExtensions:
function readPackage(pkg, context) { problematic-package:
// Add missing peer dependency peerDependencies:
if (pkg.name === 'problematic-package') {
pkg.peerDependencies = {
...pkg.peerDependencies,
react: '*' react: '*'
}
}
return pkg
}
module.exports = {
hooks: {
readPackage
}
}
``` ```
For conditional logic, use a `readPackage` hook in `.pnpmfile.mjs` instead.
## Peer Dependencies in Workspaces ## Peer Dependencies in Workspaces
Workspace packages can satisfy peer dependencies: Workspace packages can satisfy peer dependencies:
@@ -141,7 +113,7 @@ Workspace packages can satisfy peer dependencies:
} }
} }
// packages/components/package.json // packages/components/package.json
{ {
"peerDependencies": { "peerDependencies": {
"react": "^17.0.0 || ^18.0.0" "react": "^17.0.0 || ^18.0.0"
@@ -183,68 +155,47 @@ catalog:
### Suppress ESLint Plugin Warnings ### Suppress ESLint Plugin Warnings
```json ```yaml title="pnpm-workspace.yaml"
{ peerDependencyRules:
"pnpm": { ignoreMissing:
"peerDependencyRules": { - eslint
"ignoreMissing": [ - '@typescript-eslint/parser'
"eslint",
"@typescript-eslint/parser"
]
}
}
}
``` ```
### Allow Multiple Major Versions ### Allow Multiple Major Versions
```json ```yaml title="pnpm-workspace.yaml"
{ peerDependencyRules:
"pnpm": { allowedVersions:
"peerDependencyRules": { webpack: '4 || 5'
"allowedVersions": { postcss: '7 || 8'
"webpack": "4 || 5",
"postcss": "7 || 8"
}
}
}
}
``` ```
## Debugging Peer Dependencies ## Debugging Peer Dependencies
```bash ```bash
# Report unmet/missing peers straight from the lockfile (v11)
pnpm peers check
# See why a package is installed # See why a package is installed
pnpm why <package> pnpm why <package>
# List all peer dependency warnings
pnpm install --reporter=append-only 2>&1 | grep -i peer
# Check dependency tree # Check dependency tree
pnpm list --depth=Infinity pnpm list --depth=Infinity
``` ```
## Best Practices ## Best Practices
1. **Enable auto-install-peers** for convenience (default in pnpm v8+) 1. **Keep `autoInstallPeers` on** for convenience (default in v8+)
2. **Use `peerDependencyRules`** instead of blanket-ignoring warnings
2. **Use peerDependencyRules** instead of ignoring all warnings
3. **Document suppressed warnings** explaining why they're safe 3. **Document suppressed warnings** explaining why they're safe
4. **Keep peer ranges wide** in libraries (e.g. `"react": "^17 || ^18"`)
4. **Keep peer deps ranges wide** in libraries: 5. **Run `pnpm peers check`** in CI to catch peer regressions
```json
{
"peerDependencies": {
"react": "^17.0.0 || ^18.0.0"
}
}
```
5. **Test with different peer versions** if you support multiple majors
<!-- <!--
Source references: Source references:
- https://pnpm.io/package_json#pnpmpeerdependencyrules - https://pnpm.io/settings#peerdependencyrules
- https://pnpm.io/npmrc#auto-install-peers - https://pnpm.io/settings#autoinstallpeers
- https://pnpm.io/cli/peers
--> -->
.agents/skills/pnpm/references/features-supply-chain-security.md
+105
View File
@@ -0,0 +1,105 @@
---
name: pnpm-supply-chain-security
description: Build-script approval (allowBuilds), minimum release age, trust policy, and exotic-subdep blocking for safer installs
---
# pnpm Supply-Chain Security
pnpm blocks several attack vectors by default. Agents installing dependencies must understand these, since installs can fail or prompt on them.
## Build-script approval (allowBuilds)
By default pnpm does **not** run dependency lifecycle scripts (`preinstall`/`install`/`postinstall`). Packages must be explicitly approved. Approval lives in one `allowBuilds` map in `pnpm-workspace.yaml`.
```yaml title="pnpm-workspace.yaml"
allowBuilds:
esbuild: true
core-js: false
# version selectors are supported
nx@21.6.4 || 21.6.5: true
```
- Packages **not listed** are unreviewed and blocked by default.
- `strictDepBuilds: true` (default) ⇒ unreviewed builds make install exit non-zero (`ERR_PNPM_IGNORED_BUILDS`). Set `false` to warn instead.
- During install, unreviewed packages with build scripts are auto-added to `pnpm-workspace.yaml` with a placeholder so you can set `true`/`false`.
> `allowBuilds` replaces the removed `onlyBuiltDependencies`, `neverBuiltDependencies`, `ignoredBuiltDependencies`, `onlyBuiltDependenciesFile`, and `ignoreDepScripts`.
### Approving builds
```bash
pnpm approve-builds # interactive prompt
pnpm approve-builds --all # approve all pending
pnpm approve-builds esbuild fsevents !core-js # ! = deny
pnpm add --allow-build=esbuild my-bundler # approve while adding
pnpm add -g --allow-build=esbuild esbuild # global (replaces approve-builds -g)
```
### Escape hatch (dangerous)
```yaml title="pnpm-workspace.yaml"
dangerouslyAllowAllBuilds: true # runs ALL build scripts now and in the future — avoid
```
## Minimum release age
Delay installing freshly published versions so malicious releases (usually pulled within an hour) are avoided. Applies to **all** deps, including transitive.
```yaml title="pnpm-workspace.yaml"
minimumReleaseAge: 1440 # minutes; default 1440 (1 day) since v11
minimumReleaseAgeExclude: # always install newest of these immediately
- webpack
- '@myorg/*'
- nx@21.6.5 # exempt a specific version
```
- `minimumReleaseAgeStrict` — when no in-range version satisfies the age, fail (default when you set `minimumReleaseAge` yourself) vs. fall back.
- `minimumReleaseAgeIgnoreMissingTime` — skip the check for registries that omit the `time` field (default `true`).
## Trust policy
Fail if a package's trust level **decreased** vs earlier releases (e.g. was published by a trusted publisher, now only has provenance or nothing).
```yaml title="pnpm-workspace.yaml"
trustPolicy: no-downgrade # off (default) | no-downgrade
trustPolicyExclude:
- 'chokidar@4.0.3'
trustPolicyIgnoreAfter: 525600 # ignore the check for pkgs published > N minutes ago
```
## Block exotic transitive sources
```yaml title="pnpm-workspace.yaml"
blockExoticSubdeps: true # default
```
When `true`, only **direct** dependencies may use exotic sources (git repos, direct tarball URLs); all transitive deps must come from a trusted source (registry, local path, workspace link, or trusted GitHub repos).
## Lockfile integrity
Since v11, a downloaded tarball whose hash doesn't match `pnpm-lock.yaml` is a hard error (`ERR_PNPM_TARBALL_INTEGRITY`) — protecting committed lockfiles from a compromised registry/proxy. `--force` and `pnpm update` do **not** bypass it.
```bash
pnpm install --update-checksums # narrow opt-in after verifying the new bytes
```
## Trusted store/cache
The content-addressable store, global virtual store, and metadata cache are part of pnpm's trust domain. Share them only between mutually trusting users/jobs and protect with filesystem permissions. `verifyStoreIntegrity` (default `true`) detects accidental corruption but does not make a writable-by-untrusted store safe.
## Key Points
- Dependency build scripts are blocked until approved via `allowBuilds` / `pnpm approve-builds`; unreviewed builds fail by default (`strictDepBuilds`).
- `minimumReleaseAge` (default 1 day in v11) delays new releases; `trustPolicy: no-downgrade` blocks trust regressions; `blockExoticSubdeps` limits transitive git/tarball sources.
- Tarball integrity mismatches are fatal; use `--update-checksums` only after verification.
- Treat the store/cache as trusted shared state.
<!--
Source references:
- https://pnpm.io/settings#allowbuilds
- https://pnpm.io/cli/approve-builds
- https://pnpm.io/settings#minimumreleaseage
- https://pnpm.io/settings#trustpolicy
- https://pnpm.io/settings#blockexoticsubdeps
- https://pnpm.io/supply-chain-security
-->
.agents/skills/unocss/references/core-config.md
+1 -1
View File
@@ -180,7 +180,7 @@ export default defineConfig({
}) })
``` ```
<!-- <!--
Source references: Source references:
- https://unocss.dev/guide/config-file - https://unocss.dev/guide/config-file
- https://unocss.dev/config/ - https://unocss.dev/config/
.agents/skills/unocss/references/core-extracting.md
+1 -1
View File
@@ -131,7 +131,7 @@ extractors: [
] ]
``` ```
<!-- <!--
Source references: Source references:
- https://unocss.dev/guide/extracting - https://unocss.dev/guide/extracting
--> -->
.agents/skills/unocss/references/core-layers.md
+3 -5
View File
@@ -45,10 +45,8 @@ outputToCssLayers: true
// Or with custom names // Or with custom names
outputToCssLayers: { outputToCssLayers: {
cssLayerName: (layer) => { cssLayerName: (layer) => {
if (layer === 'default') if (layer === 'default') return 'utilities'
return 'utilities' if (layer === 'shortcuts') return 'utilities.shortcuts'
if (layer === 'shortcuts')
return 'utilities.shortcuts'
} }
} }
``` ```
@@ -99,7 +97,7 @@ preflights: [
| `theme` | Theme CSS variables | -150 | | `theme` | Theme CSS variables | -150 |
| `base` | Reset styles | -100 | | `base` | Reset styles | -100 |
<!-- <!--
Source references: Source references:
- https://unocss.dev/config/layers - https://unocss.dev/config/layers
- https://unocss.dev/config/preflights - https://unocss.dev/config/preflights
.agents/skills/unocss/references/core-rules.md
+2 -2
View File
@@ -30,7 +30,7 @@ Use RegExp matcher with function body for flexible utilities:
rules: [ rules: [
// Match m-1, m-2, m-100, etc. // Match m-1, m-2, m-100, etc.
[/^m-(\d+)$/, ([, d]) => ({ margin: `${d / 4}rem` })], [/^m-(\d+)$/, ([, d]) => ({ margin: `${d / 4}rem` })],
// Access theme and context // Access theme and context
[/^p-(\d+)$/, (match, ctx) => ({ padding: `${match[1] / 4}rem` })], [/^p-(\d+)$/, (match, ctx) => ({ padding: `${match[1] / 4}rem` })],
] ]
@@ -160,7 +160,7 @@ Generates:
Use `symbols.noMerge` to disable. Use `symbols.noMerge` to disable.
<!-- <!--
Source references: Source references:
- https://unocss.dev/config/rules - https://unocss.dev/config/rules
--> -->
.agents/skills/unocss/references/core-safelist.md
+6 -10
View File
@@ -14,9 +14,7 @@ Utilities always included, regardless of detection:
```ts ```ts
export default defineConfig({ export default defineConfig({
safelist: [ safelist: [
'p-1', 'p-1', 'p-2', 'p-3',
'p-2',
'p-3',
// Dynamic generation // Dynamic generation
...Array.from({ length: 4 }, (_, i) => `p-${i + 1}`), ...Array.from({ length: 4 }, (_, i) => `p-${i + 1}`),
], ],
@@ -42,11 +40,9 @@ safelist: [
safelist: [ safelist: [
// Dynamic colors from CMS // Dynamic colors from CMS
() => ['primary', 'secondary'].flatMap(c => [ () => ['primary', 'secondary'].flatMap(c => [
`bg-${c}`, `bg-${c}`, `text-${c}`, `border-${c}`,
`text-${c}`,
`border-${c}`,
]), ]),
// Component variants // Component variants
() => { () => {
const variants = ['primary', 'danger'] const variants = ['primary', 'danger']
@@ -62,8 +58,8 @@ Utilities never generated:
```ts ```ts
blocklist: [ blocklist: [
'p-1', // Exact match 'p-1', // Exact match
/^p-[2-4]$/, // Regex /^p-[2-4]$/, // Regex
] ]
``` ```
@@ -102,7 +98,7 @@ const sizes = {
safelist: ['text-sm', 'text-base', 'p-2', 'p-4'] safelist: ['text-sm', 'text-base', 'p-2', 'p-4']
``` ```
<!-- <!--
Source references: Source references:
- https://unocss.dev/config/safelist - https://unocss.dev/config/safelist
- https://unocss.dev/guide/extracting - https://unocss.dev/guide/extracting
.agents/skills/unocss/references/core-shortcuts.md
+1 -1
View File
@@ -83,7 +83,7 @@ shortcutsLayer: 'my-shortcuts-layer'
- Shortcuts are expanded at build time, not runtime - Shortcuts are expanded at build time, not runtime
- All variants work with shortcuts (`hover:btn`, `dark:btn`, etc.) - All variants work with shortcuts (`hover:btn`, `dark:btn`, etc.)
<!-- <!--
Source references: Source references:
- https://unocss.dev/config/shortcuts - https://unocss.dev/config/shortcuts
--> -->
.agents/skills/unocss/references/core-theme.md
+1 -1
View File
@@ -166,7 +166,7 @@ extendTheme: (theme) => {
- `boxShadow` - Shadow definitions - `boxShadow` - Shadow definitions
- `animation` - Animation keyframes and timing - `animation` - Animation keyframes and timing
<!-- <!--
Source references: Source references:
- https://unocss.dev/config/theme - https://unocss.dev/config/theme
--> -->
.agents/skills/unocss/references/core-variants.md
+1 -1
View File
@@ -167,7 +167,7 @@ Generates:
} }
``` ```
<!-- <!--
Source references: Source references:
- https://unocss.dev/config/variants - https://unocss.dev/config/variants
- https://unocss.dev/presets/wind3 - https://unocss.dev/presets/wind3
.agents/skills/unocss/references/integrations-nuxt.md
+5 -6
View File
@@ -56,7 +56,7 @@ Use a dedicated config file for best IDE support:
```ts ```ts
// uno.config.ts // uno.config.ts
import { defineConfig, presetIcons, presetWind3 } from 'unocss' import { defineConfig, presetWind3, presetIcons } from 'unocss'
export default defineConfig({ export default defineConfig({
presets: [ presets: [
@@ -64,7 +64,7 @@ export default defineConfig({
presetIcons(), presetIcons(),
], ],
shortcuts: { shortcuts: {
btn: 'py-2 px-4 font-semibold rounded-lg', 'btn': 'py-2 px-4 font-semibold rounded-lg',
}, },
}) })
``` ```
@@ -96,13 +96,12 @@ Or extend the merged config:
```ts ```ts
// uno.config.ts // uno.config.ts
import { mergeConfigs } from '@unocss/core' import { mergeConfigs } from '@unocss/core'
import config from './.nuxt/uno.config.mjs' import config from './.nuxt/uno.config.mjs'
export default mergeConfigs([config, { export default mergeConfigs([config, {
// Your overrides // Your overrides
shortcuts: { shortcuts: {
custom: 'text-red-500', 'custom': 'text-red-500',
}, },
}]) }])
``` ```
@@ -161,7 +160,7 @@ export default defineConfig({
```vue ```vue
<template> <template>
<div class="p-4 text-center"> <div class="p-4 text-center">
<h1 class="text-3xl text-blue-600 font-bold"> <h1 class="text-3xl font-bold text-blue-600">
Hello UnoCSS! Hello UnoCSS!
</h1> </h1>
<button class="btn mt-4"> <button class="btn mt-4">
@@ -194,7 +193,7 @@ In development, visit `/_nuxt/__unocss` to access the UnoCSS inspector.
- All Vite plugin features available - All Vite plugin features available
- Nuxt layers config merging available - Nuxt layers config merging available
<!-- <!--
Source references: Source references:
- https://unocss.dev/integrations/nuxt - https://unocss.dev/integrations/nuxt
--> -->
.agents/skills/unocss/references/integrations-vite.md
+3 -5
View File
@@ -16,7 +16,6 @@ pnpm add -D unocss
```ts ```ts
// vite.config.ts // vite.config.ts
import UnoCSS from 'unocss/vite' import UnoCSS from 'unocss/vite'
import { defineConfig } from 'vite' import { defineConfig } from 'vite'
export default defineConfig({ export default defineConfig({
@@ -134,11 +133,10 @@ Works out of the box with `@vitejs/plugin-vue`.
### Svelte ### Svelte
```ts ```ts
import { svelte } from '@sveltejs/vite-plugin-svelte'
import extractorSvelte from '@unocss/extractor-svelte' import extractorSvelte from '@unocss/extractor-svelte'
import UnoCSS from 'unocss/vite' import UnoCSS from 'unocss/vite'
import { svelte } from '@sveltejs/vite-plugin-svelte'
export default { export default {
plugins: [ plugins: [
UnoCSS({ UnoCSS({
@@ -186,8 +184,8 @@ export default {
### Elm ### Elm
```ts ```ts
import UnoCSS from 'unocss/vite'
import Elm from 'vite-plugin-elm' import Elm from 'vite-plugin-elm'
import UnoCSS from 'unocss/vite'
export default { export default {
plugins: [ plugins: [
@@ -279,7 +277,7 @@ export const classes = {
} }
``` ```
<!-- <!--
Source references: Source references:
- https://unocss.dev/integrations/vite - https://unocss.dev/integrations/vite
--> -->
.agents/skills/unocss/references/preset-attributify.md
+6 -6
View File
@@ -86,12 +86,12 @@ presetAttributify({
```ts ```ts
presetAttributify({ presetAttributify({
strict: false, // Only generate CSS for attributify strict: false, // Only generate CSS for attributify
prefix: 'un-', // Attribute prefix prefix: 'un-', // Attribute prefix
prefixedOnly: false, // Require prefix for all prefixedOnly: false, // Require prefix for all
nonValuedAttribute: true, // Support valueless attributes nonValuedAttribute: true, // Support valueless attributes
ignoreAttributes: [], // Attributes to ignore ignoreAttributes: [], // Attributes to ignore
trueToNonValued: false, // Treat value="true" as valueless trueToNonValued: false, // Treat value="true" as valueless
}) })
``` ```
@@ -136,7 +136,7 @@ export default defineConfig({
**Important:** Only use attributify if `uno.config.*` shows `presetAttributify()` is enabled. **Important:** Only use attributify if `uno.config.*` shows `presetAttributify()` is enabled.
<!-- <!--
Source references: Source references:
- https://unocss.dev/presets/attributify - https://unocss.dev/presets/attributify
--> -->
.agents/skills/unocss/references/preset-icons.md
+7 -7
View File
@@ -71,16 +71,16 @@ Icons automatically choose between `mask` (monochrome) and `background-img` (col
```ts ```ts
presetIcons({ presetIcons({
scale: 1.2, // Scale relative to font size scale: 1.2, // Scale relative to font size
prefix: 'i-', // Class prefix (default) prefix: 'i-', // Class prefix (default)
mode: 'auto', // 'auto' | 'mask' | 'bg' mode: 'auto', // 'auto' | 'mask' | 'bg'
extraProperties: { extraProperties: {
'display': 'inline-block', 'display': 'inline-block',
'vertical-align': 'middle', 'vertical-align': 'middle',
}, },
warn: true, // Warn on missing icons warn: true, // Warn on missing icons
autoInstall: true, // Auto-install missing icon sets autoInstall: true, // Auto-install missing icon sets
cdn: 'https://esm.sh/', // CDN for browser usage cdn: 'https://esm.sh/', // CDN for browser usage
}) })
``` ```
@@ -178,7 +178,7 @@ Use `icon()` in CSS (requires transformer-directives):
</a> </a>
``` ```
<!-- <!--
Source references: Source references:
- https://unocss.dev/presets/icons - https://unocss.dev/presets/icons
--> -->
.agents/skills/unocss/references/preset-mini.md
+7 -8
View File
@@ -116,16 +116,16 @@ presetMini({
presetMini({ presetMini({
// Dark mode: 'class' | 'media' | { light: string, dark: string } // Dark mode: 'class' | 'media' | { light: string, dark: string }
dark: 'class', dark: 'class',
// Generate [group=""] instead of .group for attributify // Generate [group=""] instead of .group for attributify
attributifyPseudo: false, attributifyPseudo: false,
// CSS variable prefix (default: 'un-') // CSS variable prefix (default: 'un-')
variablePrefix: 'un-', variablePrefix: 'un-',
// Utility prefix // Utility prefix
prefix: undefined, prefix: undefined,
// Preflight generation: true | false | 'on-demand' // Preflight generation: true | false | 'on-demand'
preflight: true, preflight: true,
}) })
@@ -136,9 +136,8 @@ presetMini({
Create custom preset extending mini: Create custom preset extending mini:
```ts ```ts
import type { Preset } from 'unocss'
import { presetMini } from 'unocss' import { presetMini } from 'unocss'
import type { Preset } from 'unocss'
export const myPreset: Preset = { export const myPreset: Preset = {
name: 'my-preset', name: 'my-preset',
@@ -148,12 +147,12 @@ export const myPreset: Preset = {
['card', { 'border-radius': '8px', 'box-shadow': '0 2px 8px rgba(0,0,0,0.1)' }], ['card', { 'border-radius': '8px', 'box-shadow': '0 2px 8px rgba(0,0,0,0.1)' }],
], ],
shortcuts: { shortcuts: {
btn: 'px-4 py-2 rounded bg-blue-500 text-white', 'btn': 'px-4 py-2 rounded bg-blue-500 text-white',
}, },
} }
``` ```
<!-- <!--
Source references: Source references:
- https://unocss.dev/presets/mini - https://unocss.dev/presets/mini
--> -->
.agents/skills/unocss/references/preset-rem-to-px.md
+1 -1
View File
@@ -90,7 +90,7 @@ export default defineConfig({
- Affects all utilities with rem units - Affects all utilities with rem units
- Theme values in rem are also converted - Theme values in rem are also converted
<!-- <!--
Source references: Source references:
- https://unocss.dev/presets/rem-to-px - https://unocss.dev/presets/rem-to-px
- https://unocss.dev/presets/wind4 - https://unocss.dev/presets/wind4
.agents/skills/unocss/references/preset-tagify.md
+6 -6
View File
@@ -82,13 +82,13 @@ presetTagify({
presetTagify({ presetTagify({
// Tag prefix // Tag prefix
prefix: '', prefix: '',
// Excluded tags (won't be processed) // Excluded tags (won't be processed)
excludedTags: ['b', /^h\d+$/, 'table'], excludedTags: ['b', /^h\d+$/, 'table'],
// Extra CSS properties // Extra CSS properties
extraProperties: {}, extraProperties: {},
// Enable default extractor // Enable default extractor
defaultExtractor: true, defaultExtractor: true,
}) })
@@ -109,8 +109,8 @@ presetTagify({
'b', 'b',
/^h\d+$/, /^h\d+$/,
'table', 'table',
'article', // Add custom exclusions 'article', // Add custom exclusions
/^my-/, // Exclude tags starting with 'my-' /^my-/, // Exclude tags starting with 'my-'
], ],
}) })
``` ```
@@ -128,7 +128,7 @@ presetTagify({
- Some frameworks may not support all custom elements - Some frameworks may not support all custom elements
- Utilities without hyphens need the prefix option - Utilities without hyphens need the prefix option
<!-- <!--
Source references: Source references:
- https://unocss.dev/presets/tagify - https://unocss.dev/presets/tagify
--> -->
.agents/skills/unocss/references/preset-typography.md
+3 -3
View File
@@ -79,9 +79,9 @@ Responsive:
```ts ```ts
presetTypography({ presetTypography({
selectorName: 'prose', // Custom selector selectorName: 'prose', // Custom selector
cssVarPrefix: '--un-prose', // CSS variable prefix cssVarPrefix: '--un-prose', // CSS variable prefix
important: false, // Make !important important: false, // Make !important
cssExtend: { cssExtend: {
'code': { color: '#8b5cf6' }, 'code': { color: '#8b5cf6' },
'a:hover': { color: '#f43f5e' }, 'a:hover': { color: '#f43f5e' },
@@ -89,7 +89,7 @@ presetTypography({
}) })
``` ```
<!-- <!--
Source references: Source references:
- https://unocss.dev/presets/typography - https://unocss.dev/presets/typography
--> -->
.agents/skills/unocss/references/preset-web-fonts.md
+3 -3
View File
@@ -41,10 +41,10 @@ export default defineConfig({
fonts: { fonts: {
// Simple // Simple
sans: 'Roboto', sans: 'Roboto',
// Multiple (fallback) // Multiple (fallback)
mono: ['Fira Code', 'Fira Mono:400,700'], mono: ['Fira Code', 'Fira Mono:400,700'],
// Detailed // Detailed
lato: [ lato: [
{ {
@@ -85,7 +85,7 @@ presetWebFonts({
}) })
``` ```
<!-- <!--
Source references: Source references:
- https://unocss.dev/presets/web-fonts - https://unocss.dev/presets/web-fonts
--> -->
.agents/skills/unocss/references/preset-wind3.md
+6 -6
View File
@@ -63,19 +63,19 @@ Use `@dark:` regardless of config:
presetWind3({ presetWind3({
// Dark mode strategy // Dark mode strategy
dark: 'class', // 'class' | 'media' | { light: '.light', dark: '.dark' } dark: 'class', // 'class' | 'media' | { light: '.light', dark: '.dark' }
// Generate pseudo selector as [group=""] instead of .group // Generate pseudo selector as [group=""] instead of .group
attributifyPseudo: false, attributifyPseudo: false,
// CSS custom properties prefix // CSS custom properties prefix
variablePrefix: 'un-', variablePrefix: 'un-',
// Utils prefix // Utils prefix
prefix: '', prefix: '',
// Generate preflight CSS // Generate preflight CSS
preflight: true, // true | false | 'on-demand' preflight: true, // true | false | 'on-demand'
// Mark all utilities as !important // Mark all utilities as !important
important: false, // boolean | string (selector) important: false, // boolean | string (selector)
}) })
@@ -188,7 +188,7 @@ Generates:
} }
``` ```
<!-- <!--
Source references: Source references:
- https://unocss.dev/presets/wind3 - https://unocss.dev/presets/wind3
--> -->
.agents/skills/unocss/references/preset-wind4.md
+3 -3
View File
@@ -92,10 +92,10 @@ presetWind4({
preflights: { preflights: {
// Built-in reset styles // Built-in reset styles
reset: true, reset: true,
// Theme CSS variables generation // Theme CSS variables generation
theme: 'on-demand', // true | false | 'on-demand' theme: 'on-demand', // true | false | 'on-demand'
// @property CSS rules // @property CSS rules
property: true, property: true,
}, },
@@ -241,7 +241,7 @@ Choose **preset-wind3** when:
- Using presetLegacyCompat - Using presetLegacyCompat
- Want stable, proven preset - Want stable, proven preset
<!-- <!--
Source references: Source references:
- https://unocss.dev/presets/wind4 - https://unocss.dev/presets/wind4
--> -->
.agents/skills/unocss/references/transformer-attributify-jsx.md
+9 -9
View File
@@ -24,10 +24,10 @@ The `={true}` breaks UnoCSS attributify detection.
## Installation ## Installation
```ts ```ts
import { import {
defineConfig, defineConfig,
presetAttributify, presetAttributify,
transformerAttributifyJsx transformerAttributifyJsx
} from 'unocss' } from 'unocss'
export default defineConfig({ export default defineConfig({
@@ -101,11 +101,11 @@ export default {
```ts ```ts
// uno.config.ts // uno.config.ts
import { import {
defineConfig, defineConfig,
presetAttributify, presetAttributify,
presetWind3, presetWind3,
transformerAttributifyJsx transformerAttributifyJsx
} from 'unocss' } from 'unocss'
export default defineConfig({ export default defineConfig({
@@ -150,7 +150,7 @@ declare module 'react' {
} }
``` ```
<!-- <!--
Source references: Source references:
- https://unocss.dev/transformers/attributify-jsx - https://unocss.dev/transformers/attributify-jsx
--> -->
.agents/skills/unocss/references/transformer-compile-class.md
+7 -7
View File
@@ -63,13 +63,13 @@ Add `:uno:` prefix to mark classes for compilation:
transformerCompileClass({ transformerCompileClass({
// Custom trigger string (default: ':uno:') // Custom trigger string (default: ':uno:')
trigger: ':uno:', trigger: ':uno:',
// Custom class prefix (default: 'uno-') // Custom class prefix (default: 'uno-')
classPrefix: 'uno-', classPrefix: 'uno-',
// Hash function for class names // Hash function for class names
hashFn: (str) => /* custom hash */, hashFn: (str) => /* custom hash */,
// Keep original classes alongside compiled // Keep original classes alongside compiled
keepOriginal: false, keepOriginal: false,
}) })
@@ -115,14 +115,14 @@ Options:
```ts ```ts
export default defineConfig({ export default defineConfig({
transformers: [ transformers: [
transformerVariantGroup(), // Process variant groups first transformerVariantGroup(), // Process variant groups first
transformerDirectives(), // Then directives transformerDirectives(), // Then directives
transformerCompileClass(), // Compile last transformerCompileClass(), // Compile last
], ],
}) })
``` ```
<!-- <!--
Source references: Source references:
- https://unocss.dev/transformers/compile-class - https://unocss.dev/transformers/compile-class
--> -->
.agents/skills/unocss/references/transformer-directives.md
+1 -1
View File
@@ -151,7 +151,7 @@ Convert icon utility to SVG (requires preset-icons):
} }
``` ```
<!-- <!--
Source references: Source references:
- https://unocss.dev/transformers/directives - https://unocss.dev/transformers/directives
--> -->
.agents/skills/unocss/references/transformer-variant-group.md
+1 -1
View File
@@ -91,7 +91,7 @@ Expands to: `text-sm text-gray-600 font-medium font-mono`
- Nesting is supported - Nesting is supported
- Works in class attributes and other extraction sources - Works in class attributes and other extraction sources
<!-- <!--
Source references: Source references:
- https://unocss.dev/transformers/variant-group - https://unocss.dev/transformers/variant-group
--> -->
.agents/skills/vue-best-practices/SYNC.md
+1 -1
View File
@@ -2,4 +2,4 @@
- **Source:** `vendor/vuejs-ai/skills/vue-best-practices` - **Source:** `vendor/vuejs-ai/skills/vue-best-practices`
- **Git SHA:** `f3dd1bf4d3ac78331bdc903e4519d561c538ca6a` - **Git SHA:** `f3dd1bf4d3ac78331bdc903e4519d561c538ca6a`
- **Synced:** 2026-03-13 - **Synced:** 2026-03-16
.agents/skills/vue-best-practices/references/animation-class-based-technique.md
+43 -45
View File
@@ -31,6 +31,13 @@ tags: [vue3, animation, css, class-binding, state]
## Basic Pattern ## Basic Pattern
```vue ```vue
<template>
<div :class="{ shake: showError }">
<button @click="submitForm">Submit</button>
<span v-if="showError">This feature is disabled!</span>
</div>
</template>
<script setup> <script setup>
import { ref } from 'vue' import { ref } from 'vue'
@@ -44,20 +51,11 @@ function submitForm() {
// Auto-remove class after animation completes // Auto-remove class after animation completes
setTimeout(() => { setTimeout(() => {
showError.value = false showError.value = false
}, 820) // Match animation duration }, 820) // Match animation duration
} }
} }
</script> </script>
<template>
<div :class="{ shake: showError }">
<button @click="submitForm">
Submit
</button>
<span v-if="showError">This feature is disabled!</span>
</div>
</template>
<style> <style>
.shake { .shake {
animation: shake 0.82s cubic-bezier(0.36, 0.07, 0.19, 0.97) both; animation: shake 0.82s cubic-bezier(0.36, 0.07, 0.19, 0.97) both;
@@ -78,6 +76,15 @@ function submitForm() {
### Pulse on Success ### Pulse on Success
```vue ```vue
<template>
<button
@click="save"
:class="{ pulse: saved }"
>
{{ saved ? 'Saved!' : 'Save' }}
</button>
</template>
<script setup> <script setup>
import { ref } from 'vue' import { ref } from 'vue'
@@ -90,15 +97,6 @@ async function save() {
} }
</script> </script>
<template>
<button
:class="{ pulse: saved }"
@click="save"
>
{{ saved ? 'Saved!' : 'Save' }}
</button>
</template>
<style> <style>
.pulse { .pulse {
animation: pulse 0.5s ease-in-out; animation: pulse 0.5s ease-in-out;
@@ -114,6 +112,14 @@ async function save() {
### Highlight on Change ### Highlight on Change
```vue ```vue
<template>
<div
:class="{ highlight: justUpdated }"
>
Value: {{ value }}
</div>
</template>
<script setup> <script setup>
import { ref, watch } from 'vue' import { ref, watch } from 'vue'
@@ -126,14 +132,6 @@ watch(value, () => {
}) })
</script> </script>
<template>
<div
:class="{ highlight: justUpdated }"
>
Value: {{ value }}
</div>
</template>
<style> <style>
.highlight { .highlight {
animation: highlight 1s ease-out; animation: highlight 1s ease-out;
@@ -149,6 +147,15 @@ watch(value, () => {
### Bounce Attention ### Bounce Attention
```vue ```vue
<template>
<div
:class="{ bounce: needsAttention }"
@animationend="needsAttention = false"
>
<BellIcon />
</div>
</template>
<script setup> <script setup>
import { ref } from 'vue' import { ref } from 'vue'
@@ -160,15 +167,6 @@ function notifyUser() {
} }
</script> </script>
<template>
<div
:class="{ bounce: needsAttention }"
@animationend="needsAttention = false"
>
<BellIcon />
</div>
</template>
<style> <style>
.bounce { .bounce {
animation: bounce 0.5s ease; animation: bounce 0.5s ease;
@@ -186,6 +184,15 @@ function notifyUser() {
Instead of `setTimeout`, use the `animationend` event for cleaner code: Instead of `setTimeout`, use the `animationend` event for cleaner code:
```vue ```vue
<template>
<div
:class="{ animate: isAnimating }"
@animationend="isAnimating = false"
>
Content
</div>
</template>
<script setup> <script setup>
import { ref } from 'vue' import { ref } from 'vue'
@@ -196,15 +203,6 @@ function triggerAnimation() {
// Class is automatically removed when animation ends // Class is automatically removed when animation ends
} }
</script> </script>
<template>
<div
:class="{ animate: isAnimating }"
@animationend="isAnimating = false"
>
Content
</div>
</template>
``` ```
## Composable for Reusable Animations ## Composable for Reusable Animations
.agents/skills/vue-best-practices/references/animation-state-driven-technique.md
+69 -74
View File
@@ -20,6 +20,17 @@ tags: [vue3, animation, css, transition, style-binding, state, interactive]
## Basic Pattern ## Basic Pattern
```vue ```vue
<template>
<div
@mousemove="onMousemove"
:style="{ backgroundColor: `hsl(${hue}, 80%, 50%)` }"
class="interactive-area"
>
<p>Move your mouse across this div...</p>
<p>Hue: {{ hue }}</p>
</div>
</template>
<script setup> <script setup>
import { ref } from 'vue' import { ref } from 'vue'
@@ -32,17 +43,6 @@ function onMousemove(e) {
} }
</script> </script>
<template>
<div
:style="{ backgroundColor: `hsl(${hue}, 80%, 50%)` }"
class="interactive-area"
@mousemove="onMousemove"
>
<p>Move your mouse across this div...</p>
<p>Hue: {{ hue }}</p>
</div>
</template>
<style> <style>
.interactive-area { .interactive-area {
transition: background-color 0.3s ease; transition: background-color 0.3s ease;
@@ -60,6 +60,20 @@ function onMousemove(e) {
### Following Mouse Position ### Following Mouse Position
```vue ```vue
<template>
<div
class="container"
@mousemove="onMousemove"
>
<div
class="follower"
:style="{
transform: `translate(${x}px, ${y}px)`
}"
/>
</div>
</template>
<script setup> <script setup>
import { ref } from 'vue' import { ref } from 'vue'
@@ -73,20 +87,6 @@ function onMousemove(e) {
} }
</script> </script>
<template>
<div
class="container"
@mousemove="onMousemove"
>
<div
class="follower"
:style="{
transform: `translate(${x}px, ${y}px)`,
}"
/>
</div>
</template>
<style> <style>
.container { .container {
position: relative; position: relative;
@@ -110,12 +110,6 @@ function onMousemove(e) {
### Progress Animation ### Progress Animation
```vue ```vue
<script setup>
import { ref } from 'vue'
const progress = ref(0)
</script>
<template> <template>
<div class="progress-container"> <div class="progress-container">
<div <div
@@ -124,13 +118,19 @@ const progress = ref(0)
/> />
</div> </div>
<input <input
v-model.number="progress"
type="range" type="range"
v-model.number="progress"
min="0" min="0"
max="100" max="100"
> />
</template> </template>
<script setup>
import { ref } from 'vue'
const progress = ref(0)
</script>
<style> <style>
.progress-container { .progress-container {
height: 20px; height: 20px;
@@ -150,8 +150,20 @@ const progress = ref(0)
### Scroll-based Animation ### Scroll-based Animation
```vue ```vue
<template>
<div
class="hero"
:style="{
opacity: heroOpacity,
transform: `translateY(${scrollOffset}px)`
}"
>
<h1>Scroll Down</h1>
</div>
</template>
<script setup> <script setup>
import { computed, onMounted, onUnmounted, ref } from 'vue' import { ref, computed, onMounted, onUnmounted } from 'vue'
const scrollY = ref(0) const scrollY = ref(0)
@@ -160,7 +172,7 @@ const heroOpacity = computed(() => {
}) })
const scrollOffset = computed(() => { const scrollOffset = computed(() => {
return scrollY.value * 0.5 // Parallax effect return scrollY.value * 0.5 // Parallax effect
}) })
function handleScroll() { function handleScroll() {
@@ -176,18 +188,6 @@ onUnmounted(() => {
}) })
</script> </script>
<template>
<div
class="hero"
:style="{
opacity: heroOpacity,
transform: `translateY(${scrollOffset}px)`,
}"
>
<h1>Scroll Down</h1>
</div>
</template>
<style> <style>
.hero { .hero {
height: 100vh; height: 100vh;
@@ -202,16 +202,26 @@ onUnmounted(() => {
### Color Theme Transition ### Color Theme Transition
```vue ```vue
<template>
<div
class="app"
:style="themeStyles"
>
<button @click="toggleTheme">Toggle Theme</button>
<p>Current theme: {{ isDark ? 'Dark' : 'Light' }}</p>
</div>
</template>
<script setup> <script setup>
import { computed, ref } from 'vue' import { ref, computed } from 'vue'
const isDark = ref(false) const isDark = ref(false)
const themeStyles = computed(() => ({ const themeStyles = computed(() => ({
'--bg-color': isDark.value ? '#1a1a1a' : '#ffffff', '--bg-color': isDark.value ? '#1a1a1a' : '#ffffff',
'--text-color': isDark.value ? '#ffffff' : '#1a1a1a', '--text-color': isDark.value ? '#ffffff' : '#1a1a1a',
'backgroundColor': 'var(--bg-color)', backgroundColor: 'var(--bg-color)',
'color': 'var(--text-color)' color: 'var(--text-color)'
})) }))
function toggleTheme() { function toggleTheme() {
@@ -219,18 +229,6 @@ function toggleTheme() {
} }
</script> </script>
<template>
<div
class="app"
:style="themeStyles"
>
<button @click="toggleTheme">
Toggle Theme
</button>
<p>Current theme: {{ isDark ? 'Dark' : 'Light' }}</p>
</div>
</template>
<style> <style>
.app { .app {
min-height: 100vh; min-height: 100vh;
@@ -244,10 +242,16 @@ function toggleTheme() {
For smooth number animations (counters, stats), use watchers with animation libraries: For smooth number animations (counters, stats), use watchers with animation libraries:
```vue ```vue
<script setup> <template>
import gsap from 'gsap' <div>
<input v-model.number="targetNumber" type="number" />
<p class="counter">{{ displayNumber.toFixed(0) }}</p>
</div>
</template>
import { computed, reactive, ref, watch } from 'vue' <script setup>
import { computed, ref, reactive, watch } from 'vue'
import gsap from 'gsap'
const targetNumber = ref(0) const targetNumber = ref(0)
const tweened = reactive({ value: 0 }) const tweened = reactive({ value: 0 })
@@ -263,15 +267,6 @@ watch(targetNumber, (newValue) => {
}) })
}) })
</script> </script>
<template>
<div>
<input v-model.number="targetNumber" type="number">
<p class="counter">
{{ displayNumber.toFixed(0) }}
</p>
</div>
</template>
``` ```
## Performance Considerations ## Performance Considerations
.agents/skills/vue-best-practices/references/component-async.md
+3 -5
View File
@@ -37,8 +37,8 @@ const AsyncComments = defineAsyncComponent({
<script setup lang="ts"> <script setup lang="ts">
import { import {
defineAsyncComponent, defineAsyncComponent,
hydrateOnIdle, hydrateOnVisible,
hydrateOnVisible hydrateOnIdle
} from 'vue' } from 'vue'
const AsyncComments = defineAsyncComponent({ const AsyncComments = defineAsyncComponent({
@@ -61,7 +61,6 @@ Avoid showing loading UI immediately for components that usually resolve quickly
```vue ```vue
<script setup lang="ts"> <script setup lang="ts">
import { defineAsyncComponent } from 'vue' import { defineAsyncComponent } from 'vue'
import LoadingSpinner from './LoadingSpinner.vue' import LoadingSpinner from './LoadingSpinner.vue'
const AsyncDashboard = defineAsyncComponent({ const AsyncDashboard = defineAsyncComponent({
@@ -76,9 +75,8 @@ const AsyncDashboard = defineAsyncComponent({
```vue ```vue
<script setup lang="ts"> <script setup lang="ts">
import { defineAsyncComponent } from 'vue' import { defineAsyncComponent } from 'vue'
import ErrorDisplay from './ErrorDisplay.vue'
import LoadingSpinner from './LoadingSpinner.vue' import LoadingSpinner from './LoadingSpinner.vue'
import ErrorDisplay from './ErrorDisplay.vue'
const AsyncDashboard = defineAsyncComponent({ const AsyncDashboard = defineAsyncComponent({
loader: () => import('./Dashboard.vue'), loader: () => import('./Dashboard.vue'),
.agents/skills/vue-best-practices/references/component-data-flow.md
+10 -17
View File
@@ -49,7 +49,6 @@ If state needs to change, emit an event, use `v-model` or create a local copy.
```vue ```vue
<script setup> <script setup>
import { ref } from 'vue' import { ref } from 'vue'
import UserForm from './UserForm.vue' import UserForm from './UserForm.vue'
const formRef = ref(null) const formRef = ref(null)
@@ -63,9 +62,7 @@ function submitForm() {
<template> <template>
<UserForm ref="formRef" /> <UserForm ref="formRef" />
<button @click="submitForm"> <button @click="submitForm">Submit</button>
Submit
</button>
</template> </template>
``` ```
@@ -91,8 +88,7 @@ Prefer props/emits by default. When a parent must call an exposed child method,
**BAD:** **BAD:**
```vue ```vue
<script setup lang="ts"> <script setup lang="ts">
import { onMounted, ref } from 'vue' import { ref, onMounted } from 'vue'
import DialogPanel from './DialogPanel.vue' import DialogPanel from './DialogPanel.vue'
const panelRef = ref(null) const panelRef = ref(null)
@@ -121,7 +117,6 @@ defineExpose({ open })
<!-- Parent.vue --> <!-- Parent.vue -->
<script setup lang="ts"> <script setup lang="ts">
import { onMounted, useTemplateRef } from 'vue' import { onMounted, useTemplateRef } from 'vue'
import DialogPanel from './DialogPanel.vue' import DialogPanel from './DialogPanel.vue'
// Vue 3.5+ with useTemplateRef // Vue 3.5+ with useTemplateRef
@@ -188,7 +183,7 @@ const props = defineProps({ value: String })
</script> </script>
<template> <template>
<input :value="props.value" @input="$emit('input', $event.target.value)"> <input :value="props.value" @input="$emit('input', $event.target.value)" />
</template> </template>
``` ```
@@ -199,7 +194,7 @@ const model = defineModel({ type: String })
</script> </script>
<template> <template>
<input v-model="model"> <input v-model="model" />
</template> </template>
``` ```
@@ -214,7 +209,7 @@ const emit = defineEmits(['update:modelValue'])
<input <input
:value="props.modelValue" :value="props.modelValue"
@input="emit('update:modelValue', $event.target.value)" @input="emit('update:modelValue', $event.target.value)"
> />
</template> </template>
``` ```
@@ -282,28 +277,26 @@ settings?.theme = 'dark'
**GOOD:** **GOOD:**
```vue ```vue
<script setup lang="ts"> <script setup lang="ts">
import type { InjectionKey } from 'vue'
import { inject, provide } from 'vue' import { inject, provide } from 'vue'
import type { InjectionKey } from 'vue'
interface Props { interface Props {
userId: string userId: string
} }
interface Emits { interface Emits {
save: [payload: { id: string, draft: boolean }] save: [payload: { id: string; draft: boolean }]
} }
interface Settings { interface Settings {
theme: 'light' | 'dark' theme: 'light' | 'dark'
} }
const props = defineProps<Props>()
const emit = defineEmits<Emits>()
const settingsKey: InjectionKey<Settings> = Symbol('settings') const settingsKey: InjectionKey<Settings> = Symbol('settings')
const props = defineProps<Props>()
const emit = defineEmits<Emits>()
provide(settingsKey, { theme: 'light' }) provide(settingsKey, { theme: 'light' })
const settings = inject(settingsKey) const settings = inject(settingsKey)
.agents/skills/vue-best-practices/references/component-fallthrough-attrs.md
+5 -5
View File
@@ -29,10 +29,10 @@ import { useAttrs } from 'vue'
const attrs = useAttrs() const attrs = useAttrs()
console.log(attrs.data - testid) // Syntax error console.log(attrs.data-testid) // Syntax error
console.log(attrs.dataTestid) // undefined for data-testid console.log(attrs.dataTestid) // undefined for data-testid
console.log(attrs['on-click']) // undefined console.log(attrs['on-click']) // undefined
console.log(attrs['@click']) // undefined console.log(attrs['@click']) // undefined
</script> </script>
``` ```
@@ -72,7 +72,7 @@ console.log(attrs.onMouseEnter)
**BAD:** **BAD:**
```vue ```vue
<script setup> <script setup>
import { useAttrs, watch, watchEffect } from 'vue' import { watch, watchEffect, useAttrs } from 'vue'
const attrs = useAttrs() const attrs = useAttrs()
.agents/skills/vue-best-practices/references/component-keep-alive.md
+1 -1
View File
@@ -85,7 +85,7 @@ Vue 3 has no direct API to remove a specific cached instance. Use keys or dynami
```vue ```vue
<script setup> <script setup>
import { reactive, ref } from 'vue' import { ref, reactive } from 'vue'
const currentView = ref('Dashboard') const currentView = ref('Dashboard')
const viewKeys = reactive({ Dashboard: 0, Settings: 0 }) const viewKeys = reactive({ Dashboard: 0, Settings: 0 })
.agents/skills/vue-best-practices/references/component-slots.md
+4 -4
View File
@@ -115,8 +115,8 @@ interface Product {
defineProps<{ products: Product[] }>() defineProps<{ products: Product[] }>()
defineSlots<{ defineSlots<{
default: (props: { product: Product, index: number }) => any default(props: { product: Product; index: number }): any
empty: () => any empty(): any
}>() }>()
</script> </script>
@@ -162,7 +162,7 @@ Renderless components are still useful for slot-driven composition, but composab
```vue ```vue
<!-- MouseTracker.vue --> <!-- MouseTracker.vue -->
<script setup lang="ts"> <script setup lang="ts">
import { onMounted, onUnmounted, ref } from 'vue' import { ref, onMounted, onUnmounted } from 'vue'
const x = ref(0) const x = ref(0)
const y = ref(0) const y = ref(0)
@@ -184,7 +184,7 @@ onUnmounted(() => window.removeEventListener('mousemove', onMove))
**GOOD:** **GOOD:**
```ts ```ts
// composables/useMouse.ts // composables/useMouse.ts
import { onMounted, onUnmounted, ref } from 'vue' import { ref, onMounted, onUnmounted } from 'vue'
export function useMouse() { export function useMouse() {
const x = ref(0) const x = ref(0)
.agents/skills/vue-best-practices/references/component-suspense.md
+7 -17
View File
@@ -132,15 +132,11 @@ Nested Suspense boundaries need `suspensible` on the inner boundary so the paren
<LayoutShell> <LayoutShell>
<Suspense> <Suspense>
<AsyncWidget /> <AsyncWidget />
<template #fallback> <template #fallback>Loading widget...</template>
Loading widget...
</template>
</Suspense> </Suspense>
</LayoutShell> </LayoutShell>
<template #fallback> <template #fallback>Loading layout...</template>
Loading layout...
</template>
</Suspense> </Suspense>
</template> </template>
``` ```
@@ -152,15 +148,11 @@ Nested Suspense boundaries need `suspensible` on the inner boundary so the paren
<LayoutShell> <LayoutShell>
<Suspense suspensible> <Suspense suspensible>
<AsyncWidget /> <AsyncWidget />
<template #fallback> <template #fallback>Loading widget...</template>
Loading widget...
</template>
</Suspense> </Suspense>
</LayoutShell> </LayoutShell>
<template #fallback> <template #fallback>Loading layout...</template>
Loading layout...
</template>
</Suspense> </Suspense>
</template> </template>
``` ```
@@ -175,11 +167,11 @@ import { ref } from 'vue'
const isLoading = ref(false) const isLoading = ref(false)
function onPending() { const onPending = () => {
isLoading.value = true isLoading.value = true
} }
function onResolve() { const onResolve = () => {
isLoading.value = false isLoading.value = false
} }
</script> </script>
@@ -223,9 +215,7 @@ When combining these components, the nesting order should be `RouterView` -> `Tr
<KeepAlive> <KeepAlive>
<Suspense> <Suspense>
<component :is="Component" /> <component :is="Component" />
<template #fallback> <template #fallback>Loading...</template>
Loading...
</template>
</Suspense> </Suspense>
</KeepAlive> </KeepAlive>
</Transition> </Transition>
.agents/skills/vue-best-practices/references/component-teleport.md
+5 -15
View File
@@ -26,14 +26,10 @@ When an ancestor has `transform`, `filter`, or `perspective`, fixed-position ove
```vue ```vue
<template> <template>
<div class="animated-container"> <div class="animated-container">
<button @click="open = true"> <button @click="open = true">Open</button>
Open
</button>
<!-- Broken: fixed positioning is scoped to the transformed parent --> <!-- Broken: fixed positioning is scoped to the transformed parent -->
<div v-if="open" class="modal"> <div v-if="open" class="modal">Modal</div>
Modal
</div>
</div> </div>
</template> </template>
@@ -54,14 +50,10 @@ When an ancestor has `transform`, `filter`, or `perspective`, fixed-position ove
```vue ```vue
<template> <template>
<div class="animated-container"> <div class="animated-container">
<button @click="open = true"> <button @click="open = true">Open</button>
Open
</button>
<Teleport to="body"> <Teleport to="body">
<div v-if="open" class="modal"> <div v-if="open" class="modal">Modal</div>
Modal
</div>
</Teleport> </Teleport>
</div> </div>
</template> </template>
@@ -80,9 +72,7 @@ const isMobile = useMediaQuery('(max-width: 768px)')
<template> <template>
<Teleport to="body" :disabled="isMobile"> <Teleport to="body" :disabled="isMobile">
<nav class="sidebar"> <nav class="sidebar">Navigation</nav>
Navigation
</nav>
</Teleport> </Teleport>
</template> </template>
``` ```
.agents/skills/vue-best-practices/references/component-transition-group.md
+14 -16
View File
@@ -77,9 +77,7 @@ Keys are required. Without stable keys, Vue cannot track item positions and anim
```vue ```vue
<template> <template>
<TransitionGroup name="list" tag="div" mode="out-in"> <TransitionGroup name="list" tag="div" mode="out-in">
<div v-for="item in items" :key="item.id"> <div v-for="item in items" :key="item.id">{{ item.name }}</div>
{{ item.name }}
</div>
</TransitionGroup> </TransitionGroup>
</template> </template>
``` ```
@@ -98,6 +96,19 @@ Keys are required. Without stable keys, Vue cannot track item positions and anim
For cascading list animations, pass the index to JavaScript hooks and compute delay per item. For cascading list animations, pass the index to JavaScript hooks and compute delay per item.
```vue ```vue
<template>
<TransitionGroup
tag="ul"
:css="false"
@before-enter="onBeforeEnter"
@enter="onEnter"
>
<li v-for="(item, index) in items" :key="item.id" :data-index="index">
{{ item.name }}
</li>
</TransitionGroup>
</template>
<script setup> <script setup>
function onBeforeEnter(el) { function onBeforeEnter(el) {
el.style.opacity = 0 el.style.opacity = 0
@@ -114,17 +125,4 @@ function onEnter(el, done) {
}, delay) }, delay)
} }
</script> </script>
<template>
<TransitionGroup
tag="ul"
:css="false"
@before-enter="onBeforeEnter"
@enter="onEnter"
>
<li v-for="(item, index) in items" :key="item.id" :data-index="index">
{{ item.name }}
</li>
</TransitionGroup>
</template>
``` ```
.agents/skills/vue-best-practices/references/component-transition.md
+4 -12
View File
@@ -51,12 +51,8 @@ Vue reuses the same DOM element when the tag type does not change. Add `key` so
```vue ```vue
<template> <template>
<Transition name="fade"> <Transition name="fade">
<p v-if="isActive"> <p v-if="isActive">Active</p>
Active <p v-else>Inactive</p>
</p>
<p v-else>
Inactive
</p>
</Transition> </Transition>
</template> </template>
``` ```
@@ -65,12 +61,8 @@ Vue reuses the same DOM element when the tag type does not change. Add `key` so
```vue ```vue
<template> <template>
<Transition name="fade" mode="out-in"> <Transition name="fade" mode="out-in">
<p v-if="isActive" key="active"> <p v-if="isActive" key="active">Active</p>
Active <p v-else key="inactive">Inactive</p>
</p>
<p v-else key="inactive">
Inactive
</p>
</Transition> </Transition>
</template> </template>
``` ```
.agents/skills/vue-best-practices/references/composables.md
+13 -19
View File
@@ -23,7 +23,7 @@ tags: [vue3, composables, composition-api, code-organization, api-design, readon
**BAD:** **BAD:**
```vue ```vue
<script setup> <script setup>
import { computed, onMounted, onUnmounted, ref } from 'vue' import { ref, computed, onMounted, onUnmounted } from 'vue'
const x = ref(0) const x = ref(0)
const y = ref(0) const y = ref(0)
@@ -33,11 +33,10 @@ const el = ref(null)
function onMove(e) { function onMove(e) {
x.value = e.pageX x.value = e.pageX
y.value = e.pageY y.value = e.pageY
if (!el.value) if (!el.value) return
return
const r = el.value.getBoundingClientRect() const r = el.value.getBoundingClientRect()
inside.value = x.value >= r.left && x.value <= r.right inside.value = x.value >= r.left && x.value <= r.right &&
&& y.value >= r.top && y.value <= r.bottom y.value >= r.top && y.value <= r.bottom
} }
onMounted(() => window.addEventListener('mousemove', onMove)) onMounted(() => window.addEventListener('mousemove', onMove))
@@ -59,7 +58,6 @@ export function useEventListener(target, event, callback) {
```javascript ```javascript
// composables/useMouse.js // composables/useMouse.js
import { ref } from 'vue' import { ref } from 'vue'
import { useEventListener } from './useEventListener' import { useEventListener } from './useEventListener'
export function useMouse() { export function useMouse() {
@@ -78,18 +76,16 @@ export function useMouse() {
```javascript ```javascript
// composables/useMouseInElement.js // composables/useMouseInElement.js
import { computed } from 'vue' import { computed } from 'vue'
import { useMouse } from './useMouse' import { useMouse } from './useMouse'
export function useMouseInElement(elementRef) { export function useMouseInElement(elementRef) {
const { x, y } = useMouse() const { x, y } = useMouse()
const isOutside = computed(() => { const isOutside = computed(() => {
if (!elementRef.value) if (!elementRef.value) return true
return true
const rect = elementRef.value.getBoundingClientRect() const rect = elementRef.value.getBoundingClientRect()
return x.value < rect.left || x.value > rect.right return x.value < rect.left || x.value > rect.right ||
|| y.value < rect.top || y.value > rect.bottom y.value < rect.top || y.value > rect.bottom
}) })
return { x, y, isOutside } return { x, y, isOutside }
@@ -159,7 +155,7 @@ items.value.push({ id: 1, price: 10 })
**GOOD:** **GOOD:**
```javascript ```javascript
import { computed, readonly, ref } from 'vue' import { ref, computed, readonly } from 'vue'
export function useCart() { export function useCart() {
const _items = ref([]) const _items = ref([])
@@ -195,8 +191,8 @@ export function useCart() {
**BAD:** **BAD:**
```javascript ```javascript
export function useFormatters() { export function useFormatters() {
const formatDate = date => new Intl.DateTimeFormat('en-US').format(date) const formatDate = (date) => new Intl.DateTimeFormat('en-US').format(date)
const formatCurrency = amount => const formatCurrency = (amount) =>
new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(amount) new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(amount)
return { formatDate, formatCurrency } return { formatDate, formatCurrency }
} }
@@ -222,7 +218,6 @@ export function formatCurrency(amount) {
```javascript ```javascript
// composables/useInvoiceSummary.js // composables/useInvoiceSummary.js
import { computed } from 'vue' import { computed } from 'vue'
import { formatCurrency } from '@/utils/formatters' import { formatCurrency } from '@/utils/formatters'
export function useInvoiceSummary(invoiceRef) { export function useInvoiceSummary(invoiceRef) {
@@ -236,7 +231,7 @@ export function useInvoiceSummary(invoiceRef) {
**BAD:** **BAD:**
```vue ```vue
<script setup> <script setup>
import { computed, onMounted, ref, watch } from 'vue' import { ref, computed, watch, onMounted } from 'vue'
const searchQuery = ref('') const searchQuery = ref('')
const items = ref([]) const items = ref([])
@@ -274,7 +269,7 @@ const { selectedItem, isModalOpen, selectItem, closeModal } = useSelectionModal(
```javascript ```javascript
// composables/useItems.js // composables/useItems.js
import { onMounted, ref } from 'vue' import { ref, onMounted } from 'vue'
export function useItems() { export function useItems() {
const items = ref([]) const items = ref([])
@@ -284,8 +279,7 @@ export function useItems() {
loading.value = true loading.value = true
try { try {
items.value = await api.getItems() items.value = await api.getItems()
} } finally {
finally {
loading.value = false loading.value = false
} }
} }
.agents/skills/vue-best-practices/references/directives.md
+6 -6
View File
@@ -45,11 +45,11 @@ Directives apply to DOM elements. When used on components, they attach to the ro
```vue ```vue
<!-- MyInput.vue --> <!-- MyInput.vue -->
<script setup> <script setup>
const vFocus = el => el.focus() const vFocus = (el) => el.focus()
</script> </script>
<template> <template>
<input v-focus> <input v-focus />
</template> </template>
``` ```
@@ -75,18 +75,18 @@ const vResize = {
If you only need `mounted`/`updated`, use the function form. If you only need `mounted`/`updated`, use the function form.
```ts ```ts
const vAutofocus = el => el.focus() const vAutofocus = (el) => el.focus()
``` ```
## Use the `v-` Prefix and Script Setup Registration ## Use the `v-` Prefix and Script Setup Registration
```vue ```vue
<script setup> <script setup>
const vFocus = el => el.focus() const vFocus = (el) => el.focus()
</script> </script>
<template> <template>
<input v-focus> <input v-focus />
</template> </template>
``` ```
@@ -147,7 +147,7 @@ const vTooltip = {
getSSRProps(binding) { getSSRProps(binding) {
return { return {
'data-tooltip': binding.value, 'data-tooltip': binding.value,
'class': 'has-tooltip' class: 'has-tooltip'
} }
} }
} }
.agents/skills/vue-best-practices/references/perf-avoid-component-abstraction-in-lists.md
+13 -19
View File
@@ -49,13 +49,6 @@ Don't avoid abstraction entirely, but be mindful of component depth in frequentl
**GOOD:** **GOOD:**
```vue ```vue
<!-- GOOD: Flattened structure in list items --> <!-- GOOD: Flattened structure in list items -->
<script setup>
defineProps({
user: Object
})
</script>
<!-- UserCard.vue - Flattened, uses native elements -->
<template> <template>
<div class="user-list"> <div class="user-list">
<!-- For 100 users: Creates 100 component instances --> <!-- For 100 users: Creates 100 component instances -->
@@ -63,6 +56,7 @@ defineProps({
</div> </div>
</template> </template>
<!-- UserCard.vue - Flattened, uses native elements -->
<template> <template>
<div class="card"> <div class="card">
<div class="card-header"> <div class="card-header">
@@ -74,6 +68,12 @@ defineProps({
</div> </div>
</template> </template>
<script setup>
defineProps({
user: Object
})
</script>
<style scoped> <style scoped>
/* Styles that would have been in Card, CardHeader, etc. */ /* Styles that would have been in Card, CardHeader, etc. */
.card { /* ... */ } .card { /* ... */ }
@@ -111,19 +111,17 @@ defineProps({
```javascript ```javascript
// In development, profile component counts // In development, profile component counts
import { getCurrentInstance, onMounted } from 'vue' import { onMounted, getCurrentInstance } from 'vue'
onMounted(() => { onMounted(() => {
const instance = getCurrentInstance() const instance = getCurrentInstance()
let count = 0 let count = 0
function countComponents(vnode) { function countComponents(vnode) {
if (vnode.component) if (vnode.component) count++
count++
if (vnode.children) { if (vnode.children) {
vnode.children.forEach((child) => { vnode.children.forEach(child => {
if (child.component || child.children) if (child.component || child.children) countComponents(child)
countComponents(child)
}) })
} }
} }
@@ -137,14 +135,10 @@ onMounted(() => {
```vue ```vue
<!-- Instead of a <Button> component for styling: --> <!-- Instead of a <Button> component for styling: -->
<button class="btn btn-primary"> <button class="btn btn-primary">Click</button>
Click
</button>
<!-- Instead of a <Text> component: --> <!-- Instead of a <Text> component: -->
<span class="text-body"> <span class="text-body">{{ content }}</span>
{{ content }}
</span>
<!-- Instead of layout wrapper components in lists: --> <!-- Instead of layout wrapper components in lists: -->
<div class="flex items-center gap-2"> <div class="flex items-center gap-2">
.agents/skills/vue-best-practices/references/perf-v-once-v-memo-directives.md
+29 -29
View File
@@ -28,7 +28,7 @@ Use `v-once` for truly static content and `v-memo` for conditionally-static cont
<div class="terms-content"> <div class="terms-content">
<h1>Terms of Service</h1> <h1>Terms of Service</h1>
<p>Version: {{ termsVersion }}</p> <p>Version: {{ termsVersion }}</p>
<div v-html="termsContent" /> <div v-html="termsContent"></div>
</div> </div>
<!-- This content NEVER changes, but Vue checks it every render --> <!-- This content NEVER changes, but Vue checks it every render -->
@@ -40,20 +40,12 @@ Use `v-once` for truly static content and `v-memo` for conditionally-static cont
**GOOD:** **GOOD:**
```vue ```vue
<script setup>
// These values are set once at component creation
const termsVersion = '2.1'
const termsContent = fetchedTermsHTML
const copyrightYear = 2024
const companyName = 'Acme Corp'
</script>
<template> <template>
<!-- GOOD: Rendered once, skipped on all future updates --> <!-- GOOD: Rendered once, skipped on all future updates -->
<div v-once class="terms-content"> <div class="terms-content" v-once>
<h1>Terms of Service</h1> <h1>Terms of Service</h1>
<p>Version: {{ termsVersion }}</p> <p>Version: {{ termsVersion }}</p>
<div v-html="termsContent" /> <div v-html="termsContent"></div>
</div> </div>
<!-- v-once tells Vue this never needs to update --> <!-- v-once tells Vue this never needs to update -->
@@ -61,6 +53,14 @@ const companyName = 'Acme Corp'
<p>Copyright {{ copyrightYear }} {{ companyName }}</p> <p>Copyright {{ copyrightYear }} {{ companyName }}</p>
</footer> </footer>
</template> </template>
<script setup>
// These values are set once at component creation
const termsVersion = '2.1'
const termsContent = fetchedTermsHTML
const copyrightYear = 2024
const companyName = 'Acme Corp'
</script>
``` ```
## v-memo: Conditional Memoization for Lists ## v-memo: Conditional Memoization for Lists
@@ -79,18 +79,6 @@ const companyName = 'Acme Corp'
**GOOD:** **GOOD:**
```vue ```vue
<script setup>
import { ref } from 'vue'
const list = ref([/* many items */])
const selectedId = ref(null)
// When selectedId changes:
// - Only the previously-selected item re-renders (selected: true -> false)
// - Only the newly-selected item re-renders (selected: false -> true)
// - All other items are SKIPPED (v-memo values unchanged)
</script>
<template> <template>
<!-- GOOD: Items only re-render when their selection state changes --> <!-- GOOD: Items only re-render when their selection state changes -->
<div <div
@@ -103,17 +91,23 @@ const selectedId = ref(null)
</div> </div>
</div> </div>
</template> </template>
<script setup>
import { ref } from 'vue'
const list = ref([/* many items */])
const selectedId = ref(null)
// When selectedId changes:
// - Only the previously-selected item re-renders (selected: true -> false)
// - Only the newly-selected item re-renders (selected: false -> true)
// - All other items are SKIPPED (v-memo values unchanged)
</script>
``` ```
## v-memo with Multiple Dependencies ## v-memo with Multiple Dependencies
```vue ```vue
<script setup>
const selectedId = ref(null)
const editingId = ref(null)
const items = ref([/* ... */])
</script>
<template> <template>
<!-- Re-render only when item's selection OR editing state changes --> <!-- Re-render only when item's selection OR editing state changes -->
<div <div
@@ -128,6 +122,12 @@ const items = ref([/* ... */])
/> />
</div> </div>
</template> </template>
<script setup>
const selectedId = ref(null)
const editingId = ref(null)
const items = ref([/* ... */])
</script>
``` ```
## v-memo with Empty Array = v-once ## v-memo with Empty Array = v-once
.agents/skills/vue-best-practices/references/perf-virtualize-large-lists.md
+48 -51
View File
@@ -31,19 +31,6 @@ Use a virtualization library when dealing with lists that could exceed 50-100 it
**BAD:** **BAD:**
```vue ```vue
<script setup>
import { onMounted, ref } from 'vue'
import UserCard from './UserCard.vue'
const users = ref([])
onMounted(async () => {
// 10,000 DOM nodes created, browser struggles
users.value = await fetchAllUsers()
})
</script>
<template> <template>
<!-- BAD: Renders ALL 10,000 items immediately --> <!-- BAD: Renders ALL 10,000 items immediately -->
<div class="user-list"> <div class="user-list">
@@ -54,17 +41,40 @@ onMounted(async () => {
/> />
</div> </div>
</template> </template>
<script setup>
import { ref, onMounted } from 'vue'
import UserCard from './UserCard.vue'
const users = ref([])
onMounted(async () => {
// 10,000 DOM nodes created, browser struggles
users.value = await fetchAllUsers()
})
</script>
``` ```
**GOOD:** **GOOD:**
```vue ```vue
<template>
<!-- GOOD: Only renders ~20 visible items at a time -->
<RecycleScroller
class="user-list"
:items="users"
:item-size="80"
key-field="id"
v-slot="{ item }"
>
<UserCard :user="item" />
</RecycleScroller>
</template>
<script setup> <script setup>
import { onMounted, ref } from 'vue' import { ref, onMounted } from 'vue'
import { RecycleScroller } from 'vue-virtual-scroller' import { RecycleScroller } from 'vue-virtual-scroller'
import UserCard from './UserCard.vue'
import 'vue-virtual-scroller/dist/vue-virtual-scroller.css' import 'vue-virtual-scroller/dist/vue-virtual-scroller.css'
import UserCard from './UserCard.vue'
const users = ref([]) const users = ref([])
@@ -74,19 +84,6 @@ onMounted(async () => {
}) })
</script> </script>
<template>
<!-- GOOD: Only renders ~20 visible items at a time -->
<RecycleScroller
v-slot="{ item }"
class="user-list"
:items="users"
:item-size="80"
key-field="id"
>
<UserCard :user="item" />
</RecycleScroller>
</template>
<style scoped> <style scoped>
.user-list { .user-list {
height: 600px; /* Container must have fixed height */ height: 600px; /* Container must have fixed height */
@@ -97,27 +94,12 @@ onMounted(async () => {
## Using @tanstack/vue-virtual ## Using @tanstack/vue-virtual
```vue ```vue
<script setup>
import { useVirtualizer } from '@tanstack/vue-virtual'
import { ref } from 'vue'
const users = ref([/* 10,000 users */])
const parentRef = ref(null)
const rowVirtualizer = useVirtualizer({
count: users.value.length,
getScrollElement: () => parentRef.value,
estimateSize: () => 80, // Estimated row height
overscan: 5 // Render 5 extra items above/below viewport
})
</script>
<template> <template>
<div ref="parentRef" class="list-container"> <div ref="parentRef" class="list-container">
<div <div
:style="{ :style="{
height: `${rowVirtualizer.getTotalSize()}px`, height: `${rowVirtualizer.getTotalSize()}px`,
position: 'relative', position: 'relative'
}" }"
> >
<div <div
@@ -129,7 +111,7 @@ const rowVirtualizer = useVirtualizer({
left: 0, left: 0,
width: '100%', width: '100%',
height: `${virtualRow.size}px`, height: `${virtualRow.size}px`,
transform: `translateY(${virtualRow.start}px)`, transform: `translateY(${virtualRow.start}px)`
}" }"
> >
<UserCard :user="users[virtualRow.index]" /> <UserCard :user="users[virtualRow.index]" />
@@ -138,6 +120,21 @@ const rowVirtualizer = useVirtualizer({
</div> </div>
</template> </template>
<script setup>
import { ref } from 'vue'
import { useVirtualizer } from '@tanstack/vue-virtual'
const users = ref([/* 10,000 users */])
const parentRef = ref(null)
const rowVirtualizer = useVirtualizer({
count: users.value.length,
getScrollElement: () => parentRef.value,
estimateSize: () => 80, // Estimated row height
overscan: 5 // Render 5 extra items above/below viewport
})
</script>
<style scoped> <style scoped>
.list-container { .list-container {
height: 600px; height: 600px;
@@ -149,10 +146,6 @@ const rowVirtualizer = useVirtualizer({
## Dynamic Heights with vue-virtual-scroller ## Dynamic Heights with vue-virtual-scroller
```vue ```vue
<script setup>
import { DynamicScroller, DynamicScrollerItem } from 'vue-virtual-scroller'
</script>
<template> <template>
<!-- For variable height items, use DynamicScroller --> <!-- For variable height items, use DynamicScroller -->
<DynamicScroller <DynamicScroller
@@ -171,6 +164,10 @@ import { DynamicScroller, DynamicScrollerItem } from 'vue-virtual-scroller'
</template> </template>
</DynamicScroller> </DynamicScroller>
</template> </template>
<script setup>
import { DynamicScroller, DynamicScrollerItem } from 'vue-virtual-scroller'
</script>
``` ```
## Performance Comparison ## Performance Comparison
.agents/skills/vue-best-practices/references/plugins.md
+2 -5
View File
@@ -129,8 +129,8 @@ export default {
**GOOD:** **GOOD:**
```ts ```ts
import type { AxiosInstance } from 'axios'
import type { InjectionKey } from 'vue' import type { InjectionKey } from 'vue'
import type { AxiosInstance } from 'axios'
interface AppConfig { interface AppConfig {
apiUrl: string apiUrl: string
@@ -153,11 +153,8 @@ export default {
Wrap required injections in composables that throw clear setup errors. Wrap required injections in composables that throw clear setup errors.
```ts ```ts
import type { AuthService } from '@/injection-keys'
import { inject } from 'vue' import { inject } from 'vue'
import { authKey, type AuthService } from '@/injection-keys'
import { authKey } from '@/injection-keys'
export function useAuth(): AuthService { export function useAuth(): AuthService {
const auth = inject(authKey) const auth = inject(authKey)
.agents/skills/vue-best-practices/references/reactivity.md
+19 -23
View File
@@ -36,14 +36,12 @@ This reference covers the core reactivity decisions for local state, external da
**Incorrect:** **Incorrect:**
```ts ```ts
import { ref } from 'vue' import { ref } from 'vue'
const count = ref(0) const count = ref(0)
``` ```
**Correct:** **Correct:**
```ts ```ts
import { shallowRef } from 'vue' import { shallowRef } from 'vue'
const count = shallowRef(0) const count = shallowRef(0)
``` ```
@@ -164,7 +162,7 @@ watchEffect(() => {
**GOOD:** **GOOD:**
```ts ```ts
import { computed, ref } from 'vue' import { ref, computed } from 'vue'
const items = ref([{ price: 10 }, { price: 20 }]) const items = ref([{ price: 10 }, { price: 20 }])
const total = computed(() => const total = computed(() =>
@@ -176,6 +174,16 @@ const total = computed(() =>
**BAD:** **BAD:**
```vue ```vue
<template>
<li v-for="item in items.filter(item => item.active)" :key="item.id">
{{ item.name }}
</li>
<li v-for="item in getSortedItems()" :key="item.id">
{{ item.name }}
</li>
</template>
<script setup> <script setup>
import { ref } from 'vue' import { ref } from 'vue'
@@ -188,22 +196,12 @@ function getSortedItems() {
return [...items.value].sort((a, b) => a.name.localeCompare(b.name)) return [...items.value].sort((a, b) => a.name.localeCompare(b.name))
} }
</script> </script>
<template>
<li v-for="item in items.filter(item => item.active)" :key="item.id">
{{ item.name }}
</li>
<li v-for="item in getSortedItems()" :key="item.id">
{{ item.name }}
</li>
</template>
``` ```
**GOOD:** **GOOD:**
```vue ```vue
<script setup> <script setup>
import { computed, ref } from 'vue' import { ref, computed } from 'vue'
const items = ref([ const items = ref([
{ id: 1, name: 'B', active: true }, { id: 1, name: 'B', active: true },
@@ -229,7 +227,7 @@ const visibleItems = computed(() =>
**BAD:** **BAD:**
```vue ```vue
<template> <template>
<button :class="{ 'btn': true, 'btn-primary': type === 'primary' && !disabled, 'btn-disabled': disabled }"> <button :class="{ btn: true, 'btn-primary': type === 'primary' && !disabled, 'btn-disabled': disabled }">
{{ label }} {{ label }}
</button> </button>
</template> </template>
@@ -247,7 +245,7 @@ const props = defineProps({
}) })
const buttonClasses = computed(() => ({ const buttonClasses = computed(() => ({
'btn': true, btn: true,
[`btn-${props.type}`]: !props.disabled, [`btn-${props.type}`]: !props.disabled,
'btn-disabled': props.disabled 'btn-disabled': props.disabled
})) }))
@@ -274,8 +272,7 @@ const count = ref(0)
const doubled = computed(() => { const doubled = computed(() => {
// ❌ side effect // ❌ side effect
if (count.value > 10) if (count.value > 10) console.warn('Too big!')
console.warn('Too big!')
return count.value * 2 return count.value * 2
}) })
``` ```
@@ -289,8 +286,7 @@ const count = ref(0)
const doubled = computed(() => count.value * 2) const doubled = computed(() => count.value * 2)
watch(count, (value) => { watch(count, (value) => {
if (value > 10) if (value > 10) console.warn('Too big!')
console.warn('Too big!')
}) })
``` ```
@@ -300,7 +296,7 @@ watch(count, (value) => {
**BAD:** **BAD:**
```ts ```ts
import { onMounted, ref, watch } from 'vue' import { ref, watch, onMounted } from 'vue'
const userId = ref(1) const userId = ref(1)
@@ -309,7 +305,7 @@ function loadUser(id) {
} }
onMounted(() => loadUser(userId.value)) onMounted(() => loadUser(userId.value))
watch(userId, id => loadUser(id)) watch(userId, (id) => loadUser(id))
``` ```
**GOOD:** **GOOD:**
@@ -320,7 +316,7 @@ const userId = ref(1)
watch( watch(
userId, userId,
id => loadUser(id), (id) => loadUser(id),
{ immediate: true } { immediate: true }
) )
``` ```
.agents/skills/vue-best-practices/references/render-functions.md
+10 -8
View File
@@ -54,7 +54,9 @@ export default {
setup() { setup() {
const items = ref([{ id: 1, name: 'Apple' }]) const items = ref([{ id: 1, name: 'Apple' }])
return () => h('ul', items.value.map(item => h('li', item.name))) return () => h('ul',
items.value.map(item => h('li', item.name))
)
} }
} }
``` ```
@@ -67,7 +69,9 @@ export default {
setup() { setup() {
const items = ref([{ id: 1, name: 'Apple' }]) const items = ref([{ id: 1, name: 'Apple' }])
return () => h('ul', items.value.map(item => h('li', { key: item.id }, item.name))) return () => h('ul',
items.value.map(item => h('li', { key: item.id }, item.name))
)
} }
} }
``` ```
@@ -92,7 +96,7 @@ export default {
**GOOD:** **GOOD:**
```javascript ```javascript
import { h, withKeys, withModifiers } from 'vue' import { h, withModifiers, withKeys } from 'vue'
export default { export default {
setup() { setup() {
@@ -116,7 +120,6 @@ export default {
**BAD:** **BAD:**
```javascript ```javascript
import { h, ref } from 'vue' import { h, ref } from 'vue'
import CustomInput from './CustomInput.vue' import CustomInput from './CustomInput.vue'
export default { export default {
@@ -130,14 +133,13 @@ export default {
**GOOD:** **GOOD:**
```javascript ```javascript
import { h, ref } from 'vue' import { h, ref } from 'vue'
import CustomInput from './CustomInput.vue' import CustomInput from './CustomInput.vue'
export default { export default {
setup() { setup() {
const text = ref('') const text = ref('')
return () => h(CustomInput, { return () => h(CustomInput, {
'modelValue': text.value, modelValue: text.value,
'onUpdate:modelValue': (value) => { text.value = value } 'onUpdate:modelValue': (value) => { text.value = value }
}) })
} }
@@ -150,7 +152,7 @@ export default {
```javascript ```javascript
import { h } from 'vue' import { h } from 'vue'
const vFocus = { mounted: el => el.focus() } const vFocus = { mounted: (el) => el.focus() }
export default { export default {
setup() { setup() {
@@ -163,7 +165,7 @@ export default {
```javascript ```javascript
import { h, withDirectives } from 'vue' import { h, withDirectives } from 'vue'
const vFocus = { mounted: el => el.focus() } const vFocus = { mounted: (el) => el.focus() }
export default { export default {
setup() { setup() {
.agents/skills/vue-best-practices/references/sfc.md
+9 -16
View File
@@ -50,9 +50,7 @@ const displayName = computed(() =>
<template> <template>
<div class="user-card"> <div class="user-card">
<h3 class="name"> <h3 class="name">{{ displayName }}</h3>
{{ displayName }}
</h3>
</div> </div>
</template> </template>
@@ -146,12 +144,8 @@ p { line-height: 1.6; }
```vue ```vue
<template> <template>
<article class="article"> <article class="article">
<h1 class="article-title"> <h1 class="article-title">{{ title }}</h1>
{{ title }} <p class="article-subtitle">{{ subtitle }}</p>
</h1>
<p class="article-subtitle">
{{ subtitle }}
</p>
</article> </article>
</template> </template>
@@ -178,7 +172,7 @@ onMounted(() => {
</script> </script>
<template> <template>
<input ref="input"> <input ref="input" />
</template> </template>
``` ```
@@ -187,7 +181,7 @@ onMounted(() => {
**BAD:** **BAD:**
```vue ```vue
<template> <template>
<div :style="{ 'font-size': `${fontSize}px`, 'background-color': bg }"> <div :style="{ 'font-size': fontSize + 'px', 'background-color': bg }">
Content Content
</div> </div>
</template> </template>
@@ -196,7 +190,7 @@ onMounted(() => {
**GOOD:** **GOOD:**
```vue ```vue
<template> <template>
<div :style="{ fontSize: `${fontSize}px`, backgroundColor: bg }"> <div :style="{ fontSize: fontSize + 'px', backgroundColor: bg }">
Content Content
</div> </div>
</template> </template>
@@ -264,16 +258,15 @@ const activeUsers = computed(() => users.value.filter(u => u.active))
```vue ```vue
<template> <template>
<!-- DANGEROUS: untrusted input can inject scripts --> <!-- DANGEROUS: untrusted input can inject scripts -->
<article v-html="userProvidedContent" /> <article v-html="userProvidedContent"></article>
</template> </template>
``` ```
**GOOD:** **GOOD:**
```vue ```vue
<script setup> <script setup>
import DOMPurify from 'dompurify'
import { computed } from 'vue' import { computed } from 'vue'
import DOMPurify from 'dompurify'
const props = defineProps<{ const props = defineProps<{
trustedHtml?: string trustedHtml?: string
@@ -288,7 +281,7 @@ const safeHtml = computed(() => DOMPurify.sanitize(props.trustedHtml ?? ''))
<p>{{ props.plainText }}</p> <p>{{ props.plainText }}</p>
<!-- Only for trusted/sanitized HTML --> <!-- Only for trusted/sanitized HTML -->
<article v-html="safeHtml" /> <article v-html="safeHtml"></article>
</template> </template>
``` ```
.agents/skills/vue-best-practices/references/state-management.md
+6 -7
View File
@@ -32,7 +32,7 @@ tags: [vue3, state-management, pinia, composables, ssr, vueuse]
import { reactive } from 'vue' import { reactive } from 'vue'
export const cart = reactive({ export const cart = reactive({
items: [] as Array<{ id: string, qty: number }> items: [] as Array<{ id: string; qty: number }>
}) })
``` ```
@@ -45,11 +45,11 @@ let _store: ReturnType<typeof createCartStore> | null = null
function createCartStore() { function createCartStore() {
const state = reactive({ const state = reactive({
items: [] as Array<{ id: string, qty: number }> items: [] as Array<{ id: string; qty: number }>
}) })
function addItem(id: string, qty = 1) { function addItem(id: string, qty = 1) {
const existing = state.items.find(item => item.id === id) const existing = state.items.find((item) => item.id === id)
if (existing) { if (existing) {
existing.qty += qty existing.qty += qty
return return
@@ -64,8 +64,7 @@ function createCartStore() {
} }
export function useCartStore() { export function useCartStore() {
if (!_store) if (!_store) _store = createCartStore()
_store = createCartStore()
return _store return _store
} }
``` ```
@@ -94,11 +93,11 @@ import { defineStore } from 'pinia'
export const useCartStore = defineStore('cart', { export const useCartStore = defineStore('cart', {
state: () => ({ state: () => ({
items: [] as Array<{ id: string, qty: number }> items: [] as Array<{ id: string; qty: number }>
}), }),
actions: { actions: {
addItem(id: string, qty = 1) { addItem(id: string, qty = 1) {
const existing = this.items.find(item => item.id === id) const existing = this.items.find((item) => item.id === id)
if (existing) { if (existing) {
existing.qty += qty existing.qty += qty
return return
.agents/skills/vue-best-practices/references/updated-hook-performance.md
+3 -3
View File
@@ -81,7 +81,7 @@ export default {
} }
}, },
methods: { methods: {
syncToServer: debounce((items) => { syncToServer: debounce(function(items) {
fetch('/api/sync', { fetch('/api/sync', {
method: 'POST', method: 'POST',
body: JSON.stringify(items) body: JSON.stringify(items)
@@ -94,8 +94,8 @@ export default {
```vue ```vue
<!-- GOOD: Composition API with targeted watchers --> <!-- GOOD: Composition API with targeted watchers -->
<script setup> <script setup>
import { ref, watch, onUpdated } from 'vue'
import { useDebounceFn } from '@vueuse/core' import { useDebounceFn } from '@vueuse/core'
import { onUpdated, ref, watch } from 'vue'
const items = ref([]) const items = ref([])
const scrollContainer = ref(null) const scrollContainer = ref(null)
@@ -136,7 +136,7 @@ export default {
} }
}, },
methods: { methods: {
syncContent: debounce(() => { syncContent: debounce(function() {
// Sync logic // Sync logic
}, 300) }, 300)
} }
.agents/skills/vue/SKILL.md
+8 -5
View File
@@ -38,7 +38,7 @@ metadata:
```vue ```vue
<script setup lang="ts"> <script setup lang="ts">
import { computed, onMounted, ref, watch } from 'vue' import { ref, computed, watch, onMounted } from 'vue'
const props = defineProps<{ const props = defineProps<{
title: string title: string
@@ -71,11 +71,14 @@ onMounted(() => {
```ts ```ts
// Reactivity // Reactivity
import { computed, reactive, readonly, ref, shallowRef, toRef, toRefs, toValue } from 'vue' import { ref, shallowRef, computed, reactive, readonly, toRef, toRefs, toValue } from 'vue'
// Watchers // Watchers
import { onWatcherCleanup, watch, watchEffect, watchPostEffect } from 'vue' import { watch, watchEffect, watchPostEffect, onWatcherCleanup } from 'vue'
// Lifecycle // Lifecycle
import { onBeforeMount, onBeforeUnmount, onBeforeUpdate, onMounted, onUnmounted, onUpdated } from 'vue' import { onMounted, onUpdated, onUnmounted, onBeforeMount, onBeforeUpdate, onBeforeUnmount } from 'vue'
// Utilities // Utilities
import { defineAsyncComponent, defineComponent, nextTick } from 'vue' import { nextTick, defineComponent, defineAsyncComponent } from 'vue'
``` ```
.agents/skills/vue/references/advanced-patterns.md
+7 -15
View File
@@ -12,9 +12,7 @@ Animate enter/leave of a single element or component.
```vue ```vue
<template> <template>
<Transition name="fade"> <Transition name="fade">
<div v-if="show"> <div v-if="show">Content</div>
Content
</div>
</Transition> </Transition>
</template> </template>
@@ -111,10 +109,8 @@ Render content to a different DOM location.
```vue ```vue
<template> <template>
<button @click="open = true"> <button @click="open = true">Open Modal</button>
Open Modal
</button>
<Teleport to="body"> <Teleport to="body">
<div v-if="open" class="modal"> <div v-if="open" class="modal">
Modal content rendered at body Modal content rendered at body
@@ -240,9 +236,7 @@ Skip re-renders when dependencies unchanged. Use for performance optimization.
Equivalent to `v-once` when empty: Equivalent to `v-once` when empty:
```vue ```vue
<div v-memo="[]"> <div v-memo="[]">Never updates</div>
Never updates
</div>
``` ```
## v-once ## v-once
@@ -250,9 +244,7 @@ Never updates
Render once, skip all future updates. Render once, skip all future updates.
```vue ```vue
<span v-once> <span v-once>Static: {{ neverChanges }}</span>
Static: {{ neverChanges }}
</span>
``` ```
## Custom Directives ## Custom Directives
@@ -262,7 +254,7 @@ Create reusable DOM manipulations.
```ts ```ts
// Directive definition // Directive definition
const vFocus: Directive<HTMLElement> = { const vFocus: Directive<HTMLElement> = {
mounted: el => el.focus() mounted: (el) => el.focus()
} }
// Full hooks // Full hooks
@@ -306,7 +298,7 @@ const vColor: Directive<HTMLElement, string> = {
```ts ```ts
// main.ts // main.ts
app.directive('focus', { app.directive('focus', {
mounted: el => el.focus() mounted: (el) => el.focus()
}) })
``` ```
.agents/skills/vue/references/core-new-apis.md
+25 -28
View File
@@ -14,12 +14,12 @@ import { ref, shallowRef } from 'vue'
// ref - deep reactivity (tracks nested changes) // ref - deep reactivity (tracks nested changes)
const user = ref({ name: 'John', profile: { age: 30 } }) const user = ref({ name: 'John', profile: { age: 30 } })
user.value.profile.age = 31 // Triggers reactivity user.value.profile.age = 31 // Triggers reactivity
// shallowRef - only .value assignment triggers reactivity (better performance) // shallowRef - only .value assignment triggers reactivity (better performance)
const data = shallowRef({ items: [] }) const data = shallowRef({ items: [] })
data.value.items.push('new') // Does NOT trigger reactivity data.value.items.push('new') // Does NOT trigger reactivity
data.value = { items: ['new'] } // Triggers reactivity data.value = { items: ['new'] } // Triggers reactivity
``` ```
**Prefer `shallowRef`** for large data structures or when deep reactivity is unnecessary. **Prefer `shallowRef`** for large data structures or when deep reactivity is unnecessary.
@@ -27,7 +27,7 @@ data.value = { items: ['new'] } // Triggers reactivity
### computed ### computed
```ts ```ts
import { computed, ref } from 'vue' import { ref, computed } from 'vue'
const count = ref(0) const count = ref(0)
@@ -47,10 +47,10 @@ const plusOne = computed({
import { reactive, readonly } from 'vue' import { reactive, readonly } from 'vue'
const state = reactive({ count: 0, nested: { value: 1 } }) const state = reactive({ count: 0, nested: { value: 1 } })
state.count++ // Reactive state.count++ // Reactive
const readonlyState = readonly(state) const readonlyState = readonly(state)
readonlyState.count++ // Warning, mutation blocked readonlyState.count++ // Warning, mutation blocked
``` ```
Note: `reactive()` loses reactivity on destructuring. Use `ref()` or `toRefs()`. Note: `reactive()` loses reactivity on destructuring. Use `ref()` or `toRefs()`.
@@ -72,7 +72,7 @@ watch(count, (newVal, oldVal) => {
// Watch getter // Watch getter
watch( watch(
() => props.id, () => props.id,
id => fetchData(id), (id) => fetchData(id),
{ immediate: true } { immediate: true }
) )
@@ -93,16 +93,16 @@ watch(source, callback, { once: true })
Runs immediately and auto-tracks dependencies. Runs immediately and auto-tracks dependencies.
```ts ```ts
import { onWatcherCleanup, ref, watchEffect } from 'vue' import { ref, watchEffect, onWatcherCleanup } from 'vue'
const id = ref(1) const id = ref(1)
watchEffect(async () => { watchEffect(async () => {
const controller = new AbortController() const controller = new AbortController()
// Cleanup on re-run or unmount (Vue 3.5+) // Cleanup on re-run or unmount (Vue 3.5+)
onWatcherCleanup(() => controller.abort()) onWatcherCleanup(() => controller.abort())
const res = await fetch(`/api/${id.value}`, { signal: controller.signal }) const res = await fetch(`/api/${id.value}`, { signal: controller.signal })
data.value = await res.json() data.value = await res.json()
}) })
@@ -122,23 +122,23 @@ stop()
// 'sync' - immediate, use with caution // 'sync' - immediate, use with caution
watch(source, callback, { flush: 'post' }) watch(source, callback, { flush: 'post' })
watchPostEffect(() => {}) // Alias for flush: 'post' watchPostEffect(() => {}) // Alias for flush: 'post'
``` ```
## Lifecycle Hooks ## Lifecycle Hooks
```ts ```ts
import { import {
onActivated, // KeepAlive
onBeforeMount, onBeforeMount,
onBeforeUnmount,
onBeforeUpdate,
onDeactivated, // KeepAlive
onErrorCaptured,
onMounted, onMounted,
onServerPrefetch, // SSR only onBeforeUpdate,
onUpdated,
onBeforeUnmount,
onUnmounted, onUnmounted,
onUpdated onErrorCaptured,
onActivated, // KeepAlive
onDeactivated, // KeepAlive
onServerPrefetch // SSR only
} from 'vue' } from 'vue'
onMounted(() => { onMounted(() => {
@@ -152,7 +152,7 @@ onUnmounted(() => {
// Error boundary // Error boundary
onErrorCaptured((err, instance, info) => { onErrorCaptured((err, instance, info) => {
console.error(err) console.error(err)
return false // Stop propagation return false // Stop propagation
}) })
``` ```
@@ -168,9 +168,9 @@ const scope = effectScope()
scope.run(() => { scope.run(() => {
const count = ref(0) const count = ref(0)
const doubled = computed(() => count.value * 2) const doubled = computed(() => count.value * 2)
watch(count, () => console.log(count.value)) watch(count, () => console.log(count.value))
// Cleanup when scope stops // Cleanup when scope stops
onScopeDispose(() => { onScopeDispose(() => {
console.log('Scope disposed') console.log('Scope disposed')
@@ -193,7 +193,7 @@ Composables are functions that encapsulate stateful logic using Composition API.
```ts ```ts
// composables/useMouse.ts // composables/useMouse.ts
import { onMounted, onUnmounted, ref } from 'vue' import { ref, onMounted, onUnmounted } from 'vue'
export function useMouse() { export function useMouse() {
const x = ref(0) const x = ref(0)
@@ -216,9 +216,7 @@ export function useMouse() {
Use `toValue()` (Vue 3.3+) to normalize refs, getters, or plain values. Use `toValue()` (Vue 3.3+) to normalize refs, getters, or plain values.
```ts ```ts
import type { MaybeRefOrGetter } from 'vue' import { ref, watchEffect, toValue, type MaybeRefOrGetter } from 'vue'
import { ref, toValue, watchEffect } from 'vue'
export function useFetch(url: MaybeRefOrGetter<string>) { export function useFetch(url: MaybeRefOrGetter<string>) {
const data = ref(null) const data = ref(null)
@@ -227,12 +225,11 @@ export function useFetch(url: MaybeRefOrGetter<string>) {
watchEffect(async () => { watchEffect(async () => {
data.value = null data.value = null
error.value = null error.value = null
try { try {
const res = await fetch(toValue(url)) const res = await fetch(toValue(url))
data.value = await res.json() data.value = await res.json()
} } catch (e) {
catch (e) {
error.value = e error.value = e
} }
}) })
.agents/skills/vue/references/script-setup-macros.md
+11 -17
View File
@@ -13,7 +13,6 @@ description: Vue 3 script setup syntax and compiler macros for defining props, e
<script setup lang="ts"> <script setup lang="ts">
// Top-level bindings are exposed to template // Top-level bindings are exposed to template
import { ref } from 'vue' import { ref } from 'vue'
import MyComponent from './MyComponent.vue' import MyComponent from './MyComponent.vue'
const count = ref(0) const count = ref(0)
@@ -21,9 +20,7 @@ const increment = () => count.value++
</script> </script>
<template> <template>
<button @click="increment"> <button @click="increment">{{ count }}</button>
{{ count }}
</button>
<MyComponent /> <MyComponent />
</template> </template>
``` ```
@@ -51,7 +48,7 @@ const props = withDefaults(defineProps<{
title: string title: string
items?: string[] items?: string[]
}>(), { }>(), {
items: () => [] // Use factory for arrays/objects items: () => [] // Use factory for arrays/objects
}) })
``` ```
@@ -79,7 +76,7 @@ Two-way binding prop consumed via `v-model`. Available in Vue 3.4+.
```ts ```ts
// Basic usage - creates "modelValue" prop // Basic usage - creates "modelValue" prop
const model = defineModel<string>() const model = defineModel<string>()
model.value = 'hello' // Emits "update:modelValue" model.value = 'hello' // Emits "update:modelValue"
// Named model - consumed via v-model:name // Named model - consumed via v-model:name
const count = defineModel<number>('count', { default: 0 }) const count = defineModel<number>('count', { default: 0 })
@@ -100,9 +97,7 @@ const [value, modifiers] = defineModel({
Parent usage: Parent usage:
```vue ```vue
<Child v-model="name" /> <Child v-model="name" />
<Child v-model:count="total" /> <Child v-model:count="total" />
<Child v-model.trim="text" /> <Child v-model.trim="text" />
``` ```
@@ -114,7 +109,7 @@ Explicitly expose properties to parent via template refs. Components are closed
import { ref } from 'vue' import { ref } from 'vue'
const count = ref(0) const count = ref(0)
function reset() { count.value = 0 } const reset = () => { count.value = 0 }
defineExpose({ defineExpose({
count, count,
@@ -124,7 +119,7 @@ defineExpose({
Parent access: Parent access:
```ts ```ts
const childRef = ref<{ count: number, reset: () => void }>() const childRef = ref<{ count: number; reset: () => void }>()
childRef.value?.reset() childRef.value?.reset()
``` ```
@@ -145,8 +140,8 @@ Provide type hints for slot props. Available in Vue 3.3+.
```ts ```ts
const slots = defineSlots<{ const slots = defineSlots<{
default: (props: { item: string, index: number }) => any default(props: { item: string; index: number }): any
header: (props: { title: string }) => any header(props: { title: string }): any
}>() }>()
``` ```
@@ -167,7 +162,6 @@ Multiple generics with constraints:
```vue ```vue
<script setup lang="ts" generic="T, U extends Record<string, T>"> <script setup lang="ts" generic="T, U extends Record<string, T>">
import type { Item } from './types' import type { Item } from './types'
defineProps<{ defineProps<{
data: U data: U
key: keyof U key: keyof U
@@ -180,17 +174,17 @@ defineProps<{
Use `vNameOfDirective` naming convention. Use `vNameOfDirective` naming convention.
```ts ```ts
// Or import and rename
import { myDirective as vMyDirective } from './directives'
const vFocus = { const vFocus = {
mounted: (el: HTMLElement) => el.focus() mounted: (el: HTMLElement) => el.focus()
} }
// Or import and rename
import { myDirective as vMyDirective } from './directives'
``` ```
```vue ```vue
<template> <template>
<input v-focus> <input v-focus />
</template> </template>
``` ```
.agents/skills/vueuse-functions/SKILL.md
+5 -4
View File
@@ -43,11 +43,11 @@ IMPORTANT: Each function entry includes a short `Description` and a detailed `Re
| [`useDebouncedRefHistory`](references/useDebouncedRefHistory.md) | Shorthand for `useRefHistory` with debounced filter | AUTO | | [`useDebouncedRefHistory`](references/useDebouncedRefHistory.md) | Shorthand for `useRefHistory` with debounced filter | AUTO |
| [`useLastChanged`](references/useLastChanged.md) | Records the timestamp of the last change | AUTO | | [`useLastChanged`](references/useLastChanged.md) | Records the timestamp of the last change | AUTO |
| [`useLocalStorage`](references/useLocalStorage.md) | Reactive [LocalStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) | AUTO | | [`useLocalStorage`](references/useLocalStorage.md) | Reactive [LocalStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) | AUTO |
| [`useManualRefHistory`](references/useManualRefHistory.md) | Manually track the change history of a ref when the using calls `commit()` | AUTO | | [`useManualRefHistory`](references/useManualRefHistory.md) | Manually track the change history of a ref when the user calls `commit()` | AUTO |
| [`useRefHistory`](references/useRefHistory.md) | Track the change history of a ref | AUTO | | [`useRefHistory`](references/useRefHistory.md) | Track the change history of a ref | AUTO |
| [`useSessionStorage`](references/useSessionStorage.md) | Reactive [SessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) | AUTO | | [`useSessionStorage`](references/useSessionStorage.md) | Reactive [SessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) | AUTO |
| [`useStorage`](references/useStorage.md) | Create a reactive ref that can be used to access & modify [LocalStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) or [SessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) | AUTO | | [`useStorage`](references/useStorage.md) | Create a reactive ref that can be used to access & modify [LocalStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) or [SessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) | AUTO |
| [`useStorageAsync`](references/useStorageAsync.md) | Reactive Storage in with async support | AUTO | | [`useStorageAsync`](references/useStorageAsync.md) | Reactive Storage with async support | AUTO |
| [`useThrottledRefHistory`](references/useThrottledRefHistory.md) | Shorthand for `useRefHistory` with throttled filter | AUTO | | [`useThrottledRefHistory`](references/useThrottledRefHistory.md) | Shorthand for `useRefHistory` with throttled filter | AUTO |
### Elements ### Elements
@@ -61,7 +61,7 @@ IMPORTANT: Each function entry includes a short `Description` and a detailed `Re
| [`useElementBounding`](references/useElementBounding.md) | Reactive [bounding box](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect) of an HTML element | AUTO | | [`useElementBounding`](references/useElementBounding.md) | Reactive [bounding box](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect) of an HTML element | AUTO |
| [`useElementSize`](references/useElementSize.md) | Reactive size of an HTML element | AUTO | | [`useElementSize`](references/useElementSize.md) | Reactive size of an HTML element | AUTO |
| [`useElementVisibility`](references/useElementVisibility.md) | Tracks the visibility of an element within the viewport | AUTO | | [`useElementVisibility`](references/useElementVisibility.md) | Tracks the visibility of an element within the viewport | AUTO |
| [`useIntersectionObserver`](references/useIntersectionObserver.md) | Detects that a target element's visibility | AUTO | | [`useIntersectionObserver`](references/useIntersectionObserver.md) | Detects changes to a target element's visibility | AUTO |
| [`useMouseInElement`](references/useMouseInElement.md) | Reactive mouse position related to an element | AUTO | | [`useMouseInElement`](references/useMouseInElement.md) | Reactive mouse position related to an element | AUTO |
| [`useMutationObserver`](references/useMutationObserver.md) | Watch for changes being made to the DOM tree | AUTO | | [`useMutationObserver`](references/useMutationObserver.md) | Watch for changes being made to the DOM tree | AUTO |
| [`useParentElement`](references/useParentElement.md) | Get parent element of the given element | AUTO | | [`useParentElement`](references/useParentElement.md) | Get parent element of the given element | AUTO |
@@ -138,7 +138,7 @@ IMPORTANT: Each function entry includes a short `Description` and a detailed `Re
| [`useElementByPoint`](references/useElementByPoint.md) | Reactive element by point | AUTO | | [`useElementByPoint`](references/useElementByPoint.md) | Reactive element by point | AUTO |
| [`useElementHover`](references/useElementHover.md) | Reactive element's hover state | AUTO | | [`useElementHover`](references/useElementHover.md) | Reactive element's hover state | AUTO |
| [`useFocus`](references/useFocus.md) | Reactive utility to track or set the focus state of a DOM element | AUTO | | [`useFocus`](references/useFocus.md) | Reactive utility to track or set the focus state of a DOM element | AUTO |
| [`useFocusWithin`](references/useFocusWithin.md) | Reactive utility to track if an element or one of its decendants has focus | AUTO | | [`useFocusWithin`](references/useFocusWithin.md) | Reactive utility to track if an element or one of its descendants has focus | AUTO |
| [`useFps`](references/useFps.md) | Reactive FPS (frames per second) | AUTO | | [`useFps`](references/useFps.md) | Reactive FPS (frames per second) | AUTO |
| [`useGeolocation`](references/useGeolocation.md) | Reactive [Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API) | AUTO | | [`useGeolocation`](references/useGeolocation.md) | Reactive [Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API) | AUTO |
| [`useIdle`](references/useIdle.md) | Tracks whether the user is being inactive | AUTO | | [`useIdle`](references/useIdle.md) | Tracks whether the user is being inactive | AUTO |
@@ -281,6 +281,7 @@ IMPORTANT: Each function entry includes a short `Description` and a detailed `Re
| Function | Description | Invocation | | Function | Description | Invocation |
|----------|-------------|------------| |----------|-------------|------------|
| [`createDisposableDirective`](references/createDisposableDirective.md) | Utility for authoring disposable directives | AUTO |
| [`createEventHook`](references/createEventHook.md) | Utility for creating event hooks | AUTO | | [`createEventHook`](references/createEventHook.md) | Utility for creating event hooks | AUTO |
| [`createUnrefFn`](references/createUnrefFn.md) | Make a plain function accepting ref and raw values as arguments | AUTO | | [`createUnrefFn`](references/createUnrefFn.md) | Make a plain function accepting ref and raw values as arguments | AUTO |
| [`get`](references/get.md) | Shorthand for accessing `ref.value` | EXPLICIT_ONLY | | [`get`](references/get.md) | Shorthand for accessing `ref.value` | EXPLICIT_ONLY |
.agents/skills/vueuse-functions/SYNC.md
+2 -2
View File
@@ -1,5 +1,5 @@
# Sync Info # Sync Info
- **Source:** `vendor/vueuse/skills/vueuse-functions` - **Source:** `vendor/vueuse/skills/vueuse-functions`
- **Git SHA:** `075b0d6d558cc5ca7d5ffe72a56b5fd92bbef2d1` - **Git SHA:** `b6bb79b99fb1f1dba1f907829676a651735bbc10`
- **Synced:** 2026-03-13 - **Synced:** 2026-06-22
.agents/skills/vueuse-functions/references/computedInject.md
-1
View File
@@ -12,7 +12,6 @@ In Provider Component
```ts twoslash include main ```ts twoslash include main
import type { InjectionKey, Ref } from 'vue' import type { InjectionKey, Ref } from 'vue'
import { provide, ref } from 'vue' import { provide, ref } from 'vue'
interface Item { interface Item {
.agents/skills/vueuse-functions/references/computedWithControl.md
+3 -3
View File
@@ -80,9 +80,9 @@ export interface ComputedRefWithControl<T>
extends ComputedRef<T>, ComputedWithControlRefExtra {} extends ComputedRef<T>, ComputedWithControlRefExtra {}
export interface WritableComputedRefWithControl<T> export interface WritableComputedRefWithControl<T>
extends WritableComputedRef<T>, ComputedWithControlRefExtra {} extends WritableComputedRef<T>, ComputedWithControlRefExtra {}
export type ComputedWithControlRef<T = any> export type ComputedWithControlRef<T = any> =
= | ComputedRefWithControl<T> | ComputedRefWithControl<T>
| WritableComputedRefWithControl<T> | WritableComputedRefWithControl<T>
export declare function computedWithControl<T>( export declare function computedWithControl<T>(
source: WatchSource | MultiWatchSources, source: WatchSource | MultiWatchSources,
fn: ComputedGetter<T>, fn: ComputedGetter<T>,
.agents/skills/vueuse-functions/references/createDisposableDirective.md
+47
View File
@@ -0,0 +1,47 @@
---
category: Utilities
---
# createDisposableDirective
Utility for authoring disposable directives. Reactive effects created within `mounted` directive hook will be tracked and automatically disposed when directive is unmounted.
## Usage
Creating a directive that uses `createDisposableDirective`
```ts
import { useMouse } from '@vueuse/core'
import { createDisposableDirective } from '@vueuse/shared'
export const VDirective = createDisposableDirective({
mounted(el, binding) {
const value = binding.value
if (typeof value === 'function') {
// `useMouse` event listener will be removed automatically when directive is unmounted
const { x, y } = useMouse()
watch(x, val => value(val))
}
}
})
```
## Type Declarations
```ts
type originDirective<H, V, A> =
| FunctionDirective<H, V, string, A>
| ObjectDirective<H, V, string, A>
/**
* Utility for authoring disposable directives. Reactive effects created within `mounted` directive hook will be tracked and automatically disposed when directive is unmounted.
*
* @see https://vueuse.org/createDisposableDirective
*
* @__NO_SIDE_EFFECTS__
*/
export declare function createDisposableDirective<
H extends HTMLElement,
V,
A = any,
>(origin?: originDirective<H, V, A>): originDirective<H, V, A>
```
.agents/skills/vueuse-functions/references/createEventHook.md
+6 -6
View File
@@ -53,14 +53,14 @@ onError((error) => {
* The source code for this function was inspired by vue-apollo's `useEventHook` util * The source code for this function was inspired by vue-apollo's `useEventHook` util
* https://github.com/vuejs/vue-apollo/blob/v4/packages/vue-apollo-composable/src/util/useEventHook.ts * https://github.com/vuejs/vue-apollo/blob/v4/packages/vue-apollo-composable/src/util/useEventHook.ts
*/ */
type Callback<T> type Callback<T> =
= IsAny<T> extends true IsAny<T> extends true
? (...param: any) => void ? (...param: any) => void
: [T] extends [void] : [T] extends [void]
? (...param: unknown[]) => void ? (...param: unknown[]) => void
: [T] extends [any[]] : [T] extends [any[]]
? (...param: T) => void ? (...param: T) => void
: (...param: [T, ...unknown[]]) => void : (...param: [T, ...unknown[]]) => void
export type EventHookOn<T = any> = (fn: Callback<T>) => { export type EventHookOn<T = any> = (fn: Callback<T>) => {
off: () => void off: () => void
} }
.agents/skills/vueuse-functions/references/createInjectionState.md
+15 -4
View File
@@ -149,6 +149,7 @@ const [useProvideCounterStore, useCounterStore] = createInjectionState((initialV
import { createInjectionState } from '@vueuse/core' import { createInjectionState } from '@vueuse/core'
import { computed, shallowRef } from 'vue' import { computed, shallowRef } from 'vue'
// useCounterStore does not return undefined when defaultValue is specified
const [useProvideCounterStore, useCounterStore] = createInjectionState((initialValue: number) => { const [useProvideCounterStore, useCounterStore] = createInjectionState((initialValue: number) => {
// state // state
const count = shallowRef(initialValue) const count = shallowRef(initialValue)
@@ -170,7 +171,8 @@ const [useProvideCounterStore, useCounterStore] = createInjectionState((initialV
```ts ```ts
export type CreateInjectionStateReturn< export type CreateInjectionStateReturn<
Arguments extends Array<any>, Arguments extends Array<any>,
Return, ProvideReturn,
InjectReturn,
> = Readonly< > = Readonly<
[ [
/** /**
@@ -179,13 +181,13 @@ export type CreateInjectionStateReturn<
* @param args Arguments passed to the composable * @param args Arguments passed to the composable
* @returns The state returned by the composable * @returns The state returned by the composable
*/ */
useProvidingState: (...args: Arguments) => Return, useProvidingState: (...args: Arguments) => ProvideReturn,
/** /**
* Call this function in a consumer component to inject the state. * Call this function in a consumer component to inject the state.
* *
* @returns The injected state, or `undefined` if not provided and no default value was set. * @returns The injected state, or `undefined` if not provided and no default value was set.
*/ */
useInjectedState: () => Return | undefined, useInjectedState: () => InjectReturn,
] ]
> >
export interface CreateInjectionStateOptions<Return> { export interface CreateInjectionStateOptions<Return> {
@@ -205,11 +207,20 @@ export interface CreateInjectionStateOptions<Return> {
* *
* @__NO_SIDE_EFFECTS__ * @__NO_SIDE_EFFECTS__
*/ */
export declare function createInjectionState<
Arguments extends Array<any>,
Return,
>(
composable: (...args: Arguments) => Return,
options: {
defaultValue: Return
} & CreateInjectionStateOptions<Return>,
): CreateInjectionStateReturn<Arguments, Return, Return>
export declare function createInjectionState< export declare function createInjectionState<
Arguments extends Array<any>, Arguments extends Array<any>,
Return, Return,
>( >(
composable: (...args: Arguments) => Return, composable: (...args: Arguments) => Return,
options?: CreateInjectionStateOptions<Return>, options?: CreateInjectionStateOptions<Return>,
): CreateInjectionStateReturn<Arguments, Return> ): CreateInjectionStateReturn<Arguments, Return, Return | undefined>
``` ```
.agents/skills/vueuse-functions/references/createReusableTemplate.md
+6 -1
View File
@@ -334,6 +334,10 @@ export interface CreateReusableTemplateOptions<
* @default true * @default true
*/ */
inheritAttrs?: boolean inheritAttrs?: boolean
/**
* Name for the reuse component (useful for devtools).
*/
name?: string
/** /**
* Props definition for reuse component. * Props definition for reuse component.
*/ */
@@ -349,7 +353,8 @@ export interface CreateReusableTemplateOptions<
*/ */
export declare function createReusableTemplate< export declare function createReusableTemplate<
Bindings extends Record<string, any>, Bindings extends Record<string, any>,
MapSlotNameToSlotProps extends ObjectLiteralWithPotentialObjectLiterals = Record<'default', undefined>, MapSlotNameToSlotProps extends ObjectLiteralWithPotentialObjectLiterals =
Record<"default", undefined>,
>( >(
options?: CreateReusableTemplateOptions<Bindings>, options?: CreateReusableTemplateOptions<Bindings>,
): ReusableTemplatePair<Bindings, MapSlotNameToSlotProps> ): ReusableTemplatePair<Bindings, MapSlotNameToSlotProps>
.agents/skills/vueuse-functions/references/onClickOutside.md
+4 -4
View File
@@ -191,12 +191,12 @@ export type OnClickOutsideHandler<
T extends OnClickOutsideOptions<boolean> = OnClickOutsideOptions, T extends OnClickOutsideOptions<boolean> = OnClickOutsideOptions,
> = ( > = (
event: event:
| (T['detectIframe'] extends true ? FocusEvent : never) | (T["detectIframe"] extends true ? FocusEvent : never)
| (T['controls'] extends true ? Event : never) | (T["controls"] extends true ? Event : never)
| PointerEvent, | PointerEvent,
) => void ) => void
export type OnClickOutsideReturn<Controls extends boolean = false> export type OnClickOutsideReturn<Controls extends boolean = false> =
= Controls extends false Controls extends false
? Fn ? Fn
: { : {
stop: Fn stop: Fn
.agents/skills/vueuse-functions/references/onElementRemoval.md
+3 -3
View File
@@ -70,9 +70,9 @@ stop()
```ts ```ts
export interface OnElementRemovalOptions export interface OnElementRemovalOptions
extends extends
ConfigurableWindow, ConfigurableWindow,
ConfigurableDocumentOrShadowRoot, ConfigurableDocumentOrShadowRoot,
WatchOptionsBase {} WatchOptionsBase {}
/** /**
* Fires when the element or any element containing it is removed. * Fires when the element or any element containing it is removed.
* *
.agents/skills/vueuse-functions/references/onKeyStroke.md
+5 -4
View File
@@ -1,5 +1,6 @@
--- ---
category: Sensors category: Sensors
variants: onKeyDown, onKeyUp, onKeyPressed
--- ---
# onKeyStroke # onKeyStroke
@@ -143,7 +144,7 @@ onKeyUp('Shift', () => console.log('Shift key up'))
```ts ```ts
export type KeyPredicate = (event: KeyboardEvent) => boolean export type KeyPredicate = (event: KeyboardEvent) => boolean
export type KeyFilter = true | string | string[] | KeyPredicate export type KeyFilter = true | string | string[] | KeyPredicate
export type KeyStrokeEventName = 'keydown' | 'keypress' | 'keyup' export type KeyStrokeEventName = "keydown" | "keypress" | "keyup"
export interface OnKeyStrokeOptions { export interface OnKeyStrokeOptions {
eventName?: KeyStrokeEventName eventName?: KeyStrokeEventName
target?: MaybeRefOrGetter<EventTarget | null | undefined> target?: MaybeRefOrGetter<EventTarget | null | undefined>
@@ -180,7 +181,7 @@ export declare function onKeyStroke(
export declare function onKeyDown( export declare function onKeyDown(
key: KeyFilter, key: KeyFilter,
handler: (event: KeyboardEvent) => void, handler: (event: KeyboardEvent) => void,
options?: Omit<OnKeyStrokeOptions, 'eventName'>, options?: Omit<OnKeyStrokeOptions, "eventName">,
): () => void ): () => void
/** /**
* Listen to the keypress event of the given key. * Listen to the keypress event of the given key.
@@ -193,7 +194,7 @@ export declare function onKeyDown(
export declare function onKeyPressed( export declare function onKeyPressed(
key: KeyFilter, key: KeyFilter,
handler: (event: KeyboardEvent) => void, handler: (event: KeyboardEvent) => void,
options?: Omit<OnKeyStrokeOptions, 'eventName'>, options?: Omit<OnKeyStrokeOptions, "eventName">,
): () => void ): () => void
/** /**
* Listen to the keyup event of the given key. * Listen to the keyup event of the given key.
@@ -206,6 +207,6 @@ export declare function onKeyPressed(
export declare function onKeyUp( export declare function onKeyUp(
key: KeyFilter, key: KeyFilter,
handler: (event: KeyboardEvent) => void, handler: (event: KeyboardEvent) => void,
options?: Omit<OnKeyStrokeOptions, 'eventName'>, options?: Omit<OnKeyStrokeOptions, "eventName">,
): () => void ): () => void
``` ```
.agents/skills/vueuse-functions/references/onLongPress.md
+16 -10
View File
@@ -37,11 +37,11 @@ onLongPress(
<template> <template>
<p>Long Pressed: {{ longPressedHook }}</p> <p>Long Pressed: {{ longPressedHook }}</p>
<button ref="htmlRefHook" class="button small ml-2"> <button ref="htmlRefHook" class="ml-2 button small">
Press long Press long
</button> </button>
<button class="button small ml-2" @click="resetHook"> <button class="ml-2 button small" @click="resetHook">
Reset Reset
</button> </button>
</template> </template>
@@ -85,8 +85,8 @@ You can provide an `onMouseUp` callback to be notified when the pointer is relea
import { onLongPress } from '@vueuse/core' import { onLongPress } from '@vueuse/core'
onLongPress(target, handler, { onLongPress(target, handler, {
onMouseUp(duration, distance, isLongPress) { onMouseUp(duration, distance, isLongPress, pointerEvent) {
console.log(`Held for ${duration}ms, moved ${distance}px, long press: ${isLongPress}`) console.log(`Held for ${duration}ms, moved ${distance}px, long press: ${isLongPress}, x: ${pointerEvent.clientX}`)
}, },
}) })
``` ```
@@ -134,13 +134,13 @@ function resetComponent() {
<OnLongPress <OnLongPress
as="button" as="button"
class="button small ml-2" class="ml-2 button small"
@trigger="onLongPressCallbackComponent" @trigger="onLongPressCallbackComponent"
> >
Press long Press long
</OnLongPress> </OnLongPress>
<button class="button small ml-2" @click="resetComponent"> <button class="ml-2 button small" @click="resetComponent">
Reset Reset
</button> </button>
</template> </template>
@@ -168,19 +168,19 @@ function resetDirective() {
<button <button
v-on-long-press.prevent="onLongPressCallbackDirective" v-on-long-press.prevent="onLongPressCallbackDirective"
class="button small ml-2" class="ml-2 button small"
> >
Press long Press long
</button> </button>
<button <button
v-on-long-press="[onLongPressCallbackDirective, { delay: 1000, modifiers: { stop: true } }]" v-on-long-press="[onLongPressCallbackDirective, { delay: 1000, modifiers: { stop: true } }]"
class="button small ml-2" class="ml-2 button small"
> >
Press long (with options) Press long (with options)
</button> </button>
<button class="button small ml-2" @click="resetDirective"> <button class="ml-2 button small" @click="resetDirective">
Reset Reset
</button> </button>
</template> </template>
@@ -208,8 +208,14 @@ export interface OnLongPressOptions {
* @param duration how long the element was pressed in ms * @param duration how long the element was pressed in ms
* @param distance distance from the pointerdown position * @param distance distance from the pointerdown position
* @param isLongPress whether the action was a long press or not * @param isLongPress whether the action was a long press or not
* @param pointerEvent the native {@link PointerEvent} triggered by the browser
*/ */
onMouseUp?: (duration: number, distance: number, isLongPress: boolean) => void onMouseUp?: (
duration: number,
distance: number,
isLongPress: boolean,
pointerEvent: PointerEvent,
) => void
} }
export interface OnLongPressModifiers { export interface OnLongPressModifiers {
stop?: boolean stop?: boolean
.agents/skills/vueuse-functions/references/refManualReset.md
+4
View File
@@ -20,6 +20,10 @@ message.reset()
console.log(message.value) // 'default message' console.log(message.value) // 'default message'
``` ```
> [!NOTE]
> `refManualReset` is shallow, which may cause your UI not updated on value changes.
> Wrap your value with `reactive` can achieve deep reactivity, but this workaround may not suit all use cases.
## Type Declarations ## Type Declarations
```ts ```ts
.agents/skills/vueuse-functions/references/refWithControl.md
+2 -3
View File
@@ -132,15 +132,14 @@ export interface ControlledRefOptions<T> {
export declare function refWithControl<T>( export declare function refWithControl<T>(
initial: T, initial: T,
options?: ControlledRefOptions<T>, options?: ControlledRefOptions<T>,
): ShallowUnwrapRef<{ ): {
get: (tracking?: boolean) => T get: (tracking?: boolean) => T
set: (value: T, triggering?: boolean) => void set: (value: T, triggering?: boolean) => void
untrackedGet: () => T untrackedGet: () => T
silentSet: (v: T) => void silentSet: (v: T) => void
peek: () => T peek: () => T
lay: (v: T) => void lay: (v: T) => void
}> } & Ref<T, T>
& Ref<T, T>
/** @deprecated use `refWithControl` instead */ /** @deprecated use `refWithControl` instead */
export declare const controlledRef: typeof refWithControl export declare const controlledRef: typeof refWithControl
``` ```
.agents/skills/vueuse-functions/references/syncRef.md
+25 -25
View File
@@ -64,9 +64,9 @@ console.log(a.value) // 15
## Type Declarations ## Type Declarations
```ts ```ts
type Direction = 'ltr' | 'rtl' | 'both' type Direction = "ltr" | "rtl" | "both"
type SpecificFieldPartial<T, K extends keyof T> = Partial<Pick<T, K>> type SpecificFieldPartial<T, K extends keyof T> = Partial<Pick<T, K>> &
& Omit<T, K> Omit<T, K>
/** /**
* A = B * A = B
*/ */
@@ -74,33 +74,33 @@ type Equal<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false
/** /**
* A ∩ B ≠ ∅ * A ∩ B ≠ ∅
*/ */
type IntersectButNotEqual<A, B> type IntersectButNotEqual<A, B> =
= Equal<A, B> extends true ? false : A & B extends never ? false : true Equal<A, B> extends true ? false : A & B extends never ? false : true
/** /**
* A ⊆ B * A ⊆ B
*/ */
type IncludeButNotEqual<A, B> type IncludeButNotEqual<A, B> =
= Equal<A, B> extends true ? false : A extends B ? true : false Equal<A, B> extends true ? false : A extends B ? true : false
/** /**
* A ∩ B = ∅ * A ∩ B = ∅
*/ */
type NotIntersect<A, B> type NotIntersect<A, B> =
= Equal<A, B> extends true ? false : A & B extends never ? true : false Equal<A, B> extends true ? false : A & B extends never ? true : false
interface EqualType< interface EqualType<
D extends Direction, D extends Direction,
L, L,
R, R,
O extends keyof Transform<L, R> = D extends 'both' ? 'ltr' | 'rtl' : D, O extends keyof Transform<L, R> = D extends "both" ? "ltr" | "rtl" : D,
> { > {
transform?: SpecificFieldPartial<Pick<Transform<L, R>, O>, O> transform?: SpecificFieldPartial<Pick<Transform<L, R>, O>, O>
} }
type StrictIncludeMap< type StrictIncludeMap<
IncludeType extends 'LR' | 'RL', IncludeType extends "LR" | "RL",
D extends Exclude<Direction, 'both'>, D extends Exclude<Direction, "both">,
L, L,
R, R,
> = Equal<[IncludeType, D], ['LR', 'ltr']> > = Equal<[IncludeType, D], ["LR", "ltr"]> &
& Equal<[IncludeType, D], ['RL', 'rtl']> extends true Equal<[IncludeType, D], ["RL", "rtl"]> extends true
? { ? {
transform?: SpecificFieldPartial<Pick<Transform<L, R>, D>, D> transform?: SpecificFieldPartial<Pick<Transform<L, R>, D>, D>
} }
@@ -108,25 +108,25 @@ type StrictIncludeMap<
transform: Pick<Transform<L, R>, D> transform: Pick<Transform<L, R>, D>
} }
type StrictIncludeType< type StrictIncludeType<
IncludeType extends 'LR' | 'RL', IncludeType extends "LR" | "RL",
D extends Direction, D extends Direction,
L, L,
R, R,
> = D extends 'both' > = D extends "both"
? { ? {
transform: SpecificFieldPartial< transform: SpecificFieldPartial<
Transform<L, R>, Transform<L, R>,
IncludeType extends 'LR' ? 'ltr' : 'rtl' IncludeType extends "LR" ? "ltr" : "rtl"
> >
} }
: D extends Exclude<Direction, 'both'> : D extends Exclude<Direction, "both">
? StrictIncludeMap<IncludeType, D, L, R> ? StrictIncludeMap<IncludeType, D, L, R>
: never : never
type IntersectButNotEqualType<D extends Direction, L, R> = D extends 'both' type IntersectButNotEqualType<D extends Direction, L, R> = D extends "both"
? { ? {
transform: Transform<L, R> transform: Transform<L, R>
} }
: D extends Exclude<Direction, 'both'> : D extends Exclude<Direction, "both">
? { ? {
transform: Pick<Transform<L, R>, D> transform: Pick<Transform<L, R>, D>
} }
@@ -140,13 +140,13 @@ interface Transform<L, R> {
ltr: (left: L) => R ltr: (left: L) => R
rtl: (right: R) => L rtl: (right: R) => L
} }
type TransformType<D extends Direction, L, R> type TransformType<D extends Direction, L, R> =
= Equal<L, R> extends true Equal<L, R> extends true
? EqualType<D, L, R> ? EqualType<D, L, R>
: IncludeButNotEqual<L, R> extends true : IncludeButNotEqual<L, R> extends true
? StrictIncludeType<'LR', D, L, R> ? StrictIncludeType<"LR", D, L, R>
: IncludeButNotEqual<R, L> extends true : IncludeButNotEqual<R, L> extends true
? StrictIncludeType<'RL', D, L, R> ? StrictIncludeType<"RL", D, L, R>
: IntersectButNotEqual<L, R> extends true : IntersectButNotEqual<L, R> extends true
? IntersectButNotEqualType<D, L, R> ? IntersectButNotEqualType<D, L, R>
: NotIntersect<L, R> extends true : NotIntersect<L, R> extends true
@@ -185,7 +185,7 @@ export type SyncRefOptions<
* 3. L ⊆ R * 3. L ⊆ R
* 4. L ∩ R = ∅ * 4. L ∩ R = ∅
*/ */
export declare function syncRef<L, R, D extends Direction = 'both'>( export declare function syncRef<L, R, D extends Direction = "both">(
left: Ref<L>, left: Ref<L>,
right: Ref<R>, right: Ref<R>,
...[options]: Equal<L, R> extends true ...[options]: Equal<L, R> extends true
.agents/skills/vueuse-functions/references/toRef.md
-1
View File
@@ -1,6 +1,5 @@
--- ---
category: Reactivity category: Reactivity
alias: resolveRef
--- ---
# toRef # toRef
.agents/skills/vueuse-functions/references/toRefs.md
-3
View File
@@ -8,9 +8,6 @@ Extended [`toRefs`](https://vuejs.org/api/reactivity-utilities.html#torefs) that
## Usage ## Usage
```ts ```ts
import { toRefs } from '@vueuse/core' import { toRefs } from '@vueuse/core'
import { reactive, ref } from 'vue' import { reactive, ref } from 'vue'
.agents/skills/vueuse-functions/references/unrefElement.md
+10 -10
View File
@@ -33,16 +33,16 @@ onMounted(() => {
```ts ```ts
export type VueInstance = ComponentPublicInstance export type VueInstance = ComponentPublicInstance
export type MaybeElementRef<T extends MaybeElement = MaybeElement> = MaybeRef<T> export type MaybeElementRef<T extends MaybeElement = MaybeElement> = MaybeRef<T>
export type MaybeComputedElementRef<T extends MaybeElement = MaybeElement> export type MaybeComputedElementRef<T extends MaybeElement = MaybeElement> =
= MaybeRefOrGetter<T> MaybeRefOrGetter<T>
export type MaybeElement export type MaybeElement =
= | HTMLElement | HTMLElement
| SVGElement | SVGElement
| VueInstance | VueInstance
| undefined | undefined
| null | null
export type UnRefElementReturn<T extends MaybeElement = MaybeElement> export type UnRefElementReturn<T extends MaybeElement = MaybeElement> =
= T extends VueInstance ? Exclude<MaybeElement, VueInstance> : T | undefined T extends VueInstance ? Exclude<MaybeElement, VueInstance> : T | undefined
/** /**
* Get the dom element of a ref of element or Vue component instance * Get the dom element of a ref of element or Vue component instance
* *
.agents/skills/vueuse-functions/references/until.md
+7 -7
View File
@@ -97,21 +97,21 @@ export interface UntilToMatchOptions extends ConfigurableFlushSync {
* *
* @default 'false' * @default 'false'
*/ */
deep?: WatchOptions['deep'] deep?: WatchOptions["deep"]
} }
export interface UntilBaseInstance<T, Not extends boolean = false> { export interface UntilBaseInstance<T, Not extends boolean = false> {
toMatch: (<U extends T = T>( toMatch: (<U extends T = T>(
condition: (v: T) => v is U, condition: (v: T) => v is U,
options?: UntilToMatchOptions, options?: UntilToMatchOptions,
) => Not extends true ? Promise<Exclude<T, U>> : Promise<U>) ) => Not extends true ? Promise<Exclude<T, U>> : Promise<U>) &
& (( ((
condition: (v: T) => boolean, condition: (v: T) => boolean,
options?: UntilToMatchOptions, options?: UntilToMatchOptions,
) => Promise<T>) ) => Promise<T>)
changed: (options?: UntilToMatchOptions) => Promise<T> changed: (options?: UntilToMatchOptions) => Promise<T>
changedTimes: (n?: number, options?: UntilToMatchOptions) => Promise<T> changedTimes: (n?: number, options?: UntilToMatchOptions) => Promise<T>
} }
type Falsy = false | void | null | undefined | 0 | 0n | '' type Falsy = false | void | null | undefined | 0 | 0n | ""
export interface UntilValueInstance< export interface UntilValueInstance<
T, T,
Not extends boolean = false, Not extends boolean = false,
.agents/skills/vueuse-functions/references/useActiveElement.md
+2 -2
View File
@@ -70,8 +70,8 @@ export interface UseActiveElementOptions
*/ */
triggerOnRemoval?: boolean triggerOnRemoval?: boolean
} }
export type UseActiveElementReturn<T extends HTMLElement = HTMLElement> export type UseActiveElementReturn<T extends HTMLElement = HTMLElement> =
= ShallowRef<T | null | undefined> ShallowRef<T | null | undefined>
/** /**
* Reactive `document.activeElement` * Reactive `document.activeElement`
* *

Some files were not shown because too many files have changed in this diff Show More