@intentsolutionsio/vercel-pack 1.0.0 → 1.0.3

package/skills/vercel-multi-env-setup/SKILL.md

@@ -1,222 +1,225 @@
 ---
 name: vercel-multi-env-setup
-description: |
-  Configure Vercel across development, staging, and production environments.
-  Use when setting up multi-environment deployments, configuring per-environment secrets,
-  or implementing environment-specific Vercel configurations.
+description: 'Configure Vercel across development, preview, and production environments
+  with scoped secrets.
+
+  Use when setting up per-environment configuration, managing environment-specific
+  variables,
+
+  or implementing environment isolation on Vercel.
+
   Trigger with phrases like "vercel environments", "vercel staging",
-  "vercel dev prod", "vercel environment setup", "vercel config by env".
-allowed-tools: Read, Write, Edit, Bash(aws:*), Bash(gcloud:*), Bash(vault:*)
+
+  "vercel dev prod", "vercel environment setup", "vercel env scoping".
+
+  '
+allowed-tools: Read, Write, Edit, Bash(vercel:*)
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- vercel
+- deployment
+- environments
+- configuration
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
-
-# Vercel Multi-Environment Setup
+# Vercel Multi-Env Setup
 
 ## Overview
-Configure Vercel across development, staging, and production environments.
 
-## Prerequisites
-- Separate Vercel accounts or API keys per environment
-- Secret management solution (Vault, AWS Secrets Manager, etc.)
-- CI/CD pipeline with environment variables
-- Environment detection in application
+Configure Vercel's three built-in environments (Development, Preview, Production) with scoped environment variables, branch-specific preview URLs, and custom environments for staging. Uses Vercel's native environment system and the REST API for automation.
 
-## Environment Strategy
+## Prerequisites
 
-| Environment | Purpose | API Keys | Data |
-|-------------|---------|----------|------|
-| Development | Local dev | Test keys | Sandbox |
-| Staging | Pre-prod validation | Staging keys | Test data |
-| Production | Live traffic | Production keys | Real data |
+- Vercel project linked and deployed
+- Separate database instances per environment (recommended)
+- Access to Vercel dashboard or VERCEL_TOKEN for API
 
-## Configuration Structure
+## Instructions
 
-```
-config/
-├── vercel/
-│   ├── base.json           # Shared config
-│   ├── development.json    # Dev overrides
-│   ├── staging.json        # Staging overrides
-│   └── production.json     # Prod overrides
-```
+### Step 1: Understand Vercel's Environment Model
 
-### base.json
-```json
-{
-  "timeout": 30000,
-  "retries": 3,
-  "cache": {
-    "enabled": true,
-    "ttlSeconds": 60
-  }
-}
-```
+Vercel provides three built-in environments:
 
-### development.json
-```json
-{
-  "apiKey": "${VERCEL_API_KEY}",
-  "baseUrl": "https://api-sandbox.vercel.com",
-  "debug": true,
-  "cache": {
-    "enabled": false
-  }
-}
-```
+| Environment | Trigger | URL Pattern | Use Case |
+|-------------|---------|-------------|----------|
+| Production | Push to production branch | `yourdomain.com` | Live traffic |
+| Preview | Push to any other branch | `project-git-branch-team.vercel.app` | PR review |
+| Development | `vercel dev` locally | `localhost:3000` | Local dev |
 
-### staging.json
-```json
-{
-  "apiKey": "${VERCEL_API_KEY_STAGING}",
-  "baseUrl": "https://api-staging.vercel.com",
-  "debug": false
-}
-```
+### Step 2: Scope Environment Variables
 
-### production.json
-```json
-{
-  "apiKey": "${VERCEL_API_KEY_PROD}",
-  "baseUrl": "https://api.vercel.com",
-  "debug": false,
-  "retries": 5
-}
-```
+```bash
+# Add a variable scoped to Production only
+vercel env add DATABASE_URL production
+# Enter: postgres://prod-host:5432/myapp
 
-## Environment Detection
+# Add a variable scoped to Preview only
+vercel env add DATABASE_URL preview
+# Enter: postgres://staging-host:5432/myapp_staging
 
-```typescript
-// src/vercel/config.ts
-import baseConfig from '../../config/vercel/base.json';
+# Add a variable scoped to Development only
+vercel env add DATABASE_URL development
+# Enter: postgres://localhost:5432/myapp_dev
 
-type Environment = 'development' | 'staging' | 'production';
+# Add a variable available in ALL environments
+vercel env add NEXT_PUBLIC_APP_NAME production preview development
+# Enter: My App
 
