feat(action-client): export a copy of safe action client from /zod path (#115)

Sometimes, TypeSchema causes errors with its dynamic import system, to handle multiple validation libraries.
The code in this PR exports a copy of the safe action client from the `/zod` path, that support just Zod validation library, as the name implies. This should fix problems with the edge runtime and hopefully future bundler issues too.

Author: TheEdoRan

apps/playground/src/lib/safe-action.ts

@@ -1,4 +1,3 @@
-import { randomUUID } from "crypto";
 import {
 	DEFAULT_SERVER_ERROR_MESSAGE,
 	createSafeActionClient,
@@ -58,13 +57,13 @@ export const action = createSafeActionClient({
 });
 
 async function getSessionId() {
-	return randomUUID();
+	return crypto.randomUUID();
 }
 
 export const authAction = action
 	// In this case, context is used for (fake) auth purposes.
 	.use(async ({ next }) => {
-		const userId = randomUUID();
+		const userId = crypto.randomUUID();
 
 		console.log("HELLO FROM FIRST AUTH ACTION MIDDLEWARE, USER ID:", userId);
 

packages/next-safe-action/package.json

@@ -11,6 +11,7 @@
 	],
 	"exports": {
 		".": "./dist/index.mjs",
+		"./zod": "./dist/zod.mjs",
 		"./hooks": "./dist/hooks.mjs",
 		"./status": "./dist/status.mjs"
 	},
@@ -19,6 +20,9 @@
 			".": [
 				"./dist/index.d.mts"
 			],
+			"zod": [
+				"./dist/zod.d.mts"
+			],
 			"hooks": [
 				"./dist/hooks.d.mts"
 			],
@@ -65,7 +69,6 @@
 		"@types/node": "^20.12.10",
 		"@types/react": "^18.3.1",
 		"@typeschema/core": "^0.13.2",
-		"@typeschema/zod": "^0.13.3",
 		"eslint": "^8.57.0",
 		"eslint-config-prettier": "^9.1.0",
 		"eslint-define-config": "^2.1.0",
@@ -76,12 +79,21 @@
 		"semantic-release": "^23.0.8",
 		"tsup": "^8.0.2",
 		"typescript": "^5.4.5",
-		"typescript-eslint": "^7.8.0",
-		"zod": "^3.23.6"
+		"typescript-eslint": "^7.8.0"
 	},
 	"peerDependencies": {
 		"next": ">= 14.3.0-canary.42",
-		"react": ">= 18.3.1"
+		"react": ">= 18.3.1",
+		"@typeschema/zod": "^0.13.3",
+		"zod": "^3.23.6"
+	},
+	"peerDependenciesMeta": {
+		"zod": {
+			"optional": true
+		},
+		"@typeschema/zod": {
+			"optional": true
+		}
 	},
 	"repository": {
 		"type": "git",

packages/next-safe-action/src/action-builder.ts

@@ -1,5 +1,5 @@
-import type { Infer } from "@typeschema/main";
-import { validate, type Schema } from "@typeschema/main";
+import { validate, type Infer, type Schema } from "@typeschema/main";
+import { validate as zodValidate } from "@typeschema/zod";
 import { isNotFoundError } from "next/dist/client/components/not-found.js";
 import { isRedirectError } from "next/dist/client/components/redirect.js";
 import type {} from "zod";
@@ -41,6 +41,7 @@ export function actionBuilder<
 	handleReturnedServerError: NonNullable<SafeActionClientOpts<ServerError, any>["handleReturnedServerError"]>;
 	middlewareFns: MiddlewareFn<ServerError, any, any, MD>[];
 	ctxType: Ctx;
+	validationStrategy: "typeschema" | "zod";
 }) {
 	const bindArgsSchemas = (args.bindArgsSchemas ?? []) as BAS;
 
@@ -116,11 +117,15 @@ export function actionBuilder<
 											}
 
 											// Otherwise, parse input with the schema.
-											return validate(args.schema, input);
+											return args.validationStrategy === "zod"
+												? zodValidate(args.schema, input)
+												: validate(args.schema, input);
 										}
 
 										// Otherwise, we're processing bind args client inputs.
-										return validate(bindArgsSchemas[i]!, input);
+										return args.validationStrategy === "zod"
+											? zodValidate(bindArgsSchemas[i]!, input)
+											: validate(bindArgsSchemas[i]!, input);
 									})
 								);
 

packages/next-safe-action/src/index.ts

@@ -1,6 +1,21 @@
-export { createSafeActionClient } from "./safe-action-client";
+import type { Schema } from "@typeschema/main";
+import type { SafeActionClientOpts } from "./index.types";
+import { createClientWithStrategy } from "./safe-action-client";
+
 export { DEFAULT_SERVER_ERROR_MESSAGE, EMPTY_HOOK_RESULT as EMPTY_RESULT } from "./utils";
 export { flattenBindArgsValidationErrors, flattenValidationErrors, returnValidationErrors } from "./validation-errors";
 
 export type * from "./index.types";
 export type * from "./validation-errors.types";
