@intentsolutionsio/vercel-pack 1.0.0 → 1.0.3

package/skills/vercel-upgrade-migration/SKILL.md

@@ -1,112 +1,212 @@
 ---
 name: vercel-upgrade-migration
-description: |
-  Analyze, plan, and execute Vercel SDK upgrades with breaking change detection.
-  Use when upgrading Vercel SDK versions, detecting deprecations,
-  or migrating to new API versions.
+description: 'Upgrade Vercel CLI, Node.js runtime, and Next.js framework versions
+  with breaking change detection.
+
+  Use when upgrading Vercel CLI versions, migrating Node.js runtimes,
+
+  or updating Next.js between major versions on Vercel.
+
   Trigger with phrases like "upgrade vercel", "vercel migration",
-  "vercel breaking changes", "update vercel SDK", "analyze vercel version".
-allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(git:*)
+
+  "vercel breaking changes", "update vercel CLI", "next.js upgrade on vercel".
+
+  '
+allowed-tools: Read, Write, Edit, Bash(vercel:*), Bash(npm:*), Bash(npx:*), Bash(git:*)
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- vercel
+- migration
+- upgrade
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
-
-# Vercel Upgrade & Migration
+# Vercel Upgrade Migration
 
 ## Overview
-Guide for upgrading Vercel SDK versions and handling breaking changes.
+
+Safely upgrade Vercel CLI, Node.js runtime versions, and framework versions (especially Next.js) on Vercel. Covers breaking change detection, vercel.json schema changes, and rollback strategy.
+
+## Current State
+
+!`vercel --version 2>/dev/null || echo 'Vercel CLI not installed'`
+!`node --version 2>/dev/null || echo 'N/A'`
+!`cat package.json 2>/dev/null | jq -r '.dependencies.next // "no next.js"' 2>/dev/null || echo 'N/A'`
 
 ## Prerequisites
-- Current Vercel SDK installed
+
+- Current Vercel CLI installed
 - Git for version control
 - Test suite available
-- Staging environment
+- Preview deployment for testing
 
 ## Instructions
 
-### Step 1: Check Current Version
+### Step 1: Check Current Versions
+
 ```bash
-npm list vercel
-npm view vercel version
+# Current CLI version
+vercel --version
+
+# Current Node.js runtime on Vercel
+cat package.json | jq '.engines.node'
+# Or check vercel.json
+cat vercel.json | jq '.functions'
+
+# Check for available CLI updates
+npm outdated -g vercel
+
+# Check framework version
+npm ls next react
 ```
 
-### Step 2: Review Changelog
+### Step 2: Upgrade Vercel CLI
+
 ```bash
-open https://github.com/vercel/vercel/releases
+# Upgrade to latest
+npm install -g vercel@latest
+
+# Or specific version
+npm install -g vercel@39
+
+# Verify
+vercel --version
+```
+
+**CLI breaking changes to watch for:**
+
+- v28+: `vercel env pull` output format changed
+- v32+: `vercel dev` uses new function runtime
+- v37+: `vercel.json` `builds` property deprecated in favor of framework detection
+
+### Step 3: Upgrade Node.js Runtime
+
+```json
+// package.json — specify the Node.js version
+{
+  "engines": {
+    "node": "20.x"
+  }
+}
 ```
 
-### Step 3: Create Upgrade Branch
+Available runtimes on Vercel:
+
+| Runtime | Status | EOL |
+|---------|--------|-----|
+| Node.js 18.x | Supported | April 2025 |
+| Node.js 20.x | Active LTS (recommended) | April 2026 |
+| Node.js 22.x | Current | October 2027 |
+
 ```bash
-git checkout -b upgrade/vercel-sdk-vX.Y.Z
-npm install vercel@latest
+# Test locally with the target Node version first
+nvm use 20
 npm test
+npm run build
 ```
 
-### Step 4: Handle Breaking Changes
-Update import statements, configuration, and method signatures as needed.
+### Step 4: Upgrade Next.js on Vercel
 
-## Output
-- Updated SDK version
-- Fixed breaking changes
-- Passing test suite
-- Documented rollback procedure
+```bash
+# Use the Next.js upgrade codemod
+npx @next/codemod@latest upgrade
 
-## Error Handling
-| SDK Version | API Version | Node.js | Breaking Changes |
-|-------------|-------------|---------|------------------|
-| 3.x | 2024-01 | 18+ | Major refactor |
-| 2.x | 2023-06 | 16+ | Auth changes |
-| 1.x | 2022-01 | 14+ | Initial release |
+# Or manual upgrade
+npm install next@latest react@latest react-dom@latest
 
-## Examples
+# Check for breaking changes
+npx @next/codemod --dry-run
+```
 
-### Import Changes
-```typescript
-// Before (v1.x)
-import { Client } from 'vercel';
+**Key Next.js migration points:**
 
-// After (v2.x)
-import { VercelClient } from 'vercel';
-```
+- **13 → 14**: App Router stable, Turbopack available, Server Actions stable
+- **14 → 15**: `fetch` no longer cached by default, `cookies()` is async, `NextRequest.geo` removed (use `geolocation()` from `@vercel/functions`)
+- **vercel.json changes**: `rewrites`/`redirects` in `next.config.js` take precedence over `vercel.json`
+
+### Step 5: Test in Preview Before Production
 
-### Configuration Changes
-```typescript
-// Before (v1.x)
-const client = new Client({ key: 'xxx' });
+```bash
+# Create a branch for the upgrade
+git checkout -b upgrade/vercel-cli-39
 
