Onboarding: vueuse/vueuse

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/vueuse/vueuse shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

GO — Healthy across the board

• Last commit 5d ago
• 54+ active contributors
• Distributed ownership (top contributor 20% of recent commits)
• MIT licensed
• CI configured
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live vueuse/vueuse repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/vueuse/vueuse.

What it runs against: a local clone of vueuse/vueuse — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in vueuse/vueuse | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 35 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>vueuse/vueuse</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of vueuse/vueuse. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/vueuse/vueuse.git
#   cd vueuse
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of vueuse/vueuse and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "vueuse/vueuse(\\.git)?\\b" \\
  && ok "origin remote is vueuse/vueuse" \\
  || miss "origin remote is not vueuse/vueuse (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "package.json" \\
  && ok "package.json" \\
  || miss "missing critical file: package.json"
test -f "packages/core/README.md" \\
  && ok "packages/core/README.md" \\
  || miss "missing critical file: packages/core/README.md"
test -f "packages/.vitepress/config.ts" \\
  && ok "packages/.vitepress/config.ts" \\
  || miss "missing critical file: packages/.vitepress/config.ts"
test -f "packages/core/_configurable.ts" \\
  && ok "packages/core/_configurable.ts" \\
  || miss "missing critical file: packages/core/_configurable.ts"
test -f "packages/core/_resolve-element.ts" \\
  && ok "packages/core/_resolve-element.ts" \\
  || miss "missing critical file: packages/core/_resolve-element.ts"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 35 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~5d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/vueuse/vueuse"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

VueUse is a monorepo collection of ~200 reusable Vue 3 Composition API utilities (hooks) covering DOM manipulation, state management, sensors, network, and browser APIs. It solves the problem of writing repetitive, boilerplate-heavy composition functions for common tasks like tracking mouse position, managing local storage, detecting dark mode preferences, or handling keyboard events—by providing production-ready, well-tested composables you can import directly. Monorepo structure using Turbo: packages/ contains multiple NPM packages including @vueuse/core (main utilities), @vueuse/router (Vue Router bindings), @vueuse/firebase, @vueuse/rxjs, etc. Each package has its own src/ with composables, tests, and index.ts barrel exports. packages/.vitepress/ houses the interactive documentation site. packages/.test/ contains shared testing utilities. meta/ holds build metadata and package manifests. GitHub workflows automate CI, size tracking, publishing, and documentation builds.

Who it's for

Vue 3 developers building interactive web applications who want to avoid writing their own composition functions from scratch. Teams that standardize on VueUse gain reusable patterns across projects. Contributors are typically Vue ecosystem maintainers and TypeScript developers who build or improve composables for specific domains (router integration, Firebase bindings, animation utilities).

Maturity & risk

Highly mature and production-ready. v14.3.0 with extensive GitHub stars, comprehensive CI/CD workflows (.github/workflows/ci.yml, publish.yml, autofix.yml), full TypeScript support, 100+ published packages, and documented coverage via Codecov badge. Actively maintained with turbo-based monorepo tooling and automated releases. Requires Vue 3.5+ (dropped Vue 2 support in v12.0), signaling intentional forward momentum.

Very low risk for consumption; extremely low risk for contribution. No evidence of single-maintainer bottleneck (large ecosystem project with governance). Dependencies are modern and well-maintained (Vite, Vitest, VitePress, Turbo). Breaking changes are deliberate and versioned (v12 dropped Vue 2). Monorepo scope is large (~200 composables across multiple packages), which means contributions require careful testing (test:all, test:cov workflows) and documentation adherence.

Active areas of work

Active development focused on maintaining Vue 3.5+ compatibility, expanding composable coverage, and improving documentation/demos. CI workflow (ci.yml) runs on PRs (tests, linting, type checking). Export size tracking (export-size.yml) prevents bundle bloat. Automated changelog and stale issue management enabled. Regular releases via publish.ts script. Documentation site at packages/.vitepress/config.ts with dynamic demo components and changelog plugins.

Get running

