@thednp/rpc 0.2.1 → 0.3.1

package/AGENTS.md

@@ -4,6 +4,7 @@
 
 ```bash
 pnpm dev # Run examples/spa dev server
+pnpm dev:advanced # Run examples/advanced dev server
 pnpm dev:express # Run examples/express dev server
 pnpm dev:fastify # Run examples/fastify dev server
 pnpm dev:h3 # Run examples/h3 dev server
@@ -13,18 +14,23 @@ pnpm dev:react-query # Run examples/react-query dev server
 pnpm dev:solid-query # Run examples/solid-query dev server
 pnpm dev:ssr # Run examples/ssr dev server
 pnpm lint # Lint + typecheck (deno lint + tsc)
-pnpm test # Run tests with coverage
-pnpm test-ui # Run tests with UI
+pnpm test # Run tests once with coverage (vitest run --coverage)
+pnpm test:watch # Run tests in watch mode with coverage
+pnpm test:ui # Run tests with UI
+pnpm test:dev # Run examples in dev mode (scripts/dev-test)
+pnpm test:prod # Run examples in prod preview (scripts/dev-test --mode=preview)
 pnpm lint:ts # deno lint src
 pnpm fix:ts # deno lint src --fix
 pnpm check:ts # tsc -noEmit
-pnpm format # deno fmt src
+pnpm format # deno fmt src tests examples/**/src
+pnpm clean # Remove build artifacts and caches
 pnpm build # tsdown (outputs to dist/)
 pnpm up:examples # Update all example deps (to latest published @thednp/rpc + latest example deps)
 pnpm up:examples:lib # Sync examples to the latest published @thednp/rpc version
 pnpm up:root # Update root deps
 pnpm up:deno # deno update + sync deno.json deps
 pnpm upd # Update all deps (up:examples + up:examples:lib + up:root)
+pnpm audit:src # Audit src deps
 pnpm prepareOnly # upd + up:deno + lint + format + audit:src + build
 pnpm release # Publish npm + jsr (scripts/release.js)
 ```
@@ -35,19 +41,20 @@ pnpm release # Publish npm + jsr (scripts/release.js)
 
 ## Examples
 
-The `examples/` directory contains 9 example apps:
-
-| Example       | Adapter                                                           | Type | Run Command             | Config                                  |
-| ----------------| -------------------------------------------------------------------| ------| -------------------------| -----------------------------------------|
-| `spa`          | Vite dev server (no adapter)                                      | SPA  | `pnpm dev`              | `examples/spa/rpc.config.ts`            |
-| `express`      | Express                                                           | SSR  | `pnpm dev:express`      | `examples/express/rpc.config.ts`        |
-| `fastify`      | Fastify                                                           | SSR  | `pnpm dev:fastify`      | `examples/fastify/rpc.config.ts`        |
-| `h3`           | h3                                                                | SSR  | `pnpm dev:h3`           | `examples/h3/rpc.config.ts`             |
-| `hono`         | Hono                                                              | SSR  | `pnpm dev:hono`         | `examples/hono/rpc.config.ts`           |
-| `koa`          | Koa                                                               | SSR  | `pnpm dev:koa`          | `examples/koa/rpc.config.ts`            |
-| `react-query`  | Express (React + @tanstack/react-query SSR)                       | SSR  | `pnpm dev:react-query`  | `examples/react-query/rpc.config.ts`    |
-| `solid-query`  | Express (Solid + @tanstack/solid-query SSR)                       | SSR  | `pnpm dev:solid-query`  | `examples/solid-query/rpc.config.ts`    |
-| `ssr`          | Custom `http-express.ts` (Express-compatible `node:http` server ) | SSR  | `pnpm dev:ssr`          | `examples/ssr/rpc.config.ts`            |
+The `examples/` directory contains 10 example apps:
+
+| Example       | Adapter                                                           | Type | Run Command            | Config                               |
+| ---------------| -------------------------------------------------------------------| ------| ------------------------| --------------------------------------|
+| `spa`         | Vite dev server (no adapter)                                      | SPA  | `pnpm dev`             | `examples/spa/rpc.config.ts`         |
+| `express`     | Express                                                           | SSR  | `pnpm dev:express`     | `examples/express/rpc.config.ts`     |
+| `advanced`    | Express                                                           | SSR  | `pnpm dev:advanced`    | `examples/advanced/rpc.config.ts`    |
+| `fastify`     | Fastify                                                           | SSR  | `pnpm dev:fastify`     | `examples/fastify/rpc.config.ts`     |
+| `h3`          | h3                                                                | SSR  | `pnpm dev:h3`          | `examples/h3/rpc.config.ts`          |
+| `hono`        | Hono                                                              | SSR  | `pnpm dev:hono`        | `examples/hono/rpc.config.ts`        |
+| `koa`         | Koa                                                               | SSR  | `pnpm dev:koa`         | `examples/koa/rpc.config.ts`         |
+| `react-query` | Express (React + @tanstack/react-query SSR)                       | SSR  | `pnpm dev:react-query` | `examples/react-query/rpc.config.ts` |
+| `solid-query` | Express (Solid + @tanstack/solid-query SSR)                       | SSR  | `pnpm dev:solid-query` | `examples/solid-query/rpc.config.ts` |
+| `ssr`         | Custom `http-express.ts` (Express-compatible `node:http` server ) | SSR  | `pnpm dev:ssr`         | `examples/ssr/rpc.config.ts`         |
 
 Each example follows the same structure:
 
@@ -74,6 +81,7 @@ Each example follows the same structure:
 The tsdown.config.ts produces multiple entries:
 
 - `dist/index.mjs` — main Vite plugin