+
+/**
+ * Create a new safe action client.
+ * @param createOpts Optional initialization options
+ *
+ * {@link https://next-safe-action.dev/docs/safe-action-client/initialization-options See docs for more information}
+ */
+export const createSafeActionClient = <ServerError = string, MetadataSchema extends Schema | undefined = undefined>(
+	createOpts?: SafeActionClientOpts<ServerError, MetadataSchema>
+) => {
+	return createClientWithStrategy("typeschema", createOpts);
+};

packages/next-safe-action/src/safe-action-client.ts

@@ -13,18 +13,21 @@ import type {
 class SafeActionClient<ServerError, Ctx = undefined, Metadata = undefined> {
 	readonly #handleServerErrorLog: NonNullable<SafeActionClientOpts<ServerError, any>["handleServerErrorLog"]>;
 	readonly #handleReturnedServerError: NonNullable<SafeActionClientOpts<ServerError, any>["handleReturnedServerError"]>;
+	readonly #validationStrategy: "typeschema" | "zod";
 
 	#middlewareFns: MiddlewareFn<ServerError, any, any, any>[];
 	#ctxType = undefined as Ctx;
 
 	constructor(
 		opts: {
 			middlewareFns: MiddlewareFn<ServerError, any, any, any>[];
+			validationStrategy: "typeschema" | "zod";
 		} & Required<Pick<SafeActionClientOpts<ServerError, any>, "handleReturnedServerError" | "handleServerErrorLog">>
 	) {
 		this.#middlewareFns = opts.middlewareFns;
 		this.#handleServerErrorLog = opts.handleServerErrorLog;
 		this.#handleReturnedServerError = opts.handleReturnedServerError;
+		this.#validationStrategy = opts.validationStrategy;
 	}
 
 	/**
@@ -38,6 +41,7 @@ class SafeActionClient<ServerError, Ctx = undefined, Metadata = undefined> {
 			middlewareFns: [...this.#middlewareFns, middlewareFn],
 			handleReturnedServerError: this.#handleReturnedServerError,
 			handleServerErrorLog: this.#handleServerErrorLog,
+			validationStrategy: this.#validationStrategy,
 		});
 	}
 
@@ -75,6 +79,7 @@ class SafeActionClient<ServerError, Ctx = undefined, Metadata = undefined> {
 				middlewareFns: this.#middlewareFns,
 				metadata: data,
 				ctxType: this.#ctxType,
+				validationStrategy: this.#validationStrategy,
 			}),
 		};
 	}
@@ -134,6 +139,7 @@ class SafeActionClient<ServerError, Ctx = undefined, Metadata = undefined> {
 				formatValidationErrors: args.formatValidationErrors,
 				metadata: args.metadata,
 				ctxType: this.#ctxType,
+				validationStrategy: this.#validationStrategy,
 			}),
 		};
 	}
@@ -151,6 +157,7 @@ class SafeActionClient<ServerError, Ctx = undefined, Metadata = undefined> {
 			middlewareFns: this.#middlewareFns,
 			metadata: undefined,
 			ctxType: this.#ctxType,
+			validationStrategy: this.#validationStrategy,
 		}).action(serverCodeFn);
 	}
 
@@ -170,6 +177,7 @@ class SafeActionClient<ServerError, Ctx = undefined, Metadata = undefined> {
 			middlewareFns: this.#middlewareFns,
 			metadata: undefined,
 			ctxType: this.#ctxType,
+			validationStrategy: this.#validationStrategy,
 		}).stateAction(serverCodeFn);
 	}
 
@@ -196,17 +204,13 @@ class SafeActionClient<ServerError, Ctx = undefined, Metadata = undefined> {
 			formatBindArgsValidationErrors: args.formatBindArgsValidationErrors,
 			metadata: args.metadata,
 			ctxType: this.#ctxType,
+			validationStrategy: this.#validationStrategy,
 		});
 	}
 }
 
-/**
- * Create a new safe action client.
- * @param createOpts Optional initialization options
- *
- * {@link https://next-safe-action.dev/docs/safe-action-client/initialization-options See docs for more information}
- */
-export const createSafeActionClient = <ServerError = string, MetadataSchema extends Schema | undefined = undefined>(
+export const createClientWithStrategy = <ServerError = string, MetadataSchema extends Schema | undefined = undefined>(
+	validationStrategy: "typeschema" | "zod",
 	createOpts?: SafeActionClientOpts<ServerError, MetadataSchema>
 ) => {
 	// If server log function is not provided, default to `console.error` for logging
@@ -233,5 +237,6 @@ export const createSafeActionClient = <ServerError = string, MetadataSchema exte
 		middlewareFns: [async ({ next }) => next({ ctx: undefined })],
 		handleServerErrorLog,
 		handleReturnedServerError,
+		validationStrategy,
 	});
 };

packages/next-safe-action/src/zod.ts

@@ -0,0 +1,24 @@
+import type { Schema } from "@typeschema/main";
+import type { SafeActionClientOpts } from "./index.types";
+import { createClientWithStrategy } from "./safe-action-client";
+
+export { DEFAULT_SERVER_ERROR_MESSAGE, EMPTY_HOOK_RESULT as EMPTY_RESULT } from "./utils";
+export { flattenBindArgsValidationErrors, flattenValidationErrors, returnValidationErrors } from "./validation-errors";
+
+export type * from "./index.types";
+export type * from "./validation-errors.types";
+
+/**
+ * Create a new safe action client.
+ * Note: this client only works with Zod as the validation library.
+ * This is needed when TypeSchema causes problems in your application.
+ * Check out the [troubleshooting](https://next-safe-action.dev/docs/troubleshooting/errors-with-typeschema) page of the docs for more information.
+ * @param createOpts Optional initialization options
+ *
+ * {@link https://next-safe-action.dev/docs/safe-action-client/initialization-options See docs for more information}
+ */
+export const createSafeActionClient = <ServerError = string, MetadataSchema extends Schema | undefined = undefined>(
+	createOpts?: SafeActionClientOpts<ServerError, MetadataSchema>
+) => {
+	return createClientWithStrategy("zod", createOpts);
+};

packages/next-safe-action/tsup.config.ts

@@ -1,7 +1,7 @@
 import { defineConfig } from "tsup";
 
 export default defineConfig({
-	entry: ["src/index.ts", "src/hooks.ts", "src/status.ts"],
+	entry: ["src/index.ts", "src/zod.ts", "src/hooks.ts", "src/status.ts"],
 	format: ["esm"],
 	clean: true,
 	splitting: false,

pnpm-lock.yaml

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 9
+sidebar_position: 10
 description: Learn how to contribute to next-safe-action via GitHub.
 ---
 

website/docs/contributing.md

@@ -18,6 +18,10 @@ description: Getting started with next-safe-action version 7.
 
 We will use Zod as our validation library in this documentation, but since version 6 of next-safe-action, you can use your validation library of choice, or even multiple and custom ones at the same time, thanks to the **TypeSchema** library. Note that we also need to install the related TypeSchema adapter for our validation library of choice. You can find supported libraries and related adapters [here](https://typeschema.com/#coverage).
 
+:::info
+If you experience an issue related to TypeSchema, check out the ["Errors with TypeSchema"](/docs/troubleshooting/errors-with-typeschema) section of the troubleshooting page to see how to fix it.
+:::
+
 ## Installation
 
 For Next.js >= 14, assuming you want to use Zod as your validation library, use the following command:

website/docs/getting-started.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 8
+sidebar_position: 9
 description: Learn how to migrate from a version to the next one.
 ---
 

website/docs/migrations/index.md

@@ -0,0 +1,28 @@
+---
+sidebar_position: 1
+description: Knwon errors with TypeSchema.
+---
+
+# Errors with TypeSchema
+
+[TypeSchema](https://typeschema.com/) library relies on dynamic imports to support a wide range of validation libraries. It works well most of the time, but in some cases it can cause unexpected errors.
+
+For instance, there's a known bug with TypeSchema and Next.js edge runtime. When parsing and validating client input, the server outputs the following error:
+
+```
+TypeError [ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING]:
+  A dynamic import callback was not specified.
+```
+
+To solve this, next-safe-action exports a copy of the safe action client from the `/zod` path, with the exact same functionality as the default one. The only difference is that this client **requires** Zod to work, as it supports just that validation library.
+
+So, after you installed `next-safe-action`, `zod` and `@typeschema/zod` packages, as explained in the [installation](/docs/getting-started#installation) section of the getting started page, you just need to update the import path for `createSafeActionClient`, in the `safe-action.ts` file:
+
+```typescript title="src/lib/safe-action.ts"
+// Update import path here with /zod
+import { createSafeActionClient } from "next-safe-action/zod";
+
+export const actionClient = createSafeActionClient();
+```
+
+`next-safe-action/zod` exports the same client, variables, functions and types as the default path.

website/docs/troubleshooting/errors-with-typeschema.md

@@ -0,0 +1,8 @@
+---
+sidebar_position: 8
+description: Learn how to fix known issues with next-safe-action.
+---
+
+# Troubleshooting
+
+Learn how to fix known issues with next-safe-action.