@spoosh/plugin-nextjs 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Spoosh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# @spoosh/plugin-nextjs
+
+Next.js integration plugin for Spoosh - server-side cache revalidation after mutations.
+
+**[Documentation](https://spoosh.dev/docs/plugins/nextjs)** · **Requirements:** TypeScript >= 5.0, Next.js supporting server actions · **Peer Dependencies:** `@spoosh/core`, `@spoosh/plugin-invalidation`
+
+## Installation
+
+```bash
+npm install @spoosh/plugin-nextjs
+```
+
+## Usage
+
+### Create server action
+
+```typescript
+"use server";
+
+import { revalidateTag, revalidatePath } from "next/cache";
+
+export async function revalidateAction(tags: string[], paths: string[]) {
+  tags.forEach((tag) => revalidateTag(tag));
+  paths.forEach((path) => revalidatePath(path));
+}
+```
+
+```typescript
+import { nextjsPlugin } from "@spoosh/plugin-nextjs";
+import { invalidationPlugin } from "@spoosh/plugin-invalidation";
+
+const plugins = [
+  invalidationPlugin(),
+  nextjsPlugin({ serverRevalidator: revalidateAction }),
+];
+
+// After a successful mutation, cache tags are automatically revalidated
+const { trigger } = useWrite((api) => api.posts.$post);
+
+await trigger({ body: { title: "New Post" } });
+// Revalidates: ["posts"] tag on the server
+```
+
+### Revalidate Additional Paths
+
+```typescript
+const { trigger } = useWrite((api) => api.posts.$post);
+
+await trigger({
+  body: { title: "New Post" },
+  revalidatePaths: ["/", "/posts"],
+});
+```
+
+### Skip Revalidation
+
+```typescript
+// Skip for a specific mutation
+await trigger({
+  body: { title: "Draft" },
+  serverRevalidate: false,
+});
+```
+
+## When to Use `skipServerRevalidation`
+
+### Client-Heavy Apps (CSR/SPA)
+
+For apps that primarily fetch data on the client side, set `skipServerRevalidation: true` by default and opt-in for specific mutations that affect server-rendered content:
+
+```typescript
+const plugins = [
+  nextjsPlugin({
+    serverRevalidator: revalidate,
+    skipServerRevalidation: true, // Skip by default
+  }),
+];
+
+// Most mutations don't need server revalidation
+await trigger({ body: data });
+
+// Opt-in when mutation affects server-rendered pages
+await trigger({
+  body: data,
+  serverRevalidate: true, // Explicitly enable
+});
+```
+
+### Server-Heavy Apps (SSR/RSC)
+
+For apps that rely heavily on server-side rendering or React Server Components, keep the default behavior (revalidate on every mutation) and opt-out when needed:
+
+```typescript
+const plugins = [
+  nextjsPlugin({
+    serverRevalidator: revalidate,
+    // skipServerRevalidation: false (default)
+  }),
+];
+
+// Server cache is revalidated by default
+await trigger({ body: data });
+
+// Skip for mutations that don't affect server content
+await trigger({
+  body: { theme: "dark" },
+  serverRevalidate: false, // Skip for client-only state
+});
+```
+
+## Options
+
+### Plugin Config
+
+| Option                   | Type                               | Default | Description                       |
+| ------------------------ | ---------------------------------- | ------- | --------------------------------- |
+| `serverRevalidator`      | `(tags, paths) => void \| Promise` | -       | Server action to revalidate cache |
+| `skipServerRevalidation` | `boolean`                          | `false` | Skip revalidation by default      |
+
+### Per-Request Options
+
+| Option             | Type       | Description                                     |
+| ------------------ | ---------- | ----------------------------------------------- |
+| `revalidatePaths`  | `string[]` | Additional paths to revalidate                  |
+| `serverRevalidate` | `boolean`  | Override whether to trigger server revalidation |

package/dist/index.d.mts

@@ -0,0 +1,56 @@
+import { SpooshPlugin } from '@spoosh/core';
+
+type ServerRevalidateHandler = (tags: string[], paths: string[]) => void | Promise<void>;
+interface NextjsPluginConfig {
+    /** Server action to revalidate tags and paths */
+    serverRevalidator?: ServerRevalidateHandler;
+    /** Skip server revalidation by default. Default: false */
+    skipServerRevalidation?: boolean;
+}
+type NextjsReadOptions = object;
+interface NextjsWriteOptions {
+    /** Additional paths to revalidate after mutation */
+    revalidatePaths?: string[];
+    /** Whether to trigger server revalidation. Overrides plugin default. */
+    serverRevalidate?: boolean;
+}
+type NextjsInfiniteReadOptions = object;
+type NextjsReadResult = object;
+type NextjsWriteResult = object;
+
+/**
+ * Next.js integration plugin for server-side revalidation.
+ *
+ * Automatically revalidates Next.js cache tags and paths after successful mutations.
+ *
+ * @param config - Plugin configuration
+ *
+ * @see {@link https://spoosh.dev/docs/plugins/nextjs | Next.js Plugin Documentation}
+ *
+ * @returns Next.js plugin instance
+ *
+ * @example
+ * ```ts
+ * import { nextjsPlugin } from "@spoosh/plugin-nextjs";
+ *
+ * const plugins = [
+ *   nextjsPlugin({
+ *     serverRevalidator: async (tags, paths) => {
+ *       "use server";
+ *       const { revalidateTag, revalidatePath } = await import("next/cache");
+ *       tags.forEach((tag) => revalidateTag(tag));
+ *       paths.forEach((path) => revalidatePath(path));
+ *     },
+ *   }),
+ * ];
+ * ```
+ */
+declare function nextjsPlugin(config?: NextjsPluginConfig): SpooshPlugin<{
+    readOptions: NextjsReadOptions;
+    writeOptions: NextjsWriteOptions;
+    infiniteReadOptions: NextjsInfiniteReadOptions;
+    readResult: NextjsReadResult;
+    writeResult: NextjsWriteResult;
+}>;
+
+export { type NextjsInfiniteReadOptions, type NextjsPluginConfig, type NextjsReadOptions, type NextjsReadResult, type NextjsWriteOptions, type NextjsWriteResult, type ServerRevalidateHandler, nextjsPlugin };

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+import { SpooshPlugin } from '@spoosh/core';
+
+type ServerRevalidateHandler = (tags: string[], paths: string[]) => void | Promise<void>;
+interface NextjsPluginConfig {
+    /** Server action to revalidate tags and paths */
+    serverRevalidator?: ServerRevalidateHandler;
+    /** Skip server revalidation by default. Default: false */
+    skipServerRevalidation?: boolean;
+}
+type NextjsReadOptions = object;
+interface NextjsWriteOptions {
+    /** Additional paths to revalidate after mutation */
+    revalidatePaths?: string[];
+    /** Whether to trigger server revalidation. Overrides plugin default. */
+    serverRevalidate?: boolean;
+}
+type NextjsInfiniteReadOptions = object;
+type NextjsReadResult = object;
+type NextjsWriteResult = object;
+
+/**
+ * Next.js integration plugin for server-side revalidation.
+ *
+ * Automatically revalidates Next.js cache tags and paths after successful mutations.
+ *
+ * @param config - Plugin configuration
+ *
+ * @see {@link https://spoosh.dev/docs/plugins/nextjs | Next.js Plugin Documentation}
+ *
+ * @returns Next.js plugin instance
+ *
+ * @example
+ * ```ts
+ * import { nextjsPlugin } from "@spoosh/plugin-nextjs";
+ *
+ * const plugins = [
+ *   nextjsPlugin({
+ *     serverRevalidator: async (tags, paths) => {
+ *       "use server";
+ *       const { revalidateTag, revalidatePath } = await import("next/cache");
+ *       tags.forEach((tag) => revalidateTag(tag));
+ *       paths.forEach((path) => revalidatePath(path));
+ *     },
+ *   }),
+ * ];
+ * ```
+ */
+declare function nextjsPlugin(config?: NextjsPluginConfig): SpooshPlugin<{
+    readOptions: NextjsReadOptions;
+    writeOptions: NextjsWriteOptions;
+    infiniteReadOptions: NextjsInfiniteReadOptions;
+    readResult: NextjsReadResult;
+    writeResult: NextjsWriteResult;
+}>;
+
+export { type NextjsInfiniteReadOptions, type NextjsPluginConfig, type NextjsReadOptions, type NextjsReadResult, type NextjsWriteOptions, type NextjsWriteResult, type ServerRevalidateHandler, nextjsPlugin };

package/dist/index.js

@@ -0,0 +1,55 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  nextjsPlugin: () => nextjsPlugin
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/plugin.ts
+function nextjsPlugin(config = {}) {
+  const { serverRevalidator, skipServerRevalidation = false } = config;
+  return {
+    name: "spoosh:nextjs",
+    operations: ["write"],
+    middleware: async (context, next) => {
+      const response = await next();
+      if (response.error || !serverRevalidator) {
+        return response;
+      }
+      const pluginOptions = context.pluginOptions;
+      const shouldRevalidate = pluginOptions?.serverRevalidate ?? !skipServerRevalidation;
+      if (!shouldRevalidate) {
+        return response;
+      }
+      const revalidatePaths = pluginOptions?.revalidatePaths ?? [];
+      if (context.tags.length > 0 || revalidatePaths.length > 0) {
+        await serverRevalidator(context.tags, revalidatePaths);
+      }
+      return response;
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  nextjsPlugin
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/plugin.ts"],"sourcesContent":["export * from \"./types\";\nexport * from \"./plugin\";\n","import type { SpooshPlugin } from \"@spoosh/core\";\nimport type {\n  NextjsPluginConfig,\n  NextjsReadOptions,\n  NextjsWriteOptions,\n  NextjsInfiniteReadOptions,\n  NextjsReadResult,\n  NextjsWriteResult,\n} from \"./types\";\n\n/**\n * Next.js integration plugin for server-side revalidation.\n *\n * Automatically revalidates Next.js cache tags and paths after successful mutations.\n *\n * @param config - Plugin configuration\n *\n * @see {@link https://spoosh.dev/docs/plugins/nextjs | Next.js Plugin Documentation}\n *\n * @returns Next.js plugin instance\n *\n * @example\n * ```ts\n * import { nextjsPlugin } from \"@spoosh/plugin-nextjs\";\n *\n * const plugins = [\n *   nextjsPlugin({\n *     serverRevalidator: async (tags, paths) => {\n *       \"use server\";\n *       const { revalidateTag, revalidatePath } = await import(\"next/cache\");\n *       tags.forEach((tag) => revalidateTag(tag));\n *       paths.forEach((path) => revalidatePath(path));\n *     },\n *   }),\n * ];\n * ```\n */\nexport function nextjsPlugin(config: NextjsPluginConfig = {}): SpooshPlugin<{\n  readOptions: NextjsReadOptions;\n  writeOptions: NextjsWriteOptions;\n  infiniteReadOptions: NextjsInfiniteReadOptions;\n  readResult: NextjsReadResult;\n  writeResult: NextjsWriteResult;\n}> {\n  const { serverRevalidator, skipServerRevalidation = false } = config;\n\n  return {\n    name: \"spoosh:nextjs\",\n    operations: [\"write\"],\n\n    middleware: async (context, next) => {\n      const response = await next();\n\n      if (response.error || !serverRevalidator) {\n        return response;\n      }\n\n      const pluginOptions = context.pluginOptions as\n        | NextjsWriteOptions\n        | undefined;\n\n      const shouldRevalidate =\n        pluginOptions?.serverRevalidate ?? !skipServerRevalidation;\n\n      if (!shouldRevalidate) {\n        return response;\n      }\n\n      const revalidatePaths = pluginOptions?.revalidatePaths ?? [];\n\n      if (context.tags.length > 0 || revalidatePaths.length > 0) {\n        await serverRevalidator(context.tags, revalidatePaths);\n      }\n\n      return response;\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACqCO,SAAS,aAAa,SAA6B,CAAC,GAMxD;AACD,QAAM,EAAE,mBAAmB,yBAAyB,MAAM,IAAI;AAE9D,SAAO;AAAA,IACL,MAAM;AAAA,IACN,YAAY,CAAC,OAAO;AAAA,IAEpB,YAAY,OAAO,SAAS,SAAS;AACnC,YAAM,WAAW,MAAM,KAAK;AAE5B,UAAI,SAAS,SAAS,CAAC,mBAAmB;AACxC,eAAO;AAAA,MACT;AAEA,YAAM,gBAAgB,QAAQ;AAI9B,YAAM,mBACJ,eAAe,oBAAoB,CAAC;AAEtC,UAAI,CAAC,kBAAkB;AACrB,eAAO;AAAA,MACT;AAEA,YAAM,kBAAkB,eAAe,mBAAmB,CAAC;AAE3D,UAAI,QAAQ,KAAK,SAAS,KAAK,gBAAgB,SAAS,GAAG;AACzD,cAAM,kBAAkB,QAAQ,MAAM,eAAe;AAAA,MACvD;AAEA,aAAO;AAAA,IACT;AAAA,EACF;AACF;","names":[]}

package/dist/index.mjs

@@ -0,0 +1,28 @@
+// src/plugin.ts
+function nextjsPlugin(config = {}) {
+  const { serverRevalidator, skipServerRevalidation = false } = config;
+  return {
+    name: "spoosh:nextjs",
+    operations: ["write"],
+    middleware: async (context, next) => {
+      const response = await next();
+      if (response.error || !serverRevalidator) {
+        return response;
+      }
+      const pluginOptions = context.pluginOptions;
+      const shouldRevalidate = pluginOptions?.serverRevalidate ?? !skipServerRevalidation;
+      if (!shouldRevalidate) {
+        return response;
+      }
+      const revalidatePaths = pluginOptions?.revalidatePaths ?? [];
+      if (context.tags.length > 0 || revalidatePaths.length > 0) {
+        await serverRevalidator(context.tags, revalidatePaths);
+      }
+      return response;
+    }
+  };
+}
+export {
+  nextjsPlugin
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/plugin.ts"],"sourcesContent":["import type { SpooshPlugin } from \"@spoosh/core\";\nimport type {\n  NextjsPluginConfig,\n  NextjsReadOptions,\n  NextjsWriteOptions,\n  NextjsInfiniteReadOptions,\n  NextjsReadResult,\n  NextjsWriteResult,\n} from \"./types\";\n\n/**\n * Next.js integration plugin for server-side revalidation.\n *\n * Automatically revalidates Next.js cache tags and paths after successful mutations.\n *\n * @param config - Plugin configuration\n *\n * @see {@link https://spoosh.dev/docs/plugins/nextjs | Next.js Plugin Documentation}\n *\n * @returns Next.js plugin instance\n *\n * @example\n * ```ts\n * import { nextjsPlugin } from \"@spoosh/plugin-nextjs\";\n *\n * const plugins = [\n *   nextjsPlugin({\n *     serverRevalidator: async (tags, paths) => {\n *       \"use server\";\n *       const { revalidateTag, revalidatePath } = await import(\"next/cache\");\n *       tags.forEach((tag) => revalidateTag(tag));\n *       paths.forEach((path) => revalidatePath(path));\n *     },\n *   }),\n * ];\n * ```\n */\nexport function nextjsPlugin(config: NextjsPluginConfig = {}): SpooshPlugin<{\n  readOptions: NextjsReadOptions;\n  writeOptions: NextjsWriteOptions;\n  infiniteReadOptions: NextjsInfiniteReadOptions;\n  readResult: NextjsReadResult;\n  writeResult: NextjsWriteResult;\n}> {\n  const { serverRevalidator, skipServerRevalidation = false } = config;\n\n  return {\n    name: \"spoosh:nextjs\",\n    operations: [\"write\"],\n\n    middleware: async (context, next) => {\n      const response = await next();\n\n      if (response.error || !serverRevalidator) {\n        return response;\n      }\n\n      const pluginOptions = context.pluginOptions as\n        | NextjsWriteOptions\n        | undefined;\n\n      const shouldRevalidate =\n        pluginOptions?.serverRevalidate ?? !skipServerRevalidation;\n\n      if (!shouldRevalidate) {\n        return response;\n      }\n\n      const revalidatePaths = pluginOptions?.revalidatePaths ?? [];\n\n      if (context.tags.length > 0 || revalidatePaths.length > 0) {\n        await serverRevalidator(context.tags, revalidatePaths);\n      }\n\n      return response;\n    },\n  };\n}\n"],"mappings":";AAqCO,SAAS,aAAa,SAA6B,CAAC,GAMxD;AACD,QAAM,EAAE,mBAAmB,yBAAyB,MAAM,IAAI;AAE9D,SAAO;AAAA,IACL,MAAM;AAAA,IACN,YAAY,CAAC,OAAO;AAAA,IAEpB,YAAY,OAAO,SAAS,SAAS;AACnC,YAAM,WAAW,MAAM,KAAK;AAE5B,UAAI,SAAS,SAAS,CAAC,mBAAmB;AACxC,eAAO;AAAA,MACT;AAEA,YAAM,gBAAgB,QAAQ;AAI9B,YAAM,mBACJ,eAAe,oBAAoB,CAAC;AAEtC,UAAI,CAAC,kBAAkB;AACrB,eAAO;AAAA,MACT;AAEA,YAAM,kBAAkB,eAAe,mBAAmB,CAAC;AAE3D,UAAI,QAAQ,KAAK,SAAS,KAAK,gBAAgB,SAAS,GAAG;AACzD,cAAM,kBAAkB,QAAQ,MAAM,eAAe;AAAA,MACvD;AAEA,aAAO;AAAA,IACT;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@spoosh/plugin-nextjs",
+  "version": "0.1.0-beta.0",
+  "description": "Next.js integration plugin for Spoosh - server revalidation after mutations",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nxnom/spoosh.git",
+    "directory": "packages/plugin-nextjs"
+  },
+  "bugs": {
+    "url": "https://github.com/nxnom/spoosh/issues"
+  },
+  "homepage": "https://spoosh.dev/docs/plugins/nextjs",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "spoosh",
+    "plugin",
+    "nextjs",
+    "next.js",
+    "revalidation",
+    "api-client"
+  ],
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "@spoosh/core": ">=0.1.0",
+    "next": ">=13.0.0"
+  },
+  "devDependencies": {
+    "@spoosh/core": "0.1.0-beta.0"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --max-warnings 0",
+    "format": "prettier --write 'src/**/*.ts'"
+  }
+}