Vercel Analytics Runner

Automatically configure Vercel Analytics and Speed Insights for your React or Vite single-page application with SPA routing, package installation, and deployment verification.

When to Use This Command

Run this command when...

• You are deploying a React or Vite application to Vercel and want analytics and performance monitoring enabled
• You need to install and configure @vercel/analytics and @vercel/speed-insights packages automatically
• You want to fix 404 errors on direct route access by configuring SPA rewrite rules in vercel.json
• You are setting up a new Vercel project and want analytics integration completed in a single command
• You need to add analytics components to your main App file without manually editing imports and JSX

Quick Start

Copy
# .claude/commands/vercel-analytics-runner.yaml
name: Vercel Analytics Runner
description: Configure Vercel Analytics and Speed Insights for React/Vite apps
inputs: []

Copy
# Run with no arguments needed
claude "vercel-analytics-runner"

Output:
  [install] npm install @vercel/analytics @vercel/speed-insights
  [detect] Main app file: src/App.tsx
  [modify] Added Analytics import from @vercel/analytics/react
  [modify] Added SpeedInsights import from @vercel/speed-insights/react
  [modify] Added <Analytics /> and <SpeedInsights /> to App component
  [create] vercel.json with SPA rewrite rules
  [verify] All components properly imported and rendered
  Done. Deploy with 'vercel deploy' to activate.

Core Concepts

Concept	Description
Package Installation	Installs @vercel/analytics and @vercel/speed-insights via your detected package manager
App File Detection	Locates your main React entry point: App.tsx, App.jsx, main.tsx, or main.jsx
Component Injection	Adds <Analytics /> and <SpeedInsights /> components to your main App component JSX
SPA Routing Fix	Creates vercel.json with rewrite rules that serve index.html for all routes, preventing 404 errors
React Import Path	Uses /react import paths (not /next) for SPA frameworks like Vite and Create React App

Setup Flow:
  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
  │   Install    │───>│  Detect App  │───>│   Inject     │
  │   Packages   │    │    File      │    │  Components  │
  └──────────────┘    └──────────────┘    └──────┬───────┘
                                                 │
                                          ┌──────▼───────┐
                                          │   Create     │
                                          │ vercel.json  │
                                          └──────┬───────┘
                                                 │
                                          ┌──────▼───────┐
                                          │   Verify     │
                                          │    Setup     │
                                          └──────────────┘

  vercel.json:
  { "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }] }

Configuration

Parameter	Type	Default	Description
app_file	string	auto-detected	Path to main App component file (e.g., src/App.tsx)
package_manager	string	auto-detected	Package manager: npm, pnpm, or yarn
skip_vercel_json	boolean	false	Skip vercel.json creation if it already exists
framework	string	auto-detected	SPA framework: react, vite, or cra
dry_run	boolean	false	Show what would be changed without modifying files

Best Practices

1. Run before your first Vercel deployment -- Setting up analytics before the initial deploy ensures you capture data from the first visitor. Adding it later creates gaps in historical data.
2. Do not use /next imports for SPAs -- This command correctly uses @vercel/analytics/react and @vercel/speed-insights/react. The /next variants are for Next.js only and will not work in Vite or CRA.
3. Verify vercel.json does not conflict -- If you already have a vercel.json, the command will merge rewrite rules. Review the final file to ensure existing configuration is preserved.
4. Deploy to preview first -- After setup, deploy to a Vercel preview environment to verify analytics appear in the dashboard before promoting to production.
5. Check the Vercel dashboard after deploy -- Analytics data appears within minutes of deployment. Visit vercel.com/dashboard/analytics to confirm events are being recorded.

Common Issues

1. App file not found -- The command searches for common entry points (App.tsx, App.jsx, main.tsx). If your app uses a non-standard entry file, specify it with --app-file src/MyApp.tsx.
2. 404 on direct route access persists -- The vercel.json rewrite must serve /index.html for all routes. Verify the rewrite rule exists and that no other rules are intercepting the request first.
3. Analytics not appearing in dashboard -- Analytics data only appears after deploying to Vercel. Local development does not send data. Deploy with vercel deploy and wait a few minutes for data to populate.