+- `dist/config/config.mjs` — vite-free `defineConfig` (safe for serverless bundles)
 - `dist/server/server.mjs` — standalone server
 - `dist/express/express.mjs` — Express middleware
 - `dist/fastify/fastify.mjs` — Fastify middleware
@@ -108,9 +116,10 @@ The tsdown.config.ts produces multiple entries:
 
 - Vite plugin for creating server functions with automatic RPC generation
 - Server functions return `{ data: Promise<T>, cancel: (reason?: string) => void }` shape
-- Framework-agnostic core with adapters for Express, Fastify, Hono, and Koa
+- Framework-agnostic core with adapters for Express, Fastify, Hono, Koa, and h3
 - Client modules are auto-generated with `AbortController` support for cancellation
 - Server-side caching must be handled by third party tools (e.g. `@tanstack/react-query`)
+- **Multi-prefix support**: `createServerFunction(..., { rpcPrefix })` registers functions in a prefix-scoped map (`getFunctionsForPrefix`), so multiple RPC instances can coexist (versioned/namespaced APIs). All five adapters dispatch via `getFunctionsForPrefix(rpcPrefix || defaultPrefix)`; `serverFunctionsMap` is a backward-compatible proxy for the default `"__rpc"` prefix (`defaultPrefix`)
 
 ## Security & Hardening
 
@@ -118,8 +127,8 @@ The tsdown.config.ts produces multiple entries:
 - **Prefix regex injection prevention**: `rpcPrefix` config string is escaped via `escapeRegExp()` before being embedded in the boundary regex, preventing ReDoS or unintended matching from metacharacters in the prefix
 - **Regex compilation hoisted**: All prefix/path regexes are compiled once at middleware creation time (not per-request), eliminating per-request regex overhead
 - **Koa URL normalization**: Koa adapter parses `ctx.url` through `new URL()` to strip query strings and normalize encoding before prefix checking
-- **Code injection prevention in client module generation**: `getClientModules.ts` validates all interpolated identifiers (`fnName`, `fnEntry`, `rpcPrefix`) against `/^[A-Za-z_$][A-Za-z0-9_$]*$/` (and a path-safe variant allowing `/`) before interpolating into the generated client bundle. This prevents code injection via malicious export names or prefixes containing template literal interpolations (`${...}`), backticks, or `</script>` sequences.
-- **Body size limits**: Host frameworks cap parsed JSON bodies — Express (`express.json({ limit })`), Fastify (`bodyLimit`), Koa (`koa-body`), Hono (`hono/body-limit`). Rely on your framework's body parser middleware for size limits (see wiki/best-practices.md). The raw stream path in `readBody` does not impose a built-in limit — use framework middleware or a custom body limit handler for defense-in-depth.
+- **Code injection prevention in client module generation**: `getClientModules.ts` validates all interpolated identifiers (`fnName`, `fnEntry`, `rpcPrefix`) against `/^[A-Za-z_$][A-Za-z0-9_$]*$/` (and a path-safe variant allowing `/`, `@`, `:`, `-`) before interpolating into the generated client bundle. This prevents code injection via malicious export names or prefixes containing template literal interpolations (`${...}`), backticks, or `</script>` sequences.
+- **Body size limits**: Host frameworks cap parsed JSON bodies — Express (`express.json({ limit })`), Fastify (`bodyLimit`), Koa (`koa-body`), Hono (`hono/body-limit`), h3 (`bodyLimit`/`assertBodySize`). Rely on your framework's body parser middleware for size limits (see wiki/best-practices.md). The raw stream path in `readBody` does not impose a built-in limit — use framework middleware or a custom body limit handler for defense-in-depth.
 - **Generic 404 responses**: Error messages never echo the requested function name (no message-based function enumeration). Note the status code still distinguishes unknown (`404`) from known functions (`405`/`415`/`403`); function names ship in the client bundle so they are not secret — see `wiki/security.md`
 - **Auth is middleware's responsibility**: Authentication should be handled by middleware registered before `createRPCMiddleware()`. The middleware chain naturally composes — no built-in auth hook is needed.
 - **No client-side secrets or stack traces**: Error responses always return `"Internal Server Error"` regardless of the underlying error; `console.error(String(err))` is server-side only for debugging and does not surface internals to the client
