Automated Vercel Inspector

Inspects Vercel deployment details after deploy commands, extracting build logs, environment status, and domain configuration for immediate feedback.

When to Use This Hook

Attach this hook when you need to:

• Automatically inspect Vercel deployment output after every deploy command to extract actionable build information and error details
• Monitor environment variable configuration and domain assignment for each deployment without manually checking the Vercel dashboard
• Generate deployment summary reports that capture build duration, function count, and output size for tracking deployment health over time

Consider alternatives when:

• You deploy to platforms other than Vercel and need a platform-agnostic deployment inspection solution
• Your CI/CD pipeline already captures and reports comprehensive Vercel deployment metadata through its own integration

Quick Start

Configuration

Copy
name: automated-vercel-inspector
type: hook
trigger: PostToolUse
category: automation

Example Trigger

Copy
vercel deploy --prod
# Hook output:
# Vercel Inspector: Analyzing deployment...

Example Output

Vercel Inspector: Deployment Analysis
Deployment URL: https://my-app-abc123.vercel.app
Production URL: https://my-app.vercel.app
Build Duration: 42s
Framework: Next.js 15.1
Node Version: 20.x
Output Size: 12.4MB
Serverless Functions: 8
Edge Functions: 2
Environment: Production
Domain Status: Active (SSL valid)
Status: READY

Core Concepts

Vercel Inspection Overview

Aspect	Details
Trigger Point	PostToolUse on Bash commands matching vercel deploy patterns
API Integration	Vercel REST API v6 for fetching deployment metadata
Metrics Captured	Build duration, output size, function count, framework, domains
Authentication	VERCEL_TOKEN environment variable for API access
Domain Check	Validates SSL certificate and domain assignment status
History	Appends inspection results to .claude/vercel-inspections.json

Inspection Workflow

PostToolUse (Bash with vercel deploy detected)
    |
    v
[Parse deployment URL from command output]
    |
    v
[Query Vercel API for deployment details]
    |
    v
[Extract: framework, build time, functions, size]
    |
    v
[Check domain assignment and SSL status]
    |
    v
[Generate inspection summary report]
    |
    v
[Append to inspection history]
    |
    v
[Output formatted report]

Configuration

Parameter	Type	Default	Description
VERCEL_TOKEN	string	(required)	Vercel API token for authenticated deployment queries
VERCEL_PROJECT_ID	string	(optional)	Project ID to filter inspections to a specific project
check_domains	boolean	true	Whether to verify domain assignment and SSL certificate status
history_file	string	.claude/vercel-inspections.json	Path to store historical inspection results
include_build_logs	boolean	false	Whether to fetch and display recent build log entries

Best Practices

1. Use inspection data for deployment optimization - Track build duration and output size over time using the history file. Identify trends where builds are getting slower or outputs are growing, and address the root causes before they impact deployment times significantly.

2. Monitor serverless function count - Each deployment's function count can indicate whether new API routes are being added as expected or whether code splitting is fragmenting the application unnecessarily. Set informal thresholds for your team.

3. Verify domain configuration after DNS changes - After modifying DNS records or adding custom domains, the inspector's domain check confirms that SSL certificates are valid and domains are correctly assigned. This catches propagation issues early.

4. Enable build log inspection for failed deployments - When a deployment fails, enable include_build_logs to pull the recent build log entries directly into your terminal. This saves a trip to the Vercel dashboard for common build errors.

5. Integrate with deployment health monitoring - Combine the inspector with the deployment health monitor hook for comprehensive coverage. The inspector provides per-deployment detail while the health monitor tracks aggregate trends across multiple deployments.

Common Issues

1. Inspector cannot find deployment URL in command output - The hook parses vercel deploy output for URLs. If the output format changes in a new Vercel CLI version, the parser may fail. Update the URL extraction regex to match the current Vercel CLI output format.

2. API queries return 403 Forbidden - The VERCEL_TOKEN may lack the required scope for deployment queries. Generate a new token with the "Read" scope for deployments in the Vercel dashboard. Team-scoped tokens require the team ID to access team projects.

3. Inspection history file becomes corrupted - If the hook is interrupted while writing to the JSON history file, the file may contain invalid JSON. Validate the file with python3 -m json.tool .claude/vercel-inspections.json and recreate it if corrupted.