Shopify · frehner · Mar 3, 2023 · Sep 27, 2022 · Sep 28, 2022 · Sep 28, 2022
diff --git a/.eslintignore b/.eslintignore
@@ -1,4 +1,9 @@
 build
 node_modules
 bin
-*.d.ts
+*.d.ts
+dist
+coverage
+packages/hydrogen-react/codegen.ts
+packages/hydrogen-react/vite.config.ts
+packages/hydrogen-react/vitest.setup.ts
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -17,9 +17,22 @@ body:
       label: What is the location of your example repository?
     validations:
       required: false
+  - type: dropdown
+    attributes:
+      label: Which package or tool is having this issue?
+      description: Which package or tool is having this issue?
+      options:
+        - Hydrogen
+        - CLI
+        - hydrogen-react
+        - Oxygen
+        - Storefront API
+        - Other / I don't know
+    validations:
+      required: true
   - type: input
     attributes:
-      label: What version of Hydrogen are you using?
+      label: What version of that package or tool are you using?
     validations:
       required: true
   - type: input

diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -15,4 +15,4 @@ contact_links:
       use the Discussions for this instead of the issues tab 🙂.
   - name: 💬 Hydrogen Discord Channel
     url: https://discord.gg/shopifydevs
-    about: Interact with other people using Hydrogen
+    about: Interact with other people using Hydrogen.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -49,6 +49,7 @@ Fixes #0000 <!-- link to issue if one exists -->
 - [ ] I've considered possible cross-platform impacts (Mac, Linux, Windows)
 - [ ] I've added a [changeset](CONTRIBUTING.md#changesets) if this PR contains user-facing or noteworthy changes
 - [ ] I've added [tests](CONTRIBUTING.md#testing) to cover my changes
+- [ ] I've added or updated the documentation
 
 <!--
  THANK YOU for your pull request! Members from the Hydrogen team will review these changes and provide feedback as soon as they are available.

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -48,7 +48,7 @@ jobs:
       - name: 📥 Install dependencies
         run: npm ci
 
-      - name: 🔬 Lint
+      - name: 🔬 Check Formatting
         run: npm run format:check
 
   typecheck:

diff --git a/.gitignore b/.gitignore
@@ -6,3 +6,128 @@ node_modules
 .turbo
 .cache
 **/dist
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+.env.test
+!**/playground/**/.env
+
+# parcel-bundler cache (https://parceljs.org/)
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+# VSCode launch configs
+.vscode/
+!examples/*/.vscode/
+!templates/*/.vscode/
+
+# yarn v2
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.*
+
+# User localdev package
+packages/localdev
+
+.DS_Store
+
+temp
+snow-devil
+artifacts
+
+yarn.lock
+!/yarn.lock
diff --git a/.graphqlrc.yml b/.graphqlrc.yml
@@ -1,3 +1,3 @@
 # This file should be part of the demo-store template, but the GraphQL VSCode plugin doesn't actually look at folders when searching for this file, so it has to live at the root.
 # There is a duplicated file in templates/demo-store/ , and it's kept there so that if someone were to spin up the demo-store on their own then it would be included and "just work"
-schema: node_modules/@shopify/hydrogen-react/storefront.schema.json
+schema: packages/hydrogen-react/storefront.schema.json
diff --git a/.prettierignore b/.prettierignore
@@ -1,3 +1,6 @@
 node_modules
 build
 packages/cli/oclif.manifest.json
+dist
+packages/hydrogen-react/storefront.schema.json
+coverage
diff --git a/README.md b/README.md
@@ -1,12 +1,12 @@
 <p align="center">
     <a href="https://hydrogen.shopify.dev"><img src="./.github/images/hydrogen-logo.svg" alt="Hydrogen Logo"/></a>
 </p>
