Skip to main content

Third-party dependencies

tip

Hydrogen 2.0 is out now. These archival Hydrogen 1.0 docs are provided only to assist developers during their upgrade process. Please migrate as soon as possible.

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.

Installation​

To install third party dependencies, run the following command:


npm install <dependency>
yarn add <dependency>

Where to insert dependencies​

Consider the following:

  • If the dependency interacts with useState or browser APIs, then place it inside a *.client.jsx component. 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 <head> element of index.html.
  • If the dependency includes a style import from a CSS file, then you can import that in the <head> element of index.html.

Troubleshooting dependencies​

This section provides strategies for troubleshooting third-party dependencies in your Hydrogen project.

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.json
  • Package manager lockfiles (for example yarn.lock) are updated
  • Any fields in vite.config.js are updated

You can force Vite to re-bundle dependencies by completing one of the following tasks:

  • Start the dev server with the --force command line option
  • Manually delete the node_modules/.vite cache directory

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 vite.config.js file:

// vite.config.js

import {defineConfig} from 'vite';
import hydrogen from '@shopify/hydrogen/plugin';

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [hydrogen()],

  optimizeDeps: {
    include: ['YOUR_DEPENDENCY'],
  },
});

Tip: If you find that a dependency is being optimized when it shouldn't, then you can try adding the dependency to optimizeDeps.exclude to see if it fixes the issue.

Next steps​