-// After (v2.x)
-const client = new VercelClient({
-  apiKey: 'xxx',
-});
+# Make changes and push
+git add -A && git commit -m "chore: upgrade vercel CLI and Node.js 20"
+git push -u origin upgrade/vercel-cli-39
+
+# Vercel auto-deploys a preview — test it
+vercel ls | head -3
+curl -s https://my-app-git-upgrade-vercel-cli-39-team.vercel.app/api/health
+
+# Run full test suite against preview
+npm test -- --env=preview
 ```
 
-### Rollback Procedure
+### Step 6: Rollback Strategy
+
 ```bash
-npm install vercel@1.x.x --save-exact
+# If the upgrade breaks production — instant rollback
+vercel rollback
+
+# Pin to a specific CLI version in CI
+# .github/workflows/deploy.yml
+# - run: npm install -g vercel@38  # pin to known good version
+
+# Revert Node.js runtime
+# Change engines.node back in package.json
+# Push and redeploy
 ```
 
-### Deprecation Handling
-```typescript
-// Monitor for deprecation warnings in development
-if (process.env.NODE_ENV === 'development') {
-  process.on('warning', (warning) => {
-    if (warning.name === 'DeprecationWarning') {
-      console.warn('[Vercel]', warning.message);
-      // Log to tracking system for proactive updates
-    }
-  });
+## vercel.json Schema Migration
+
+Deprecated `builds` property (v2 → current):
+
+```json
+// Old (deprecated):
+{
+  "builds": [
+    { "src": "api/**/*.ts", "use": "@vercel/node" }
+  ]
 }
 
-// Common deprecation patterns to watch for:
-// - Renamed methods: client.oldMethod() -> client.newMethod()
-// - Changed parameters: { key: 'x' } -> { apiKey: 'x' }
-// - Removed features: Check release notes before upgrading
+// New (framework auto-detection):
+{
+  "functions": {
+    "api/**/*.ts": {
+      "runtime": "nodejs20.x",
+      "maxDuration": 30
+    }
+  }
+}
 ```
 
+## Output
+
+- Vercel CLI upgraded to latest version
+- Node.js runtime version updated in package.json
+- Framework upgraded with codemods applied
+- Preview deployment tested before production promotion
+- Rollback strategy documented
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Build failed` after Node upgrade | Dependency incompatible with new Node | Check `npm ls` for native modules, rebuild |
+| `Module not found` after Next.js upgrade | Import paths changed | Run `npx @next/codemod` for automatic fixes |
+| `vercel.json` validation error | Schema changed in new CLI version | Remove deprecated `builds`, use `functions` |
+| `FUNCTION_INVOCATION_FAILED` | Runtime API removed in new Node.js | Check Node.js changelog for removed APIs |
+| Preview works but prod fails | Env vars differ between environments | Verify production env vars match preview |
+
 ## Resources
-- [Vercel Changelog](https://github.com/vercel/vercel/releases)
-- [Vercel Migration Guide](https://vercel.com/docs/migration)
+
+- [Vercel CLI Changelog](https://github.com/vercel/vercel/releases)
+- [Node.js Runtime on Vercel](https://vercel.com/docs/functions/runtimes/node-js)
+- [Next.js Upgrade Guide](https://nextjs.org/docs/app/building-your-application/upgrading)
+- [vercel.json Reference](https://vercel.com/docs/project-configuration)
 
 ## Next Steps
-For CI integration during upgrades, see `vercel-ci-integration`.
+
+For CI/CD integration, see `vercel-ci-integration`.

package/skills/vercel-upgrade-migration/references/errors.md

@@ -0,0 +1,10 @@
+# Error Handling Reference
+
+| SDK Version | API Version | Node.js | Breaking Changes |
+|-------------|-------------|---------|------------------|
+| 3.x | 2024-01 | 18+ | Major refactor |
+| 2.x | 2023-06 | 16+ | Auth changes |
+| 1.x | 2022-01 | 14+ | Initial release |
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/vercel-upgrade-migration/references/examples.md

@@ -0,0 +1,51 @@
+## Examples
+
+### Import Changes
+
+```typescript
+// Before (v1.x)
+import { Client } from 'vercel';
+
+// After (v2.x)
+import { VercelClient } from 'vercel';
+```
+
+### Configuration Changes
+
+```typescript
+// Before (v1.x)
+const client = new Client({ key: 'xxx' });
+
+// After (v2.x)
+const client = new VercelClient({
+  apiKey: 'xxx',
+});
+```
+
+### Rollback Procedure
+
+```bash
+npm install vercel@1.x.x --save-exact
+```
+
+### Deprecation Handling
+
+```typescript
+// Monitor for deprecation warnings in development
+if (process.env.NODE_ENV === 'development') {
+  process.on('warning', (warning) => {
+    if (warning.name === 'DeprecationWarning') {
+      console.warn('[Vercel]', warning.message);
+      // Log to tracking system for proactive updates
+    }
+  });
+}
+
+// Common deprecation patterns to watch for:
+// - Renamed methods: client.oldMethod() -> client.newMethod()
+// - Changed parameters: { key: 'x' } -> { apiKey: 'x' }
+// - Removed features: Check release notes before upgrading
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/vercel-upgrade-migration/references/implementation.md

@@ -0,0 +1,29 @@
+## Implementation Guide
+
+### Step 1: Check Current Version
+
+```bash
+npm list vercel
+npm view vercel version
+```
+
+### Step 2: Review Changelog
+
+```bash
+open https://github.com/vercel/vercel/releases
+```
+
+### Step 3: Create Upgrade Branch
+
+```bash
+git checkout -b upgrade/vercel-sdk-vX.Y.Z
+npm install vercel@latest
+npm test
+```
+
+### Step 4: Handle Breaking Changes
+
+Update import statements, configuration, and method signatures as needed.
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*