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 Fastly and 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.
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 app to Oxygen and other runtimes.