Migration

If you are moving from mongoose-zod or an earlier zod-mongoose release, start with these replacements. New projects can follow Start Here.

Replace old functions

toZodMongooseSchema()

Previously, this returned a ZodMongoose wrapper used to generate the Mongoose schema.

• Replacement: Use toMongooseSchema() which returns a full mongoose.Schema instance directly, or extractMongooseDef() which returns the raw Mongoose schema definition (POJO).

mongooseZodCustomType()

This was previously used to directly define a Mongoose type on a Zod schema.

• Replacement: Use withMongoose(z.any(), { type: mongoose.Schema.Types.YourType }) or specialized helpers like zObjectId() and zBuffer().

Update environment and types

setFrontendMode()

setFrontendMode() is deprecated in v3.1 and emits a console warning when called.

• Replacement: Remove it and rely on package conditional exports.

Legacy inference aliases

InferMongoose<T>, OutputMongoose<T>, and InputMongoose<T> are deprecated in v3.1.

• Replacement: Use InferDocument<T> for persisted Mongoose documents and InferInput<T> for raw Zod input.

ZodMongoose class

The ZodMongoose class has been removed.

• Replacement: The library now uses standard Zod types with metadata stored in the zod/v4 registry. All functions are now standalone helpers.

setup({ z })

This initialization step is no longer required.

• Reason: The library uses the zod/v4 registry directly and does not modify the Zod prototype.

Prototype Extensions

Methods like .mongoose(), .mongooseTypeOptions(), and .mongooseSchemaOptions() are not available on current Zod types.

• Replacement: Use withMongoose(zodSchema, metadata) instead.

Configure plugins explicitly

Automatic Plugin Loading

Optional peer dependencies like mongoose-lean-* are no longer automatically attached to the generated schemas.

• Replacement: Plugins should be applied to the Mongoose schema manually using the plugins option in toMongooseSchema or the schema:created hook.