feat(site): add templates

[NathanFlurry]

No description provided.

[vercel]

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

Project	Deployment	Preview	Comments	Updated (UTC)
rivet-inspector	Ready	Preview	Comment	Dec 6, 2025 8:43am
rivet-site	Ready	Preview	Comment	Dec 6, 2025 8:43am
rivetkit-serverless	Error			Dec 6, 2025 8:43am

1 Skipped Deployment

Project	Deployment	Preview	Comments	Updated (UTC)
rivet-cloud	Ignored			Dec 6, 2025 8:43am

[NathanFlurry]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat(site): auto-generate templates from examples dir #3603
• feat(site): add templates #3567 👈 (View in Graphite)
• feat(examples): add user-generated-actors example #3560
• feat(frontend): create api key #3556
• fix(frontend): do not show tokens button if not on namespace page #3558
• fix(frontend): update env vars for dev #3557
• docs: clean up last few missing pieces of content #3538
• main

---

How to use the Graphite Merge Queue

Add the label merge-queue to this PR to add it to the merge queue.

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]

Pull Request Review: Add Templates Feature

Overview

This PR adds a templates/examples registry feature to the website, creating a centralized system for managing and displaying RivetKit examples. The implementation includes:

• A new @rivet-gg/example-registry package that generates template metadata from example directories
• New website pages for browsing and viewing templates
• Template metadata added to all example package.json files

Code Quality & Architecture ✅

Strengths

1. Clean separation of concerns: The example registry is properly separated as its own package
2. Auto-generation approach: Using a build script to generate _gen.ts from source data is a solid pattern
3. Type-safe implementation: Good use of TypeScript interfaces and type exports
4. DRY principle: Centralizing template metadata in package.json files eliminates duplication

Areas for Improvement

1. Error Handling - Build Script ⚠️

Location: frontend/packages/example-registry/scripts/build.ts:91-93

The build script catches errors but continues silently. The script requires template metadata (line 47-50 throws if missing) but catches and ignores the error. This could lead to incomplete data generation without clear feedback.

Recommendation:

• Track failed examples and report them at the end
• Consider failing the build if required examples are missing metadata

2. Inconsistent Technology Handling 🤔

Location: frontend/packages/example-registry/scripts/build.ts:79-82

The build script adds "rivet" if not present, but remove-rivet-tech.ts removes it. Should "rivet" be automatically added or not? This seems circular.

Recommendation:

• If "rivet" should always be implied, remove it from all package.json files and only add it in the build script
• If it's metadata, keep it in package.json and remove the auto-add logic
• Document the decision

3. Missing Package.json Fields ℹ️

Location: frontend/packages/example-registry/package.json

The package has "exports" pointing to source files rather than built files. The main and module fields point to dist/ but exports points to src/.

Recommendation: Update exports to match build output or add a build step (currently missing in package.json scripts).

Potential Bugs 🐛

1. Race Condition in Parallel Updates

Location: website/src/app/(v2)/(marketing)/templates/components/TemplatesSidebar.tsx:76-79

The clear all button calls state setters in a loop, which could lead to stale state. Add a onClearAll callback from parent component instead.

2. Potential Undefined Behavior

Location: frontend/packages/example-registry/scripts/build.ts:64-65

No validation that the title isn't empty after trimming. Edge case: a README with just # would set displayName to empty string.

Performance Considerations ⚡

Efficient Implementation ✅

The fuzzy search implementation is well optimized:

• Fuse instance is correctly memoized ✅
• Search only runs when query is non-empty ✅
• Filtering logic is properly memoized ✅

Security Concerns 🔒

No Issues Found ✅

• No user-generated content rendered without sanitization
• Package.json parsing is from trusted sources
• Markdown rendering uses proper component

Test Coverage 📊

Missing Tests ⚠️

No test files were added for:

• @rivet-gg/example-registry package
• Build script validation
• Template page components
• Filtering/search logic

Recommendations:

1. Add tests for build script (valid/invalid package.json, missing README, etc.)
2. Add tests for React components (filtering, search, tag selection)
3. Add integration test to verify all examples have required metadata

Code Style & Best Practices 📝

Follows Repository Standards ✅

• Uses TypeScript correctly
• Proper use of async/await
• Clean component structure

Suggestions:

1. Add JSDoc Comments for the public API
2. Consider Adding Validation - The build script could validate that technology/tag names match the constants to catch typos early

Additional Observations

Migration Scripts ℹ️

The PR includes migration scripts (migrate-templates.ts, remove-rivet-tech.ts) that appear to be one-time utilities. Consider moving them to a scripts/migrations/ directory or removing them if no longer needed.

Deleted File ✅

website/scripts/generateExamples.mjs was removed - good, it's replaced by the new registry system.

Summary

Overall Assessment: Strong Implementation ✅

This PR introduces a well-architected template system with clean separation of concerns.

Must Fix Before Merge:

• None (all issues are minor)

Should Fix:

1. Clarify and document the "rivet" technology handling strategy
2. Improve error handling in build script to fail loudly on missing metadata
3. Fix package.json exports field

Nice to Have:

1. Add test coverage
2. Add JSDoc documentation
3. Add validation for technology/tag names
4. Clean up migration scripts

Recommendations:

• Consider adding a validate script that checks all examples have required metadata
• Add the registry build to CI to catch metadata issues early
• Document the template metadata schema in a README within the example-registry package

Great work on this feature! The foundation is solid and extensible. 🎉

[pkg-pr-new]

More templates

• example-ai-agent
• example-ai-and-user-generated-actors-freestyle
• chat-room
• example-cloudflare-workers
• example-cloudflare-workers-hono
• example-cloudflare-workers-inline-client
• example-counter
• example-counter-next-js
• example-counter-serverless
• example-cursors
• example-cursors-raw-websocket
• example-deno
• example-sqlite
• example-elysia
• example-express
• example-hono
• example-hono-bun
• example-hono-react
• example-kitchen-sink
• example-next-js
• quickstart-actions
• quickstart-cross-actor-actions
• quickstart-multi-region
• quickstart-raw-websockets
• quickstart-realtime
• quickstart-scheduling
• quickstart-state
• example-raw-fetch-handler
• example-raw-websocket-handler
• example-raw-websocket-handler-proxy
• example-react
• starter
• example-stream
• example-trpc

@rivetkit/cloudflare-workers

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/cloudflare-workers@3567

@rivetkit/db

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/db@3567

@rivetkit/framework-base

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/framework-base@3567

@rivetkit/next-js

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/next-js@3567

@rivetkit/react

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/react@3567

rivetkit

pnpm add https://pkg.pr.new/rivet-dev/rivet/rivetkit@3567

@rivetkit/sql-loader

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/sql-loader@3567

@rivetkit/engine-runner

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner@3567

@rivetkit/engine-runner-protocol

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/engine-runner-protocol@3567

commit: 3082543