chore(nextjs): Improve type safety of #safe-node-apis #6597

panteliselef · 2025-08-21T10:24:39Z

Description

Checklist

pnpm test runs as expected.
pnpm build runs as expected.
(If applicable) JSDoc comments have been added or updated for any package exports
(If applicable) Documentation has been updated

Type of change

Summary by CodeRabbit

Bug Fixes
- Made server telemetry event handling synchronous for more reliable, deterministic behavior.
Refactor
- Hardened Node API access with stricter non-null checks and clearer error messaging when unavailable.
Chores
- Added typed definitions for safe Node APIs to improve type safety and editor tooling.
Documentation
- Recorded a patch changeset entry for the Next.js package.

vercel · 2025-08-21T10:24:44Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Comment	Aug 21, 2025 11:52am

pkg-pr-new · 2025-08-21T10:27:40Z

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@6597

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@6597

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@6597

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@6597

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@6597

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@6597

@clerk/elements

npm i https://pkg.pr.new/@clerk/elements@6597

@clerk/clerk-expo

npm i https://pkg.pr.new/@clerk/clerk-expo@6597

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@6597

@clerk/express

npm i https://pkg.pr.new/@clerk/express@6597

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@6597

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@6597

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@6597

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@6597

@clerk/clerk-react

npm i https://pkg.pr.new/@clerk/clerk-react@6597

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@6597

@clerk/remix

npm i https://pkg.pr.new/@clerk/remix@6597

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@6597

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@6597

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@6597

@clerk/themes

npm i https://pkg.pr.new/@clerk/themes@6597

@clerk/types

npm i https://pkg.pr.new/@clerk/types@6597

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@6597

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@6597

commit: b25921d

coderabbitai · 2025-08-21T10:31:39Z

📝 Walkthrough

Walkthrough

