eslint-plugin-no-server-imports 1.0.0 → 1.1.1

package/README.md

@@ -1,13 +1,10 @@
 # eslint-plugin-no-server-imports
 
-Modern frameworks cram server and client files together. You flip between them fast, review a PR, feel confident…and then the bundle explodes because someone `import prisma from '@prisma/client'` in a component. Builds take minutes. CI nags later. Users see the error first. Meanwhile you're diffing stack traces wondering where your day went.
+Server and client code sit side by side in modern frameworks, so it is easy to `import { PrismaClient } from '@prisma/client'` in a component and never notice. The build fails minutes later, or the bundle ships and breaks in someone's browser. This plugin flags that import in your editor the moment you write it.
 
-This plugin shortens the feedback loop to zero:
-
-- **Write code → see error immediately** - ESLint surfaces violations as you type, not minutes later in a build
-- **Stay in flow** - Fix happens in the same editor where you're working. No context switching, no waiting for bundlers
-- **Builds become boring** - Errors are caught in dev mode, so `npm run build` confirms what you already know instead of surprising you
-- **Productive dev loop** - Write, see feedback, fix, move on. The way it should be.
+- You see the error as you type, not minutes later in a build.
+- You fix it in the editor you are already in, with no context switch.
+- `npm run build` stops surprising you, because the errors are gone before you run it.
 
 ## TL;DR
 
