chore: scaffold hydrogen core module

CONTRIBUTING.md

@@ -12,19 +12,18 @@ Run the following commands to get started working on Hydrogen.
 | ----------------------------------------------- | --------------------------------------------- |
 | `git clone git@github.com:Shopify/hydrogen.git` | Clones the repo to your local computer        |
 | `pnpm install`                                  | Installs the dependencies with `pnpm`         |
-| `ppnpm run dev`                                  | Runs the `dev` command in all packages        |
+| `ppnpm run dev`                                 | Runs the `dev` command in all packages        |
 | `pnpm run build`                                | `build`s packages for production distribution |
 
 ### Shopify Contributors
 
 If you have access to Shopify's `dev` CLI tool, you can use these commands instead:
 
-| Command      | Description                                                |
-| ------------ | ---------------------------------------------------------- |
+| Command      | Description                                                                     |
+| ------------ | ------------------------------------------------------------------------------- |
 | `dev up`     | Sets up the development environment (installs dependencies and builds packages) |
-| `dev server` | Starts the skeleton template dev server                    |
-| `dev watch`  | Starts a server to automatically rebuild changes in packages upon saving |
-
+| `dev server` | Starts the skeleton template dev server                                         |
+| `dev watch`  | Starts a server to automatically rebuild changes in packages upon saving        |
 
 > **Note:** When running `dev up`, if prompted about git hooks, select **"no"** to preserve the existing Husky hooks configuration. The project uses Husky for pre-commit hooks, and overriding this would disable important checks.
 