-function detectEnvironment(): Environment {
-  const env = process.env.NODE_ENV || 'development';
-  const validEnvs: Environment[] = ['development', 'staging', 'production'];
-  return validEnvs.includes(env as Environment)
-    ? (env as Environment)
-    : 'development';
-}
+# List all env vars with their scopes
+vercel env ls
+```
 
-export function getVercelConfig() {
-  const env = detectEnvironment();
-  const envConfig = require(`../../config/vercel/${env}.json`);
+### Step 3: Via REST API (Automation)
 
-  return {
-    ...baseConfig,
-    ...envConfig,
-    environment: env,
-  };
-}
+```bash
+# Create env vars with specific scoping
+curl -X POST "https://api.vercel.com/v9/projects/my-app/env" \
+  -H "Authorization: Bearer $VERCEL_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "key": "DATABASE_URL",
+    "value": "postgres://prod-host:5432/myapp",
+    "type": "encrypted",
+    "target": ["production"]
+  }'
+
+# Upsert — update if exists, create if not
+curl -X POST "https://api.vercel.com/v9/projects/my-app/env?upsert=true" \
+  -H "Authorization: Bearer $VERCEL_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "key": "DATABASE_URL",
+    "value": "postgres://staging-host:5432/myapp_staging",
+    "type": "encrypted",
+    "target": ["preview"]
+  }'
+
+# List all env vars for a project
+curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \
+  "https://api.vercel.com/v9/projects/my-app/env" \
+  | jq '.envs[] | {key, target, type}'
 ```
 
-## Secret Management by Environment
+### Step 4: Custom Environments (Beyond Dev/Preview/Prod)
+
+Vercel supports custom environments for staging, QA, etc.:
 
-### Local Development
 ```bash
-# .env.local (git-ignored)
-VERCEL_API_KEY=sk_test_dev_***
+# Create a custom environment via API
+curl -X POST "https://api.vercel.com/v1/projects/my-app/custom-environments" \
+  -H "Authorization: Bearer $VERCEL_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Staging",
+    "slug": "staging",
+    "branchPattern": "staging"
+  }'
 ```
 
-### CI/CD (GitHub Actions)
-```yaml
-env:
-  VERCEL_API_KEY: ${{ secrets.VERCEL_API_KEY_${{ matrix.environment }} }}
-```
+Or in the dashboard: **Settings > Environments > Create Environment**
 
-### Production (Vault/Secrets Manager)
-```bash
-# AWS Secrets Manager
-aws secretsmanager get-secret-value --secret-id vercel/production/api-key
+Custom environments let you:
 
-# GCP Secret Manager
-gcloud secrets versions access latest --secret=vercel-api-key
+- Link a specific Git branch to the environment
+- Scope environment variables to it
+- Assign a custom domain (e.g., `staging.yourdomain.com`)
 
-# HashiCorp Vault
-vault kv get -field=api_key secret/vercel/production
+### Step 5: Branch-Specific Preview Domains
+
+```bash
+# Assign a custom domain to a specific branch
+# In dashboard: Settings > Domains > Add
+# Set Git Branch: "staging"
+# Domain: staging.yourdomain.com
+
+# Via API — add domain to project with branch targeting
+curl -X POST "https://api.vercel.com/v9/projects/my-app/domains" \
+  -H "Authorization: Bearer $VERCEL_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "staging.yourdomain.com",
+    "gitBranch": "staging"
+  }'
 ```
 
-## Environment Isolation
+### Step 6: Environment Detection in Code
 
 ```typescript
-// Prevent production operations in non-prod
-function guardProductionOperation(operation: string): void {
-  const config = getVercelConfig();
+// src/lib/env.ts — detect environment at runtime
+export function getEnvironment(): 'production' | 'preview' | 'development' {
+  return (process.env.VERCEL_ENV as any) ?? 'development';
+}
 
-  if (config.environment !== 'production') {
-    console.warn(`[vercel] ${operation} blocked in ${config.environment}`);
-    throw new Error(`${operation} only allowed in production`);
+// Environment-specific behavior
+export function getApiBaseUrl(): string {
+  switch (getEnvironment()) {
+    case 'production':
+      return 'https://api.yourdomain.com';
+    case 'preview':
+      return `https://${process.env.VERCEL_URL}`;
+    case 'development':
+      return 'http://localhost:3000';
   }
 }
 