-<p align="center">
-    <a href="https://www.npmjs.com/package/@shopify/hydrogen"><img src="https://img.shields.io/npm/v/@shopify/hydrogen.svg?sanitize=true" alt="Version"></a>
-    <a href="https://github.com/Shopify/hydrogen/blob/main/LICENSE.md"><img src="https://img.shields.io/npm/l/@shopify/hydrogen.svg?sanitize=true" alt="License"></a>
-    <a href="https://npmcharts.com/compare/@shopify/hydrogen?minimal=true"><img src="https://img.shields.io/npm/dm/@shopify/hydrogen.svg?sanitize=true" alt="Downloads"></a>
- </p>
+<div style="text-align: center;">
+
+[![MIT License](https://img.shields.io/github/license/shopify/hydrogen)](LICENSE.md)
+[![npm downloads](https://img.shields.io/npm/dm/@shopify/hydrogen.svg?sanitize=true)](https://npmcharts.com/compare/@shopify/hydrogen?minimal=true)
 
+</div>
 <div align="center">
 
 📚 [Docs](https://shopify.dev/custom-storefronts/hydrogen) | 🗣 [Discord](https://discord.gg/Hefq6w5c5d) | 💬 [Discussions](https://github.com/Shopify/hydrogen/discussions) | 📝 [Changelog](./packages/hydrogen/CHANGELOG.md)
@@ -17,49 +17,51 @@ Hydrogen is a set of tools, utilities, and best-in-class examples for building a
 
 Hydrogen legacy v1, which is not built on Remix, is available here: https://github.com/Shopify/hydrogen-v1
 
-Get started with Hydrogen with the instructions below ⬇️
-
-## Getting Started
+## Getting started with Hydrogen
 
 **Requirements:**
 
 - Node.js version 16.14.0 or higher
-- `npm`, `yarn` or `pnpm`
+- `npm` (or your package manager of choice, such as `yarn` or `pnpm`)
+
+1. Install the latest version of Hydrogen:
 
-**Installation:**
+   ```bash
+   npm create @shopify/hydrogen@latest
+   ```
 
-```bash
-# Using `npm`
-npm create @shopify/hydrogen@latest
+1. Run the local development server:
 
-# Using `yarn`
-yarn create @shopify/hydrogen@latest
+   ```bash
+   npm install
+   npm run dev
+   ```
 
-# Using `pnpm`
-pnpm create @shopify/hydrogen@latest
-```
+1. Open your new Hydrogen app running at http://localhost:3000.
 
-**Running locally:**
+See the complete [Hydrogen docs](https://shopify.dev/custom-storefronts/hydrogen).
 
-1. Start a development server
+## Packages in this repo
 
-```bash
-# Using `npm`
-npm install
-npm run dev
+Hydrogen is organized as a [monorepo](https://monorepo.tools/), which includes multiple packages that can be used together.
 
-# Using `yarn`
-yarn install
-yarn dev
+| Package                                                  | Latest version                                                                                                                              | Description                                                                                                    | Readme                                     |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| [`@shopify/hydrogen`](/packages/hydrogen/)               | [![Latest badge](https://img.shields.io/npm/v/@shopify/hydrogen/latest.svg)](https://www.npmjs.com/package/@shopify/hydrogen)               | Opinionated tools, utilities, and best-in-class examples for building a commerce application with Remix.       | [Readme](/packages/hydrogen#readme)        |
+| [`@shopify/hydrogen-react`](/packages/hydrogen-react/)   | [![Latest badge](https://img.shields.io/npm/v/@shopify/hydrogen-react/latest.svg)](https://www.npmjs.com/package/@shopify/hydrogen-react)   | Unopionated and performant library of Shopify-specific commerce components, hooks, and utilities.              | [Readme](/packages/hydrogen-react#readme)  |
+| [`@shopify/cli-hydrogen`](/packages/cli/)                | [![Latest badge](https://img.shields.io/npm/v/@shopify/cli-hydrogen/latest.svg)](https://www.npmjs.com/package/@shopify/cli-hydrogen)       | Hydrogen extension for [Shopify CLI](https://shopify.dev/docs/custom-storefronts/hydrogen/cli).                | [Readme](/packages/cli#readme)             |
+| [`@shopify/create-hydrogen`](/packages/create-hydrogen/) | [![Latest badge](https://img.shields.io/npm/v/@shopify/create-hydrogen/latest.svg)](https://www.npmjs.com/package/@shopify/create-hydrogen) | Generate a new Hydrogen project from the command line.                                                         | [Readme](/packages/create-hydrogen#readme) |
+| [`@shopify/remix-oxygen`](/packages/remix-oxygen/)       | [![Latest badge](https://img.shields.io/npm/v/@shopify/remix-oxygen/latest.svg)](https://www.npmjs.com/package/@shopify/remix-oxygen)       | Remix adapter enabling Hydrogen to run on the [Oxygen](https://shopify.dev/custom-storefronts/oxygen) runtime. | [Readme](/packages/remix-oxygen#readme)    |
 
-# Using `pnpm`
-pnpm install
-pnpm dev
-```
+## Versioning
 
-2. Visit the development environment running at http://localhost:3000.
+Hydrogen and hydrogen-react are tied to specific versions of the [Shopify Storefront API](https://shopify.dev/api/storefront), which follows [calver](https://calver.org/).
 
-Learn more about [getting started with Hydrogen](https://shopify.dev/custom-storefronts/hydrogen).
+For example, if you're using Storefront API version `2023-01`, then Hydrogen and hydrogen-react versions `2022.1.x` are fully compatible.
+
+If the Storefront API version update includes breaking changes, then Hydrogen and hydrogen-react may also include breaking changes. Because the API version is updated every three months, breaking changes could occur every three months.
+
+Learn more about API [release schedules](https://shopify.dev/api/usage/versioning#release-schedule) at Shopify.
 
 ## Contributing to Hydrogen
 
@@ -68,9 +70,3 @@ Learn more about [getting started with Hydrogen](https://shopify.dev/custom-stor
 ## Other handy links
 
 [Learn more about Hydrogen](https://shopify.dev/hydrogen).
-
-👷‍♀️ Add `npm` packages to your project:
-
-- [`@shopify/hydrogen`](https://www.npmjs.com/package/@shopify/hydrogen)
-- [`@shopify/cli-hydrogen`](https://www.npmjs.com/package/@shopify/cli-hydrogen)
-- [`@shopify/remix-oxygen`](https://www.npmjs.com/package/@shopify/remix-oxygen)