Vue Storefront is now Alokai! Learn More
Multistore Debugging Guide

Multistore Debugging Guide

Guide for debugging storefront and middleware in a multistore setup using Node.js inspect protocol.

Quick Start

1. Configure Debug Ports (see "Configuring Debug Ports" section for details)

Add to your package.json files:

  • /apps/storefront-middleware/package.json
    • Middleware debugging: Add --inspect=localhost:9229 to middleware dev script
  • /apps/storefront-unified-nextjs/package.json
    • SSR debugging (optional): Add NODE_OPTIONS='--inspect=9230' to frontend dev script
  • /apps/storefront-unified-nuxt/package.json
    • SSR debugging (optional): Add NODE_OPTIONS='--inspect=9230' to frontend dev script

2. Start Your Store

yarn store dev --store-id=default

3. Attach Chrome DevTools

  1. Open chrome://inspect in Chrome
  2. Click "Configure" and add localhost:9229, localhost:9230, localhost:9231
  3. Click "inspect" on available ports

4. Add Debugger Statements

Add debugger; in your code where you want execution to pause.

5. Trigger Debugging

  • Refresh page (SSR)
  • Click button (client)
  • Make API call (middleware)

Port Configuration

Debug Ports (must be configured in each app's package.json):

  • 9229 - Middleware (opt-in, recommended for middleware debugging)
  • 9230 - Next.js main server (opt-in for SSR debugging)
  • 9231 - Next.js router server ← Most SSR code runs here!
  • Browser - Client-side code (always available via dev tools F12)

Important: Debug ports are NOT enabled by default. Configure them in each app's package.json as needed. See "Configuring Debug Ports" section.

Debugging Middleware

Chrome DevTools

Setup: Add --inspect=localhost:9229 to apps/storefront-middleware/package.json:

{
  "scripts": {
    "dev": "concurrently --raw \"tspc --preserveWatchOutput --watch\" \"NODE_ENV=development tsx watch --inspect=localhost:9229 --clear-screen=false src/index.ts\""
  }
}

Then start:

yarn store dev --store-id=default
  1. Open chrome://inspect
  2. Add localhost:9229 in Configure
  3. Click "inspect" under Remote Target

VS Code

Add to .vscode/launch.json:

{
  "type": "node",
  "request": "attach",
  "name": "Debug Middleware",
  "port": 9229,
  "restart": true,
  "skipFiles": ["<node_internals>/**"]
}

Steps:

  1. Start: yarn store dev --store-id=default
  2. Press F5 → Select "Debug Middleware"
  3. Set breakpoints

WebStorm/IntelliJ

  1. Run → Edit Configurations
  2. Add "Attach to Node.js/Chrome"
  3. Set port to 9229
  4. Start middleware, then click Debug

Debugging Next.js Storefront

SSR Debugging

Setup: Add to apps/storefront-unified-nextjs/package.json:

{
  "scripts": {
    "dev": "NODE_OPTIONS='--inspect=9230' NODE_ENV=development next dev"
  }
}

Note: SSR debugging slows down the dev server. Only enable when debugging Server Components.

yarn store dev --store-id=default
  1. Open chrome://inspect
  2. Attach to both 9230 and 9231
  3. Hard refresh page (Cmd+Shift+R) to trigger SSR
  4. Debugger pauses on Server Components (usually port 9231)

    Why port 9231?

    Even though we set the inspector on port 9230, Next.js spawns another process that opens the inspector on port 9231, and you'll be able to debug Next.js code via that port.

Client-Side Debugging

Just open Browser DevTools (F12) - no special setup needed.

VS Code Configuration

{
  "type": "node",
  "request": "attach",
  "name": "Debug Next.js SSR",
  "port": 9231,
  "restart": true
}

Debugging Nuxt Storefront

Setup: Add to apps/storefront-unified-nuxt/package.json:

{
  "scripts": {
    "dev": "NODE_OPTIONS='--inspect=9230' nuxt dev"
  }
}

Then start and attach to port 9230 via chrome://inspect.

Common Scenarios

Debug Custom Middleware Method

  1. Add debugger; in apps/storefront-middleware/api/custom-methods/myMethod.ts
  2. Start: yarn store dev --store-id=default
  3. Attach to port 9229
  4. Make API call from frontend

Debug Server Component (SSR)

  1. Enable SSR debugging in apps/storefront-unified-nextjs/package.json (see "Configuring Debug Ports")
  2. Add debugger; in your Server Component
  3. Start: yarn store dev --store-id=default
  4. Attach to ports 9230 AND 9231 in chrome://inspect
  5. Hard refresh page (Cmd+Shift+R)
  6. Debugger pauses (usually on port 9231)

Debug Store-Specific Override

Check which file is being used:

Base: apps/storefront-middleware/api/custom-methods/myMethod.ts
Override: apps/stores/default/storefront-middleware/api/custom-methods/myMethod.ts

Set breakpoint in the override file, then start that specific store.

Debugging Tips

Conditional Breakpoints

// Only pause if condition is true
if (storeId === "sapcc") debugger;
if (error !== null) debugger;

Debug Startup Issues

Modify middleware dev script to use --inspect-brk instead of --inspect:

{
  "dev": "tsx watch --inspect-brk --clear-screen=false src/index.ts"
}

This pauses on first line - useful for debugging initialization.

Remote/Docker Debugging

Change --inspect to --inspect=0.0.0.0:9229 in package.json to bind to all interfaces:

{
  "dev": "tsx watch --inspect=0.0.0.0:9229 --clear-screen=false src/index.ts"
}

Troubleshooting

Breakpoints Not Hitting

  • ✅ Restart debugger after file changes
  • ✅ Check whether source maps are enabled (tsconfig.json)
  • ✅ Verify you're debugging a correct file (base vs override)

SSR Debugger Not Pausing

  • ✅ Verify NODE_OPTIONS='--inspect=9230' is in your package.json dev script
  • ✅ Attach to both 9230 AND 9231
  • ✅ Use hard refresh (Cmd+Shift+R), not F5
  • ✅ Check you didn't client-side navigate (use direct URL)

Port Already in Use

# Find and kill process
lsof -i :9229
kill -9 <PID>

# Or configure a different port in package.json
# apps/storefront-unified-nextjs/package.json:
# "dev": "NODE_OPTIONS='--inspect=9240' next dev"

Configuring Debug Ports

Important: Debug ports must be configured in each app's package.json. You cannot use NODE_OPTIONS as a command prefix because it affects all spawned processes.

Resources