docs: document incompatibility for Next.js storefront + Node v25 (#14538)

www/apps/book/app/learn/installation/page.mdx

@@ -49,6 +49,12 @@ npx create-medusa-app@latest my-medusa-store
 
 Where `my-medusa-store` is the name of the project's directory and PostgreSQL database created for the project. When you run the command, you'll be asked whether you want to install the Next.js Starter Storefront.
 
+<Note title="Installations with Next.js Starter Storefront">
+
+If you choose to install the Next.js Starter Storefront, note that it currently doesn't support Node v25+. Make sure to downgrade to Node v24 LTS or lower before installing the Medusa application with the storefront.
+
+</Note>
+
 <Note>
 
 To customize the default installation behavior, such as specify a database URL, refer to the [create-medusa-app reference](!resources!/create-medusa-app).

www/apps/book/generated/edit-dates.mjs

@@ -96,7 +96,7 @@ export const generatedEditDates = {
   "app/learn/build/page.mdx": "2025-10-27T09:30:26.957Z",
   "app/learn/deployment/general/page.mdx": "2026-01-08T09:18:20.179Z",
   "app/learn/fundamentals/workflows/multiple-step-usage/page.mdx": "2025-08-01T14:59:59.501Z",
-  "app/learn/installation/page.mdx": "2026-01-08T09:18:46.731Z",
+  "app/learn/installation/page.mdx": "2026-01-14T08:26:19.937Z",
   "app/learn/fundamentals/data-models/check-constraints/page.mdx": "2025-07-25T13:50:21.065Z",
   "app/learn/fundamentals/module-links/link/page.mdx": "2025-12-09T13:27:05.446Z",
   "app/learn/fundamentals/workflows/store-executions/page.mdx": "2025-04-17T08:29:10.166Z",

www/apps/resources/app/nextjs-starter/page.mdx

@@ -2,6 +2,7 @@ import { DetailsList, Prerequisites } from "docs-ui"
 import CmaOptionTroubleshooting from "../troubleshooting/_sections/nextjs/cma-option.mdx"
 import CorsErrorTroubleshooting from "../troubleshooting/_sections/other/cors-errors.mdx"
 import ModuleXErrorTroubleshooting from "../troubleshooting/_sections/common-installation-errors/module-x-error.mdx"
+import Node25Troubleshooting from "../troubleshooting/_sections/create-medusa-app-errors/nextjs-node-25.mdx"
 
 export const metadata = {
   title: `Next.js Starter Storefront`,
@@ -25,7 +26,7 @@ This guide helps technical users set up the Next.js Start storefront. If you're
 
 <Prerequisites items={[
   {
-    text: "Node.js v20+",
+    text: "Node.js v20+ LTS, less than v25",
     link: "https://nodejs.org/en/download"
   },
   {
@@ -54,7 +55,7 @@ For other information related to the Medusa application's installation, refer to
 
 <Prerequisites items={[
   {
-    text: "Node.js v20+",
+    text: "Node.js v20+ LTS, less than v25",
     link: "https://nodejs.org/en/download"
   },
   {
@@ -113,6 +114,10 @@ Your Next.js Starter storefront is now running at `http://localhost:8000`.
     {
       title: `Resolve "Cannot find module X" Errors`,
       content: <ModuleXErrorTroubleshooting />
+    },
+    {
+      title: `Issues when installing with Node v25+`,
+      content: <Node25Troubleshooting />
     }
   ]}
 />

www/apps/resources/app/troubleshooting/_sections/create-medusa-app-errors/nextjs-node-25.mdx

@@ -0,0 +1,17 @@
+If you install the Next.js Starter Storefront with Node v25+, you may encounter the following error when starting the storefront:
+
+```bash
+[TypeError: localStorage.getItem is not a function]
+```
+
+### Why this Error Occurred
+
+This error occurs because the Next.js Starter Storefront uses Next.js v15.3.8, which doesn't yet support Node v25+.
+
+The error is related to changes in Node v25+ that affect how certain web APIs, like `localStorage`, are handled in server-side environments.
+
+---
+
+### How to Fix it
+
+Our team is actively working on updating the Next.js Starter Storefront to support Node v25+. In the meantime, you can resolve this error by downgrading your Node.js version to v24 LTS or lower.

www/apps/resources/app/troubleshooting/create-medusa-app-errors/page.mdx

@@ -7,6 +7,7 @@ import DbUrlError from "../_sections/create-medusa-app-errors/db-url-error.mdx"
 import ForwardingError from "../_sections/create-medusa-app-errors/forwarding.mdx"
 import SaslSection from '../_sections/database-errors/sasl.mdx'
 import ModuleXErrorSection from '../_sections/common-installation-errors/module-x-error.mdx'
+import Node25Troubleshooting from "../_sections/create-medusa-app-errors/nextjs-node-25.mdx"
 
 export const metadata = {
   title: `Common create-medusa-app Errors`,
@@ -58,6 +59,12 @@ This troubleshooting guide covers common errors you may encounter when using the
 
 ---
 
+## Issues when installing with Node v25+
+
+<Node25Troubleshooting />
+
+---
+
 ## Resolve "Cannot find module X" Errors
 
 <ModuleXErrorSection />

www/apps/resources/app/troubleshooting/nextjs-node-25/page.mdx

@@ -0,0 +1,13 @@
+import Node25Troubleshooting from "../_sections/create-medusa-app-errors/nextjs-node-25.mdx"
+ 
+export const metadata = {
+  title: `Next.js Starter Storefront on Node v25+ Issues`,
+}
+
+# {metadata.title}
+
+This troubleshooting guide addresses issues that may arise when installing or running a Medusa application with the Next.js Starter Storefront on Node.js version 25 or higher.
+
+## Error After Installing with Node v25+
+
+<Node25Troubleshooting />

www/apps/resources/generated/edit-dates.mjs

@@ -107,7 +107,7 @@ export const generatedEditDates = {
   "app/medusa-cli/page.mdx": "2024-08-28T11:25:32.382Z",
   "app/medusa-container-resources/page.mdx": "2025-07-31T13:24:15.786Z",
   "app/medusa-workflows-reference/page.mdx": "2025-01-20T08:21:29.962Z",
-  "app/nextjs-starter/page.mdx": "2025-02-26T11:37:47.137Z",
+  "app/nextjs-starter/page.mdx": "2026-01-14T08:32:07.149Z",
   "app/recipes/b2b/page.mdx": "2025-05-20T07:51:40.718Z",
   "app/recipes/commerce-automation/page.mdx": "2025-05-20T07:51:40.719Z",
   "app/recipes/digital-products/examples/standard/page.mdx": "2025-11-28T09:43:09.959Z",
@@ -178,7 +178,7 @@ export const generatedEditDates = {
   "app/storefront-development/tips/page.mdx": "2025-12-09T13:33:33.997Z",
   "app/storefront-development/page.mdx": "2025-12-09T13:30:25.379Z",
   "app/troubleshooting/cors-errors/page.mdx": "2024-05-03T17:36:38+03:00",
-  "app/troubleshooting/create-medusa-app-errors/page.mdx": "2025-12-04T14:12:21.480Z",
+  "app/troubleshooting/create-medusa-app-errors/page.mdx": "2026-01-14T08:32:33.242Z",
   "app/troubleshooting/database-errors/page.mdx": "2025-12-04T14:14:46.745Z",
   "app/troubleshooting/eaddrinuse/page.mdx": "2024-05-03T17:36:38+03:00",
   "app/troubleshooting/errors-after-upgrading/page.mdx": "2025-12-04T14:08:49.980Z",
@@ -6936,5 +6936,6 @@ export const generatedEditDates = {
   "app/how-to-tutorials/how-to/admin/auth/page.mdx": "2025-12-30T06:35:28.828Z",
   "app/integrations/guides/okta/page.mdx": "2025-12-30T06:35:28.653Z",
   "app/nextjs-starter/guides/remove-country-code/page.mdx": "2025-12-30T10:28:10.072Z",
-  "app/commerce-modules/translation/custom-data-models/page.mdx": "2026-01-06T15:54:25.801Z"
+  "app/commerce-modules/translation/custom-data-models/page.mdx": "2026-01-06T15:54:25.801Z",
+  "app/troubleshooting/nextjs-node-25/page.mdx": "2026-01-14T08:34:00.550Z"
 }

www/apps/resources/generated/files-map.mjs

@@ -1551,6 +1551,10 @@ export const filesMap = [
     "filePath": "/www/apps/resources/app/troubleshooting/medusa-admin/no-widget-route/page.mdx",
     "pathname": "/troubleshooting/medusa-admin/no-widget-route"
   },
+  {
+    "filePath": "/www/apps/resources/app/troubleshooting/nextjs-node-25/page.mdx",
+    "pathname": "/troubleshooting/nextjs-node-25"
+  },
   {
     "filePath": "/www/apps/resources/app/troubleshooting/nextjs-starter-rewrites/page.mdx",
     "pathname": "/troubleshooting/nextjs-starter-rewrites"

www/apps/resources/generated/generated-commerce-modules-sidebar.mjs

@@ -135,6 +135,14 @@ const generatedgeneratedCommerceModulesSidebarSidebar = {
                       "path": "https://docs.medusajs.com/resources/references/medusa-workflows/createApiKeysWorkflow",
                       "children": []
                     },
+                    {
+                      "loaded": true,
+                      "isPathHref": true,
+                      "type": "ref",
+                      "title": "createDefaultsWorkflow",
+                      "path": "https://docs.medusajs.com/resources/references/medusa-workflows/createDefaultsWorkflow",
+                      "children": []
+                    },
                     {
                       "loaded": true,
                       "isPathHref": true,
@@ -701,6 +709,14 @@ const generatedgeneratedCommerceModulesSidebarSidebar = {
                       "title": "removeUserAccountWorkflow",
                       "path": "https://docs.medusajs.com/resources/references/medusa-workflows/removeUserAccountWorkflow",
                       "children": []
+                    },
+                    {
+                      "loaded": true,
+                      "isPathHref": true,
+                      "type": "ref",
+                      "title": "setAuthAppMetadataWorkflow",
+                      "path": "https://docs.medusajs.com/resources/references/medusa-workflows/setAuthAppMetadataWorkflow",
+                      "children": []
                     }
                   ]
                 },
@@ -2838,6 +2854,14 @@ const generatedgeneratedCommerceModulesSidebarSidebar = {
                       "title": "updateCustomersWorkflow",
                       "path": "https://docs.medusajs.com/resources/references/medusa-workflows/updateCustomersWorkflow",
                       "children": []
+                    },
+                    {
+                      "loaded": true,
+                      "isPathHref": true,
+                      "type": "ref",
+                      "title": "updateOrderWorkflow",
+                      "path": "https://docs.medusajs.com/resources/references/medusa-workflows/updateOrderWorkflow",
+                      "children": []
                     }
                   ]
                 },
@@ -7712,6 +7736,14 @@ const generatedgeneratedCommerceModulesSidebarSidebar = {
                       "path": "https://docs.medusajs.com/resources/references/medusa-workflows/steps/updateOrderShippingMethodsStep",
                       "children": []
                     },
+                    {
+                      "loaded": true,
+                      "isPathHref": true,
+                      "type": "ref",
+                      "title": "updateOrderShippingMethodsTranslationsStep",
+                      "path": "https://docs.medusajs.com/resources/references/medusa-workflows/steps/updateOrderShippingMethodsTranslationsStep",
+                      "children": []
+                    },
                     {
                       "loaded": true,
                       "isPathHref": true,

www/apps/resources/generated/generated-troubleshooting-sidebar.mjs

@@ -304,6 +304,14 @@ const generatedgeneratedTroubleshootingSidebarSidebar = {
           "type": "sub-category",
           "title": "Next.js Starter",
           "children": [
+            {
+              "loaded": true,
+              "isPathHref": true,
+              "type": "link",
+              "path": "/troubleshooting/nextjs-node-25",
+              "title": "Errors with Node v25+",
+              "children": []
+            },
             {
               "loaded": true,
               "isPathHref": true,

www/apps/resources/sidebars/troubleshooting.mjs

@@ -202,6 +202,11 @@ export const troubleshootingSidebar = [
         type: "sub-category",
         title: "Next.js Starter",
         children: [
+          {
+            type: "link",
+            path: "/troubleshooting/nextjs-node-25",
+            title: "Errors with Node v25+",
+          },
           {
             type: "link",
             path: "/troubleshooting/nextjs-starter-rewrites",

www/packages/tags/src/tags/api-key.ts

@@ -43,6 +43,10 @@ export const apiKey = [
     "title": "updateApiKeysWorkflow",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/updateApiKeysWorkflow"
   },
+  {
+    "title": "createDefaultsWorkflow",
+    "path": "https://docs.medusajs.com/resources/references/medusa-workflows/createDefaultsWorkflow"
+  },
   {
     "title": "apiKey",
     "path": "https://docs.medusajs.com/resources/references/js-sdk/admin/apiKey"

www/packages/tags/src/tags/auth.ts

@@ -51,6 +51,10 @@ export const auth = [
     "title": "setAuthAppMetadataStep",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/steps/setAuthAppMetadataStep"
   },
+  {
+    "title": "setAuthAppMetadataWorkflow",
+    "path": "https://docs.medusajs.com/resources/references/medusa-workflows/setAuthAppMetadataWorkflow"
+  },
   {
     "title": "createCustomerAccountWorkflow",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/createCustomerAccountWorkflow"

www/packages/tags/src/tags/customer.ts

@@ -211,6 +211,10 @@ export const customer = [
     "title": "orderExchangeAddNewItemWorkflow",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/orderExchangeAddNewItemWorkflow"
   },
+  {
+    "title": "updateOrderWorkflow",
+    "path": "https://docs.medusajs.com/resources/references/medusa-workflows/updateOrderWorkflow"
+  },
   {
     "title": "customer",
     "path": "https://docs.medusajs.com/resources/references/js-sdk/admin/customer"

www/packages/tags/src/tags/event-bus.ts

@@ -63,6 +63,18 @@ export const eventBus = [
     "title": "updateDraftOrderWorkflow",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/updateDraftOrderWorkflow"
   },
+  {
+    "title": "createShippingOptionsWorkflow",
+    "path": "https://docs.medusajs.com/resources/references/medusa-workflows/createShippingOptionsWorkflow"
+  },
+  {
+    "title": "deleteShippingOptionsWorkflow",
+    "path": "https://docs.medusajs.com/resources/references/medusa-workflows/deleteShippingOptionsWorkflow"
+  },
+  {
+    "title": "updateShippingOptionsWorkflow",
+    "path": "https://docs.medusajs.com/resources/references/medusa-workflows/updateShippingOptionsWorkflow"
+  },
   {
     "title": "acceptInviteWorkflow",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/acceptInviteWorkflow"

www/packages/tags/src/tags/link.ts

@@ -87,6 +87,10 @@ export const link = [
     "title": "updateLinksWorkflow",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/updateLinksWorkflow"
   },
+  {
+    "title": "createDefaultsWorkflow",
+    "path": "https://docs.medusajs.com/resources/references/medusa-workflows/createDefaultsWorkflow"
+  },
   {
     "title": "deleteDraftOrdersWorkflow",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/deleteDraftOrdersWorkflow"
@@ -143,6 +147,10 @@ export const link = [
     "title": "createVariantPricingLinkStep",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/steps/createVariantPricingLinkStep"
   },
+  {
+    "title": "dismissProductVariantsInventoryStep",
+    "path": "https://docs.medusajs.com/resources/references/medusa-workflows/steps/dismissProductVariantsInventoryStep"
+  },
   {
     "title": "batchProductVariantsWorkflow",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/batchProductVariantsWorkflow"
@@ -175,6 +183,10 @@ export const link = [
     "title": "deleteProductsWorkflow",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/deleteProductsWorkflow"
   },
+  {
+    "title": "updateProductVariantsWorkflow",
+    "path": "https://docs.medusajs.com/resources/references/medusa-workflows/updateProductVariantsWorkflow"
+  },
   {
     "title": "updateProductsWorkflow",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/updateProductsWorkflow"

www/packages/tags/src/tags/order.ts

@@ -327,6 +327,10 @@ export const order = [
     "title": "updateOrderShippingMethodsStep",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/steps/updateOrderShippingMethodsStep"
   },
+  {
+    "title": "updateOrderShippingMethodsTranslationsStep",
+    "path": "https://docs.medusajs.com/resources/references/medusa-workflows/steps/updateOrderShippingMethodsTranslationsStep"
+  },
   {
     "title": "updateOrdersStep",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/steps/updateOrdersStep"

www/packages/tags/src/tags/query.ts

@@ -51,6 +51,10 @@ export const query = [
     "title": "useQueryGraphStep",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/steps/useQueryGraphStep"
   },
+  {
+    "title": "createDefaultsWorkflow",
+    "path": "https://docs.medusajs.com/resources/references/medusa-workflows/createDefaultsWorkflow"
+  },
   {
     "title": "addDraftOrderItemsWorkflow",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/addDraftOrderItemsWorkflow"
@@ -107,6 +111,10 @@ export const query = [
     "title": "updateDraftOrderShippingMethodWorkflow",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/updateDraftOrderShippingMethodWorkflow"
   },
+  {
+    "title": "updateDraftOrderWorkflow",
+    "path": "https://docs.medusajs.com/resources/references/medusa-workflows/updateDraftOrderWorkflow"
+  },
   {
     "title": "deleteInventoryItemWorkflow",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/deleteInventoryItemWorkflow"
@@ -119,6 +127,10 @@ export const query = [
     "title": "exportOrdersStep",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/steps/exportOrdersStep"
   },
+  {
+    "title": "updateOrderShippingMethodsTranslationsStep",
+    "path": "https://docs.medusajs.com/resources/references/medusa-workflows/steps/updateOrderShippingMethodsTranslationsStep"
+  },
   {
     "title": "beginOrderEditOrderWorkflow",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/beginOrderEditOrderWorkflow"
@@ -195,6 +207,14 @@ export const query = [
     "title": "updateOrderEditItemQuantityWorkflow",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/updateOrderEditItemQuantityWorkflow"
   },
+  {
+    "title": "updateOrderWorkflow",
+    "path": "https://docs.medusajs.com/resources/references/medusa-workflows/updateOrderWorkflow"
+  },
+  {
+    "title": "dismissProductVariantsInventoryStep",
+    "path": "https://docs.medusajs.com/resources/references/medusa-workflows/steps/dismissProductVariantsInventoryStep"
+  },
   {
     "title": "batchProductVariantsWorkflow",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/batchProductVariantsWorkflow"
@@ -207,6 +227,14 @@ export const query = [
     "title": "deleteProductsWorkflow",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/deleteProductsWorkflow"
   },
+  {
+    "title": "updateProductVariantsWorkflow",
+    "path": "https://docs.medusajs.com/resources/references/medusa-workflows/updateProductVariantsWorkflow"
+  },
+  {
+    "title": "updateProductsWorkflow",
+    "path": "https://docs.medusajs.com/resources/references/medusa-workflows/updateProductsWorkflow"
+  },
   {
     "title": "deleteShippingProfileWorkflow",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/deleteShippingProfileWorkflow"

www/packages/tags/src/tags/step.ts

@@ -183,6 +183,10 @@ export const step = [
     "title": "getTranslatedLineItemsStep",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/steps/getTranslatedLineItemsStep"
   },
+  {
+    "title": "getTranslatedShippingOptionsStep",
+    "path": "https://docs.medusajs.com/resources/references/medusa-workflows/steps/getTranslatedShippingOptionsStep"
+  },
   {
     "title": "removeRemoteLinkStep",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/steps/removeRemoteLinkStep"
@@ -595,6 +599,10 @@ export const step = [
     "title": "updateOrderShippingMethodsStep",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/steps/updateOrderShippingMethodsStep"
   },
+  {
+    "title": "updateOrderShippingMethodsTranslationsStep",
+    "path": "https://docs.medusajs.com/resources/references/medusa-workflows/steps/updateOrderShippingMethodsTranslationsStep"
+  },
   {
     "title": "updateOrdersStep",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/steps/updateOrdersStep"
@@ -1071,6 +1079,10 @@ export const step = [
     "title": "deleteProductsStep",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/steps/deleteProductsStep"
   },
+  {
+    "title": "dismissProductVariantsInventoryStep",
+    "path": "https://docs.medusajs.com/resources/references/medusa-workflows/steps/dismissProductVariantsInventoryStep"
+  },
   {
     "title": "generateProductCsvStep",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/steps/generateProductCsvStep"

www/packages/tags/src/tags/workflow.ts

@@ -27,6 +27,10 @@ export const workflow = [
     "title": "generateResetPasswordTokenWorkflow",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/generateResetPasswordTokenWorkflow"
   },
+  {
+    "title": "setAuthAppMetadataWorkflow",
+    "path": "https://docs.medusajs.com/resources/references/medusa-workflows/setAuthAppMetadataWorkflow"
+  },
   {
     "title": "addShippingMethodToCartWorkflow",
     "path": "https://docs.medusajs.com/resources/references/medusa-workflows/addShippingMethodToCartWorkflow"