-// Usage
-async function deleteAllData() {
-  guardProductionOperation('deleteAllData');
-  // Dangerous operation here
+// Production safeguards
+export function assertNotProduction(operation: string): void {
+  if (getEnvironment() === 'production') {
+    throw new Error(`Dangerous operation "${operation}" blocked in production`);
+  }
 }
 ```
 
-## Feature Flags by Environment
-
-```typescript
-const featureFlags: Record<Environment, Record<string, boolean>> = {
-  development: {
-    newFeature: true,
-    betaApi: true,
-  },
-  staging: {
-    newFeature: true,
-    betaApi: false,
-  },
-  production: {
-    newFeature: false,
-    betaApi: false,
-  },
-};
-```
+### Step 7: Pull Env Vars for Local Development
 
-## Instructions
+```bash
+# Pull Development-scoped vars to local file
+vercel env pull .env.development.local
 
-### Step 1: Create Config Structure
-Set up the base and per-environment configuration files.
+# Pull Preview-scoped vars (for testing preview behavior locally)
+vercel env pull --environment=preview .env.preview.local
 
-### Step 2: Implement Environment Detection
-Add logic to detect and load environment-specific config.
+# .gitignore these files
+echo '.env*.local' >> .gitignore
+```
 
-### Step 3: Configure Secrets
-Store API keys securely using your secret management solution.
+## Environment Variable Types
 
-### Step 4: Add Environment Guards
-Implement safeguards for production-only operations.
+| Type | Dashboard Visibility | Log Visibility | Use Case |
+|------|---------------------|---------------|----------|
+| `plain` | Visible | Visible | Non-sensitive config |
+| `encrypted` | Hidden after save | Hidden | API keys, secrets |
+| `sensitive` | Always hidden | Hidden | High-security secrets |
+| `system` | Auto-set by Vercel | Visible | `VERCEL_ENV`, `VERCEL_URL` |
 
 ## Output
-- Multi-environment config structure
-- Environment detection logic
-- Secure secret management
-- Production safeguards enabled
 
-## Error Handling
-| Issue | Cause | Solution |
-|-------|-------|----------|
-| Wrong environment | Missing NODE_ENV | Set environment variable |
-| Secret not found | Wrong secret path | Verify secret manager config |
-| Config merge fails | Invalid JSON | Validate config files |
-| Production guard triggered | Wrong environment | Check NODE_ENV value |
+- Environment variables scoped per environment (dev/preview/prod)
+- Custom staging environment with dedicated branch and domain
+- Environment detection logic for runtime behavior switching
+- Local development env vars pulled from Vercel
 
-## Examples
+## Error Handling
 
-### Quick Environment Check
-```typescript
-const env = getVercelConfig();
-console.log(`Running in ${env.environment} with ${env.baseUrl}`);
-```
+| Error | Cause | Solution |
+|-------|-------|----------|
+| Env var undefined in preview | Not scoped to Preview target | Re-add with Preview in target array |
+| Wrong database in production | Preview DB URL used in prod | Check env var scoping per environment |
+| `vercel env pull` empty | No Development-scoped vars | Add vars with Development target |
+| Custom env not triggering | Branch pattern doesn't match | Check branch name matches environment slug |
+| Sensitive var can't be read | type=sensitive hides value | Re-add the var if value is lost |
 
 ## Resources
-- [Vercel Environments Guide](https://vercel.com/docs/environments)
-- [12-Factor App Config](https://12factor.net/config)
+
+- [Environment Variables](https://vercel.com/docs/environment-variables)
+- [Environments](https://vercel.com/docs/deployments/environments)
+- [System Environment Variables](https://vercel.com/docs/environment-variables/system-environment-variables)
+- [Managing Environment Variables](https://vercel.com/docs/environment-variables/managing-environment-variables)
+- [REST API: Environment Variables](https://vercel.com/docs/rest-api/sdk/examples/environment-variables)
 
 ## Next Steps
-For observability setup, see `vercel-observability`.
+
+For observability and monitoring, see `vercel-observability`.

package/skills/vercel-multi-env-setup/references/configuration-structure.md

@@ -0,0 +1,59 @@
+# Configuration Structure
+
+## Configuration Structure
+
+```
+config/
+├── vercel/
+│   ├── base.json           # Shared config
+│   ├── development.json    # Dev overrides
+│   ├── staging.json        # Staging overrides
+│   └── production.json     # Prod overrides
+```
+
+### base.json
+
+```json
+{
+  "timeout": 30000,
+  "retries": 3,
+  "cache": {
+    "enabled": true,
+    "ttlSeconds": 60
+  }
+}
+```
+
+### development.json
+
+```json
+{
+  "apiKey": "${VERCEL_API_KEY}",
+  "baseUrl": "https://api-sandbox.vercel.com",
+  "debug": true,
+  "cache": {
+    "enabled": false
+  }
+}
+```
+
+### staging.json
+
+```json
+{
+  "apiKey": "${VERCEL_API_KEY_STAGING}",
+  "baseUrl": "https://api-staging.vercel.com",
+  "debug": false
+}
+```
+
+### production.json
+
+```json
+{
+  "apiKey": "${VERCEL_API_KEY_PROD}",
+  "baseUrl": "https://api.vercel.com",
+  "debug": false,
+  "retries": 5
+}
+```

package/skills/vercel-multi-env-setup/references/errors.md

@@ -0,0 +1,11 @@
+# Error Handling Reference
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Wrong environment | Missing NODE_ENV | Set environment variable |
+| Secret not found | Wrong secret path | Verify secret manager config |
+| Config merge fails | Invalid JSON | Validate config files |
+| Production guard triggered | Wrong environment | Check NODE_ENV value |
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/vercel-multi-env-setup/references/examples.md

@@ -0,0 +1,11 @@
+## Examples
+
+### Quick Environment Check
+
+```typescript
+const env = getVercelConfig();
+console.log(`Running in ${env.environment} with ${env.baseUrl}`);
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*