Skip to main content
skill CX Codex

vercel-policy-guardrails — Claude Code skill

The vercel-policy-guardrails skill adds Vercel project checks for secret exposure, CI policy violations, Edge Runtime imports, and protected routes.

MIT 1 installs ★ 2,935 updated 2026-11-01

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add jeremylongshore/tons-of-skills-marketplace --skill vercel-policy-guardrails -a claude-code
Open on GitHub

What vercel-policy-guardrails does

The skill sets guardrails for Vercel projects. It checks sensitive variables that use the NEXT_PUBLIC_ prefix, blocks Node.js imports in Edge Runtime files, and scans staged files for credential patterns before a commit.

Its setup includes ESLint rules, a pre-commit hook, CI validation for vercel.json, Edge Runtime checks, a .next/ output-size check, and a guard that keeps .env.example aligned with variables used in code. It also includes middleware for enforcing authentication on protected routes. The project needs ESLint, Git hook infrastructure, a CI/CD pipeline, and TypeScript. Without ESLint configured, the main lint rules cannot run.

What it helps with

  • block secrets from client bundles
  • scan staged files before commits
  • validate vercel.json in CI
  • catch Node.js imports in Edge Runtime code
  • keep .env.example aligned with code

Example prompts for the agent

  • Set up Vercel guardrails that prevent secrets from reaching client bundles.
  • Add CI checks for vercel.json, Edge Runtime imports, and the build output size.
  • Check that protected routes require authentication and every environment variable is documented in .env.example.

How to install vercel-policy-guardrails

1Skills CLI (Vercel)

npx skills add jeremylongshore/tons-of-skills-marketplace --skill vercel-policy-guardrails -a claude-code

2Manually: put the files in place

~/.claude/skills/vercel-policy-guardrails/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/vercel-policy-guardrails/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about vercel-policy-guardrails

How do I install vercel-policy-guardrails in Claude Code?

Run npx skills add jeremylongshore/tons-of-skills-marketplace --skill vercel-policy-guardrails -a claude-code, then check ~/.claude/skills/vercel-policy-guardrails/SKILL.md.

What does vercel-policy-guardrails do?

It adds ESLint rules, credential scanning before commits, and CI policy checks for Vercel projects. The checks cover Edge Runtime compatibility, build output size, environment variable documentation, and route authentication.

What does the project need before using this skill?

The project needs configured ESLint, Git hook infrastructure, a CI/CD pipeline, and TypeScript. The checks work with files such as vercel.json and .env.example.

Source text

SKILL.md · MIT
---
name: vercel-policy-guardrails
description: 'Implement lint rules, CI policy checks, and automated guardrails for
  Vercel projects.

  Use when setting up code quality rules, preventing secret exposure,

  or enforcing deployment policies for Vercel applications.

  Trigger with phrases like "vercel policy", "vercel lint",

  "vercel guardrails", "vercel best practices check", "vercel secret scan".

  '
allowed-tools: Read, Write, Edit, Bash(npx:*), Bash(npm:*)
version: 1.18.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- vercel
- policy
- linting
- security
compatibility: Designed for Claude Code
---
# Vercel Policy Guardrails

## Overview

Protect against common Vercel failure modes with automated guardrails: ESLint rules preventing secret exposure in client bundles, pre-commit hooks scanning for credentials, CI checks validating vercel.json and edge runtime compatibility, and runtime middleware enforcing auth on protected routes.

## Prerequisites

- ESLint configured in project
- Git hooks infrastructure (husky or lefthook)
- CI/CD pipeline (GitHub Actions or similar)
- TypeScript for type enforcement

## Instructions

### Step 1: ESLint Rules — Prevent Secret Exposure

```javascript
// .eslintrc.js — custom rules for Vercel projects
module.exports = {
  rules: {
    // Prevent using NEXT_PUBLIC_ prefix for sensitive variables
    'no-restricted-syntax': [
      'error',
      {
        selector: 'MemberExpression[object.property.name="env"][property.name=/^NEXT_PUBLIC_(SECRET|KEY|TOKEN|PASSWORD|PRIVATE)/]',
        message: 'Do not prefix secrets with NEXT_PUBLIC_ — they will be exposed in the client bundle',
      },
    ],
  },
  overrides: [
    {
      // Edge runtime files — prevent Node.js API usage
      files: ['**/edge-*.ts', '**/middleware.ts'],
      rules: {
        'no-restricted-imports': [
          'error',
          {
            paths: [
              { name: 'fs', message: 'fs is not available in Edge Runtime. Use fetch or Vercel Blob.' },
              { name: 'path', message: 'path is not available in Edge Runtime. Use URL API.' },
              { name: 'crypto', message: 'Use globalThis.crypto (Web Crypto API) in Edge Runtime.' },
              { name: 'child_process', message: 'child_process is not available in Edge Runtime.' },
              { name: 'net', message: 'net is not available in Edge Runtime.' },
            ],
          },
        ],
      },
    },
  ],
};
```

### Step 2: Pre-Commit Hook — Credential Scanning