@@ -146,6 +155,12 @@ The framework's security boundary is the **RPC prefix-gated HTTP endpoint**. Inp
 - Be free to hit any URL (no auth — host's responsibility via prior middleware)
 - Be rejected with generic error bodies (no function-name disclosure in messages, no stack traces); status-code differential still reveals existence — see `wiki/security.md`
 
+## Workflow notes (important!)
+
+- **Harness folders**: when scaffolding a minimal repro/harness to debug the Vite plugin or an adapter, create it inside the repo (e.g. `TEMP/`) — **never** in the root or in OS temp dirs. Root-level harness files break `tsdown`/`vitest` path resolution, and temp dirs outside the project get swept by OS cleaners and leave stale `node_modules`/`.vite` state that corrupts the next run.
+- **Never delete files**: do not `rm` source/test files. If a file must be removed from the tree, **rename it to `<name>-bak.<ext>`** (e.g. `foo.ts` → `foo-bak.ts`) and leave it in place. The `-bak` suffix is the only sanctioned way to retire a file; the repo may be scanned for history or references later.
+
+
 ## Documentation
 
 - `wiki/quickstart.md` — Rebuild the Express SSR example from `create-vite` in under a minute (copy-paste)

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## [0.3.1] - 2026-08-21
+
+### Breaking Changes
+
+- **`defineConfig` moved to `@thednp/rpc/config`**: the config helper no longer ships from the main plugin entry. `@thednp/rpc` statically imports Vite (it *is* a Vite plugin), so any server-side file importing it — including a serverless function bundle that merely reads your `rpc.config.ts` — would emit a runtime `require("vite")` and crash at cold start on platforms where Vite isn't installed (Netlify: `Runtime.ImportModuleError: Cannot find module 'vite'` → 502). The new `/config` subpath has zero dependencies, making serverless deployments behave like any other Express server. Update one import line in `rpc.config.ts`: `import { defineConfig } from "@thednp/rpc/config"`. All examples and the demo updated; `tests/fixtures/*` configs now import from source to stay resolution-safe before publish
+- **demo Netlify function hardened** (`demo/netlify/functions/rpc.ts`): URL rewrite reconstructs the path from `cfg.rpcPrefix` instead of a hardcoded `"/@demo/"`; `serverless-http` moved from devDependencies to dependencies (it is runtime code inside the function bundle)
+
+### Added
+
+- **Vite-free `defineConfig` module** (`src/config.ts`, built to `dist/config/config.mjs`): merges partial config over `defaultRPCOptions`, skipping explicitly `undefined` values so callers can't accidentally blank out defaults; zero runtime dependencies (type-only import erased at build)
+- **`./config` subpath export**: wired into `package.json` exports and `deno.json` exports/imports maps; new tsdown build entry alongside the existing adapter/helper entries
+
+### Removed
+
+- **`ensurePrefixFromGlobal` deleted** (`src/functionsMap.ts`) together with its call sites across all five adapter `createMiddleware` files — the copy-from-default-prefix fallback is superseded by the explicit prefix bootstrap below; also removed dead commented `setGlobalPrefix` calls from the adapters and `src/index.ts`
+- **Serverless prefix bootstrap made explicit**: `setGlobalPrefix(cfg.rpcPrefix)` at the top of `src/api/server.ts` replaces implicit framework magic — static-import hoisting guarantees it runs before any `createServerFunction`, regardless of import order in the host function bundle (`demo/src/api/server.ts`)
+
+### Docs
+
+- `wiki/adapters.md` **Serverless section rewritten** around two rules: (1) import `defineConfig` from `@thednp/rpc/config`, never the main entry, with the cold-start crash explained; (2) set the prefix at the top of `src/api/server.ts`; references the working [demo/netlify/functions/rpc.ts](../demo/netlify/functions/rpc.ts) and keeps `netlify.toml external_node_modules = ["vite"]` documented as a size optimization
+- `wiki/configuration.md` — `defineConfig` section documents the `/config` subpath and why the main entry must never be imported server-side
+- `README.md`, `wiki/quickstart.md`, `wiki/getting-started.md` — all `rpc.config.ts` snippets switched to `@thednp/rpc/config`
+- `AGENTS.md` — h3 added to the adapter list and body-size-limits row (`bodyLimit`/`assertBodySize`); build output table gains `dist/config/config.mjs`
+- `llms.txt` — config section notes the vite-free subpath and its serverless rationale
+
+### Tests
+
+- Fixtures (`tests/fixtures/*.config.ts`) import `defineConfig` from source instead of the main entry, keeping `loadRPCConfig` suites green before publish
+- "load config from file" suite targets `examples/advanced/rpc.config.ts` (the `link:../..` example) so it resolves current source including the unpublished `./config` export
+- New coverage: `defineConfig` skips explicitly `undefined` values back to defaults — **428 tests, 100% on all metrics**
+
+### Fixed
+
+- **Graceful scan without Vite** (`src/scanForServerFiles.ts`): the lazy `import("vite")` is now wrapped in try/catch — when Vite isn't installed (serverless bundles where it's externalized or absent), the scan exits silently instead of crashing the host cold start with `Runtime.ImportModuleError: Cannot find module 'vite'` → 502. Defense-in-depth for deployments whose function bundle doesn't import its server module directly; covered by a new suite that mocks Vite as missing (`tests/scan.test.ts`) — **429 tests, 100% on all metrics**
+- **demo `rpc.config.ts` restored to `defineConfig`**: the plain-object workaround from the Netlify debugging session is retired — the config file now uses the documented `defineConfig({ rpcPrefix: "@demo" })` from `@thednp/rpc/config`, proving the vite-free subpath works end-to-end inside the live Netlify function bundle
+
+## [0.3.0] - 2026-08-21
+
+### Features
+
+- **Multi-prefix support**: `createServerFunction` accepts a per-function `rpcPrefix` option (`{ rpcPrefix: "v1:rpc" }`) so multiple RPC instances can coexist in parallel — versioned APIs, namespaced endpoints, and API segregation without function-name collisions. The server functions map is now scoped by prefix (`getFunctionsForPrefix(prefix)`), the plugin generates client stubs per prefix (`getClientModules` reads only the requested prefix's map), and all five adapters (Express, Fastify, Hono, Koa, h3) look functions up in the prefix-scoped map instead of a single global map. Functions default to `"__rpc"` for full backward compatibility; the same registered name under different prefixes is no longer a duplicate, while same-prefix duplicates still throw in dev / warn in production
+- **`getFunctionsForPrefix(prefix)`**: new exported server helper returning (and lazily creating) the `Map<name, ServerFnEntry>` for a given RPC prefix; `serverFunctionsMap` remains as the backward-compatible proxy for the default `"__rpc"` prefix
+- **`defaultPrefix` constant**: the default `"__rpc"` prefix is now a named export from `@thednp/rpc/server`, used consistently across the scan, adapters, and function registration instead of a hardcoded string
+- **Prefix charset widened**: `validatePathSegment` now permits `:` (and `@` in the first position) so versioned prefixes like `v1:rpc` / `v2:rpc` pass validation; `.` remains disallowed to keep path-traversal rejection (`foo..bar`, `foo/../bar`) intact
+- **`getClientStub` helper** (`@thednp/rpc/helpers`): manual typed client stub factory for privileged prefixes not emitted in the public bundle — `getClientStub("admin:rpc","get-user")` (also curried `getClientStub("admin:rpc")("get-user")`) returns the same `{data,cancel}` shape as auto-generated stubs, with `method`/`credentials`/`contentType` options; code-splittable so `admin:rpc` literals never appear in the public chunk when `await import`-ed only inside `/admin` routes
+- **Advanced example auth**: `examples/advanced` now has cookie-session auth (`HttpOnly; SameSite=Lax` `sid` via `Symbol.for("thednp.rpc.advanced.session")`), `public:rpc/login`/`logout`/`me`, `admin:rpc` guarded by `requireAdminSession` (403 without admin role), and SSR guard for `/admin` → `403` in `server.js` — demonstrates that `admin:rpc` isolation is not obscurity and that `getClientStub` must be used with real auth
+
+### Fixes
+
+- **Cross-bundle map sharing**: `serverFunctionsByPrefix` now on `globalThis[Symbol.for("thednp.rpc.functionsMap")]` (`src/functionsMap.ts:12`) like `requestContext` — plugin scan (`dist/index.mjs`) and adapter dispatch (`dist/express/*.mjs`) share one map instead of per-bundle copies (dev 404 fix)
+- **Config fallback**: scan fallback `exportValue.options?.rpcPrefix || config.rpcPrefix || defaultPrefix` (`src/scanForServerFiles.ts:138`) and `ScanConfig.rpcPrefix` (`src/types.d.ts:217`) propagated from `vite.config.ts`/`rpc.config.ts` via `src/index.ts:193` and lazy `src/*/*createMiddleware.ts:107` — existing examples without per-function `rpcPrefix` now register under the config prefix instead of `__rpc`
+- **Glob scan in prod**: `MiddlewareOptions.serverFiles/scanRoot` (`src/types.d.ts:333`) now forwarded to lazy `scanForServerFiles` in all five adapters, and `examples/advanced/server.js:25` `admin:rpc` mounts with `serverFiles:"glob"` — prod `preview` finds `*.server.ts` files instead of defaulting to `exact`
+- **Client generation DRY**: `src/getClientModules.ts:47` now emits `getClientStub("prefix","name",{...})` via `src/client-helpers.ts:32` `makeStub` instead of duplicating `body`/`headers` per function
+
+### Docs
+
+- New `wiki/multi-prefix-guide.md` — parallel RPC instances: versioned/public/admin API layouts, per-prefix middleware wiring, canary deployments, origin validation per instance, and backward compatibility; added **Security: Do Not Trust the Prefix** section
+- `wiki/security.md:92` **Multi-Prefix Client Isolation** — `getClientModules` virtual modules (`src/index.ts:221`), no disk files, only config prefix emitted, prefix is not a secret, must use `requireAdminSession`/`sendResponse(403)`
+- `wiki/index.md` TOC + cross-links from `wiki/configuration.md` and `wiki/adapters.md` to the multi-prefix guide
+- `AGENTS.md`, `llms.txt`, and `README.md` updated for the multi-prefix feature, `defaultPrefix` constant, `getClientStub`, and `dev:advanced`/`test:dev`/`test:prod` scripts
+- `examples/advanced/README.md` rewritten for auth + multi-prefix demo
+
+### Tests
+
+- Multi-prefix coverage: `createServerFunction` registers under a custom prefix (isolated from the default map), `getClientModules` generates `getClientStub` stubs only for the requested prefix, and the scan registers functions under their declared prefix without name collision
+- Adapter middleware tests updated to register functions in the prefix-scoped map for non-default prefixes
+- `getClientStub` coverage: curried `getClientStub("admin:rpc")("get-user")` and direct `getClientStub("admin:rpc","get-user")` plus `GET`/`text/plain`/`urlencoded`/`multipart` branches (`tests/client-helpers.test.ts:198`)
+- **100% coverage**: all metrics (statements, branches, functions, lines) at 100% — 427 tests
+
+### Chores
+
+- `pnpm test` now `vitest run --coverage`; new `pnpm test:watch` `vitest --watch --coverage`; `pnpm test:dev`/`test:prod` now `test:dev`/`test:prod` with colon; `pnpm clean` and `pnpm audit:src` documented; `scripts/update-examples.js:33` skips `advanced` (`link:../..`)
+
 ## [0.2.1] - 2026-08-10
 
 ### Features
@@ -16,6 +89,7 @@
 - **demo**: `body-limit.ts` stashes multipart bodies as `{ raw: body }` to mirror `@thednp/rpc/express`'s `readBody` streaming semantics; the render page and `getLibraryInfo` now count 9 examples and list the h3 adapter; the features grid grows to 9 cards (3×3) with request-context, no-JS form-fallback, and boundary-enforcement entries
 - **fastify example**: switch the production server to `@fastify/compress` (gzip) for the RPC endpoint and static HTML. `@fastify/compress` attaches its per-route `onSend` hook via `onRoute`, which never fires for the RPC plugin's global `preHandler` handling, so the example registers a scoped `app.post("/_server/*")` catch-all route — the RPC `preHandler` short-circuits before the handler runs, letting compress's hook attach to RPC POSTs while non-RPC POSTs still get a 404. Verified with curl: HTML and RPC POST responses (200 and 404) compress (gzip) with byte-identical decompression (md5 match), and non-RPC POSTs keep their 404
 - Sync all 9 examples to `@thednp/rpc ^0.2.0`
+- **advanced example** (`examples/advanced`): Express SSR showcase of the multi-prefix model and universal middleware — the same `get-user` function name is registered under both `public:rpc` (rate-limited, 5 req/10s, returns public user data) and `admin:rpc` (guarded by a `x-admin-token` header check, returns full record), served by two `createRPCMiddleware` instances mounted in `server.js` while the client stubs are generated only for the config `public:rpc` prefix; a `middleware.ts` module (`rateLimit`, `auditLog`, `requireAdmin`) built on `getRequestContext`/`getRequestMeta`/`sendResponse` is shared across both prefixes. Dev mode mounts the admin middleware explicitly since the Vite plugin only auto-mounts the configured prefix; `scripts/dev-test.js` PREFIX_MAP includes `advanced: "public:rpc"` and the root `dev:advanced` script runs it
 
 ### Docs
 

package/README.md

@@ -99,6 +99,18 @@ Server errors return a generic `Internal Server Error` — no messages, codes, o
 Generic type inference flows from your server function's arguments and return type all the way to the client stub. You get autocomplete for function names, argument types, and return types without writing a single type annotation on the client side.
 </details>
 
+<details>
+<summary><b>Multi-prefix support</b></summary>
+
+Run multiple RPC instances in parallel. Pass `{ rpcPrefix: "v1:rpc" }` to `createServerFunction` to register a function under a custom prefix — versioned APIs, namespaced endpoints, and API segregation without function-name collisions. The same name can coexist under different prefixes (`v1:rpc/login` + `v2:rpc/login`), middleware dispatches to the prefix-scoped map, and the plugin generates client stubs per prefix. Functions default to `"__rpc"` for full backward compatibility. See the [Multi-Prefix Guide](./wiki/multi-prefix-guide.md).
+</details>
+
+<details>
+<summary><b>Universal middleware</b></summary>
+
+Write **one** middleware function that runs unchanged on every adapter (Express, Fastify, Hono, Koa, h3). Because every dispatch runs inside a per-request context, middleware written against `getRequestContext()` — reading normalized request data via `getRequestMeta()`, short-circuiting with `sendResponse(status, body, headers)` — behaves identically regardless of the host framework. No per-framework rewrites for cross-cutting RPC rules like per-function rate limiting, audit logging, or feature flags. See the [Middleware Guide](./wiki/middleware.md).
+</details>
+
 ## Examples
 
 | Source                                                                                 | Demo                                                                                         | Clone                                                   |
@@ -112,6 +124,7 @@ Generic type inference flows from your server function's arguments and return ty
 | [examples/koa](https://github.com/thednp/rpc/tree/master/examples/koa)                 | [StackBlitz](https://stackblitz.com/fork/github/thednp/rpc/tree/master/examples/koa)         | `pnpm dlx degit thednp/rpc/examples/koa my-app`         |
 | [examples/react-query](https://github.com/thednp/rpc/tree/master/examples/react-query) | [StackBlitz](https://stackblitz.com/fork/github/thednp/rpc/tree/master/examples/react-query) | `pnpm dlx degit thednp/rpc/examples/react-query my-app` |
 | [examples/solid-query](https://github.com/thednp/rpc/tree/master/examples/solid-query) | [StackBlitz](https://stackblitz.com/fork/github/thednp/rpc/tree/master/examples/solid-query) | `pnpm dlx degit thednp/rpc/examples/solid-query my-app` |
+| [examples/advanced](https://github.com/thednp/rpc/tree/master/examples/advanced)       | [StackBlitz](https://stackblitz.com/fork/github/thednp/rpc/tree/master/examples/advanced)    | `pnpm dlx degit thednp/rpc/examples/advanced my-app`    |
 
 > **Clone an example**: `degit` scaffolds a fresh copy straight from the repo — no git history, ready to run:
 
@@ -156,7 +169,7 @@ npm i @thednp/rpc
 Create `rpc.config.ts` at your project root:
 
 ```ts
-import { defineConfig } from "@thednp/rpc";
+import { defineConfig } from "@thednp/rpc/config";
 
 export default defineConfig({
   adapter: "express",
@@ -244,9 +257,9 @@ See the [Adapters guide](./wiki/adapters.md) for full snippets for each framewor
 ### Unit Testing
 
 ```bash
-pnpm test         # Run tests with coverage
-pnpm test-ui      # Run tests with UI
-pnpm test --run   # Single run
+pnpm test         # Run tests once with coverage (vitest run --coverage)
+pnpm test:watch   # Run tests in watch mode with coverage
+pnpm test:ui      # Run tests with UI
 ```
 
 Tests use **Vitest** with **Istanbul** coverage — 10 test files covering the plugin, scanning, server/client helpers, request context, and all five adapters, at 100% coverage.
@@ -254,8 +267,8 @@ Tests use **Vitest** with **Istanbul** coverage — 10 test files covering the p
 ### Live Testing
 
 ```bash
-pnpm test-dev     # Runs all examples/<example> in DEV mode and reports their status in a table
-pnpm test-prod    # Runs all examples/<example> in PRODUCTION mode and reports their status in a table
+pnpm test:dev     # Runs all examples/<example> in DEV mode and reports their status in a table
+pnpm test:prod    # Runs all examples/<example> in PRODUCTION mode and reports their status in a table
 ```
 
 These tests check the following:
@@ -277,10 +290,10 @@ Contributions are welcome. This project uses:
 
 ```bash
 pnpm lint         # deno lint + tsc -noEmit
-pnpm format       # deno fmt src
-pnpm test         # Run tests with coverage
-pnpm test-ui      # Run tests with interactive UI 
-pnpm build        # Bundle with tsdown
+pnpm format       # deno fmt src tests examples/**/src
+pnpm test         # Run tests once with coverage (vitest run --coverage)
+pnpm test:ui      # Run tests with UI
+pnpm build        # Bundle with tsdown (tsdown)
 ```
 
 All changes should pass `pnpm lint && pnpm format && pnpm test` before submitting. See [AGENTS.md](./AGENTS.md) for the full command reference and project conventions.

package/dist/config/config.d.mts

@@ -0,0 +1,65 @@
+import "vite";
+import "@thednp/rpc";
+import "express";
+import "hono";
+import "@hono/node-server";
+import "hono/utils/http-status";
+import "hono/factory";
+import "fastify";
+import "fastify-plugin";
+import "koa";
+import "h3";
+//#region src/types.d.ts
+/**
+ * ### @thednp/rpc
+ * The plugin configuration allows for granular control of your
+ * application RPC calls. The default settings are optimized for development
+ * environments while providing a secure foundation for production use.
+ */
+interface RpcPluginOptions {
+  // RPC Middleware Options
+  /**
+   * RPC prefix without leading slash (e.g. "__rpc")
+   * Leading slash will be added automatically by the middleware.
+   * This prefix defines the base path for all RPC endpoints.
+   * @default "__rpc"
+   * @example
+   * // Results in endpoints like: /api/rpc/myFunction
+   * rpcPrefix: "api/rpc"
+   */
+  rpcPrefix: "__rpc" | string;
+  /**
+   * Option to set an adapter for the middleware connection. The default is _express_,
+   * which is the most popular and battle tested server app. The _express_ adapter is
+   * also compatible with the vite's Connect development server.
+   * @default express
+   */
+  adapter: "express" | "hono" | "h3" | "fastify" | "koa";
+  /**
+   * Root directory from which the plugin scans for server files.
+   * Defaults to `<root>/src/api`. Use this in monorepos where server files
+   * live in a shared package outside the current project root.
+   * @default undefined (resolves to src/api relative to the Vite root)
+   */
+  scanRoot?: string;
+  /**
+   * Server file matching mode. Use `"exact"` (default) for the classic
+   * `server.ts|js|mjs|mts` names, or `"glob"` to match `**\/*.server.{ts,js,mjs,mts}`
+   * inside the scan root.
+   * @default "exact"
+   */
+  serverFiles?: "exact" | "glob";
+}
+//#endregion
+//#region src/config.d.ts
+/**
+ * Type-safe helper to create an RPC configuration object.
+ * Merges the provided partial config over the built-in defaults,
+ * skipping explicitly `undefined` values.
+ * @param uniConfig - System-wide RPC configuration overrides
+ * @returns Complete RPC plugin options with defaults applied
+ */
+declare const defineConfig: (c: Partial<RpcPluginOptions>) => RpcPluginOptions;
+//#endregion
+export { defineConfig };
+//# sourceMappingURL=config.d.mts.map

package/dist/config/config.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.mts","names":[],"sources":["../../src/types.d.ts","../../src/config.ts"],"mappings":";;;;;;;;;;;;;;;;;;UAsPiB;;;;;;;;;;;EAWf;;;;;;;EAQA;;;;;;;EAQA;;;;;;;EAQA;;;;;;;;;;;cCvQW,eACX,GAAG,QAAQ,sBACR"}

package/dist/config/config.mjs

@@ -0,0 +1,24 @@
+const defaultRPCOptions = {
+	rpcPrefix: "__rpc",
+	adapter: "express",
+	serverFiles: "exact",
+	scanRoot: void 0
+};
+//#endregion
+//#region src/config.ts
+/**
+* Type-safe helper to create an RPC configuration object.
+* Merges the provided partial config over the built-in defaults,
+* skipping explicitly `undefined` values.
+* @param uniConfig - System-wide RPC configuration overrides
+* @returns Complete RPC plugin options with defaults applied
+*/
+const defineConfig = (uniConfig) => {
+	const merged = { ...defaultRPCOptions };
+	for (const [key, value] of Object.entries(uniConfig)) if (value !== void 0) merged[key] = value;
+	return merged;
+};
+//#endregion
+export { defineConfig };
+
+//# sourceMappingURL=config.mjs.map

package/dist/config/config.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.mjs","names":[],"sources":["../../src/options.ts","../../src/config.ts"],"sourcesContent":["import type {\n  MiddlewareOptions,\n  RpcPluginOptions,\n  ServerFunctionOptions,\n} from \"./types.d.ts\";\n\nexport const defaultServerFnOptions: ServerFunctionOptions = {\n  contentType: \"application/json\",\n  credentials: \"same-origin\",\n  method: \"POST\",\n};\n\nexport const defaultPrefix = \"__rpc\";\n\nexport const defaultRPCOptions: RpcPluginOptions = {\n  rpcPrefix: defaultPrefix,\n  adapter: \"express\",\n  serverFiles: \"exact\",\n  scanRoot: undefined,\n};\n\nexport const defaultMiddlewareOptions: MiddlewareOptions = {\n  rpcPrefix: undefined,\n  path: undefined,\n  origin: undefined,\n};\n","/**\n * Vite-free configuration helpers.\n *\n * This module intentionally has zero runtime dependencies (not even on `vite`),\n * so `rpc.config.ts` files that import it stay safe to load in serverless\n * bundles where Vite is not installed. Importing the main plugin entry\n * (`@thednp/rpc`) instead would drag Vite into every server-side consumer.\n */\nimport type { RpcPluginOptions } from \"./types.d.ts\";\nimport { defaultRPCOptions } from \"./options.ts\";\n\n/**\n * Type-safe helper to create an RPC configuration object.\n * Merges the provided partial config over the built-in defaults,\n * skipping explicitly `undefined` values.\n * @param uniConfig - System-wide RPC configuration overrides\n * @returns Complete RPC plugin options with defaults applied\n */\nexport const defineConfig: (\n  c: Partial<RpcPluginOptions>,\n) => RpcPluginOptions = (uniConfig: Partial<RpcPluginOptions>) => {\n  const merged: RpcPluginOptions & Record<string, string> = {\n    ...defaultRPCOptions,\n  };\n  for (const [key, value] of Object.entries(uniConfig)) {\n    // istanbul ignore else\n    if (value !== undefined) {\n      merged[key] = value;\n    }\n  }\n  return merged;\n};\n"],"mappings":"AAcA,MAAa,oBAAsC;CACjD,WAAW;CACX,SAAS;CACT,aAAa;CACb,UAAU,KAAA;AACZ;;;;;;;;;;ACDA,MAAa,gBAEY,cAAyC;CAChE,MAAM,SAAoD,EACxD,GAAG,kBACL;CACA,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,SAAS,GAEjD,IAAI,UAAU,KAAA,GACZ,OAAO,OAAO;CAGlB,OAAO;AACT"}

package/dist/express/express.d.mts

@@ -67,9 +67,11 @@ type RequestDetails = {
 declare const createMiddleware: ExpressMiddlewareFn;
 /**
  * Creates the Express RPC middleware that routes incoming requests to registered server functions.
- * Reads the request body, dispatches to the matching function via serverFunctionsMap,
+ * Reads the request body, dispatches to the matching function via getFunctionsForPrefix,
  * and sends the JSON-serialized result. Handles client disconnection via abort signals.
- * @param initialOptions - Options including rpcPrefix for URL routing
+ * Supports multi-prefix setups where different middleware instances can route to functions
+ * registered under different prefixes.
+ * @param initialOptions - Options including rpcPrefix for URL routing and prefix-scoped function lookup
  * @returns An Express middleware function
  */
 declare const createRPCMiddleware: ExpressMiddlewareFn;

package/dist/express/express.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"express.d.mts","names":[],"sources":["../../src/express/types.d.ts","../../src/express/createMiddleware.ts","../../src/express/helpers.ts"],"mappings":";;;;;;;;KAgBY,2BAA2B;;;;;KAM3B,uBACV,UAAU,yCAEV,iBAAiB,QAAQ,8BACtB;;;;UAKY;;;;;;;EAOf,UACE,KAAK,kBAAkB,SACvB,KAAK,iBAAiB,UACtB,MAAM,QAAQ,eAAe,iBAC1B;;;;;;KAOK;;EAEV;;EAEA,YAAY,cAAc;;EAE1B;;EAEA,gBAAgB;;EAEhB,eAAe,cAAc,QAAQ;;;;;KAM3B;;EAEV;;EAEA;;EAEA,cAAc;;EAEd,SAAS;;EAET;;;;;;;;;;;cC1BW,kBAAkB;;;;;;;;cAyElB,qBAAqB;;;;;;;;iBCvGZ,UAAU,KAAK,UAAO;;;;;;iBAc5B,WAAW,KAAK,SAAS,MAAM;;;;;;;;cAWlC,WAAQ,KACd,UAAiB,oBACrB,QAAQ;;;;;;cAqFE,mBAAgB,KACtB,kBAAkB,YACtB,OAAO;;;;;;cASG,oBAAiB,KACvB,iBAAiB,aACrB,OAAO;;;;;;;;;;;;cAeG,WAAQ,KACd,iBAAiB,UAAe,kBACrB;;;;;;;cAkBL,mBAAgB,KACtB,kBAAkB,YACtB,OAAO;;;;;;;cAUG,oBAAiB,SACnB,UAAiB,oBACzB;;;;;;;cAqBU,qBAAkB,UACnB,WAAkB,mBAC3B"}
+{"version":3,"file":"express.d.mts","names":[],"sources":["../../src/express/types.d.ts","../../src/express/createMiddleware.ts","../../src/express/helpers.ts"],"mappings":";;;;;;;;KAgBY,2BAA2B;;;;;KAM3B,uBACV,UAAU,yCAEV,iBAAiB,QAAQ,8BACtB;;;;UAKY;;;;;;;EAOf,UACE,KAAK,kBAAkB,SACvB,KAAK,iBAAiB,UACtB,MAAM,QAAQ,eAAe,iBAC1B;;;;;;KAOK;;EAEV;;EAEA,YAAY,cAAc;;EAE1B;;EAEA,gBAAgB;;EAEhB,eAAe,cAAc,QAAQ;;;;;KAM3B;;EAEV;;EAEA;;EAEA,cAAc;;EAEd,SAAS;;EAET;;;;;;;;;;;cCrBW,kBAAkB;;;;;;;;;;cAiFlB,qBAAqB;;;;;;;;iBCpHZ,UAAU,KAAK,UAAO;;;;;;iBAc5B,WAAW,KAAK,SAAS,MAAM;;;;;;;;cAWlC,WAAQ,KACd,UAAiB,oBACrB,QAAQ;;;;;;cAqFE,mBAAgB,KACtB,kBAAkB,YACtB,OAAO;;;;;;cASG,oBAAiB,KACvB,iBAAiB,aACrB,OAAO;;;;;;;;;;;;cAeG,WAAQ,KACd,iBAAiB,UAAe,kBACrB;;;;;;;cAkBL,mBAAgB,KACtB,kBAAkB,YACtB,OAAO;;;;;;;cAUG,oBAAiB,SACnB,UAAiB,oBACzB;;;;;;;cAqBU,qBAAkB,UACnB,WAAkB,mBAC3B"}

package/dist/express/express.mjs

@@ -1,5 +1,4 @@
-import { escapeRegExp, formatError, hasContentTypeMismatch, provideRequestContext, scanForServerFiles, serverFunctionsMap } from "@thednp/rpc/server";
-//#region src/options.ts
+import { escapeRegExp, formatError, getGlobalPrefix, hasContentTypeMismatch, provideRequestContext, scanForServerFiles } from "@thednp/rpc/server";
 const defaultRPCOptions = {
 	rpcPrefix: "__rpc",
 	adapter: "express",
@@ -12,6 +11,32 @@ const defaultMiddlewareOptions = {
 	origin: void 0
 };
 //#endregion
+//#region src/functionsMap.ts
+/**
+* Global symbol under which the shared `serverFunctionsByPrefix` map is stored
+* on `globalThis`. Keeping it on a `Symbol.for` key makes it instance-stable
+* across the bundled entry copies (`index.mjs`, `server.mjs`, `express.mjs`,
+* ...) and dev-server hot reloads, exactly like the request-context storage in
+* `context.ts`. Without this, `scanForServerFiles` (bundled into the plugin)
+* would populate a map copy the adapter middleware could not read.
+*/
+const functionsMapSymbol = Symbol.for("thednp.rpc.functionsMap");
+/**
+* Map of rpcPrefix -> Map of function names -> ServerFnEntry
+* Enables multiple RPC instances with different prefixes to coexist
+* without name collisions.
+*/
+const serverFunctionsByPrefix = globalThis[functionsMapSymbol] ??= /* @__PURE__ */ new Map();
+/**
+* Gets or creates the function map for a specific prefix.
+* @param prefix - The RPC prefix (e.g., "__rpc", "v1:rpc", "admin:rpc")
+* @returns Map of function names to ServerFnEntry for that prefix
+*/
+const getFunctionsForPrefix = (prefix) => {
+	if (!serverFunctionsByPrefix.has(prefix)) serverFunctionsByPrefix.set(prefix, /* @__PURE__ */ new Map());
+	return serverFunctionsByPrefix.get(prefix);
+};
+//#endregion
 //#region src/constants.ts
 const FUNCTION_NOT_FOUND = "Function not found";
 const METHOD_NOT_ALLOWED = "Method Not Allowed";
@@ -226,7 +251,7 @@ const middlewareStack = /* @__PURE__ */ new Set();
 const createMiddleware = (initialOptions = {}) => {
 	const options = Object.assign({}, defaultMiddlewareOptions, initialOptions);
 	const middlewareName = options.name;
-	const rpcPrefix = options.rpcPrefix;
+	let rpcPrefix = options.rpcPrefix;
 	const path = options.path;
 	const handler = options.handler;
 	let name = middlewareName;
@@ -240,10 +265,15 @@ const createMiddleware = (initialOptions = {}) => {
 	const pathMatcher = path ? typeof path === "string" ? new RegExp(path) : path : null;
 	const middlewareHandler = async (req, res, next) => {
 		const { url } = getRequestDetails(req);
-		if (serverFunctionsMap.size === 0) await scanForServerFiles();
 		if (!handler) return next?.();
 		if (pathMatcher && !pathMatcher.test(url)) return next?.();
 		if (prefixRegex && !prefixRegex.test(url)) return next?.();
+		rpcPrefix = rpcPrefix ?? "__rpc";
+		if (getFunctionsForPrefix(rpcPrefix).size === 0) await scanForServerFiles({
+			rpcPrefix,
+			serverFiles: options.serverFiles,
+			scanRoot: options.scanRoot
+		});
 		await handler(req, res, next);
 	};
 	Object.defineProperty(middlewareHandler, "name", { value: name });
@@ -251,16 +281,19 @@ const createMiddleware = (initialOptions = {}) => {
 };
 /**
 * Creates the Express RPC middleware that routes incoming requests to registered server functions.
-* Reads the request body, dispatches to the matching function via serverFunctionsMap,
+* Reads the request body, dispatches to the matching function via getFunctionsForPrefix,
 * and sends the JSON-serialized result. Handles client disconnection via abort signals.
-* @param initialOptions - Options including rpcPrefix for URL routing
+* Supports multi-prefix setups where different middleware instances can route to functions
+* registered under different prefixes.
+* @param initialOptions - Options including rpcPrefix for URL routing and prefix-scoped function lookup
 * @returns An Express middleware function
 */
 const createRPCMiddleware = (initialOptions = {}) => {
 	const options = Object.assign({}, defaultMiddlewareOptions, { rpcPrefix: defaultRPCOptions.rpcPrefix }, initialOptions);
 	const rpcPrefix = options.rpcPrefix;
+	const prefix = rpcPrefix || getGlobalPrefix() || "__rpc";
 	const prefixRegex = rpcPrefix ? new RegExp(`^/${escapeRegExp(rpcPrefix)}/`) : null;
-	const prefixReplace = `/${rpcPrefix}/`;
+	const prefixReplace = `/${prefix}/`;
 	return createMiddleware({
 		...options,
 		handler: async (req, res, _next) => {
@@ -274,7 +307,7 @@ const createRPCMiddleware = (initialOptions = {}) => {
 				return;
 			}
 			const functionName = path.replace(prefixReplace, "");
-			const serverFunction = serverFunctionsMap.get(functionName);
+			const serverFunction = getFunctionsForPrefix(prefix).get(functionName);
 			if (!serverFunction) {
 				sendResponse(404, { error: FUNCTION_NOT_FOUND });
 				return;