Third-party dependencies will generally work out-of-the-box with Hydrogen. This guide describes how to install third-party dependencies, where to insert them, and offers tips for troubleshooting dependencies.
InstallationAnchor link to section titled "Installation"
To install third party dependencies, run the following command:
Where to insert dependenciesAnchor link to section titled "Where to insert dependencies"
Consider the following:
- If the dependency interacts with
useStateor browser APIs, then place it inside a
*.client.jsxcomponent. Follow the rules of server and client components.
- If the dependency is purely client-based, and you don't need to interact with it in individual components, then you can insert it in the
- If the dependency includes a style import from a CSS file, then you can import that in the
Troubleshooting dependenciesAnchor link to section titled "Troubleshooting dependencies"
This section provides strategies for troubleshooting third-party dependencies in your Hydrogen project.
Updating Vite dependenciesAnchor link to section titled "Updating Vite dependencies"
Vite caches pre-bundled dependencies in
node_modules/.vite. It re-runs the pre-bundling step if any of the following changes occur:
- The dependencies list is updated in
- Package manager lockfiles (for example
yarn.lock) are updated
- Any fields in
You can force Vite to re-bundle dependencies by completing one of the following tasks:
- Start the dev server with the
--forcecommand line option
- Manually delete the
Bundling third-party dependenciesAnchor link to section titled "Bundling third-party dependencies"
When bundling third-party dependencies, you might see errors in development or production related to the incorrect bundle type being used from the package.
This happens because Vite uses a heuristic to determine whether to load a module-based import (ESM) or a CommonJS-based import (CJS). Sometimes, the heuristic chooses the wrong version, or the third-party package formats their project in an unusual way.
To fix this, you can try adding the dependency to the
optimizeDeps.include property of your