```bash
# Install husky
npm install --save-dev husky
npx husky init
```

```bash
#!/usr/bin/env bash
# .husky/pre-commit
set -euo pipefail

# Scan staged files for credentials
PATTERNS=(
  'VERCEL_TOKEN\s*[:=]\s*\S+'
  'vercel_[a-zA-Z]*_token\s*[:=]\s*\S+'
  'sk_live_[a-zA-Z0-9]+'
  'NEXT_PUBLIC_.*SECRET'
  'api\.vercel\.com.*Bearer\s+[a-zA-Z0-9]+'
)

STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
FOUND=0

for file in $STAGED_FILES; do
  for pattern in "${PATTERNS[@]}"; do
    if grep -qEi "$pattern" "$file" 2>/dev/null; then
      echo "ERROR: Potential credential found in $file"
      echo "  Pattern: $pattern"
      FOUND=1
    fi
  done
done

if [ $FOUND -ne 0 ]; then
  echo ""
  echo "Commit blocked: Remove credentials and use environment variables."
  echo "See: vercel env add <KEY> <environment>"
  exit 1
fi
```

### Step 3: CI Policy Check — vercel.json Validation

```yaml
# .github/workflows/vercel-policy.yml
name: Vercel Policy Checks
on: [pull_request]

jobs:
  policy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }

      - name: Validate vercel.json schema
        run: |
          if [ -f vercel.json ]; then
            node -e "
              const config = require('./vercel.json');
              const errors = [];

              // Check for deprecated builds property
              if (config.builds) {
                errors.push('vercel.json uses deprecated \"builds\" property — use \"functions\" instead');
              }

              // Check compressHTML (iOS Safari issue)
              if (config.compressHTML === true) {
                errors.push('compressHTML should be disabled — causes iOS Safari rendering issues');
              }

              // Check for hardcoded secrets in headers
              const headerStr = JSON.stringify(config.headers ?? []);
              if (/Bearer\s+[a-zA-Z0-9]{20,}/.test(headerStr)) {
                errors.push('Hardcoded token found in vercel.json headers');
              }

              if (errors.length > 0) {
                console.error('Policy violations:');
                errors.forEach(e => console.error('  - ' + e));
                process.exit(1);
              }
              console.log('vercel.json policy checks passed');
            "
          fi

      - name: Check edge runtime compatibility
        run: |
          # Find files with edge runtime declaration
          for file in $(grep -rl "runtime.*=.*'edge'" src/ api/ 2>/dev/null || true); do
            echo "Checking edge compatibility: $file"
            # Check for Node.js-only imports
            if grep -E "require\(['\"]fs['\"]|from ['\"]fs['\"]|from ['\"]path['\"]|from ['\"]crypto['\"]" "$file"; then
              echo "ERROR: $file uses Node.js APIs incompatible with Edge Runtime"
              exit 1
            fi
          done
          echo "Edge runtime compatibility checks passed"

      - name: Check bundle size budget
        run: |
          npm ci
          npm run build
          # Check output size
          TOTAL=$(du -sb .next/ 2>/dev/null | cut -f1 || echo 0)
          MAX=$((250 * 1024 * 1024))  # 250MB
          if [ "$TOTAL" -gt "$MAX" ]; then
            echo "ERROR: Build output ($TOTAL bytes) exceeds budget ($MAX bytes)"
            exit 1
          fi
          echo "Bundle size within budget: $TOTAL bytes"
```

### Step 4: Env Var Documentation Guard

```bash
#!/usr/bin/env bash
# scripts/check-env-docs.sh — ensure .env.example stays in sync
set -euo pipefail

# Extract env vars used in code
CODE_VARS=$(grep -roh 'process\.env\.\w\+' src/ api/ 2>/dev/null \
  | sed 's/process\.env\.//' \
  | sort -u)

# Extract vars documented in .env.example
if [ ! -f .env.example ]; then
  echo "ERROR: .env.example file missing"
  exit 1
fi

DOC_VARS=$(grep -oE '^\w+=' .env.example | sed 's/=//' | sort -u)

# Find undocumented vars
MISSING=$(comm -23 <(echo "$CODE_VARS") <(echo "$DOC_VARS"))
if [ -n "$MISSING" ]; then
  echo "ERROR: Undocumented environment variables:"
  echo "$MISSING" | sed 's/^/  /'
  echo "Add these to .env.example"
  exit 1
fi

echo "All environment variables documented"
```

### Step 5: Runtime Auth Middleware Guard

```typescript
// middleware.ts — enforce that protected routes always require auth
import { NextRequest, NextResponse } from 'next/server';

// Routes that MUST require authentication
const PROTECTED_PATTERNS = [
  /^\/api\/admin/,
  /^\/api\/users/,
  /^\/dashboard/,
  /^\/settings/,
];

// Routes explicitly allowed without auth
const PUBLIC_PATTERNS = [
  /^\/api\/health/,
  /^\/api\/webhooks/,
  /^\/$/, // homepage
  /^\/login/,
  /^\/signup/,
];

export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;

  const isProtected = PROTECTED_PATTERNS.some(p => p.test(pathname));
  const isPublic = PUBLIC_PATTERNS.some(p => p.test(pathname));

  if (isProtected && !isPublic) {
    const token = request.cookies.get('session')?.value;
    if (!token) {
      if (pathname.startsWith('/api/')) {
        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
      }
      return NextResponse.redirect(new URL('/login', request.url));
    }
  }

  return NextResponse.next();
}

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};
```