Clone: git clone https://github.com/vueuse/vueuse.git && cd vueuse. Install with pnpm (required: v10.33.2+): pnpm install. Start dev server with docs: pnpm dev (opens VitePress site with live demos). Build packages: pnpm build:packages. Run tests: pnpm test or pnpm test:all for full coverage.

Daily commands: pnpm dev starts VitePress documentation server with hot reload at http://localhost:5173 (inferred from .vitepress/config.ts). For testing: pnpm test:unit runs unit tests, pnpm test:browser runs browser tests, pnpm test:server runs server tests. pnpm docs:build builds the static documentation site.

Map of the codebase

• package.json — Monorepo root configuration defining all workspace packages, build scripts, and pnpm workspace setup that orchestrates the entire VueUse project.
• packages/core/README.md — Documentation hub for the core composables package, explaining the primary use of VueUse and its most essential utilities.
• packages/.vitepress/config.ts — VitePress documentation site configuration that generates the official VueUse documentation site from markdown and Vue components.
• packages/core/_configurable.ts — Internal utility for making VueUse composables configurable, a foundational pattern used across many composables in the library.
• packages/core/_resolve-element.ts — Critical helper for resolving DOM element references, essential for composables that interact with the DOM (useElementSize, useFocus, etc.).
• eslint.config.js — Project-wide ESLint configuration defining code style and quality standards that all contributors must follow.
• CONTRIBUTING.md — Contribution guidelines documenting the expected workflow, testing standards, and submission process for all contributors.

How to make changes

Add a New Core Composable

1. Create a new directory in packages/core/yourComposableName following the _template structure (packages/core/_template)
2. Implement the composable function in packages/core/yourComposableName/index.ts, exporting types and default function (packages/core/yourComposableName/index.ts)
3. Write comprehensive tests in packages/core/yourComposableName/index.test.ts using the test utilities from packages/.test/setup.ts (packages/core/yourComposableName/index.test.ts)
4. Create markdown documentation in packages/core/yourComposableName/index.md with usage examples and API details (packages/core/yourComposableName/index.md)
5. Add an interactive demo component in packages/core/yourComposableName/demo.vue showcasing the composable (packages/core/yourComposableName/demo.vue)
6. Update meta/packages.ts to register your new composable with category, description, and ecosystem tags (meta/packages.ts)

Add a New Vue Component

1. Create a new Vue file in packages/components/ implementing your component using VueUse composables (packages/components)
2. Export the component from packages/components/index.ts to make it available to users (packages/components/index.ts)
3. Create component documentation in packages/components/ with the same name as the .vue file but .md extension (packages/components)
4. Add TypeScript types and JSDoc comments directly in the component for IDE intellisense (packages/components)

Add Documentation to a Composable

1. Create or update the index.md file in the composable directory with Type Declarations section using TypeScript code blocks (packages/core/yourComposableName/index.md)
2. Use markdown frontmatter to add metadata like function category, since version, and ecosystem tags (packages/core/yourComposableName/index.md)
3. Add Usage, Example, and Related sections in markdown format that will be transformed by packages/.vitepress/plugins/markdownTransform.ts (packages/core/yourComposableName/index.md)
4. Ensure demo.vue component shows interactive examples matching the documentation (packages/core/yourComposableName/demo.vue)

Why these technologies

• Vue 3 Composition API — Core foundation for all composables, providing reactive state management and lifecycle hooks for reusable logic
• TypeScript — Provides type safety, IDE intellisense, and clear API contracts for composable functions
• Vitest + @vue/test-utils — Fast unit testing framework optimized for Vue 3, integrated with Vite for quick feedback loops
• VitePress — Static documentation site generator with Vue 3 component support, enabling interactive demos alongside documentation
• Turbo — Monorepo build orchestrator enabling parallel compilation of multiple packages with caching
• pnpm — Efficient package manager with native monorepo support via workspace protocol and strict dependency resolution

Trade-offs already made

• Single monorepo for 100+ composables instead of separate repos

  • Why: Easier maintenance, consistent versioning, atomic cross-composable refactors, shared test utilities
  • Consequence: Larger initial clone size, but single npm install for all packages; must coordinate releases across related utilities

