Enforce browser/node code boundaries with linter and build plugin

[jog1t]

Summary

This PR adds comprehensive enforcement of browser/node code boundaries to prevent accidental mixing of platform-specific code. It implements both static linting rules and a runtime build-time plugin to catch violations early.

Key Changes

• Biome Linter Configuration: Added a new linter override for .browser.ts/tsx files that restricts imports of all Node.js built-in modules (both node: prefixed and unprefixed variants). This provides immediate IDE feedback and CI/CD checks.

• esbuild Boundary Enforcement Plugin: Created tsup.plugin.boundaries.ts that enforces bidirectional boundaries:

  • Prevents .browser files from importing Node.js built-ins
  • Prevents .browser files from importing .node modules
  • Prevents .node files from importing .browser modules
  • Provides detailed error messages with file locations and line numbers

• Build Integration: Integrated the boundary enforcement plugin into the base tsup configuration to run during the build process.

Implementation Details

• The esbuild plugin uses onLoad hooks instead of onResolve because tsup's external config prevents onResolve from being called for Node built-in modules
• Supports both node: prefixed and unprefixed module imports (e.g., both node:fs and fs)
• Uses regex-based import detection to find all import and require statements
• Provides clear error messages with file paths and line numbers for easy debugging
• File naming convention: *.browser.ts/tsx for browser-only, *.node.ts/tsx for Node-only, and plain *.ts/tsx for universal code

This dual approach ensures violations are caught both during development (via linter) and at build time (via plugin).

[graphite-app]

Graphite Automations

"Test" took an action on this PR • (01/26/26)

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

[pkg-pr-new]

More templates

• actor-actions
• actor-actions-vercel
• example-ai-agent
• example-ai-agent-vercel
• example-ai-and-user-generated-actors-freestyle
• chat-room
• chat-room-vercel
• example-cloudflare-workers
• example-cloudflare-workers-hono
• cross-actor-actions
• cross-actor-actions-vercel
• example-cursors
• example-cursors-raw-websocket
• example-cursors-raw-websocket-vercel
• example-cursors-vercel
• custom-serverless
• custom-serverless-vercel
• example-sqlite
• example-elysia
• example-elysia-vercel
• example-experimental-durable-streams-ai-agent
• example-experimental-durable-streams-ai-agent-vercel
• hello-world
• hello-world-vercel
• example-hono
• hono-react
• hono-react-vercel
• example-hono-vercel
• example-kitchen-sink
• example-kitchen-sink-vercel
• multi-region
• multi-region-vercel
• native-websockets
• native-websockets-vercel
• next-js
• example-raw-fetch-handler
• example-raw-fetch-handler-vercel
• example-raw-websocket-handler
• example-raw-websocket-handler-proxy
• example-raw-websocket-handler-proxy-vercel
• example-raw-websocket-handler-vercel
• example-react
• example-react-vercel
• scheduling
• scheduling-vercel
• state
• state-vercel
• example-stream
• example-stream-vercel
• example-trpc
• example-trpc-vercel

@rivetkit/cloudflare-workers

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

@rivetkit/db

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

@rivetkit/framework-base

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

@rivetkit/next-js

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

@rivetkit/react

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

rivetkit

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

@rivetkit/sql-loader

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

@rivetkit/virtual-websocket

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

@rivetkit/engine-runner

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

@rivetkit/engine-runner-protocol

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

commit: b767db8

[claude]

Pull Request Review: Enforce browser/node code boundaries

This PR introduces a dual-layered approach to enforcing platform-specific code boundaries using both static linting and build-time validation. The implementation is well-structured and addresses an important architectural concern.

---

✅ Strengths

1. Dual-Layer Enforcement

The combination of Biome linter rules (for IDE/dev feedback) and esbuild plugin (for build-time validation) provides comprehensive coverage. This catches violations early in development while ensuring nothing slips through to production.

2. Clear Error Messages

The esbuild plugin provides helpful error messages with file paths and line numbers, making violations easy to identify and fix.

3. Good Documentation

The plugin includes clear JSDoc comments explaining the file naming conventions and why onLoad is used instead of onResolve.

