Static assets
When building your custom storefront, it can be useful to have access to static assets that aren't already hosted elsewhere, like images. This guide describes how to reference and serve static assets in Hydrogen.
How static assets work
Anchor link to section titled "How static assets work"Static assets are files that your app downloads from a server. In Hydrogen, you import a static asset into your JavaScript runtime as a URL. When you import a static asset, it returns the resolved public URL where the asset is served.
The following example shows how to render the /src/icon.png image:
Static assets in Oxygen
Anchor link to section titled "Static assets in Oxygen"If you're using Oxygen to deploy your Hydrogen custom storefront, then static assets are automatically deployed to Shopify's content delivery network (CDN).
Shopify provides merchants with a world-class CDN backed by Cloudflare. Using a CDN means that your custom storefront will load quickly around the globe.
Files delivered over the Shopify CDN are minified and compressed automatically using Brotli, Zopfli, and gzip, reducing the size of the files the browser must download. Requests use HTTP/3 and TLS 1.3 to further enhance request performance and security.
Change the base URL
Anchor link to section titled "Change the base URL"If you want to serve your static assets from a different domain or path, then you can specify the HYDROGEN_ASSET_BASE_URL environment variable when building your project.
For example, running the following command will cause references to /icon.png to instead reference https://mycdn.example/path/to/folder/icon.png in the compiled code.
Asset Versioning
Anchor link to section titled "Asset Versioning"If asset content hasn't changed but you want to regenerate the already-compiled assets, then you can use the following configuration:
The configuration adds an optional string to force all files to be recompiled with a new hash. This can be helpful when the asset is cached but you want to change the behavior of your cache or the response headers that are currently cached, such as in a CDN or user's browser.
Considerations and limitations
Anchor link to section titled "Considerations and limitations"You should only import assets, such as styles or images, from client components. Any static assets that are referenced in server components, or shared components that are rendered from server components, won't display in the browser.
- Learn about React Server Components, an opinionated data-fetching and rendering workflow for React apps.
- Learn how to deploy your Hydrogen storefront to Oxygen and other runtimes.