hydrogen/docs/contributing.md

Contributing to Hydrogen

Requirements:

• Node v14+
• Yarn

git clone git@github.com:Shopify/hydrogen.git
yarn

# Start the library dev server first
yarn dev-lib

# In a new tab, start the dev server
yarn dev-server

Visit the dev environment at http://localhost:3000.

To make changes to the starter template, edit the files in packages/dev.

To modify Hydrogen framework, components, and hooks, edit the files in packages/hydrogen.

You can inspect Vite plugin transformations by visiting http://localhost:3000/__inspect.

Context

Hydrogen is a Yarn v1 monorepo. It consists of several key packages:

• hydrogen: The Hydrogen React framework & SDK
• dev: The starter template and local development playground
• create-hydrogen-app: The CLI used to scaffold new projects
• playground: Test cases used for both manual testing and automated end-to-end tests

For more information, check out the following resources:

• Decision Log
• Principles & Assumptions

Formatting and Linting

Hydrogen uses ESLint for linting and Prettier for code formatting.

Yorkie is used to install a Git precommit hook, which lints and formats staged commits automatically.

To manually lint and format:

yarn lint
yarn format

Commit Messages

Commit messages must follow the commit message convention so that changelogs can be more easily generated. Commit messages are automatically validated before commit (by invoking Git Hooks via yorkie).

Headless components

If you are building or making changes to a component, be sure to read What are headless components? and How to build headless components.

GraphQL Types

If you make changes to or add any new .graphql files within Hydrogen, you will need to run the following commands in order to generate the type definitions and Graphql documents for the newly added/updated files:

cd packages/hydrogen
yarn graphql-types

Running a local version of Hydrogen in a Hydrogen app

Caution: You must use yarn for all commands, due to issues with NPM and dependencies, even if the prompt tells you to use npm.

Follow these instructions to create your own Hydrogen app using the local development version of the Hydrogen framework.

Before running any commands, be sure to build the Hydrogen lib with yarn dev-lib or yarn build.

cd packages/create-hydrogen-app && yarn link

This makes the executable create-hydrogen available globally.

Next, choose an option below.

Option 1: localdev package

This option creates a new Hydrogen app similar to dev directly in the monorepo under packages/localdev. This directory is ignored in git, so your changes will not be tracked.

create-hydrogen packages/localdev
# when prompted, use `localdev` for the package name

Then run your app:

yarn workspace localdev dev

Option 2: Standalone package

Caution: This requires you to have a directory structure on your machine like ~/src/github.com/Shopify/*, and it requires you to create your custom Hydrogen app in a namespace similar to ~/src/github.com/<namespace>/<your hydrogen app here>.

1. In the directory you want to create your Hydrogen app, run LOCAL=true create-hydrogen and answer the prompts.
2. Run cd <your app>.
3. Run yarn or npm i --legacy-peer-deps.
4. Optional. Replace default shopify.config.js with your own storefront credentials.
5. Run yarn dev or npm run dev to start your dev server.
6. Open the dev server in your browser at http://localhost:3000.

If you make changes to core Hydrogen packages, then you'll need to delete node_modules, install dependencies again and start the server as mentioned above.

Testing

Hydrogen is tested with unit tests for components, hooks and utilities. It is also tested with a suite of end-to-end tests inspired by Vite's playground tests.

Run unit tests with:

yarn test

# Optionally watch for changes
yarn test --watch

Run end-to-end tests with:

yarn test-e2e

# Optionally watch for changes
yarn test-e2e --watch

Debugging tests in Github Actions

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.

End-to-end tests

End-to-end tests are powered by Playwright and Chromium. They are modeled closely after how Vite handles E2E tests.

Each mini-project under packages/playground contains a tests folder. You are welcome to modify an existing project or add a new project if it represents a different framework scenario, e.g. using a specific CSS framework or integration.

You can run a single E2E test by passing a keyword, which is matched using regex, e.g. yarn test-e2e server will run the server-components test.

Releasing new versions

To release a new version of Hydrogen NPM packages, Shopifolk should follow these instructions:

First, ensure all changes have been merged to main.

Then:

git checkout main && git pull
yarn bump-version

Important: Until our official release, we will only release minor and patch updates. This means that breaking changes will be included in minor releases. Once we officially launch Hydrogen, we'll switch to 1.0.0 and follow a normal semantic release pattern.

When finished, push up your changes.

Next, visit the Shipit page for Hydrogen and click Deploy.

After Shipit has released your version, visit the releases page on GitHub, click on the version number you just released, and select "Create release from tag." Then, select "Auto-generate release notes." At this point, edit the release notes as you see fit (e.g. call out any breaking changes or upgrade guides). Finally, click "Publish release."