Skip to content

Shopify Integration

Jump to bottom
tavlean edited this page Jul 2, 2026 · 2 revisions

Shopify Integration

Living notes for Shopify CLI dev-server support.

Goal

Treat Shopify local development servers as first-class Dev Servers rows while preserving the extension's OS-driven detection model.

The dashboard should catch Shopify servers started from any terminal, package script, or tool. Start/restart support lives in the shared spawn path so the generic Node/Bun path stays boring.

Supported now

  • Detect global Shopify CLI dev processes that are not launched from node_modules.
  • Recognize these commands:
    • shopify theme dev
    • shopify app dev
    • shopify hydrogen dev
  • Show dedicated tool tags:
    • shopify-theme -> Shopify Theme
    • shopify-app -> Shopify App
    • shopify-hydrogen -> Hydrogen
  • Keep the existing runtime tag behavior. Shopify CLI currently runs under Node, so the runtime remains node.
  • Start and restart pure theme roots via shopify theme dev. A theme root is layout/theme.liquid or shopify.theme.toml; no package.json is required.
  • Start and restart app roots via package scripts when present, or shopify app dev when shopify.app.toml exists and no dev script is usable.
  • Detect Hydrogen before the shopify.app.toml marker. Hydrogen projects can also carry app markers, but @shopify/hydrogen is the more specific signal.

Implementation:

  • src/servers.ts: detectShopifyTool(command) classifies Shopify CLI dev commands.
  • src/servers.ts: isCandidate accepts Shopify CLI dev commands in addition to node_modules and bare Bun candidates.
  • src/tool-display.ts: labels and colors for Shopify tags.
  • src/start.tsx: guessFramework(cwd) uses theme markers first, then the Hydrogen dependency, then the app marker.
  • src/servers.ts: findProjectRoot accepts theme/app roots, and planSpawn falls back to Shopify CLI commands when scripts do not cover the project.

Detection contract

Detection is intentionally command-line based, matching the existing dashboard model.

Positive examples:

node /Users/me/.nvm/versions/node/v24/bin/shopify theme dev
shopify app dev --use-localhost
/opt/homebrew/bin/shopify hydrogen dev

Negative examples:

shopify theme check
shopify theme language-server
/path/to/shopify-plugin
/path/to/shopify.theme-check-vscode/server.js

The detector should stay strict. A process merely containing the word shopify is not enough; it must be a Shopify CLI dev command.

Start/restart contract

Package scripts still win. Scaffolded Shopify apps, Hydrogen storefronts, and themes that wrap shopify theme dev in concurrently should keep their project-owned script as the launch surface.

The Shopify CLI fallbacks are only for roots the generic script path cannot start: pure themes and app roots without a usable dev script. First-run auth/store selection stays a log-surfaced caveat, because the CLI prompts for login and store choice and a detached spawn cannot answer.

Theme port fallback

shopify theme dev has no next-free-port fallback and dies with EADDRINUSE when 9292 is taken (Shopify/cli#5554). Before starting a theme, the extension probes the default bind and exports SHOPIFY_FLAG_PORT with the next free port when needed.

An environment variable was chosen instead of adding --port to argv because it reaches every wrapping shape: bare theme roots and dev scripts that nest the CLI under another tool. A user-written --port still wins because Shopify CLI gives explicit flags precedence over env.

Parallel starts reserve picked ports for the same 15s window as the spawn watchdog. The probe socket closes before Shopify binds, so the reservation prevents two selected theme worktrees from being handed the same apparently-free fallback port.

Planned phases

Shopify-specific actions

Use Shopify CLI output when the extension started the process.

  • Parse and store the local preview URL when it differs from localhost:PORT.
  • Parse the theme editor URL for shopify theme dev.
  • Parse the shareable preview link for shopify theme dev.
  • Add row actions such as Open Theme Editor and Copy Preview Link when the URLs are known.

App and Hydrogen polish

Handle multi-port Shopify sessions more deliberately.

  • shopify app dev --use-localhost uses a localhost proxy port by default and can be overridden with --localhost-port.
  • shopify app dev can also involve app and extension child servers. If the dashboard gets noisy, group or prioritize Shopify-owned listeners.
  • Hydrogen dev mirrors Oxygen/workerd behavior and may expose static assets on another localhost origin. Prefer the primary CLI dev URL when discoverable.

Open questions

  • Should pure Shopify theme starts prompt for --store if no previous store is configured, or should the spawn log remain the first-run setup surface?
  • Should the extension ever run shopify theme info --json, or should it avoid extra CLI calls during polling?
  • Should Shopify App and Hydrogen eventually get separate display colors, or is a shared Shopify green enough?

References

Clone this wiki locally