If you want to use Hydrogen but prefer not to use Oxygen, you can deploy Hydrogen to various hosting platforms that support Remix. This guide walks you through adapting your Hydrogen app for an alternative hosting runtime.
Note: While Hydrogen and Remix are designed to run on any platform, some features of Hydrogen rely on Oxygen's Workers platform and support for certain Web APIs like Cache. This is an advanced guide that covers the areas to consider when hosting Hydrogen apps on your own architecture, and assumes you are comfortable with using Remix's adapters or creating your own. The steps in this guide are not supported by Shopify.
To adapt your Hydrogen app for an alternative hosting runtime, follow these steps:
First, consult the hosting platform's documentation and install the required CLI for running projects locally. For adapters that are officially supported by Remix, you may use the Remix CLI for local development.
Update your local package.json#scripts with the matching commands for the hosting platform, as seen in the platform's Remix template:
{
"scripts": {
"dev": "<platform-specific-dev-command>",
"build": "<platform-specific-build-command>",
"start": "<platform-specific-start-command>"
}
}Every hosting platform needs a single entrypoint into your app to execute it. Remix also needs to know about this entrypoint to run and bundle your app (Learn more in Remix’s documentation). Hydrogen’s entrypoint is created in the server.js file, in the root of your application.
Refer to the hosting platform's documentation, or Remix’s template for the platform, to determine the entrypoint contents required. This file will typically import a function from the platform-specific Remix adapter and use it to handle requests.
In addition to configuring Remix, Hydrogen may also require some configuration depending on where you deploy to. In particular, the createStorefrontClient function in the server.js file expects certain Headers in your Request object (requestGroupId, buyerIp, and cookie) as well as a waitUntil function. Refer to the createStorefrontClient reference documentation to learn more about the expected signature, and to the Workers platform documentation to learn about waitUntil.
Now that you've made the necessary changes to your Hydrogen app, it's time to deploy it to the alternative hosting platform. Follow the deployment instructions provided by the hosting platform to deploy your app.
After adapting your Hydrogen app for an alternative hosting runtime, consider the following next steps to ensure a successful deployment and seamless operation:
If the alternative hosting runtime does not support the Cache API, explore substitute caching solutions. Some popular options include:
-
Redis: Redis is an open-source, in-memory data structure store that can be used as a cache, database, or message broker. It supports various data structures like strings, hashes, lists, sets, and more.
-
Memcached: Memcached is a high-performance, distributed memory object caching system that is designed to speed up dynamic web applications by reducing database load.
-
Amazon ElastiCache: Amazon ElastiCache is a fully managed in-memory data store and cache service by AWS. It supports both Redis and Memcached engines, providing a seamless and scalable caching solution.
- Website: [aws.amazon.com/elasticache
-
Google Cloud Memorystore: Google Cloud Memorystore is a fully managed in-memory data store service built on Google Cloud Platform. It offers both Redis and Memcached instances for caching purposes.
-
Azure Cache for Redis: Azure Cache for Redis is a fully managed, dedicated Redis cache service provided by Microsoft Azure. It offers high throughput and low latency access to data while supporting various Redis data structures.
-
LRU Cache: LRU Cache is a simple, fast, and efficient in-memory Least Recently Used (LRU) cache implementation available in various programming languages. It is suitable for small-scale applications or when you need a lightweight caching solution.
- Node Example: github.com/isaacs/node-lru-cache
Choose the caching solution that best fits your application's requirements, scalability needs, and the programming language you are using.
Some hosting platforms runtimes may have different limitations compared to Workers, which Oxygen runs on. Review the hosting platform's documentation to identify any constraints that could impact the functionality of your Hydrogen app. For example, if the platform has different request timeout limits, you may need to adjust your app's logic to handle these differences or implement a retry mechanism for long-running tasks.
Depending on the hosting platform, you may need to customize the build process to accommodate platform-specific requirements. This might involve modifying the remix.config.js file or other configuration files. Refer to the hosting platform's documentation for guidance on customizing the build process.
Ensure that all environment variables used in your Hydrogen app are correctly set and accessible in the alternative hosting runtime. Update your app's code to use platform-specific environment variable APIs, and use the hosting platform's UI or CLI to set environment variables. Double-check that all required variables are correctly set before deploying your app. For example, you might need to use a .env file, a specific configuration file, or a platform-specific tool like AWS Systems Manager Parameter Store to manage environment variables.
If you prefer a more lightweight approach, you can use the Hydrogen React package with the React framework of your choice, including Remix. This option allows you to leverage Hydrogen's components and utilities while maintaining flexibility in your choice of hosting runtime and React framework.
To get started with Hydrogen React and Remix, refer to the Hydrogen React documentation. This guide will help you set up the Hydrogen Storefront client, import and use Hydrogen components, and deploy your Remix project to the hosting platform of your choice.