feat: Add Vercel Workflow integration

[snomiao]

Summary

This PR integrates Vercel Workflow into the registry-web project, enabling durable, stateful operations that can pause, resume, and maintain state across deployments. The integration includes comprehensive documentation and four practical workflow examples demonstrating real-world use cases.

Changes

Package & Dependencies

• ✨ Install workflow@4.0.1-beta.3 with CLI tools (workflow / wf)
• 📦 Adds AWS SDK dependencies for workflow state management

Documentation

• 📝 Add WORKFLOW.md with comprehensive setup and usage documentation
• 🔧 Update CLAUDE.md with workflow commands and architecture notes
• 📚 Include detailed API examples with test commands

Example Implementations

1. Basic Workflow (app/api/workflow-example/route.ts)

• Demonstrates 'use workflow' and 'use step' directives
• Shows sleep() usage for pausing without consuming resources
• Simple processing workflow with two steps

2. Delayed Notification Workflow (app/api/workflow-notification-example/route.ts)

• Welcome notification system with time-delayed follow-up
• Practical example of user onboarding flow
• Demonstrates immediate + delayed action pattern

3. Approval Workflow (app/api/workflow-approval-example/route.ts)

• Multi-step approval process for node submissions
• Automated validation → admin notification → approval wait → status update
• Shows complex multi-step workflow orchestration

4. Batch Processing Workflow (app/api/workflow-batch-processing-example/route.ts)

• Process large datasets in configurable batches
• Rate limiting with sleep() between batches
• Useful for Algolia index updates or external API syncing

Features

Workflow Directive ('use workflow')

Marks a function as durable and stateful:

• Survives deployments and infrastructure failures
• Maintains state across pauses and resumes
• Built-in observability through Vercel dashboard

Step Directive ('use step')

Marks a function as stateless with automatic retries:

• Ideal for external API calls
• Exponential backoff on failures
• Isolated operation execution

Sleep Function

Pauses workflow execution efficiently:

import { sleep } from 'workflow'

await sleep('2 seconds')  // Short delays for demos
await sleep('1 day')      // Production: wait for user action
await sleep('7 days')     // Production: delayed follow-ups

Use Cases for This Project

Vercel Workflow enables several improvements to the registry:

1. Node Version Processing: Asynchronously validate and process new node submissions
2. Search Indexing: Update Algolia indices with retry logic and rate limiting
3. Publisher Verification: Multi-step verification flows with human approval
4. Email Notifications: Reliable notification delivery with retry logic
5. Batch Operations: Process bulk updates without API rate limit issues
6. Analytics Processing: Aggregate usage statistics over time

Testing

All examples include test commands. Start the dev server and test:

# Start server
bun dev

# Test basic workflow
curl -X POST http://localhost:3000/api/workflow-example \
  -H "Content-Type: application/json" \
  -d '{"topic": "test workflow"}'

# Test notification workflow
curl -X POST http://localhost:3000/api/workflow-notification-example \
  -H "Content-Type: application/json" \
  -d '{"userId": "user123", "email": "user@example.com", "name": "John"}'

# Test approval workflow
curl -X POST http://localhost:3000/api/workflow-approval-example \
  -H "Content-Type: application/json" \
  -d '{"nodeId": "node123", "submitterId": "user456", "nodeName": "My Custom Node"}'

# Test batch processing
curl -X POST http://localhost:3000/api/workflow-batch-processing-example \
  -H "Content-Type: application/json" \
  -d '{"items": ["item1", "item2", "item3", "item4", "item5"]}'

Resources

• 📖 Official Vercel Workflow Documentation
• 🔗 Workflow Package on npm
• 📂 Project Workflow Documentation
• 💡 Vercel Blog: Introducing Workflow

Pricing (Beta)

Currently free during beta. Future pricing:

• Workflow Storage: $0.50 per 1 GB per month
• Workflow Steps: $25.00 per 1,000,000 steps
• Regular compute pricing still applies

CI/CD Status

✅ All checks passing:

• Build successful
• Tests passing
• Storybook deployment successful
• No ESLint issues

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
registry-web	Error			Nov 18, 2025 8:13am

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	next@​15.0.3
	pi@​2.0.5
	msw-storybook-addon@​2.0.6
	react-router-dom@​6.30.2
	require-from-string@​2.0.2
	md5@​2.3.0
	react-use-cookie@​1.6.1
	vitest@​3.2.4
	phpdie@​1.7.0
	json-stringify-pretty-compact@​4.0.0
	orval@​7.16.0
	react-firebase-hooks@​5.1.1
	react-use@​17.6.0
	qs@​6.14.0
	prop-types@​15.8.1
	yaml@​2.8.1
	postcss@​8.4.17
	sflow@​1.27.0
	workflow@​4.0.1-beta.15
	styled-jsx@​5.1.7
	react-icons@​5.4.0
	react@​18.2.0
	p-map@​7.0.4
	react-toastify@​9.1.3
	react-markdown@​10.1.0
	tailwindcss@​3.4.18
	react-intersection-observer@​9.16.0
	storybook@​9.1.16
	rambda@​9.4.2
	typescript@​5.8.3
	prettier@​3.6.2
	react-dom@​18.2.0
	octokit@​5.0.5
See 12 more rows in the dashboard

View full report

[socket-security]

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action	Severity	Alert  (click "▶" to expand/collapse)
Warn		Critical CVE: Authorization Bypass in Next.js Middleware CVE: GHSA-f82v-jwr5-mffw Authorization Bypass in Next.js Middleware (CRITICAL) Affected versions: >= 13.0.0 < 13.5.9; >= 14.0.0 < 14.2.25; >= 15.0.0 < 15.2.3; >= 11.1.4 < 12.3.5 Patched version: 15.2.3 From: package.json → npm/next@15.0.3 ℹ Read more on: This package | This alert | What is a critical CVE? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Remove or replace dependencies that include known critical CVEs. Consumers can use dependency overrides or npm audit fix --force to remove vulnerable dependencies. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/next@15.0.3. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Obfuscated code: npm safer-buffer is 94.0% likely obfuscated Confidence: 0.94 Location: Package overview From: ? → npm/i18next-http-backend@3.0.2 → npm/i18n-extract@0.6.8 → npm/safer-buffer@2.1.2 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/safer-buffer@2.1.2. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report