• Vue 3 only (Composition API), dropped Vue 2 support

  • Why: Composition API enables better code organization, type inference, and tree-shaking than Vue 2 Options API
  • Consequence: Users must use Vue 3; eliminates need for polyfills and compatibility layers; simpler codebase

• Generate docs from markdown + Vue components instead of separate doc site

  • Why: Docs stay in sync with code, demos are runnable, single source of truth
  • Consequence: Docs build time increases with package count; VitePress must render all demos at build time

• Composable-first design with zero runtime dependencies in @vueuse/core

  • Why: Minimal bundle size, zero external dependencies means users can tree-shake unused composables
  • Consequence: Composables must not rely on shared helper libraries; some code duplication across utilities

Non-goals (don't propose these)

• Does not provide UI component library (components are opt-in add-on, not core)
• Does not handle server-side rendering (composables are client-side only, Nuxt integration is external)
• Does not manage global state (composables are for local component state and side effects)
• Does not provide TypeORM-like database abstractions (browser-focused utilities only)
• Does not support Vue 2 (Vue 3 Composition API required)

Traps & gotchas

1. pnpm update must be run after adding new composables to regenerate metadata in meta/packages.ts—without it, new functions won't appear in docs. 2) Tests use Vitest with multiple project configs (browser (chromium), browser (firefox), server, unit, exports)—ensure you run pnpm test:all not just test:unit before committing, or CI will catch failures. 3) The monorepo uses Turbo caching; if you make cross-package changes, run pnpm clean first to avoid stale builds. 4) Documentation components in packages/.vitepress/theme/components/ are auto-loaded—changes take effect after dev server restart.

Architecture

Concepts to learn

• Composition API (Vue 3 specific) — Every VueUse composable is built on Vue 3's Composition API (ref, reactive, computed, watch); understanding this paradigm is essential to reading, using, and contributing composables
• Dependency Injection (DI) via provide/inject — Several VueUse composables use Vue's provide and inject for implicit state sharing (e.g., router composables), allowing parent-child composable coordination without prop drilling
• Event listener lifecycle management — Many VueUse utilities (useMouse, useKeyboard, useEventListener) must clean up DOM event listeners on unmount to prevent memory leaks; VueUse provides patterns like onBeforeUnmount hooks for this
• Tree-shaking (ES modules) — VueUse is designed to be maximally tree-shakeable via barrel exports and ES module structure; unused composables should not appear in final bundles, a core design goal verified by export-size.yml
• Monorepo package management (pnpm workspaces + Turbo) — VueUse's ~15+ packages (core, router, firebase, rxjs, etc.) are managed as a single monorepo; understanding pnpm workspaces and turbo orchestration is critical for building and testing across packages
• Server-Side Rendering (SSR) compatibility — VueUse composables explicitly support Node.js execution (e.g., useLocalStorage has fallback behavior when window is undefined); composables must guard DOM APIs with checks like if (typeof window !== 'undefined')
• Event filtering and debouncing/throttling — VueUse provides built-in event filter chains (pause/resume patterns, debounce, throttle) that wrap composables to prevent excessive handler execution; understanding these improves composable composition and prevents performance bugs

Related repos

• vuejs/core — Vue 3 framework itself; VueUse composables are built entirely on Vue 3 Composition API, so understanding Vue's reactive system is foundational
• nuxt/nuxt — Nuxt auto-imports VueUse composables via first-class integration; many VueUse users consume it through Nuxt projects
• unjs/unhead — Companion library for reactive head management in Vue 3; commonly used alongside VueUse utilities in meta-tag and SEO scenarios
• vue-reactivity/watch — Predecessor/sibling ecosystem: explores advanced reactivity patterns that VueUse composables build upon (e.g., watchDebounced, watchThrottled in VueUse use similar concepts)
• solidjs/solid — Alternative reactive framework with similar composable patterns; some VueUse composables have inspired or been ported to Solid's primitive libraries

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for VitePress theme composables and utilities

The packages/.vitepress/theme/composables directory (dark.ts, versions.ts) and theme utilities lack corresponding unit tests. These composables handle critical functionality like dark mode state management and version tracking that should have dedicated test coverage to prevent regressions in documentation builds.

• [ ] Create packages/.test/vitepress-theme.ts test file
• [ ] Add unit tests for packages/.vitepress/theme/composables/dark.ts (dark mode toggle, persistence, SSR safety)
• [ ] Add unit tests for packages/.vitepress/theme/composables/versions.ts (version fetching, caching)
• [ ] Add tests for VitePress theme redirect logic in packages/.vitepress/theme/redirects.ts
• [ ] Update vitest.config.ts to include a new 'vitepress-theme' test project if needed
• [ ] Ensure tests run as part of the ci.yml workflow

Implement automated export validation workflow for published packages

While there's a test:exports script in package.json, there's no dedicated GitHub Actions workflow to validate package exports in CI/CD. This would catch broken exports, missing type definitions, and tree-shaking issues before releases. The existing .github/workflows structure shows ci.yml, publish.yml, and export-size_yml patterns but no dedicated export validation workflow.

• [ ] Create .github/workflows/validate-exports.yml workflow file
• [ ] Configure workflow to run 'npm run test:exports' on PRs and before publish
• [ ] Add step to validate that all packages in packages/* have correct export maps in package.json
• [ ] Add step to verify type definitions are generated (build:types) and accessible
• [ ] Add step to check for circular dependencies or export conflicts
• [ ] Integrate with existing ci.yml or create separate conditional trigger

Add integration tests for VitePress documentation build pipeline

The complex docs build process (docs:build:vitepress with custom plugins for changelog, contributors, markdown transforms, and PWA) lacks end-to-end tests. The .github/workflows/ci.yml doesn't validate that the documentation actually builds successfully. Given the custom plugins in packages/.vitepress/plugins (changelog.ts, contributors.ts, markdownTransform.ts), a dedicated test ensures breaking changes are caught early.

• [ ] Create packages/.test/vitepress-build.test.ts for documentation pipeline validation
• [ ] Add test that validates VitePress config (packages/.vitepress/config.ts) loads without errors
• [ ] Add tests for markdown transform plugin (packages/.vitepress/plugins/markdownTransform.ts) with sample function documentation
• [ ] Add test for changelog plugin (packages/.vitepress/plugins/changelog.ts) to verify changelog parsing
• [ ] Add test for contributors plugin (packages/.vitepress/plugins/contributors.ts) to verify data generation
• [ ] Add 'docs:build' validation step to ci.yml workflow that runs vitest on vitepress-build tests

Good first issues

• Add missing test coverage for packages/core/src/ composables that only have example code but no index.test.ts files. Pick a utility like useAsyncQueue or useAsyncValidator, write Vitest tests mirroring existing test patterns (see useMouse.test.ts or useLocalStorage.test.ts), and ensure pnpm test:unit passes.: Low to Medium: Improves code reliability and teaches you Vitest + composable testing patterns without modifying API surfaces.
• Improve TypeScript JSDoc coverage for a composable package. Pick 3 utilities in packages/router/src/ or packages/integrations/firebase/src/ that lack @param and @returns annotations, add detailed TSDoc comments following existing patterns (e.g., packages/core/src/useMouse.ts), and verify pnpm typecheck and docs rendering work.: Low: Directly improves developer experience via IDE autocomplete and docs generation, low risk since it's documentation-only.
• Add a missing demo or fix a demo for a composable in packages/.vitepress/theme/components/. Identify a composable with no interactive example on vueuse.org, create a .vue demo file in the composable's folder, register it in markdown frontmatter (similar to existing DemoContainer.vue usage), and test locally with pnpm dev.: Low to Medium: Makes the library more discoverable and helps users understand composable behavior through interactive examples; directly visible impact.

Top contributors

• @9romise — 20 commits
• @antfu — 17 commits
• @serkodev — 4 commits
• @babu-ch — 3 commits
• @IceMooncake — 2 commits

Recent commits

• 99c5df9 — chore: release v14.3.0 (antfu)
• 9d0804f — chore: fix types (antfu)
• 28a458c — chore: update deps (antfu)
• 1a3e572 — feat(useTextareaAutosize): add optional maxHeight to limit autosize growth (#5324) (palamarchukser)
• e890d4c — docs: render sponsor links as HTML for better discoverability (#5348) (shtefcs)
• d886c2f — fix(useCached): update comparator type and improve documentation (#5376) (IceMooncake)
• acf182e — docs(useCloned): add tip about watch flush timing (#5375) (iXueJie)
• 5ec568d — fix(useClipboard): prevents fail in Safari for async operation (#5369) (MatteoGabriele)
• 3341fca — fix(useSortable): re-query DOM on every start() for string selectors (#5374) (Mini-ghost)
• c541332 — chore: replace exports testing with tsnapi and tsdown-stale-guard (#5366) (antfu)

Security observations

VueUse demonstrates a generally sound security posture as a Vue utility library. The codebase is a monorepo with documentation site and utilities focused on composition functions - inherently lower risk for injection attacks. No hardcoded secrets, exposed credentials, or obvious SQL injection vectors were detected. Primary concerns are: (1) incomplete dependency visibility prevents full vulnerability assessment, (2) documentation site components should be reviewed for XSS risks in demo rendering, (3) service worker and mock server configurations need security validation. The project follows modern security practices with ESLint configuration and appears well-maintained. Recommended actions: complete dependency audit, configure security headers for the documentation site, and review theme components handling dynamic content.

• Medium · Incomplete Package.json Dependency Analysis — package.json. The package.json file provided is truncated at the devDependencies section, preventing complete analysis of all dependencies for known vulnerabilities. The full dependency tree cannot be verified against CVE databases. Fix: Provide complete package.json file content and run npm audit or pnpm audit to identify vulnerable dependencies. Set up automated dependency scanning in CI/CD pipeline.
• Low · Missing Security Headers Configuration — netlify.toml. The netlify.toml configuration file is present but not visible for review. Security headers (CSP, X-Frame-Options, X-Content-Type-Options, etc.) may not be properly configured for the documentation site. Fix: Configure comprehensive security headers in netlify.toml including: Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, and X-XSS-Protection headers.
• Low · Potential XSS Risk in Documentation Theme — packages/.vitepress/theme/components/. Multiple Vue components in the documentation theme (DemoContainer.vue, Home.vue, etc.) may render dynamic content. Vue's template escaping is generally safe, but custom demo rendering could be vulnerable to XSS if user input is not properly sanitized. Fix: Review DemoContainer.vue and any components that render user-generated or external content. Ensure v-html is never used with untrusted content. Use v-text or string interpolation for dynamic content.
• Low · Test Mock Server Configuration — packages/.test/mockServer.ts. A mock server is configured in test utilities (packages/.test/mockServer.ts). If not properly isolated, this could potentially be exposed or misconfigured in development environments. Fix: Ensure mock server is only used in test environments. Verify it uses appropriate CORS policies and is not exposed to production builds. Add environment checks to prevent accidental activation.
• Low · Service Worker Configuration — packages/.vitepress/sw.ts. A service worker is present in the documentation (packages/.vitepress/sw.ts). Service workers have elevated privileges and must be carefully secured to prevent cache poisoning or offline attacks. Fix: Review service worker implementation for: proper cache versioning, validation of cached content, secure update mechanisms, and prevention of stale cache serving. Use strict CSP headers for SW scope.
• Low · Markdown File Processing Plugin — packages/.vitepress/plugins/markdownTransform.ts. A custom markdown transformation plugin exists (packages/.vitepress/plugins/markdownTransform.ts). Custom markdown processing can introduce security issues if not properly validating/sanitizing input. Fix: Review markdown transformation logic for proper HTML sanitization. Use established libraries like sanitize-html or DOMPurify if processing untrusted markdown. Avoid eval() or Function() constructors.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.