4. Comprehensive Module Coverage

Both node: prefixed and unprefixed variants are handled, covering common developer patterns.

---

🔍 Issues & Concerns

1. Critical: Missing Bidirectional Enforcement

The PR description mentions preventing .node files from importing .browser modules, but this functionality is not implemented in the esbuild plugin. The plugin only checks .browser files for Node.js built-in imports.

Impact: Browser-specific code could be imported into Node.js files, potentially causing runtime errors or bundling issues.

Recommendation: Add an onLoad hook for *.node.(ts|tsx|js|jsx|mts|mjs|cts|cjs) files that checks for imports from .browser files.

2. Critical: Regex Limitations

The import detection regex has several limitations. It does not catch dynamic imports, template literals, or multi-line imports properly.

Recommendation: Consider using a proper AST parser (like @babel/parser or TypeScript compiler API) for more robust import detection.

3. Performance: File Re-reading

The plugin uses readFile in onLoad, which means files are read from disk twice—once by esbuild and once by the plugin.

Impact: Minor performance overhead, especially for large codebases.

4. Code Quality: Global Regex State

The regex is defined at module scope with the g flag and manually reset after use. This creates shared mutable state that could cause issues if the plugin is reused or called concurrently.

Recommendation: Create the regex inside the onLoad callback for better isolation.

5. Missing: .browser → .node Import Prevention

The PR description states: "Prevents .browser files from importing .node modules", but this is not implemented.

Recommendation: Add logic to check if imported paths end with .node.ts, .node.tsx, etc., and reject those imports in .browser files.

6. Biome Configuration: Redundancy

The biome.json lists all modules twice (with and without node: prefix). While this ensures coverage, it creates maintenance burden.

Recommendation: Consider a code comment or documentation note about this requirement.

7. Testing: No Test Coverage

There are no tests for the boundary enforcement plugin.

Recommendation: Add tests that verify .browser files cannot import Node.js built-ins, .node files cannot import .browser files, and test both node: prefixed and unprefixed imports.

---

🔒 Security Concerns

None identified. This is a build-time enforcement tool that improves code quality but does not introduce security vulnerabilities.

---

⚡ Performance Considerations

1. File I/O overhead: The plugin reads each .browser file from disk during build. This is acceptable for boundary validation but adds some overhead.
2. Build time impact: The plugin will add a small amount to build times. Consider measuring this with large codebases.

---

📋 Test Coverage

Missing entirely. No tests are included for the boundary enforcement plugin or the Biome configuration changes.

---

🎯 Recommendations Summary

High Priority (Must Fix)

1. Implement bidirectional enforcement: Add checks to prevent .node → .browser imports
2. Fix missing .browser → .node import detection: Implement the feature described in the PR
3. Add support for dynamic imports: Extend regex or use AST parsing
4. Add test coverage: Create tests for all boundary violation scenarios

Medium Priority (Should Fix)

5. Fix global regex state: Move regex creation inside callback
6. Add documentation: Explain the file naming convention in a README or comments

Low Priority (Nice to Have)

7. Consider AST parsing: For more robust import detection
8. Add performance benchmarks: Measure impact on build times

---

📝 Additional Notes

• The PR assumes all files in rivetkit-typescript will follow the .browser/.node naming convention, but there are no existing .browser or .node files in the codebase currently. Is this PR intended to enable a future migration? If so, consider adding a migration guide or example files.
• The tsup.base.ts sets platform: "node", which may conflict with the intent of having browser-specific files. Ensure the build configuration properly handles browser targets.
• Consider adding a pre-commit hook or CI check that runs biome check to catch violations before build time.

---

Verdict

Needs work before merging. The concept is excellent and the implementation is on the right track, but several critical features described in the PR are not implemented, and the regex-based approach has limitations that could allow violations to slip through. With the recommended fixes, this will be a valuable addition to the codebase.

Estimated Risk: Medium (missing features could allow violations; regex limitations could miss edge cases)
Code Quality: Good (well-structured, clear documentation)
Completeness: Incomplete (missing bidirectional checks and test coverage)