docs: fix Cloud storefront troubleshooting, Node.js version warning, and variables set scope defaults [automated] (#16220)

* docs: fix documentation issues from triage inbox

* Revise environment variable creation notes

Updated documentation regarding environment variable creation and its default scope settings.

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: shahednasser

www/apps/cloud/app/deployments/troubleshooting/page.mdx

@@ -267,6 +267,21 @@ If your storefront build fails with a `build-failed` status but the build logs a
 - An outdated lockfile that is out of sync with `package.json`
 - Incompatible or missing dependencies in the monorepo
 
+### Check for Storefront Root Directory Misconfiguration
+
+If the storefront build fails immediately (within 1-2 seconds) with no build logs and you see file retrieval errors, the storefront root directory configured in your Cloud project may not match the actual location of your storefront in the repository.
+
+To verify and fix the storefront root directory:
+
+1. In the [Cloud dashboard](../../organizations/page.mdx), open your project and go to **Settings**.
+2. Check the **Storefront root directory** field and confirm it matches the actual path of your storefront in the repository. For example, if your storefront is at `apps/storefront`, the field should contain `apps/storefront`.
+3. If the path is incorrect, update it and save.
+4. Trigger a new deployment.
+
+Refer to the [Projects](../../projects/page.mdx) guide for details on editing the storefront root directory setting.
+
+---
+
 ### Check for Lockfile Mismatches
 
 Cloud installs dependencies with a frozen lockfile to ensure reproducible builds. If your lockfile is out of sync with `package.json`, the dependency installation step may fail silently.
@@ -478,6 +493,38 @@ This is because Cloud does not currently support Node.js middlewares in Next.js
 
 ---
 
+## Next.js Turbopack Workspace Root Error in Monorepos
+
+If your Next.js 16+ storefront build fails with the following error:
+
+```bash
+Error: Next.js inferred your workspace root, but it may not be correct.
+We couldn't find the Next.js package (next/package.json) from the project directory
+```
+
+This occurs in monorepo setups where the storefront is in a subdirectory (for example, `/storefront`) but `node_modules` is installed at the monorepo root. Turbopack's default workspace inference looks for `next/package.json` relative to the storefront directory, but the package is installed at the monorepo root.
+
+### Fix Turbopack Workspace Root
+
+Set the `turbopack.root` option in your `next.config.ts` to point to the monorepo root:
+
+```ts title="apps/storefront/next.config.ts"
+import path from "path"
+import type { NextConfig } from "next"
+
+const nextConfig: NextConfig = {
+  turbopack: {
+    root: path.join(__dirname, ".."),
+  },
+}
+
+export default nextConfig
+```
+
+Replace `".."` with the relative path from your storefront directory to the monorepo root. Commit the updated `next.config.ts` and push to trigger a new deployment.
+
+---
+
 ## npm Cache Errors During Build
 
 If your build fails with an error similar to:

www/apps/cloud/app/projects/prerequisites/page.mdx

@@ -1,3 +1,5 @@
+import { Note } from "docs-ui"
+
 export const metadata = {
   title: `Prerequisites for New Projects`,
 }
@@ -121,6 +123,20 @@ Medusa uses Node.js v24.x (LTS) to build storefronts. You can't override this ve
 
 So, ensure that your storefront is compatible with Node.js v24.x.
 
+<Note type="warning">
+
+If your storefront's `package.json` has an `engines.node` field that restricts the Node.js version to a range that excludes v24.x (for example, `"22.x"`), the build will fail with a version incompatibility error. Update the field to accept v24.x, for example:
+
+```json title="apps/storefront/package.json"
+{
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}
+```
+
+</Note>
+
 ### Root Build Script
 
 Your monorepo must have a `build` script that builds both the Medusa application and the storefront. Medusa executes this script during the deployment process.