Requirements:
- Node.js version 16.14.0 or higher
Run the following commands to get started working on Hydrogen.
Command | Description |
---|---|
git clone [email protected]:Shopify/hydrogen.git |
Clones the repo to your local computer |
npm install |
Installs the dependencies with npm |
npm run dev |
Runs the dev command in all workspaces |
npm run build |
build s packages for production distribution |
Hydrogen is a monorepo built with Turborepo and consists of the following workspaces:
templates
: Full working implementations of a Hydrogen storefront, such as thedemo-store
templatepackages/hydrogen
: The hooks, components, and utilities provided by Hydrogenpackages/remix-oxygen
: A Remix runtime adapter for Oxygenpackages/cli
: A plugin for the Shopify CLI to provide specific commands for working on Hydrogen storefronts
Running npm run dev
at the root of the monorepo is the most common way to develop in Hydrogen. With this task running, each package will be rebuilt when files change and you can preview the results in the templates/demo-store
template at (http://localhost:3000)[http://localhost:3000].
The Readme.md
files in the directories of individual packages and templates contain more specific information for developing in that workspace.
The Hydrogen monorepo provides commands for linting and formatting, and uses Yorkie to run checks on staged commits automatically.
Command | Description |
---|---|
npm run typecheck |
Checks source-code for invalid TypeScript |
npm run lint |
Lints the code with ESLint |
npm run format |
Formats the code with prettier |
Hydrogen follows common React naming conventions for filenames, component names, classes, constants, and more.
- For component filenames and class names, always use
PascalCase
. - For non-component filenames, always use fully lowercase
kebab-case
. - For test filenames, append
.test
before the file extension. - When declaring instances of components, always use
camelCase
. - When declaring exported constants, always use
SCREAMING_SNAKE_CASE
.
✅ Valid | 🚫 Invalid | |
---|---|---|
Component filenames: | ProductTitle.tsx ProductTitle.tsx |
productTitle.tsx product_title.tsx product-title.tsx |
Non-component filenames: | client.ts handle-event.ts |
Client.ts handleEvent.ts handle_event.ts |
Test filenames: | ExternalVideo.test.tsx |
ExternalVideo-test.tsx ExternalVideo_test.tsx ExternalVideoTest.tsx |
Component classes: | <AddToCartButton /> |
<addToCartButton /> |
Component instances: | const cartSelector = <CartSelector /> |
const CartSelector = <CartSelector /> const cart_selector = <CartSelector /> |
Exported constants: | export const CART_COOKIE_TTL_DAYS = 14; |
export const CartCookieTTLDays = 14; export const cart_cookie_ttl_days = 14; |
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 |
---|---|
npm 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.
Considerations:
- You can use markdown in your changeset to include code examples, headings, and more. However, please use plain text for the first line of your changeset. The formatting of the GitHub release notes does not support headings as the first line of the changeset.
When merging PRs, please select the Squash and Merge option, which consolidates all the changes from the PR into a single commit. This helps reduce the commit noise in our Git repository.
Hydrogen tests are run using vitest. You can run the tests with the following commands.
Command | Description |
---|---|
npm run test |
Run the tests once |
npm run test:watch |
Run the tests once and re-run them when files are saved |
Tests that fail only in CI can be difficult and time-consuming to debug. If you find yourself in this situation, you can use tmate to pause the Github Action on a given step and ssh
into the container. Once in the container you can use vim
, inspect the file system and try determining what might be diverging from running tests on your local computer and leading to the failure.
- Add the following
step
in your Github Actions workflow:
- name: Setup tmate session
uses: mxschmitt/action-tmate@v3
- Commit and push your changes to Github.
- The testing Github Action will run automatically and you will see it paused with both a Web Shell address and SSH address.
- Copy and paste the SSH address into your terminal.
Consider what commerce concepts you’ll be working with for the component or abstraction. Hydrogen is coupled to the Shopify Storefront API; examining how a commerce primitive is represented there -what data is essential in the API and which other resources use them- is important.
Consider what a sensible default would be for the component or abstraction. Look at high GMV commerce websites and check if there is a common pattern for how this information is displayed -be sure to examine both Shopify and non-Shopify storefronts. Browse through the Liquid documentation, look forfilters related to your component or abstraction, and consider what defaults those provide and the customizations they support.
Consider how to provide the best developer experience when using this component or abstraction. Hydrogen must be fun and easy to use, with good ergonomics, types and tooling. Developers should be delighted when they use Hydrogen. To quote Tobi Lütke: “Delight works by taking your experience minus your expectation, and if the end result is a positive number, you are delighted by that margin.”