@@ -39,7 +36,8 @@ Done. Blocks `fs`, `prisma`, `pino`, and 100+ server-only modules in client code
 
 ```bash
 pnpm add -D eslint-plugin-no-server-imports @typescript-eslint/utils
-# npm/yarn/bun work too - ESLint 9+ is the only peer dependency.
+# npm, yarn, and bun work too. Peers: ESLint 9 or 10, plus @typescript-eslint/utils.
+# The package ships ESM only, which flat config (eslint.config.mjs) loads natively.
 ```
 
 ```ts
@@ -104,7 +102,9 @@ By default the rule runs in `client-only` mode, meaning "only check paths that l
 - Re-exports (`export * from 'pino'`) ✅
 - Dynamic imports (`await import('pg')`) stay untouched because they're runtime-only.
 
-The rule also understands server function scopes. If every reference to a value import stays inside a callback passed to functions like `createServerFn`, `createIsomorphicFn`, `server$`, `action$`, or `loader$`, it's considered safe. Configure `serverFunctionNames` to teach it your own helpers (Nuxt's `defineEventHandler`, Remix loaders, etc.). Next.js Server Actions aren't special-cased - keep the imports inside the `'use server'` function via `await import(...)` and you're good.
+The rule also understands server function scopes. If every reference to a value import stays inside a callback passed to functions like `createServerFn`, `createIsomorphicFn`, `server$`, `action$`, or `loader$`, the rule treats it as safe. Configure `serverFunctionNames` to teach it your own helpers, such as Nuxt's `defineEventHandler` or Remix loaders. Next.js Server Actions are not special-cased: keep the import inside the `'use server'` function via `await import(...)` and the rule stays quiet.
+
+One thing the rule does **not** do: ban one file from importing another by path. It flags named server-only *modules* (`pino`, `node:fs`, your own `serverModules` entries), not local imports. So in TanStack Start a client route can `import { listUsers } from '../server/users'` to call a `createServerFn` over RPC, and the rule leaves it alone. To catch a genuine leak, add the Node-only package a component should never touch (a database client, a telemetry provider) to `serverModules`, or keep that code under a `serverFilePatterns` path. See the [TanStack Start example](../../apps/tanstack-start-example) for a working setup.
 
 ### What remains allowed
 
@@ -372,19 +372,19 @@ The extension works alongside the [ESLint VS Code extension](https://marketplace
 
 **Does this replace the `server-only` runtime guard?**
 
-No - keep it for defense in depth. This rule stops mistakes earlier; the runtime guard still protects you if someone bypasses linting. Think of it like wearing both a seatbelt and having airbags.
+No. Keep the runtime guard for defense in depth. This rule catches the mistake earlier, in the editor; the runtime guard still protects you if someone bypasses linting.
 
 **Will it slow down ESLint?**
 
-Nope. The rule only inspects files whose path matches the client patterns, and the AST work is limited to imports/exports/server-function calls. Expect negligible overhead compared to `typescript-eslint` itself. We're pretty efficient about this.
+No. The rule inspects only files whose path matches the client patterns, and the AST work covers imports, exports, and server-function calls. Overhead is negligible next to `typescript-eslint` itself.
 
 **How do I allow a specific file?**
 
-Use `ignoreFiles` with any glob, or drop a `/* eslint-disable no-server-imports/no-server-imports */` pragma if you absolutely must. But really, try to fix the underlying issue first - that's usually the better path.
+Use `ignoreFiles` with any glob, or add a `/* eslint-disable no-server-imports/no-server-imports */` pragma. Fix the underlying import first when you can.
 
 **What if my framework isn't supported?**
 
-We've got defaults for Next.js, Astro, SvelteKit, TanStack Start, Remix, and SolidStart. If your framework uses different patterns, just configure `clientFilePatterns` and `serverFilePatterns` to match your setup. It's pretty flexible.
+The rule ships defaults for Next.js, Astro, SvelteKit, TanStack Start, Remix, and SolidStart. For anything else, set `clientFilePatterns` and `serverFilePatterns` to match your layout and `serverFunctionNames` to match your server helpers.
 
 ## Contributing & support
 

package/dist/index.d.mts

@@ -1,15 +1,16 @@
-import { ESLintUtils } from '@typescript-eslint/utils';
+import { ESLintUtils } from "@typescript-eslint/utils";
 
+//#region src/framework-detection.d.ts
 /**
  * Framework Auto-Detection
  * ========================
  * Automatically detects the frontend framework being used and provides
  * optimal default configurations for the no-server-imports rule.
  */
-type DetectedFramework = 'next' | 'astro' | 'sveltekit' | 'unknown';
+type DetectedFramework = 'next' | 'astro' | 'sveltekit' | 'tanstack-start' | 'unknown';
 interface FrameworkDefaults {
-    clientFilePatterns: string[];
-    serverFilePatterns: string[];
+  clientFilePatterns: string[];
+  serverFilePatterns: string[];
 }
 /**
  * Framework-specific default configurations
@@ -37,103 +38,113 @@ declare function getFrameworkDefaults(filePath?: string): FrameworkDefaults;
  * Clears the cached framework detection (useful for testing)
  */
 declare function clearFrameworkCache(): void;
-
-/**
- * ESLint Plugin: eslint-plugin-no-server-imports
- * ===============================================
- * Prevents server-only module imports in client code.
- * Catches bundling issues in your editor instead of at build time.
- *
- * @author Jag Reehal [@jagreehal] <jag@jagreehal.com>
- * @license MIT
- */
-
+//#endregion
+//#region src/index.d.ts
 /** Configuration options for the no-server-imports rule */
 interface RuleOptions {
-    /** Additional server-only modules to check (merged with defaults) */
-    serverModules?: string[];
-    /** Additional server-only file patterns to check (merged with defaults) */
-    serverFilePatterns?: string[];
-    /** File patterns that indicate client code (overrides defaults if provided) */
-    clientFilePatterns?: string[];
-    /** File patterns to completely ignore */
-    ignoreFiles?: string[];
-    /** Whether to check for 'server-only' import marker */
-    checkServerOnlyMarker?: boolean;
-    /** Whether to check for server function usage (createServerFn, etc.) */
-    checkServerFunctions?: boolean;
-    /** Server function names to check for */
-    serverFunctionNames?: string[];
-    /** Whether to report unused server-only imports (default: true) */
-    reportUnusedImports?: boolean;
-    /** File selection mode: 'client-only' checks only clientFilePatterns, 'all-non-server' checks all except server files */
-    mode?: 'client-only' | 'all-non-server';
-    /** Next.js serverExternalPackages - merged into serverModules (for Next.js projects) */
-    serverExternalPackages?: string[];
+  /** Additional server-only modules to check (merged with defaults) */
+  serverModules?: string[];
+  /** Additional server-only file patterns to check (merged with defaults) */
+  serverFilePatterns?: string[];
+  /** File patterns that indicate client code (overrides defaults if provided) */
+  clientFilePatterns?: string[];
+  /** File patterns to completely ignore */
+  ignoreFiles?: string[];
+  /** Whether to check for 'server-only' import marker */
+  checkServerOnlyMarker?: boolean;
+  /** Whether to check for server function usage (createServerFn, etc.) */
+  checkServerFunctions?: boolean;
+  /** Server function names to check for */
+  serverFunctionNames?: string[];
+  /** Whether to report unused server-only imports (default: true) */
+  reportUnusedImports?: boolean;
+  /** File selection mode: 'client-only' checks only clientFilePatterns, 'all-non-server' checks all except server files */
+  mode?: 'client-only' | 'all-non-server';
+  /** Next.js serverExternalPackages - merged into serverModules (for Next.js projects) */
+  serverExternalPackages?: string[];
 }
 type MessageIds = 'serverOnlyImport' | 'serverOnlyRequire' | 'suggestServerOnlyMarker';
 type Options = [RuleOptions?];
-declare const rule: ESLintUtils.RuleModule<MessageIds, Options, unknown, ESLintUtils.RuleListener>;
-
+declare const rule: ESLintUtils.RuleModule<MessageIds, Options, unknown, ESLintUtils.RuleListener> & {
+  name: string;
+};
 /** Plugin configuration */
 declare const plugin: {
-    readonly rules: {
-        readonly 'no-server-imports': ESLintUtils.RuleModule<MessageIds, Options, unknown, ESLintUtils.RuleListener>;
+  readonly rules: {
+    readonly 'no-server-imports': ESLintUtils.RuleModule<MessageIds, Options, unknown, ESLintUtils.RuleListener> & {
+      name: string;
+    };
+  };
+  readonly configs: {
+    /**
+     * Recommended config - uses sensible defaults that work across frameworks.
+     * For framework-specific optimizations, use one of the framework presets.
+     */
+    readonly recommended: {
+      readonly plugins: readonly ["no-server-imports"];
+      readonly rules: {
+        readonly 'no-server-imports/no-server-imports': "error";
+      };
+    };
+    /**
+     * Next.js optimized configuration.
+     * Best for Next.js App Router and Pages Router projects.
+     */
+    readonly 'recommended-next': {
+      readonly plugins: readonly ["no-server-imports"];
+      readonly rules: {
+        readonly 'no-server-imports/no-server-imports': readonly ["error", {
+          readonly clientFilePatterns: string[];
+          readonly serverFilePatterns: string[];
+        }];
+      };
     };
-    readonly configs: {
-        /**
-         * Recommended config - uses sensible defaults that work across frameworks.
-         * For framework-specific optimizations, use one of the framework presets.
-         */
-        readonly recommended: {
-            readonly plugins: readonly ["no-server-imports"];
-            readonly rules: {
-                readonly 'no-server-imports/no-server-imports': "error";
-            };
-        };
-        /**
-         * Next.js optimized configuration.
-         * Best for Next.js App Router and Pages Router projects.
-         */
-        readonly 'recommended-next': {
-            readonly plugins: readonly ["no-server-imports"];
-            readonly rules: {
-                readonly 'no-server-imports/no-server-imports': readonly ["error", {
-                    readonly clientFilePatterns: string[];
-                    readonly serverFilePatterns: string[];
-                }];
-            };
-        };
-        /**
-         * Astro optimized configuration.
-         * Best for Astro projects with islands architecture.
-         */
-        readonly 'recommended-astro': {
-            readonly plugins: readonly ["no-server-imports"];
-            readonly rules: {
-                readonly 'no-server-imports/no-server-imports': readonly ["error", {
-                    readonly clientFilePatterns: string[];
-                    readonly serverFilePatterns: string[];
-                }];
-            };
-        };
-        /**
-         * SvelteKit optimized configuration.
-         * Best for SvelteKit projects.
-         */
-        readonly 'recommended-sveltekit': {
-            readonly plugins: readonly ["no-server-imports"];
-            readonly rules: {
-                readonly 'no-server-imports/no-server-imports': readonly ["error", {
-                    readonly clientFilePatterns: string[];
-                    readonly serverFilePatterns: string[];
-                }];
-            };
-        };
+    /**
+     * Astro optimized configuration.
+     * Best for Astro projects with islands architecture.
+     */
+    readonly 'recommended-astro': {
+      readonly plugins: readonly ["no-server-imports"];
+      readonly rules: {
+        readonly 'no-server-imports/no-server-imports': readonly ["error", {
+          readonly clientFilePatterns: string[];
+          readonly serverFilePatterns: string[];
+        }];
+      };
     };
-    readonly meta: {
-        readonly name: "eslint-plugin-no-server-imports";
+    /**
+     * SvelteKit optimized configuration.
+     * Best for SvelteKit projects.
+     */
+    readonly 'recommended-sveltekit': {
+      readonly plugins: readonly ["no-server-imports"];
+      readonly rules: {
+        readonly 'no-server-imports/no-server-imports': readonly ["error", {
+          readonly clientFilePatterns: string[];
+          readonly serverFilePatterns: string[];
+        }];
+      };
     };
+    /**
+     * TanStack Start optimized configuration.
+     * Best for TanStack Start projects using createServerFn.
+     */
+    readonly 'recommended-tanstack-start': {
+      readonly plugins: readonly ["no-server-imports"];
+      readonly rules: {
+        readonly 'no-server-imports/no-server-imports': readonly ["error", {
+          readonly clientFilePatterns: string[];
+          readonly serverFilePatterns: string[];
+          readonly checkServerFunctions: true;
+          readonly serverFunctionNames: readonly ["createServerFn", "createIsomorphicFn", "createServerOnlyFn"];
+        }];
+      };
+    };
+  };
+  readonly meta: {
+    readonly name: "eslint-plugin-no-server-imports";
+  };
 };
-
-export { type DetectedFramework, FRAMEWORK_DEFAULTS, type FrameworkDefaults, type RuleOptions, clearFrameworkCache, plugin as default, detectFramework, getFrameworkDefaults, rule };
+//#endregion
+export { type DetectedFramework, FRAMEWORK_DEFAULTS, type FrameworkDefaults, RuleOptions, clearFrameworkCache, plugin as default, detectFramework, getFrameworkDefaults, rule };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/framework-detection.ts","../src/index.ts"],"mappings":";;;;;;AAUA;;;KAAY,iBAAA;AAAA,UAEK,iBAAA;EACf,kBAAA;EACA,kBAAkB;AAAA;;AAAA;AAMpB;cAAa,kBAAA,EAAoB,MAAA,CAAO,iBAAA,EAAmB,iBAAA;;;;;;;;;;;iBA4L3C,eAAA,CAAgB,QAAA,YAAoB,iBAAiB;AAArE;;;;AAAqE;AAuCrE;AAvCA,iBAuCgB,oBAAA,CAAqB,QAAA,YAAoB,iBAAiB;;;AAAA;iBAQ1D,mBAAA;;;;UC5FC,WAAA;EDrJG;ECuJlB,aAAA;EDzED;EC2EC,kBAAA;EDnJsC;ECqJtC,kBAAA;EDrJ+B;ECuJ/B,WAAA;EDvJqC;ECyJrC,qBAAA;EDzJsC;EC2JtC,oBAAA;ED3J0E;EC6J1E,mBAAA;ED+Bc;EC7Bd,mBAAA;;EAEA,IAAA;ED2BmE;ECzBnE,sBAAA;AAAA;AAAA,KAGG,UAAA;AAAA,KAIA,OAAA,IAAW,WAAW;AAAA,cAkPd,IAAA,EAAI,WAAA,CAAA,UAAA,CAAA,UAAA,EAAA,OAAA,WAAA,WAAA,CAAA,YAAA;;;ADjLkB;AAAA,cC8tB7B,MAAA;EAAA;;;;;;;;;;;;;;;;IAtzBJ;;;;IAAA;;;;;;;;;IAmBa;;AAAA;AAAA;IAAA;;;;;;;;;IAsPE;;;;IAAA;;;;;;;;;IA6iBX;;;;IAAA"}