Adds a new ambient module declaration (#safe-node-apis) with typed accessors for fs, path, and cwd.
Refactors fs utils to introduce a generic assertNotNullable helper; replaces prior null checks.
Updates nodeFsOrThrow, nodePathOrThrow, and nodeCwdOrThrow to use assertNotNullable and return NonNullable types.
Switches keyless telemetry flag-writing from async to sync (mkdirSync/writeFileSync); adjusts call site accordingly.
Removes an internal throwMissingFsModule helper and a ts-ignore.
Adds a patch changeset entry for @clerk/nextjs describing added types for safe-node-apis.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

CodeRabbit Commands (Invoked using PR/Issue comments)

Type @coderabbitai help to get the list of available commands.

Other keywords and placeholders

Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (`.coderabbit.yaml`)

You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Status, Documentation and Community

Visit our Status Page to check the current availability of CodeRabbit.
Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

coderabbitai

Actionable comments posted: 1

🧹 Nitpick comments (7)

.changeset/sharp-suits-lay.md (1)
5-5: Consider documenting the internal runtime tweak in the changeset.

This PR also switches keyless telemetry writes to synchronous I/O. Even if internal, calling that out helps consumers scanning release notes.

Apply this diff to make the note explicit:
 ---
 '@clerk/nextjs': patch
 ---
 
-Add types to safe-node-apis modules.
+Add types to safe-node-apis modules.
+
+Internal:
+- Switch keyless telemetry flag creation to synchronous FS APIs to simplify control flow.
packages/nextjs/src/types/safe-node-apis.d.ts (1)
9-16: Tighten typings: prefer optional + readonly properties and readonly export.

Using optional properties communicates intent better than | undefined, and readonly prevents accidental mutation at type level.

Apply this diff:
   interface FileSystem {
-    existsSync: typeof existsSync;
-    writeFileSync: typeof writeFileSync;
-    readFileSync: typeof readFileSync;
-    appendFileSync: typeof appendFileSync;
-    mkdirSync: typeof mkdirSync;
-    rmSync: typeof rmSync;
+    readonly existsSync: typeof existsSync;
+    readonly writeFileSync: typeof writeFileSync;
+    readonly readFileSync: typeof readFileSync;
+    readonly appendFileSync: typeof appendFileSync;
+    readonly mkdirSync: typeof mkdirSync;
+    readonly rmSync: typeof rmSync;
   }
 
   interface SafeNodeApis {
-    fs: FileSystem | undefined;
-    path: typeof nodePath | undefined;
-    cwd: (() => string) | undefined;
+    readonly fs?: FileSystem;
+    readonly path?: typeof nodePath;
+    readonly cwd?: () => string;
   }
 
-  declare const safeNodeApis: SafeNodeApis;
+  declare const safeNodeApis: Readonly<SafeNodeApis>;
Also applies to: 18-24
packages/nextjs/src/server/keyless-telemetry.ts (5)
44-44: Sync I/O: verify impact and concurrency behavior.

Switching to sync FS is simpler and fine given one-time flag creation, but it blocks the event loop on a hot path if drift detection is invoked during requests. Validate that this code runs during boot or a non-latency-critical path.

If you want non-blocking I/O without promises at the call site, consider a small worker or deferring flag creation to a background tick:
-function tryMarkTelemetryEventAsFired(): boolean {
+function tryMarkTelemetryEventAsFired(): boolean {
   try {
     if (canUseKeyless) {
       const { mkdirSync, writeFileSync } = nodeFsOrThrow();
       // ...
Optionally, gate with a cheap in-memory boolean to avoid hitting disk after the first attempt in-process.

52-53: Set explicit directory permissions (defense-in-depth).

While telemetry data here isn’t sensitive, it’s good practice to restrict perms for internal dirs.

Apply this diff:
-      mkdirSync(flagDirectory, { recursive: true });
+      mkdirSync(flagDirectory, { recursive: true, mode: 0o700 });
58-59: Specify encoding and file mode for the telemetry flag file.

Avoids platform defaults and ensures restrictive perms.

Apply this diff:
-      writeFileSync(flagFilePath, JSON.stringify(flagData, null, 2), { flag: 'wx' });
+      writeFileSync(flagFilePath, JSON.stringify(flagData, null, 2), {
+        flag: 'wx',
+        encoding: 'utf8',
+        mode: 0o600,
+      });
29-31: Optional: use the typed safe path/cwd wrappers for consistency.

This module imports path and uses process.cwd(). To stay aligned with the #safe-node-apis surface, you can switch to nodePathOrThrow() and nodeCwdOrThrow(). Not required if this file is guaranteed to be server-only.

Outside the changed lines, here is a concrete refactor sketch:
// Replace imports:
import { nodeFsOrThrow, nodePathOrThrow, nodeCwdOrThrow } from './fs/utils';

// Update implementation:
function getTelemetryFlagFilePath(): string {
  const cwd = nodeCwdOrThrow();
  const { join } = nodePathOrThrow();
  return join(cwd(), TELEMETRY_FLAG_FILE);
}

// Where dirname is needed:
const { dirname } = nodePathOrThrow();
const flagDirectory = dirname(flagFilePath);
Also applies to: 47-50

44-70: Add targeted tests for the new sync behavior.

Creating the flag when it doesn’t exist returns true and writes file with 0o600 perms.

Subsequent calls return false (EEXIST path).

Errors other than EEXIST log a warning and return false.

I can scaffold a test harness that stubs nodeFsOrThrow() to a temp dir FS and asserts the above without touching real disk. Want me to push a test file?

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

MCP integration is disabled by default for public repositories
Jira integration is disabled
Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 4ac7b25 and d604022.

📒 Files selected for processing (4)

.changeset/sharp-suits-lay.md (1 hunks)
packages/nextjs/src/server/fs/utils.ts (1 hunks)
packages/nextjs/src/server/keyless-telemetry.ts (2 hunks)
packages/nextjs/src/types/safe-node-apis.d.ts (1 hunks)

🧰 Additional context used

📓 Path-based instructions (8)

.changeset/**

📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)

Automated releases must use Changesets.

Files:

.changeset/sharp-suits-lay.md

**/*.{js,jsx,ts,tsx}