export const metadata = { title: ${pageNumber} Replace Zod Imports Codemod (v2.13.0+), }

{metadata.title}

In this chapter, you'll learn about the codemod that helps you replace Zod imports in your codebase when upgrading to Medusa v2.13.0.

What is the Replace Zod Imports Codemod?

As of v2.13.0, Medusa exports Zod from the @medusajs/framework package.

Starting from Medusa v2.14.0, Zod has been upgraded to v4, which introduces breaking changes to the Zod API. You may need to update your validation schemas accordingly. See the Zod v4 upgrade guide for details.

Zod is a validation library that you can use to validate request bodies, query parameters, and more in your Medusa application.

Starting in v2.13.0, you can import Zod from @medusajs/framework/zod in your backend customizations. For example:

import { z } from "@medusajs/framework/zod"

For Medusa Admin customizations, you can install and import Zod as needed.

The replace-zod-imports codemod automates the process of updating your import statements to use the new Zod import path. Use it after updating your Medusa project to v2.13.0 or later.

How to Run the Codemod

To use the replace imports codemod, update your Medusa project to v2.13.0 or later. Refer to the Update Medusa guide for instructions.

Then, run the following command in the root directory of your Medusa project:

npx medusa codemod replace-zod-imports

This command scans your codebase for Zod import statements in the backend customizations and replaces them with the new import path.

All Zod imports will be changed to:

import { z } from "@medusajs/framework/zod"

Next Steps

After running the codemod, review the changes made to your codebase. You can:

• Use git diff to see the modifications.
• Check for Zod v4 breaking changes: If upgrading to Medusa v2.14.0+, review your Zod schemas for breaking changes. Common issues include:
  • z.record() now requires explicit key types: z.record(z.string(), ValueType) instead of z.record(ValueType)
  • Some internal types have changed (though this typically doesn't affect user code)
• Run your tests to ensure everything works as expected.

If everything is working correctly, you can push the changes to your repository. If you've installed zod and you're not using it for Medusa Admin customizations, you can remove it from your package.json dependencies.