@shopify/cli-hydrogen 13.0.0 → 13.0.1

package/dist/assets/hydrogen/starter/CHANGELOG.md

@@ -1,5 +1,13 @@
 # skeleton
 
+## 2026.4.5
+
+### Patch Changes
+
+- Add an explicit `~` app alias to new Hydrogen projects. ([#3852](https://github.com/Shopify/hydrogen/pull/3852)) by [@andguy95](https://github.com/andguy95)
+
+  JavaScript projects use `jsconfig.json`, which is not reliably covered by Vite's native `resolve.tsconfigPaths` behavior. New projects now define Hydrogen's `~/` import convention directly in the Vite config so imports like `~/assets/favicon.svg` work in both TypeScript and JavaScript projects.
+
 ## 2026.4.4
 
 ### Patch Changes

package/dist/assets/hydrogen/starter/README.md

@@ -1,13 +1,13 @@
 # Hydrogen template: Skeleton
 
-Hydrogen is Shopify’s stack for headless commerce. Hydrogen is designed to dovetail with [Remix](https://remix.run/), Shopify’s full stack web framework. This template contains a **minimal setup** of components, queries and tooling to get started with Hydrogen.
+Hydrogen is Shopify’s stack for headless commerce. Hydrogen is designed to dovetail with [React Router](https://reactrouter.com/), the modern multi-strategy router for React. This template contains a **minimal setup** of components, queries and tooling to get started with Hydrogen.
 
 [Check out Hydrogen docs](https://shopify.dev/custom-storefronts/hydrogen)
-[Get familiar with Remix](https://remix.run/docs/en/v1)
+[Get familiar with React Router](https://reactrouter.com/start/framework/routing)
 
 ## What's included
 
-- Remix
+- React Router
 - Hydrogen
 - Oxygen
 - Vite
@@ -22,7 +22,7 @@ Hydrogen is Shopify’s stack for headless commerce. Hydrogen is designed to dov
 
 **Requirements:**
 
-- Node.js version 18.0.0 or higher
+- Node.js version 22.x or 24.x
 
 ```bash
 npm create @shopify/hydrogen@latest

package/dist/assets/hydrogen/starter/package.json

@@ -2,7 +2,7 @@
   "name": "skeleton",
   "private": true,
   "sideEffects": false,
-  "version": "2026.4.4",
+  "version": "2026.4.5",
   "type": "module",
   "scripts": {
     "build": "shopify hydrogen build --codegen",

package/dist/assets/hydrogen/starter/vite.config.ts

@@ -1,3 +1,4 @@
+import {fileURLToPath} from 'node:url';
 import {defineConfig} from 'vite';
 import {hydrogen} from '@shopify/hydrogen/vite';
 import {oxygen} from '@shopify/mini-oxygen/vite';
@@ -6,6 +7,11 @@ import {reactRouter} from '@react-router/dev/vite';
 export default defineConfig({
   plugins: [hydrogen(), oxygen(), reactRouter()],
   resolve: {
+    alias: {
+      // Vite's native tsconfig path resolver does not cover JavaScript
+      // projects that use jsconfig.json, so define Hydrogen's app alias here.
+      '~': fileURLToPath(new URL('./app', import.meta.url)),
+    },
     tsconfigPaths: true,
   },
   build: {

package/dist/commands/hydrogen/deploy.js

@@ -47,7 +47,7 @@ class Deploy extends Command {
     }),
     force: Flags.boolean({
       char: "f",
-      description: "Forces a deployment to proceed if there are uncommitted changes in its Git repository.",
+      description: "Forces a deployment to proceed if there are uncommitted changes in its Git repository, and skips confirmation prompts for non-preview environments.",
       default: false,
       env: "SHOPIFY_HYDROGEN_FLAG_FORCE",
       required: false
@@ -166,7 +166,7 @@ async function runDeploy(options) {
     env: envHandle,
     envBranch,
     environmentFile,
-    force: forceOnUncommittedChanges,
+    force,
     forceClientSourcemap = false,
     noVerify,
     lockfileCheck,
@@ -188,7 +188,7 @@ async function runDeploy(options) {
     if (error instanceof GitDirectoryNotCleanError) {
       isCleanGit = false;
     }
-    if (!forceOnUncommittedChanges && !isCleanGit) {
+    if (!force && !isCleanGit) {
       let errorMessage = "Uncommitted changes detected";
       let changedFiles = void 0;
       const nextSteps = [
@@ -355,11 +355,11 @@ ${changedFiles.trimEnd()}`;
     workerDir = workerDirFlag ?? workerDir;
   } else {
     const viteConfig = await getViteConfig(root, ssrEntry).catch(() => null);
-    const outputDirs = await resolveDeploymentOutputDirs({
+    const outputDirs = resolveDeploymentOutputDirs({
       root,
-      viteConfig,
-      assetsDir: assetsDirFlag,
-      workerDir: workerDirFlag
+      viteOutputDirs: viteConfig,
+      assetsDirFlag,
+      workerDirFlag
     });
     assetsDir = outputDirs.assetsDir;
     workerDir = outputDirs.workerDir;
@@ -388,7 +388,7 @@ ${changedFiles.trimEnd()}`;
     workerDir,
     overriddenEnvironmentVariables
   };
-  if (!isCI && !config.defaultEnvironment && (userProvidedEnvironmentTag || userChosenEnvironmentTag)) {
+  if (!isCI && !config.defaultEnvironment && (userProvidedEnvironmentTag || userChosenEnvironmentTag) && !force) {
     let chosenEnvironment = findEnvironmentByBranchOrThrow(
       deploymentData.environments,
       config.environmentTag
@@ -422,6 +422,7 @@ Continue?`.value
     }
   );
   let deployError = null;
+  let buildError = null;
   let resolveDeploy;
   let rejectDeploy;
   const deployPromise = new Promise((resolve, reject) => {
@@ -466,21 +467,26 @@ Continue?`.value
     config.buildCommand = buildCommand ?? DEFAULT_BUILD_COMMAND;
   } else {
     hooks.buildFunction = async (assetPath) => {
-      outputInfo(
-        outputContent`${colors.whiteBright("Building project...")}`.value
-      );
-      if (isClassicCompiler) {
-        throw new AbortError(REMIX_COMPILER_ERROR_MESSAGE);
+      try {
+        outputInfo(
+          outputContent`${colors.whiteBright("Building project...")}`.value
+        );
+        if (isClassicCompiler) {
+          throw new AbortError(REMIX_COMPILER_ERROR_MESSAGE);
+        }
+        await runBuild({
+          directory: root,
+          assetPath,
+          lockfileCheck,
+          sourcemap: true,
+          forceClientSourcemap,
+          useCodegen: false,
+          entry: ssrEntry
+        });
+      } catch (error) {
+        buildError = error;
+        throw error;
       }
-      await runBuild({
-        directory: root,
-        assetPath,
-        lockfileCheck,
-        sourcemap: true,
-        forceClientSourcemap,
-        useCodegen: false,
-        entry: ssrEntry
-      });
     };
   }
   const uploadStart = async () => {
@@ -542,27 +548,21 @@ Continue?`.value
     }
     resolveDeploy();
   }).catch((error) => {
-    rejectDeploy(deployError || error);
+    rejectDeploy(deployError || buildError || error);
   });
   return deployPromise;
 }
-async function resolveDeploymentOutputDirs({
+function resolveDeploymentOutputDirs({
   root,
-  viteConfig,
-  assetsDir,
-  workerDir
+  viteOutputDirs,
+  assetsDirFlag,
+  workerDirFlag
 }) {
-  const fallbackOutputDirs = {
-    assetsDir: "dist/client",
-    workerDir: "dist/server"
-  };
-  const viteOutputDirs = viteConfig ? {
-    assetsDir: relativePath(root, viteConfig.clientOutDir),
-    workerDir: relativePath(root, viteConfig.serverOutDir)
-  } : void 0;
+  const viteAssetsDir = viteOutputDirs && relativePath(root, viteOutputDirs.clientOutDir);
+  const viteWorkerDir = viteOutputDirs && relativePath(root, viteOutputDirs.serverOutDir);
   return {
-    assetsDir: assetsDir ?? viteOutputDirs?.assetsDir ?? fallbackOutputDirs.assetsDir,
-    workerDir: workerDir ?? viteOutputDirs?.workerDir ?? fallbackOutputDirs.workerDir
+    assetsDir: assetsDirFlag ?? viteAssetsDir ?? "dist/client",
+    workerDir: workerDirFlag ?? viteWorkerDir ?? "dist/server"
   };
 }
 function isHydrogenPreviewVersion(version) {

package/dist/commands/hydrogen/env/push.js

@@ -1,4 +1,5 @@
 import Command from '@shopify/cli-kit/node/base-command';
+import { Flags } from '@oclif/core';
 import { diffLines } from 'diff';
 import { commonFlags, flagsToCamelObject } from '../../../lib/flags.js';
 import { login } from '../../../lib/auth.js';
@@ -19,7 +20,17 @@ class EnvPush extends Command {
   static flags = {
     ...commonFlags.env,
     ...commonFlags.envFile,
-    ...commonFlags.path
+    ...commonFlags.path,
+    force: Flags.boolean({
+      char: "f",
+      description: "Push environment variable changes without confirmation.",
+      env: "SHOPIFY_HYDROGEN_FLAG_FORCE"
+    }),
+    "dry-run": Flags.boolean({
+      description: "Preview environment variable changes without pushing them.",
+      env: "SHOPIFY_HYDROGEN_FLAG_DRY_RUN",
+      exclusive: ["force"]
+    })
   };
   async run() {
     const { flags } = await this.parse(EnvPush);
@@ -27,8 +38,10 @@ class EnvPush extends Command {
   }
 }
 async function runEnvPush({
+  dryRun = false,
   env: envHandle,
   envFile,
+  force = false,
   path = process.cwd()
 }) {
   let validatedEnvironment;
@@ -114,8 +127,18 @@ async function runEnvPush({
       body: "No changes to your environment variables."
     });
     return;
-  } else {
-    const diff = diffLines(comparableRemoteVars, compareableLocalVars);
+  }
+  const diff = diffLines(comparableRemoteVars, compareableLocalVars);
+  if (dryRun) {
+    renderInfo({
+      body: outputContent`The following changes would be made to your environment variables for ${validatedEnvironment.name}:
+
+${outputToken.linesDiff(diff)}
+No changes were pushed because --dry-run was used.`.value
+    });
+    return;
+  }
+  if (!force) {
     const confirmPush = await renderConfirmationPrompt({
       confirmationMessage: "Yes, confirm changes",
       cancellationMessage: "No, make changes later",

package/dist/hooks/init.js

@@ -1,8 +1,8 @@
-import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
 import { outputNewline, outputDebug } from '@shopify/cli-kit/node/output';
-import { cwd, resolvePath, joinPath } from '@shopify/cli-kit/node/path';
+import { cwd, resolvePath } from '@shopify/cli-kit/node/path';
 import { renderWarning } from '@shopify/cli-kit/node/ui';
+import { isHydrogenProject, applyHydrogenCommandPolicy } from '../lib/hydrogen-command-policy.js';
 
 const hook = async function(options) {
   if (!options.id?.startsWith("hydrogen:") || options.id === "hydrogen:init") {
@@ -36,6 +36,9 @@ const hook = async function(options) {
     });
     process.exit(1);
   }
+  if (applyHydrogenCommandPolicy({ id: options.id, projectPath })) {
+    process.exit(1);
+  }
   if (commandNeedsVM(options.id, options.argv) && !process.execArgv.includes(EXPERIMENTAL_VM_MODULES_FLAG) && !(process.env.NODE_OPTIONS ?? "").includes(EXPERIMENTAL_VM_MODULES_FLAG)) {
     outputDebug(
       `Restarting CLI process with ${EXPERIMENTAL_VM_MODULES_FLAG} flag.`
@@ -50,18 +53,6 @@ const EXPERIMENTAL_VM_MODULES_FLAG = "--experimental-vm-modules";
 function commandNeedsVM(id = "", argv = []) {
   return id === "hydrogen:debug:cpu";
 }
-function isHydrogenProject(projectPath) {
-  try {
-    const require2 = createRequire(import.meta.url);
-    const { dependencies, scripts } = require2(
-      joinPath(projectPath, "package.json")
-    );
-    return !!dependencies?.["@shopify/hydrogen"] || // Diff examples don't have dependencies:
-    !!scripts?.dev?.includes("--diff");
-  } catch {
-    return false;
-  }
-}
 var init_default = hook;
 
 export { init_default as default };

package/dist/index.d.ts

@@ -126,6 +126,8 @@ declare class EnvPull extends Command {
 declare class EnvPush extends Command {
     static description: string;
     static flags: {
+        force: _oclif_core_lib_interfaces_parser_js.BooleanFlag<boolean>;
+        'dry-run': _oclif_core_lib_interfaces_parser_js.BooleanFlag<boolean>;
         path: _oclif_core_lib_interfaces_parser_js.OptionFlag<string | undefined, _oclif_core_lib_interfaces_parser_js.CustomOptions>;
         'env-file': _oclif_core_lib_interfaces_parser_js.OptionFlag<string, _oclif_core_lib_interfaces_parser_js.CustomOptions>;
         env: _oclif_core_lib_interfaces_parser_js.OptionFlag<string | undefined, _oclif_core_lib_interfaces_parser_js.CustomOptions>;

package/dist/lib/hydrogen-command-policy.js

@@ -0,0 +1,45 @@
+import { createRequire } from 'node:module';
+import { outputNewline } from '@shopify/cli-kit/node/output';
+import { joinPath } from '@shopify/cli-kit/node/path';
+import { renderError } from '@shopify/cli-kit/node/ui';
+
+function applyHydrogenCommandPolicy({
+  id,
+  projectPath
+}) {
+  if (!id || !isHydrogenProject(projectPath) || !isHydrogenCommandDisabled(projectPath, id)) {
+    return false;
+  }
+  outputNewline();
+  renderError({
+    headline: `\`shopify ${id.replace(/:/g, " ")}\` is not supported by this version of Hydrogen`,
+    body: "The installed version of @shopify/hydrogen disables this command.",
+    nextSteps: ["Use your framework or package tooling instead."]
+  });
+  return true;
+}
+function isHydrogenCommandDisabled(projectPath, id) {
+  try {
+    const require2 = createRequire(joinPath(projectPath, "package.json"));
+    const hydrogenPackageJson = require2("@shopify/hydrogen/package.json");
+    const disabledCommands = hydrogenPackageJson?.shopify?.cli?.disabledCommands;
+    return Array.isArray(disabledCommands) && disabledCommands.includes(id);
+  } catch {
+    return false;
+  }
+}
+function isHydrogenProject(projectPath) {
+  try {
+    const require2 = createRequire(import.meta.url);
+    const projectPackageJson = require2(joinPath(projectPath, "package.json"));
+    return [
+      projectPackageJson?.dependencies,
+      projectPackageJson?.devDependencies,
+      projectPackageJson?.peerDependencies
+    ].some((dependencies) => !!dependencies?.["@shopify/hydrogen"]);
+  } catch {
+    return false;
+  }
+}
+
+export { applyHydrogenCommandPolicy, isHydrogenCommandDisabled, isHydrogenProject };

package/dist/lib/vite-config.js

@@ -37,9 +37,7 @@ async function getViteConfig(root, ssrEntryFlag) {
     mode,
     mode
   );
-  const { appDirectory, serverBuildFile, routes } = getReactRouterOrRemixConfigFromVite(resolvedViteConfig);
-  const serverOutDir = resolvedViteConfig.environments.ssr?.build.outDir ?? resolvedViteConfig.build.outDir;
-  const clientOutDir = resolvedViteConfig.environments.client?.build.outDir ?? serverOutDir.replace(/server$/, "client");
+  const { appDirectory, clientOutDir, serverBuildFile, serverOutDir, routes } = getBuildConfigFromVite(resolvedViteConfig);
   const rollupOutput = resolvedViteConfig.build.rollupOptions.output;
   const { entryFileNames } = (Array.isArray(rollupOutput) ? rollupOutput[0] : rollupOutput) ?? {};
   const serverOutFile = joinPath(
@@ -68,33 +66,58 @@ async function getViteConfig(root, ssrEntryFlag) {
     }
   };
 }
-function getReactRouterOrRemixConfigFromVite(viteConfig) {
-  try {
-    const reactRouterConfig = getReactRouterConfigFromVite(viteConfig);
-    return reactRouterConfig;
-  } catch (error) {
-    const remixConfig = getRemixConfigFromVite(viteConfig);
-    return remixConfig;
+function resolveViteOutputDirs({
+  routingBuildDirectory,
+  serverEnvironmentOutDir,
+  clientEnvironmentOutDir,
+  buildOutDir
+}) {
+  if (routingBuildDirectory) {
+    return {
+      clientOutDir: joinPath(routingBuildDirectory, "client"),
+      serverOutDir: joinPath(routingBuildDirectory, "server")
+    };
   }
+  const serverOutDir = serverEnvironmentOutDir ?? buildOutDir;
+  const clientOutDir = clientEnvironmentOutDir && clientEnvironmentOutDir !== serverOutDir ? clientEnvironmentOutDir : serverOutDir.replace(/server$/, "client");
+  return {
+    clientOutDir,
+    serverOutDir
+  };
+}
+function getBuildConfigFromVite(viteConfig) {
+  const buildConfig = getReactRouterConfigFromVite(viteConfig) ?? getRemixConfigFromVite(viteConfig);
+  const { clientOutDir, serverOutDir } = resolveViteOutputDirs({
+    routingBuildDirectory: buildConfig?.buildDirectory,
+    serverEnvironmentOutDir: viteConfig.environments?.ssr?.build.outDir,
+    clientEnvironmentOutDir: viteConfig.environments?.client?.build.outDir,
+    buildOutDir: viteConfig.build.outDir
+  });
+  return {
+    ...buildConfig,
+    clientOutDir,
+    serverOutDir
+  };
 }
 function getReactRouterConfigFromVite(viteConfig) {
-  if (!viteConfig.__reactRouterPluginContext) {
-    throw new Error("Could not resolve React Router config");
-  }
-  const { appDirectory, serverBuildFile, routes } = viteConfig.__reactRouterPluginContext.reactRouterConfig;
+  if (!viteConfig.__reactRouterPluginContext) return;
+  const { appDirectory, buildDirectory, serverBuildFile, routes } = viteConfig.__reactRouterPluginContext.reactRouterConfig;
   return {
     appDirectory,
+    buildDirectory,
     serverBuildFile,
     routes
   };
 }
 function getRemixConfigFromVite(viteConfig) {
   const { remixConfig } = findHydrogenPlugin(viteConfig)?.api?.getPluginOptions() ?? {};
-  return remixConfig ? {
-    appDirectory: remixConfig.appDirectory,
-    serverBuildFile: remixConfig.serverBuildFile,
-    routes: remixConfig.routes
-  } : {};
+  if (remixConfig) {
+    return {
+      appDirectory: remixConfig.appDirectory,
+      serverBuildFile: remixConfig.serverBuildFile,
+      routes: remixConfig.routes
+    };
+  }
 }
 function findPlugin(config, name) {
   return config.plugins.find((plugin) => plugin.name === name);

package/oclif.manifest.json

@@ -353,7 +353,7 @@
         },
         "force": {
           "char": "f",
-          "description": "Forces a deployment to proceed if there are uncommitted changes in its Git repository.",
+          "description": "Forces a deployment to proceed if there are uncommitted changes in its Git repository, and skips confirmation prompts for non-preview environments.",
           "env": "SHOPIFY_HYDROGEN_FLAG_FORCE",
           "name": "force",
           "required": false,
@@ -805,6 +805,24 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "force": {
+          "char": "f",
+          "description": "Push environment variable changes without confirmation.",
+          "env": "SHOPIFY_HYDROGEN_FLAG_FORCE",
+          "name": "force",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "dry-run": {
+          "description": "Preview environment variable changes without pushing them.",
+          "env": "SHOPIFY_HYDROGEN_FLAG_DRY_RUN",
+          "exclusive": [
+            "force"
+          ],
+          "name": "dry-run",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -1693,5 +1711,5 @@
       ]
     }
   },
-  "version": "13.0.0"
+  "version": "13.0.1"
 }

package/package.json

@@ -4,7 +4,7 @@
     "access": "public",
     "@shopify:registry": "https://registry.npmjs.org"
   },
-  "version": "13.0.0",
+  "version": "13.0.1",
   "license": "MIT",
   "type": "module",
   "repository": {