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 8, 2025 8:16am
rivet-site	Ready	Preview	Comment	Dec 8, 2025 8:16am
rivetkit-serverless	Error			Dec 8, 2025 8:16am

1 Skipped Deployment

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

[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]

PR Review: Add Templates Feature

Overview

This PR introduces a template/example registry system that consolidates example metadata and creates a browsable templates page on the website. The implementation moves from a manually-maintained examples list to a generated system that reads metadata from each example's package.json.

---

✅ Strengths

1. Well-structured architecture

• Clean separation of concerns with the example-registry package generating data consumed by the website
• Good use of TypeScript with proper type definitions
• Single source of truth for template metadata in each example's package.json

2. Good developer experience

• Migration scripts provided (migrate-templates.ts, remove-rivet-tech.ts) show thoughtfulness
• Build script properly integrated into website's prebuild step
• Error handling with helpful messages when template metadata is missing

3. Clean UI implementation

• Fuzzy search using Fuse.js for better discoverability
• Filter system by tags and technologies
• Responsive design with sidebar and grid layout

---

🔍 Issues & Recommendations

Critical Issues

1. Missing validation for technologies/tags constants

The example-registry package exports TECHNOLOGIES and TAGS constants, but the build script doesn't validate that template metadata only uses values from these constants. This could lead to:

• Typos in template metadata going undetected
• UI filters showing technologies/tags that don't match the constants
• Maintenance issues as the codebase grows

Recommendation: Add validation in build.ts to verify all technologies and tags used in templates are defined in the constants.

2. Inconsistent template metadata

Looking at the diff:

• ai-agent has technologies: ["typescript"] but clearly uses React (has react dependencies)
• Several React examples don't list "react" in their technologies array
• The build script adds "rivet" if missing (line 79-82), but package.json files don't include "rivet" in template metadata

Recommendation: Audit all examples and ensure technologies accurately reflect dependencies. Consider auto-detecting technologies from package.json dependencies.

Medium Priority Issues

3. Hardcoded path assumptions

At website/src/app/(v2)/(marketing)/templates/[slug]/page.tsx:39-45:

const readmePath = path.join(
  process.cwd(),
  "..",
  "examples",
  templateName,
  "README.md",
);

Using relative paths from process.cwd() is fragile and assumes a specific monorepo structure. This will break if the build context changes.

Recommendation: Use a consistent path resolution approach or make the examples path configurable.

4. Silent failures for missing READMEs

At build.ts:75-76, warnings for missing READMEs are swallowed. Templates without documentation aren't very useful.

Recommendation: Make README.md required, or make it configurable whether to fail the build on missing READMEs.

5. No graceful handling of build failures

TemplatesPageClient.tsx imports from @/data/templates/shared which re-exports from example-registry. If the build step fails or hasn't run, this causes import errors rather than helpful messages.

Minor Issues

6. Unused migration scripts

The scripts migrate-templates.ts and remove-rivet-tech.ts appear to be one-time migration scripts. Consider removing them or moving to a migrations/ archive folder.

7. Package.json build output mismatch

The example-registry/package.json specifies dist/ outputs (main, module, types), but the build script only generates src/_gen.ts. The exports point to src/index.ts which works for TypeScript but won't work for the specified main/module fields.

Recommendation: Either add a proper TypeScript build step or update package.json to remove dist references.

8. Brittle README parsing

The README parsing at build.ts:62-68 assumes a specific format. Consider using a markdown parser or documenting the expected format.

---

📊 Test Coverage

Missing tests for:

• Build script logic
• Template metadata validation
• README parsing
• UI component rendering
• Search/filter functionality

Recommendation: Add at least unit tests for the build script, especially error cases and validation.

---

🔒 Security Considerations

No major security issues, but consider:

1. Path traversal: The build script reads from examplesDir based on directory names. While low risk (internal build), ensure directory names are sanitized if this ever becomes dynamic.

2. XSS in templates: Template descriptions come from README files. Verify proper sanitization (React handles this, but check for dangerouslySetInnerHTML).

---

⚡ Performance Considerations

Generally good:

1. ✅ Template detail pages use generateStaticParams for static generation
2. ✅ README reads happen at build time
3. ⚠️ Fuse.js fuzzy search computed client-side - fine for ~35 templates, but consider optimization if count grows

---

📝 Code Quality & Style

Follows project conventions:

• ✅ TypeScript with proper types
• ✅ Clean component structure
• ⚠️ Inconsistent error handling (throw vs console.warn)
• ⚠️ Could use more JSDoc comments

---

🎯 Summary

Solid foundation, but needs refinement:

Must Fix:

1. Add validation for technologies/tags against constants
2. Audit and fix inconsistent template metadata
3. Fix hardcoded path assumptions
4. Resolve package.json build output mismatch

Should Fix:
5. Add error handling for missing READMEs
6. Remove or archive migration scripts
7. Add basic tests for build script

Nice to Have:
8. Auto-detect technologies from dependencies
9. More robust README parsing
10. UI component test coverage

---

📋 Checklist for Author

• Run build script and verify all examples generate correctly
• Manually verify template metadata matches dependencies for key examples
• Test templates page with various search queries and filters
• Verify individual template detail pages load correctly
• Add smoke tests for build process
• Remove one-time migration scripts

---

Overall: Good architectural approach, but needs validation improvements and consistency fixes. Code quality is solid, but metadata accuracy and error handling need attention.

Review by Claude Code

[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: 4c36897