feat(site): auto-generate templates from examples dir

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

1 Skipped Deployment

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

[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 👈 (View in Graphite)
• feat(site): add templates #3567
• 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.

[pkg-pr-new]

More templates

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

@rivetkit/cloudflare-workers

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

@rivetkit/db

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

@rivetkit/framework-base

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

@rivetkit/next-js

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

@rivetkit/react

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

rivetkit

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

@rivetkit/sql-loader

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

@rivetkit/engine-runner

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

@rivetkit/engine-runner-protocol

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

commit: d1effc2

[claude]

Pull Request Review: Auto-generate Templates from Examples Directory

This PR standardizes the README format across all examples in the repository and makes configuration changes to support auto-generation of templates from the examples directory. Overall, this is a positive change that improves documentation consistency.

---

Summary of Changes

Core Changes

1. New Template Guidelines (.claude/resources/EXAMPLE_TEMPLATE.md): Establishes standardized README structure
2. Example Reorganization: Renames/removes several examples (e.g., quickstart-actions → actor-actions, removes counter examples)
3. README Standardization: Updates 30+ example READMEs to follow the new template
4. Configuration Updates: Adds metadata to package.json files (priority, frontendPort, license)
5. Docker Config: Updates .dockerignore to include pre-built dist directories
6. Vite Config: Adds host: "0.0.0.0" to all vite.config.ts files

---

Positive Aspects

1. Documentation Consistency ✅

• Excellent standardization across all examples
• Clear, consistent section structure makes examples easy to navigate
• GitHub source code links are helpful for users

2. Template Quality ✅

• Well-thought-out template structure
• Good focus on RivetKit concepts rather than just features
• Appropriate separation of "Prerequisites" vs "Getting Started"

3. Metadata Additions ✅

• Adding priority, frontendPort, and license to package.json supports automation
• Consistent MIT licensing across examples

---

Issues and Concerns

1. Critical: Missing Implementation Details ⚠️

Many READMEs lack sufficient implementation details. According to the template guidelines:

Implementation: Always required. Explain the technical details and include GitHub source code links to key files.

Examples of insufficient detail:

actor-actions/README.md (line 23-26):

## Implementation

This example demonstrates the fundamentals of defining and calling actor actions:

- **Actor Definition** ([...](...)): Shows how to define actions with parameters, return values, and state management

Recommendation: Add 1-2 paragraphs explaining how it works, not just what files exist. For example:

This example demonstrates the fundamentals of defining and calling actor actions. Actions are defined within the actor definition using the `actions` property, where each action is a function that receives the actor context and any parameters. The actor context provides access to state management and the ability to broadcast events.

The `src/backend/registry.ts` file shows how to define actions with parameters, return values, and state management using the `actor()` function from RivetKit.

Same issue in: chat-room/README.md, chat-room-next-js/README.md, custom-serverless/README.md, and others.

2. Naming Inconsistency 📝

The PR renames quickstart-actions to actor-actions but keeps other examples with different naming patterns:

• chat-room (kebab-case)
• ai-agent (kebab-case)
• chat-room-next-js (kebab-case with framework)
• hono-bun (framework-runtime)

Recommendation: Consider establishing a naming convention guideline:

• Feature-based: feature-name (e.g., actor-actions, chat-room)
• Platform-specific: feature-name-platform (e.g., chat-room-next-js)
• Framework examples: framework-name (e.g., hono, express)

3. Vite Configuration Pattern 🔧

All vite.config.ts files now include host: "0.0.0.0" (line 8 in actor-actions/vite.config.ts):

server: {
    host: "0.0.0.0",
    port: 5173,
}

Question: Is this intended for Docker/container support? If so, consider:

• Adding a comment explaining why (e.g., // Bind to all interfaces for Docker compatibility)
• Or documenting this in the template/contributing guide

Security Note: While 0.0.0.0 is safe for development, ensure examples don't encourage this in production.

4. Docker Configuration 🐳

The .dockerignore additions (lines 50-52):

# RivetKit packages (need pre-built dist for screenshot generation)
!rivetkit-typescript/packages/*/dist/
!engine/sdks/typescript/*/dist/

Concerns:

• The comment mentions "screenshot generation" - this isn't explained elsewhere in the PR
• Negating ignore patterns (!) can be fragile and hard to maintain
• Consider documenting the screenshot generation workflow

5. Example Removal Justification ❓

Several examples were completely removed:

• counter (standalone)
• counter-next-js
• counter-serverless

Question: Were these consolidated into other examples? If so, migration notes would be helpful for existing users.

6. Template Guideline - Implementation Section 📋

The template states (line 30):

## Implementation - Technical details (NOT "How it Works")

But many existing projects use "How It Works" - why the strong preference against it? "How It Works" is more approachable for beginners. Consider allowing both or explaining the reasoning.

7. Missing Test Updates 🧪

With all these renames (e.g., quickstart-actions → actor-actions), are there any:

• CI/CD pipelines that reference old paths?
• Documentation elsewhere that needs updating?
• Test suites that build all examples?

---

Minor Issues

1. CLAUDE.md Update (line 71)

## Examples

All example READMEs in `/examples/` should follow the format defined in `.claude/resources/EXAMPLE_TEMPLATE.md`.

Good addition, but consider adding a note about why this is important (e.g., "to support auto-generation of templates and maintain consistency").

2. Extra Blank Line (CLAUDE.md line 191)

There's a trailing blank line added - minor style issue.

3. Package.json Inconsistency

Some examples have "stableVersion" removed (e.g., chat-room-next-js/package.json) - is this intentional cleanup or oversight?

---

Testing Recommendations

1. Verify all examples build and run with the new configurations
2. Test the screenshot generation mentioned in .dockerignore
3. Check all GitHub source links are valid and point to correct files
4. Verify the template auto-generation works as intended
5. Test examples in Docker to ensure 0.0.0.0 binding works correctly

---

Final Recommendations

Must Address Before Merge:

1. ✅ Enhance Implementation sections - Add actual technical explanations, not just file listings
2. ✅ Document screenshot generation - Explain the .dockerignore changes
3. ✅ Verify example removal - Confirm counter examples are intentionally removed

Should Consider:

1. 📝 Add naming convention guidelines for new examples
2. 💬 Document the vite.config.ts host binding rationale
3. 🔗 Add migration notes for removed examples

Nice to Have:

1. Clarify why "Implementation" is preferred over "How It Works"
2. Add contributing guide referencing the template
3. Consider adding a linter/validator for README format compliance

---

Overall Assessment

This PR makes positive strides toward documentation consistency and sets up good infrastructure for template auto-generation. The main concern is that many READMEs still lack sufficient implementation detail despite the template requiring it.

Recommendation: Address the implementation detail issue before merging, as this is a core requirement of the template. The rest are minor improvements that can be addressed now or in follow-up PRs.

Rating: 7/10 - Good direction, needs more technical depth in documentation.

---

Review completed on 2025-12-09

[graphite-app]

Merge activity

• Dec 9, 9:44 AM UTC: NathanFlurry added this pull request to the Graphite merge queue.
• Dec 9, 9:44 AM UTC: CI is running for this pull request on a draft pull request (#3608) due to your merge queue CI optimization settings.
• Dec 9, 9:45 AM UTC: Merged by the Graphite merge queue via draft PR: #3608.