chore(examples): add bots, background-jobs, and workflows examples

[NathanFlurry]

No description provided.

[vercel]

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

Project	Deployment	Preview	Comments	Updated (UTC)
rivetkit-serverless	Ready	Preview	Comment	Oct 15, 2025 11:09am

[NathanFlurry]

• chore(examples): add bots, background-jobs, and workflows examples #1395 👈 (View in Graphite)
• main

---

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

• merge queue - adds this PR to the back of the merge queue
• hotfix - for urgent hot fixes, skip the queue and merge this PR next

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

Claude finished @NathanFlurry's task —— View job

---

Code Review for PR #1395: Add bots, background-jobs, and workflows examples

Todo List

• Read and understand the repository guidelines from CLAUDE.md
• Review new bots example project
• Review new background-jobs example project
• Review new workflows example project
• Review refactoring changes to existing examples
• Check package.json compliance across all examples
• Check README.md compliance across all examples
• Analyze code quality and TypeScript usage
• Check for potential bugs and security issues
• Assess test coverage
• Provide comprehensive feedback

Summary

This PR adds three well-structured examples that demonstrate important RivetKit use cases: bot management, background job scheduling, and workflow state machines. The code quality is generally good and follows the project's established patterns.

Code Quality & Best Practices ✅

Positive aspects:

• All examples follow the established RivetKit patterns correctly
• TypeScript usage is proper with well-defined interfaces in separate types.ts files
• Clean separation of concerns between registry, server, and utility functions
• Consistent error handling using UserError from RivetKit
• Good use of structured logging (where applicable)
• Proper use of assertUnreachable for exhaustive type checking in examples/workflows/src/registry.ts:34

Refactoring improvements:

• Extracting common types to separate types.ts files in existing examples improves maintainability
• Consistent project structure across all examples

Potential Issues & Concerns

1. Documentation Mismatch in Bots Example ⚠️

• File: examples/bots/README.md:1
• Issue: README title says "Discord Bot Gateway" but the code implements a Slack bot
• Impact: Confusing for developers trying to understand the example

2. Missing Error Handling in External API Calls ⚠️

• File: examples/bots/src/utils.ts:10-20
• Issue: Slack API call doesn't handle network errors or API failures
• File: examples/background-jobs/src/registry.ts:29-34
• Issue: Resend API call doesn't log failures or handle rate limiting

3. Missing Test Coverage ❌

• Issue: None of the three new examples have test files
• Impact: Examples should demonstrate testing patterns for RivetKit applications
• Expected: Each example should have tests in tests/ directory

4. Security Considerations 🔒

• File: examples/bots/src/server.ts:32
• Issue: Webhook endpoint returns 400 for unrecognized events without validating request source
• Recommendation: Add Slack signature verification for production use

5. Environment Variable Validation ⚠️

• File: examples/background-jobs/src/registry.ts:27
• Issue: Missing environment variable validation could cause runtime failures
• File: examples/bots/src/utils.ts:5-8
• Issue: Silently fails when SLACK_BOT_TOKEN is missing

Performance Considerations ✅

• Scheduling patterns are efficient and appropriate
• State management follows RivetKit best practices
• No obvious performance bottlenecks identified

Package Configuration Compliance

✅ Compliant with CLAUDE.md guidelines:

• All examples named example-{name} format
• All use workspace:* for rivetkit dependency
• Include required dev and check-types scripts
• Proper turbo.json configuration
• Use tsx for development as specified

✅ README format compliance:

• All follow the required structure from CLAUDE.md
• Include proper getting started instructions
• Have required license sections

❌ Missing from package.json:

• Issue: examples/workflows/package.json missing dependency declarations
• File: examples/workflows/package.json:17-18
• Impact: Missing @hono/node-server and hono dependencies that other examples include

Recommendations

1. Fix documentation mismatch in bots example README
2. Add proper error handling for external API calls with logging
3. Add test coverage for all new examples following existing patterns
4. Add environment variable validation with clear error messages
5. Consider adding webhook signature verification for production-ready bot example
6. Fix missing dependencies in workflows example

Overall Assessment

This is a solid contribution that adds valuable examples demonstrating key RivetKit capabilities. The code follows established patterns well, but would benefit from improved error handling, test coverage, and fixing the documentation issues mentioned above.

Recommendation: Approve with suggested improvements for robustness and completeness.

---