feat(devtools): add devtools

[jog1t]

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	Dec 5, 2025 8:42pm

3 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
rivet-cloud	Ignored			Dec 5, 2025 8:42pm
rivet-inspector	Ignored	Preview		Dec 5, 2025 8:42pm
rivet-site	Ignored	Preview		Dec 5, 2025 8:42pm

[jog1t]

• feat(devtools): add devtools #3589 👈 (View in Graphite)
• 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

• 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@3589

@rivetkit/db

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

@rivetkit/framework-base

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

@rivetkit/next-js

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

@rivetkit/react

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

rivetkit

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

@rivetkit/sql-loader

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

@rivetkit/engine-runner

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

@rivetkit/engine-runner-protocol

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

commit: f0d13f9

[claude]

Code Review: RivetKit DevTools

Overview

This PR adds a browser-based devtools integration for RivetKit. The implementation creates a floating button that opens the RivetKit Inspector with pre-configured connection parameters.

---

🔴 Critical Issues

1. Security Risk: Token Exposure in URL Parameters (rivetkit-typescript/packages/devtools/src/mod.ts:56-57)

if (config.token) {
    url.searchParams.set("t", config.token);
}

Issue: Authentication tokens are being passed as URL query parameters. This is a security vulnerability because:

• URL parameters appear in browser history
• They are logged in server access logs
• They can leak through HTTP Referer headers
• Browser extensions can access them
• They persist in browser autocomplete

Recommendation:

• Use POST requests with tokens in request body, or
• Use secure session-based authentication, or
• At minimum, add a security warning in the documentation about this risk
• Consider using short-lived tokens or OAuth flows specifically for devtools

2. Resource Leak: Event Listeners Never Removed (rivetkit-typescript/packages/devtools/src/mod.ts:36-65)

Issue: Event listeners are added at module load time but never cleaned up. In single-page applications, this could lead to memory leaks if the script is reloaded or the devtools are toggled.

Recommendation: Export a cleanup function or use AbortController for automatic cleanup

3. Missing Environment Check Before DOM Manipulation (rivetkit-typescript/packages/devtools/src/mod.ts:68)

document.body.appendChild(root);

Issue: The code assumes document.body exists and will execute immediately when the module loads. If the script loads before body is available, this will fail or append to null.

Recommendation: Wrap in DOMContentLoaded check or verify document.body exists first

---

🟡 Important Issues

4. Type Safety: Unsafe Global Variable (rivetkit-typescript/packages/devtools/src/mod.ts:45)

const config = window._rivetkit_devtools_configs?.[0];
if (\!config || typeof config \!== "object") { ... }

Issue: Only checking typeof config \!== "object" is insufficient - arrays, null, and many other things are objects in JavaScript.

Recommendation: Add more specific type checking to validate the config structure

5. Multiple Client Support Not Handled (rivetkit-typescript/packages/devtools/src/mod.ts:45)

const config = window._rivetkit_devtools_configs?.[0];

Issue: The code always uses the first config, but multiple clients can be created. Users have no way to switch between multiple client configurations.

Recommendation: Either add UI to select which client config to inspect, or document that only the first client is inspectable

6. Build Configuration Inconsistency (rivetkit-typescript/packages/rivetkit/tsup.config.ts:10-12)

Issue: The define replacement sets the value to string "false" (not boolean false) when the env var is not set. This is inconsistent and could cause confusion.

Recommendation: Use "undefined" instead of "false" for consistency

---

🟢 Minor Issues & Suggestions

7. DevTools Auto-Enable Logic Could Be More Robust (rivetkit-typescript/packages/rivetkit/src/client/config.ts:46-50)

Suggestion: This only enables for localhost. Consider also enabling for 127.0.0.1, local IP addresses, or when NODE_ENV === "development"

8. Duplicate Script Injection Possible (rivetkit-typescript/packages/rivetkit/src/devtools/mod.ts:20-26)

Issue: If injectDevtools is called multiple times rapidly before the script has loaded, there is a race condition where multiple scripts could be injected.

Recommendation: Use a flag or promise to track injection state

9. CSS Positioning Could Conflict (rivetkit-typescript/packages/devtools/src/styles.css:3-9)

Issues:

• Duplicate bottom property (12px is overridden by 25px)
• Using max z-index could conflict with other libraries
• Fixed positioning might overlap important UI elements

Recommendation: Remove duplicate bottom property, consider making z-index configurable

10. Missing Error Handling for Script Load Failures (rivetkit-typescript/packages/rivetkit/src/devtools/mod.ts:21-25)

Suggestion: Add onerror handler to log when devtools script fails to load

11. Documentation Typo (rivetkit-typescript/packages/devtools/README.md:17)

"This will ensure that the RivetKit will use local devtool assets"
Fix: Remove duplicate article - "This will ensure that RivetKit will use..."

12. Package.json Side Effects Configuration (rivetkit-typescript/packages/devtools/package.json:10-12)

Issue: The module has side effects (DOM manipulation at import time), but the side effects array only lists chunk files, not the main entry point.

Recommendation: Set "sideEffects": true or include the main entry points in the array

---

✅ Positive Aspects

1. Shadow DOM Usage: Good use of Shadow DOM to isolate styles and prevent conflicts
2. TypeScript Declarations: Proper global type declarations for Window interface
3. Development Workflow: Clear README with development setup instructions
4. Conditional Loading: Smart default to only enable on localhost
5. Build Configuration: Clean tsup configuration with appropriate loaders

---

📋 Testing Recommendations

The PR lacks test coverage. Consider adding tests for:

1. Unit Tests:

   • DevTools injection with various config combinations
   • URL construction with different config parameters
   • Handling of missing/invalid configs

2. Integration Tests:

   • DevTools UI rendering in different browsers
   • Multiple client scenarios
   • Shadow DOM isolation

3. Security Tests:

   • Token handling and exposure
   • XSS prevention in config values

---

🎯 Priority Recommendations

Must Fix Before Merge:

1. Address token security issue ([SVC-2555] Set up issue templates #1)
2. Fix DOM access before body exists ([SVC-2504] Fix 5 GB upload limit for local development from Cloudflare #3)
3. Fix duplicate bottom CSS property ([SOC-15] Fix error when running user-delete #9)

Should Fix:
4. Handle multiple clients properly (#5)
5. Fix event listener memory leaks (#2)
6. Improve type checking (#4)

Nice to Have:
7. All other suggestions for robustness and maintainability

---

Summary

This is a solid foundation for RivetKit DevTools integration. The implementation is clean and uses modern web APIs appropriately. However, there are critical security concerns around token handling that must be addressed before merging. The code quality is generally good, but would benefit from more defensive programming practices and comprehensive test coverage.

[graphite-app]

Graphite Automations

"Test" took an action on this PR • (12/04/25)

1 assignee was added to this PR based on Kacper Wojciechowski's automation.