### Step 6: Deployment Freeze Guard

```bash
#!/usr/bin/env bash
# scripts/check-deploy-freeze.sh — prevent production deploys during freeze windows
set -euo pipefail

# Check if we're in a deployment freeze window
HOUR=$(date -u +%H)
DAY=$(date -u +%u)  # 1=Monday, 7=Sunday

# No deploys on weekends
if [ "$DAY" -gt 5 ]; then
  echo "BLOCKED: No production deploys on weekends"
  exit 1
fi

# No deploys after 4pm UTC (Friday especially)
if [ "$DAY" -eq 5 ] && [ "$HOUR" -ge 16 ]; then
  echo "BLOCKED: No production deploys after 4pm UTC on Fridays"
  exit 1
fi

echo "Deploy allowed"
```

## Guardrails Summary

| Guardrail | Enforcement Point | Prevents |
|-----------|-------------------|----------|
| Secret prefix lint | ESLint (editor + CI) | Client bundle secret exposure |
| Edge runtime lint | ESLint (editor + CI) | Node.js APIs in edge functions |
| Credential scan | Pre-commit hook | Secrets in version control |
| vercel.json validation | CI | Deprecated config, hardcoded tokens |
| Env var documentation | CI | Missing .env.example entries |
| Auth middleware | Runtime | Unprotected routes |
| Deploy freeze | CI | Weekend/late deploys |

## Output

- ESLint rules preventing secret exposure and edge runtime violations
- Pre-commit hooks blocking credentials from entering git
- CI policy checks validating configuration and compatibility
- Runtime middleware enforcing authentication on protected routes
- Deployment freeze windows preventing risky deploys

## Error Handling

| Error | Cause | Solution |
|-------|-------|----------|
| ESLint rule false positive | Variable name matches pattern | Add `// eslint-disable-next-line` with justification |
| Pre-commit hook blocks valid commit | Pattern too broad | Narrow the regex or add allowlist |
| CI edge check false positive | Dead import | Remove unused import |
| Deploy freeze too restrictive | Urgent hotfix needed | Use `--force` flag with team approval |

## Examples

### Authorize an urgent deployment-freeze exception

For a production incident, create a time-boxed exception that names the incident, deployment SHA, approving owner, and rollback deployment. Run required tests and a synthetic preview check before the exception is used; the bypass must be scoped to this release rather than disabling the freeze globally. After recovery, revoke the exception, review why the normal window could not be used, and add a focused prevention item to the incident record.

## Resources

- [ESLint Custom Rules](https://eslint.org/docs/latest/extend/plugins)
- [Husky Documentation](https://typicode.github.io/husky/)
- [Vercel Project Configuration](https://vercel.com/docs/project-configuration)
- [Edge Runtime API](https://vercel.com/docs/functions/runtimes/edge)

## Next Steps

For architecture variants, see `vercel-architecture-variants`.

© Jeremy Longshore · MIT · jeremylongshore/tons-of-skills-marketplace

Similar skills

All skills for Security →

From the same set139

The whole set →
apollo-core-workflow-a apollo-core-workflow-a builds an Apollo.io lead generation pipeline in Claude Code to search prospects and enrich qualified contacts with verified emails and phone numbers. CX Codex +1 1installs firecrawl-migration-deep-dive The firecrawl-migration-deep-dive skill guides a move from Puppeteer, Playwright, Cheerio, or another scraper to Firecrawl v2, with checks for parity, policy, spend, and rollback. CX Codex +1 1installs vercel-webhooks-events vercel-webhooks-events — a skill for Claude Code, Codex, Cursor and other platforms that processes Vercel deployment events with HMAC signature verification. CX Codex +1 1installs vercel-reference-architecture vercel-reference-architecture sets up a layered Vercel architecture for Next.js applications. Helps structure edge middleware, serverless API routes, and environment validation. CX Codex +1 1installs gcs-lifecycle-policy gcs-lifecycle-policy — a skill that handles lifecycle policy work in Google Cloud Storage. It activates on its own when a request mentions gcs or lifecycle policy. CX Codex +1 1installs gcs-bucket-config gcs-bucket-config automates Google Cloud Storage bucket configuration in Claude Code. Generates configs and gcloud commands for your storage setups. CX Codex +1 1installs s3-bucket-policy-generator The s3-bucket-policy-generator skill guides S3 bucket policy work, generates configurations, and checks results against common standards when AWS tasks call for it. CX Codex +1 1installs sqs-queue-setup Guides you through Amazon SQS queue setup and generates configurations. It activates on its own when SQS comes up in a request. CX Codex +1 1installs

Project sponsors

Companies that keep this analytics open