1. Docs
  2. Hydrogen Theme Customizer

Integrating Weaverse with existing Hydrogen projects


If you're keen on integrating Weaverse into your existing Hydrogen project or simply curious about Weaverse's inner workings, you're in the right place. This guide will walk you through integrating Weaverse SDKs & Theme Customizer using a clean demo-store sample from Shopify Hydrogen. Before diving in, ensure your Hydrogen project is ready in your preferred IDE.

1. Installing the Weaverse SDK:

Kickstart by integrating the Weaverse SDK library for Hydrogen:

npm install @weaverse/hydrogen

2. Scaffolding the Weaverse Directory:

Create a weaverse directory within your Hydrogen app folder. This will house essential files to establish a Weaverse Client Provider, register Section Components, and define theme schema settings. Simply copy the following files into your app/weaverse directory:

  • File: app/weaverse/components.ts


  • File app/weaverse/theme-schema.ts


  • File app/weaverse/client.ts


3. Integrating Weaverse Client into Hydrogen's Server Context

Navigate to the server.ts file in your Hydrogen project. Incorporate the weaverse client into the getLoadContext function as illustrated below:


4. Incorporating Weaverse Global Theme Settings

The Global Theme Settings feature facilitates theme setting sharing across all routes, akin to Shopify's Online Store Theme Customizer. To leverage this, open the root.tsx file and integrate the weaverseTheme data properties into the loader function. Here's a comprehensive loader snippet:


Notice the added here:

weaverseTheme: await context.weaverse.loadThemeSettings(),

Additionally, the App component needs to be wrapped with the withWeaverse API.


5. Updating Routes for Weaverse Content Rendering

To effectively display content managed by Weaverse, it's essential to incorporate the <WeaverseContent /> component within the desired routes. This component is a core part of Weaverse's functionality, ensuring that your theme customizations are reflected accurately in the live project.

For instance, consider the app/routes/($locale)._index.tsx file:


Key Takeaway:
While it's possible to render the <WeaverseContent /> component alongside other components, it's recommended to position the WeaverseContent at the topmost level of the route hierarchy. This ensures that Weaverse's configurations and customizations are prioritized and rendered accurately throughout your project.

6. Incorporating the Section Component

Main Component:


Video Section:

For a more specific example, let's explore how to add a Video section:


Registering the Sections:

After creating the Main and Video sections, you need to register them. Update the app/weaverse/components.ts file as follows:


7. What's Next?

Congratulations! You've now grasped how to integrate Weaverse into your existing Hydrogen project. Perhaps you've also gained insights into the mechanics of Weaverse's Hydrogen SDKs. To delve further, our upcoming article will guide you through defining Section Input settings, enabling sections to be tailored via the Weaverse Hydrogen Theme Customizer. Stay tuned!