doc: auto-generate docs for engine config and registry config #3902

NathanFlurry · 2026-01-14T22:24:23Z

No description provided.

NathanFlurry · 2026-01-14T22:24:48Z

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

fix(website): fix code group #3914
doc: auto-generate docs for engine config and registry config #3902 👈 (View in Graphite)
doc: document version upgrades #3901
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 · 2026-01-14T22:26:24Z

More templates

@rivetkit/cloudflare-workers

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

@rivetkit/db

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

@rivetkit/framework-base

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

@rivetkit/next-js

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

@rivetkit/react

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

rivetkit

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

@rivetkit/sql-loader

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

@rivetkit/virtual-websocket

pnpm add https://pkg.pr.new/rivet-dev/rivet/@rivetkit/virtual-websocket@3902

@rivetkit/engine-runner

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

@rivetkit/engine-runner-protocol

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

commit: 8c5aaf8

claude · 2026-01-14T22:27:47Z

Pull Request Review: Auto-generate docs for engine config and registry config

This PR introduces automated JSON schema generation for engine configuration and RivetKit configuration, significantly improving documentation maintainability. Overall, the implementation is well-structured and follows good practices.

✅ Strengths

Strong type safety: Uses Rust's schemars and TypeScript's Zod to generate schemas from actual type definitions
Build-time generation: Schemas are generated during the build process, ensuring they stay in sync with code
Good separation of concerns: Separates runtime schemas from documentation schemas (e.g., ActorConfigSchema vs DocActorConfigSchema)
Consistent patterns: Uses similar approaches for both Rust and TypeScript schema generation
Comprehensive documentation: New MDX files provide good coverage of configuration options

🔍 Code Quality Issues

Critical Issues

1. Error handling in config-schema-gen/build.rs (Lines 7-18, 24-25)
Multiple .unwrap() calls that could panic at build time:

let workspace_root = std::env::var("CARGO_MANIFEST_DIR")
    .map(|dir| {
        Path::new(&dir)
            .parent()
            .unwrap()  // Could panic
            .parent()
            .unwrap()  // Could panic
            .parent()
            .unwrap()  // Could panic
            .to_path_buf()
    })
    .unwrap();  // Could panic

Recommendation: Use proper error handling with expect() and descriptive messages:

let workspace_root = std::env::var("CARGO_MANIFEST_DIR")
    .expect("CARGO_MANIFEST_DIR must be set")
    .map(|dir| {
        Path::new(&dir)
            .parent()
            .expect("Failed to get parent of packages")
            .parent()
            .expect("Failed to get parent of engine")
            .parent()
            .expect("Failed to get workspace root")
            .to_path_buf()
    });

Medium Priority Issues

2. Typo in actor config description (rivetkit-typescript/packages/rivetkit/src/actor/config.ts:101)
Line 101 has .prefault(() => ({})) - should this be .default(() => ({}))? The method name "prefault" appears to be a typo.

3. Missing file in workspace members
The new package rivet-config-schema-gen is created but not added to the workspace members list in the root Cargo.toml. This might cause build issues or prevent the schema from being regenerated.

Recommendation: Add to Cargo.toml:

members = [
  # ... existing members ...
  "engine/packages/config-schema-gen",
]

4. Hardcoded path traversal (config-schema-gen/build.rs)
The build script uses hardcoded .parent().parent().parent() which is fragile and assumes a specific directory structure. If the package is moved, this will break.

Recommendation: Consider using a more robust approach, perhaps by setting an environment variable or using a workspace-level configuration.

Low Priority Issues

5. Inconsistent naming convention

Package renamed from rivet-dump-openapi to rivet-api-public-openapi-gen
New package named rivet-config-schema-gen
Consider consistency: either use -gen suffix for all generation packages or use a different pattern

6. Empty lib.rs file (config-schema-gen/src/lib.rs)
The file only contains a comment explaining it exists to trigger build.rs. Consider adding a more descriptive module-level doc comment:

//\! JSON schema generation for Rivet engine configuration.
//\!
//\! This crate generates a JSON Schema file at build time from the
//\! engine's configuration types defined in rivet-config.
//\! The generated schema is written to `engine/artifacts/config-schema.json`.

7. TypeScript any types (schema-utils.ts:9, actor/config.ts:193)

Line 9: export function toJsonSchema(schema: z.ZodType): any
Line 193: createVars: (c: CreateVarsContext<TState, TInput, TDatabase>, driverCtx: any) => ...

These could use more specific types or at least document why any is necessary.

🔒 Security Considerations

No security issues identified. The schema generation happens at build time and doesn't involve user input or runtime execution.

⚡ Performance Considerations

Build-time overhead: Schema generation adds build time, but this is acceptable since:

Schemas only regenerate when source files change (Turbo.build caching)
Trade-off for better documentation is worthwhile

Runtime impact: None - schemas are static files loaded at build/startup time.

🧪 Test Coverage

Missing test coverage for:

Schema generation scripts (both Rust and TypeScript)
Generated schemas validation
Documentation components rendering the schemas

Recommendation: Add tests to verify:

Generated schemas match expected structure
All required configuration fields are documented
Schema generation doesn't fail with missing dependencies

📝 Documentation Quality

Excellent improvements:

New environment variables documentation is comprehensive
Actor and registry configuration schemas are auto-generated
Good use of existing JsonSchemaPreview component

Minor suggestions:

Add a comment in generated JSON files indicating they are auto-generated and shouldn't be edited manually
Consider adding examples to the environment variables documentation
The RIVET_ENGINE variable is listed as "Alternative to RIVET_ENDPOINT" but could clarify when to use which

🎯 Summary

This is a well-designed PR that adds valuable auto-documentation infrastructure. The main concerns are:

Critical: Fix error handling in build.rs to prevent potential build failures
Important: Add config-schema-gen to workspace members
Minor: Fix the .prefault() typo
Enhancement: Improve type safety in TypeScript code

Once the critical and important issues are addressed, this PR will be ready to merge.

Estimated Risk: Low-Medium (mostly build configuration changes)
Recommendation: Request changes for items 1-3, then approve.

graphite-app · 2026-01-15T05:08:29Z

Merge activity

Jan 15, 5:08 AM UTC: NathanFlurry added this pull request to the Graphite merge queue.
Jan 15, 5:08 AM UTC: CI is running for this pull request on a draft pull request (#3915) due to your merge queue CI optimization settings.
Jan 15, 5:09 AM UTC: Merged by the Graphite merge queue via draft PR: #3915.

NathanFlurry mentioned this pull request Jan 14, 2026

doc: document version upgrades #3901

Closed

NathanFlurry force-pushed the 01-14-doc_auto-generate_docs_for_engine_config_and_registry_config branch from c8807c1 to 8c5aaf8 Compare January 15, 2026 03:22

NathanFlurry force-pushed the 01-14-doc_document_version_upgrades branch from 9800079 to 82ade5d Compare January 15, 2026 03:22

doc: auto-generate docs for engine config and registry config

fe63ee7

NathanFlurry force-pushed the 01-14-doc_auto-generate_docs_for_engine_config_and_registry_config branch from 8c5aaf8 to fe63ee7 Compare January 15, 2026 05:08

NathanFlurry marked this pull request as ready for review January 15, 2026 05:08

NathanFlurry mentioned this pull request Jan 15, 2026

fix(website): fix code group #3914

Closed

graphite-app bot pushed a commit that referenced this pull request Jan 15, 2026

doc: auto-generate docs for engine config and registry config (#3902)

ec33dbd

graphite-app bot closed this Jan 15, 2026

graphite-app bot deleted the 01-14-doc_auto-generate_docs_for_engine_config_and_registry_config branch January 15, 2026 05:09

claude bot mentioned this pull request Jan 15, 2026

[Graphite MQ] Draft PR GROUP:spec_0228e5 (PRs 3901, 3902) #3915

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

doc: auto-generate docs for engine config and registry config #3902

doc: auto-generate docs for engine config and registry config #3902

Uh oh!

NathanFlurry commented Jan 14, 2026

Uh oh!

NathanFlurry commented Jan 14, 2026 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Jan 14, 2026 •

edited

Loading

Uh oh!

claude bot commented Jan 14, 2026 •

edited

Loading

Uh oh!

graphite-app bot commented Jan 15, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

doc: auto-generate docs for engine config and registry config #3902

doc: auto-generate docs for engine config and registry config #3902

Uh oh!

Conversation

NathanFlurry commented Jan 14, 2026

Uh oh!

NathanFlurry commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

How to use the Graphite Merge Queue

Uh oh!

pkg-pr-new bot commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

claude bot commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Review: Auto-generate docs for engine config and registry config

✅ Strengths

🔍 Code Quality Issues

Critical Issues

Medium Priority Issues

Low Priority Issues

🔒 Security Considerations

⚡ Performance Considerations

🧪 Test Coverage

📝 Documentation Quality

🎯 Summary

Uh oh!

graphite-app bot commented Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge activity

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

NathanFlurry commented Jan 14, 2026 •

edited

Loading

pkg-pr-new bot commented Jan 14, 2026 •

edited

Loading

claude bot commented Jan 14, 2026 •

edited

Loading

graphite-app bot commented Jan 15, 2026 •

edited

Loading