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 workAnchor link to section titled "How static assets work"
The following example shows how to render the
Static assets in OxygenAnchor 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 URLAnchor 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 VersioningAnchor 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 limitationsAnchor 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.