@@ -40,8 +39,9 @@ Hydrogen is a monorepo built with [Turborepo](https://turbo.build/) and consists
 
 - `packages/hydrogen`: Opinionated [Remix](https://remix.run) components, hooks, and utilities provided by Hydrogen
 - `packages/hydrogen-react`: Platform-agnostic components, hooks, and utilities. This package is used by Hydrogen and published on its own for use by other React-based frameworks.
-- `packages/create-hydrogen`: Package scripts to create new Hydrogen apps from the command line.
+- `packages/hydrogen-core`: Framework-agnostic core utilities shared across Hydrogen packages.
 - `packages/hydrogen-codegen`: GraphQL <> TypeScript code generator for Storefront API queries.
+- `packages/create-hydrogen`: Package scripts to create new Hydrogen apps from the command line.
 - `packages/remix-oxygen`: A [Remix](https://remix.run) runtime adapter for [Oxygen](https://shopify.dev/custom-storefronts/oxygen), Shopify’s serverless hosting platform.
 - `packages/cli`: A plugin for the [Shopify CLI](https://github.com/Shopify/cli) to provide specific commands for working on Hydrogen storefronts.
 - `templates`: Full working implementations of Hydrogen storefronts. Used for scaffolding new starter Hydrogen apps, testing, and feature development.
@@ -54,8 +54,8 @@ The `Readme.md` files in the directories of individual packages and templates co
 
 The Hydrogen monorepo provides commands for linting and formatting, and uses [Husky](https://typicode.github.io/husky/) to run checks on staged commits automatically.
 
-| Command             | Description                               |
-| ------------------- | ----------------------------------------- |
+| Command              | Description                               |
+| -------------------- | ----------------------------------------- |
 | `pnpm run typecheck` | Checks source-code for invalid TypeScript |
 | `pnpm run lint`      | Lints the code with ESLint                |
 | `pnpm run format`    | Formats the code with prettier            |
@@ -83,8 +83,8 @@ Hydrogen follows common React naming conventions for filenames, component names,
 
 If you are contributing a user-facing or noteworthy change to Hydrogen that should be added to the changelog, you should include a changeset with your PR by running the following command.
 
-| Command                 | Description             |
-| ----------------------- | ----------------------- |
+| Command                  | Description             |
+| ------------------------ | ----------------------- |
 | `pnpm run changeset add` | Add a changeset locally |
 
 Follow the prompts to select which package(s) are affected by your change, and whether the change is a major, minor or patch change. This will create a file in the `.changesets` directory of the repo. This change should be committed and included with your PR.
@@ -101,8 +101,8 @@ When merging PRs, please select the **Squash and Merge** option, which consolida
 
 Hydrogen tests are run using [vitest](https://vitest.dev). You can run the tests with the following commands.
 
-| Command              | Description                                             |
-| -------------------- | ------------------------------------------------------- |
+| Command               | Description                                             |
+| --------------------- | ------------------------------------------------------- |
 | `pnpm run test`       | Run the tests once                                      |
 | `pnpm run test:watch` | Run the tests once and re-run them when files are saved |
 
@@ -180,6 +180,7 @@ We use the ejson file `secrets.ejson` to store all our secrets. You can add new
 Secrets can only be decrypted if you have the private key. If you are new to the Shopify Hydrogen team, ask one of the other team members to send you a hush link with the private key.
 
 Once you have the hush link, paste this command in your terminal **WITHOUT running it yet**, then copy the private key value (from the hush link) to your clipboard and run the command:
+
 ```
 ./scripts/setup-ejson-private-key.sh
 ```

package.json

@@ -82,6 +82,7 @@
     "@shopify/cli": "3.91.1",
     "@total-typescript/ts-reset": "^0.6.1",
     "@types/eslint": "9.6.1",
+    "@types/node": "catalog:",
     "@types/semver": "^7.5.8",
     "@typescript-eslint/eslint-plugin": "8.42.0",
     "@typescript-eslint/parser": "8.42.0",

packages/hydrogen-core/README.md

@@ -0,0 +1,9 @@
+# @shopify/hydrogen-core
+
+Framework-agnostic core utilities shared across Hydrogen packages. This package provides foundational helpers that are not tied to any specific rendering framework, making them reusable across the Hydrogen ecosystem.
+
+[Check out the docs](https://shopify.dev/custom-storefronts/hydrogen)
+
+## Contributing
+
+Interested in contributing? [Read our contributing guide](../../CONTRIBUTING.md)

packages/hydrogen-core/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@shopify/hydrogen-core",
+  "version": "0.0.0",
+  "description": "Framework-agnostic core utilities shared across Hydrogen packages",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "@shopify:registry": "https://registry.npmjs.org"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Shopify/hydrogen",
+    "directory": "packages/hydrogen-core"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {},
+  "peerDependencies": {},
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "@types/node": "catalog:",
+    "vitest": "^3.2.4"
+  }
+}

packages/hydrogen-core/skills/hydrogen-core-docs/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: hydrogen-core-docs
+description: >
+  Guide for working with framework-agnostic core utilities
+  shared across Hydrogen.
+  Use when importing from `@shopify/hydrogen/core` or `@shopify/hydrogen-core`.
+---
+
+# @shopify/hydrogen-core
+
+`@shopify/hydrogen-core` provides framework-agnostic core utilities shared across the Hydrogen ecosystem. It can also be used from `@shopify/hydrogen` using the `core` entrypoint.
+
+## Public API
+
+### Mock Shop Utilities
+
+- `MOCK_SHOP_DOMAIN` — The domain string for Shopify's mock shop
+- `isMockShop(domain: string): boolean` — Returns `true` if the given domain contains the mock shop domain
+
+## Architecture
+
+This package is the lowest layer in the Hydrogen package hierarchy. It contains utilities that:
+
+- Have **no framework dependencies** (no React, no Remix, no Node-specific APIs)
+- Are shared by multiple Hydrogen packages (e.g., `@shopify/hydrogen`, `@shopify/cli-hydrogen`)
+- Need to be independently testable and tree-shakeable

packages/hydrogen-core/src/index.ts

@@ -0,0 +1 @@
+export * from './mock-shop';

packages/hydrogen-core/src/mock-shop.test.ts

@@ -0,0 +1,20 @@
+import {describe, it, expect} from 'vitest';
+import {isMockShop, MOCK_SHOP_DOMAIN} from './mock-shop';
+
+describe('isMockShop', () => {
+  it('returns true for the exact mock.shop domain', () => {
+    expect(isMockShop(MOCK_SHOP_DOMAIN)).toBe(true);
+  });
+
+  it('returns true when mock.shop appears within a URL', () => {
+    expect(isMockShop('https://mock.shop/api/graphql')).toBe(true);
+  });
+
+  it('returns false for a real shop domain', () => {
+    expect(isMockShop('my-store.myshopify.com')).toBe(false);
+  });
+
+  it('returns false for an empty string', () => {
+    expect(isMockShop('')).toBe(false);
+  });
+});

packages/hydrogen-core/src/mock-shop.ts

@@ -0,0 +1,3 @@
+export const MOCK_SHOP_DOMAIN = 'mock.shop';
+export const isMockShop = (domain: string): boolean =>
+  domain.includes(MOCK_SHOP_DOMAIN);

packages/hydrogen-core/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src/**/*.ts", "globals.d.ts"],
+  "compilerOptions": {
+    "noEmit": false,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "outDir": "dist",
+    "rootDir": ".",
+    "moduleResolution": "bundler",
+    "types": ["node"]
+  }
+}

packages/hydrogen-core/tsup.config.ts

@@ -0,0 +1,17 @@
+import {defineConfig, Options} from 'tsup';
+
+const sharedConfig: Options = {
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  format: ['esm'],
+};
+
+export default defineConfig([
+  {
+    ...sharedConfig,
+    dts: true,
+    entry: ['src/index.ts'],
+    tsconfig: 'tsconfig.json',
+  },
+]);

packages/hydrogen-core/vitest.config.ts

@@ -0,0 +1,8 @@
+import {defineConfig} from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: false,
+    environment: 'happy-dom',
+  },
+});

pnpm-workspace.yaml

@@ -4,6 +4,7 @@ packages:
   - packages/cli
   - packages/create-hydrogen
   - packages/hydrogen-codegen
+  - packages/hydrogen-core
   - packages/hydrogen-react
   - packages/hydrogen
   - packages/mini-oxygen