Project Structure

Hydrogen is a set of tools, utilities, and best-in-class examples for building a commerce application on top of Remix. A Hydrogen project's structure is similar to what you find in any Remix application.

After setting up a new Hello World template, your app has the following directory structure:

The server.js file is the main application entry point. After handleServer() is called within server.js, you can manipulate the Response object before it's returned to the client. Here you can add headers or other custom response logic.

server.js is also where the Storefront API client and markets configuration is set up.

The default server.js file is setup to work with Oxygen. If you choose deploy to another hosting provider, you'll need to update this file to support that platform.

The .env file is where you define environment variables for local development. These variables aren't used in production. Make sure to update the variables for your unique storefront. You can also add your own custom variables for your application. Learn more about environment variables in Hydrogen.

The following is the default .env file:

The public directory is where static assets are stored. Everything within the directory is uploaded to Shopify's CDN on the deploy to Oxygen. It's the recommended location for images and other static files that don't change.

The root.jsx file is the root route of any Remix application. Setup the base document here, including any custom <link>, <meta>, or <script> tags that are global to the application. The root route is also where a Remix loader should be defined for any global data that's necessary for the entire application. For example, the storefront name, description, and cart should be queried from here.

You can also use root.jsx to define any common UI for the app, such as a responsive layout.

For more information, refer to the Remix documentation on the root route.

The routes directory is where all routes are defined in a Remix application. Refer to the Remix documentation on routing conventions.

Remix uses app/entry.client.jsx as the entry point for the browser bundle. This module gives you full control over the "hydrate" step after JavaScript loads into the document. Refer to the Remix documentation on entry.client for more information.

Remix uses app/entry.server.jsx to generate the HTTP response when rendering on the server. The default export of this module is a function that lets you create the response, including HTTP status, headers, and HTML, giving you full control over the way the markup is generated and sent to the client. Refer to the Remix documentation on entry.server for more information.

This file may change based on the hosting platform you're using in order to support React streaming server-side rendering.

By convention, Hydrogen uses the app/components directory to store reusable React components in the application. This is necessary because all jsx files within app/routes correspond to the application's URL paths.

The dist folder is where both the server and client artifacts are generated. It should be added to your .gitignore file.

This file has a few build and development configuration options, but does not actually run on your server. Refer to the Remix documentation on remix.config for more information.