Weaverse SDKs

The Weaverse SDK is organized into multiple packages, each serving a specific role in the development of Weaverse Hydrogen themes. These packages provide the necessary tools and functionalities for an efficient and streamlined development process.

Package Overview

`@weaverse/core`

This foundational package contains the core logic of Weaverse and Weaverse Items, focusing on essential operations and data handling within the Weaverse ecosystem. Key Features:

Data model definitions for Weaverse components
Core rendering logic
State management utilities
Type definitions shared across the ecosystem

Installation:

npm install @weaverse/core

`@weaverse/react`

Specializing in the user interface, this package provides React bindings for Weaverse, managing the rendering of Weaverse Items as React components and ensuring proper display and interaction within themes. Key Features:

React component rendering system for Weaverse items
Context providers for Weaverse and item states
Custom hooks for accessing Weaverse data and item instances
Utility functions for CSS generation and class name handling

Installation:

npm install @weaverse/react

Core Components:

WeaverseRoot: The main component that renders your Weaverse content tree
WeaverseContextProvider: Provides the Weaverse context to all child components
ItemComponent: Renders individual Weaverse items based on their type and properties

Essential Hooks:

useWeaverse(): Access the Weaverse instance from any component
useItemInstance(id?): Get a specific item instance by ID or the current item
useParentInstance(): Get the parent item of the current component
useChildInstances(id?): Get all child instances of an item

Basic Usage:

import { registerElement, Weaverse } from '@weaverse/core';
import { WeaverseRoot } from '@weaverse/react';

// Initialize Weaverse
const weaverse = new Weaverse({
  projectId: 'your-project-id',
  data: yourWeaverseData
});

// Register your components.
// Registration is static — the registry is shared across every Weaverse
// instance. Use the exported `registerElement`, or `Weaverse.registerElement`.
registerElement({
  type: 'Button',
  Component: ButtonComponent,
  schema: {
    title: 'Button',
    type: 'Button',
    settings: [
      {
        group: 'Content',
        inputs: [
          // Input configurations
        ]
      }
    ]
  }
});

// Render the Weaverse content
function App() {
  return (
    <WeaverseRoot context={weaverse} />
  );
}

registerElement keys the registry by type and ignores a re-registration of a type that already exists, so register each element type once.

`@weaverse/hydrogen`

Tailored for theme development, this package carries the logic required to build a Hydrogen Theme and facilitate its integration with Weaverse Studio’s customization features. Key Features:

Shopify Hydrogen integration
Theme customization components
Studio preview capabilities
Hydrogen-specific renderers and utilities

Installation:

npm install @weaverse/hydrogen

Basic Usage:

// app/weaverse/index.tsx
import { WeaverseHydrogenRoot } from '@weaverse/hydrogen';
import { GenericError } from '~/components/root/generic-error';
import { components } from './components';

export function WeaverseContent() {
  return (
    <WeaverseHydrogenRoot
      components={components}
      errorComponent={GenericError}
    />
  );
}

WeaverseHydrogenRoot takes no children — it renders the Weaverse page resolved for the current React Router route. Its props are:

Prop	Type	Required	Description
`components`	`HydrogenComponent[]`	Yes	Theme components available to the page renderer
`data`	`WeaverseLoaderData \| Promise<WeaverseLoaderData \| null> \| null`	No	Explicit `weaverseData` payload that bypasses automatic route-scoped resolution. Pass `null` to suppress rendering
`errorComponent`	`React.FC<{ error: Error \| unknown }>`	No	Component rendered when page data cannot be resolved

`@weaverse/cli`

The command-line scaffolding tool for creating a Weaverse Hydrogen project from a supported template. Key Features:

Project scaffolding with templates
Non-interactive project configuration through CLI flags
Dependency installation and optional development-server startup

Usage:

npx @weaverse/cli@latest create --template=pilot --project-id=YOUR_PROJECT_ID

`@weaverse/biome`

A package that provides standardized Biome configuration for Weaverse projects, ensuring consistent code formatting and linting across all Weaverse-related codebases. Key Features:

Preconfigured Biome settings optimized for Weaverse development
Consistent code style enforcement
Standardized linting rules with appropriate severity levels
Compatible with React and TypeScript projects

Installation:

npm install @weaverse/biome --save-dev

Usage: In your project’s root directory, create or update your biome.json file to extend the Weaverse configuration:

{
  "extends": ["./node_modules/@weaverse/biome/biome.json"],
  // Add any project-specific overrides here
}

Key Configuration Details: The Weaverse Biome configuration includes:

JavaScript/TypeScript formatting:
- Uses single quotes
- Employs spaces for indentation
- Semicolons only as needed
Linting rules with sensible defaults:
- Accessibility (a11y) checks
- React-specific best practices
- Security protections
- Code complexity guidance

This configuration helps maintain code quality and consistency across Weaverse projects while providing flexibility for project-specific needs.

Package Compatibility

The Weaverse SDK packages are designed to work together seamlessly, but each can also be used independently based on your project needs:

Package	Compatible With	Node.js	Runtime Dependencies
`@weaverse/core`	Any JavaScript project	`>=18`	None
`@weaverse/react`	React applications	`>=18`	`@weaverse/core`, `react` `>=19`, `react-dom` `>=19`, `clsx`
`@weaverse/hydrogen`	Shopify Hydrogen storefronts	`>=20`	`@weaverse/react`, `@weaverse/schema`, `@shopify/hydrogen` `>=2025.5`, `@shopify/remix-oxygen` `3`, `react`/`react-dom` `>=19`, `react-router` `^7`, `react-error-boundary` `^6`
`@weaverse/schema`	Any JavaScript/TypeScript project	-	`zod` `^4`
`@weaverse/cli`	Node.js environment	`>=18`	None (run via `npx`)
`@weaverse/biome`	Any JavaScript/TypeScript project	-	None (peer: `@biomejs/biome`)

System Requirements

Requirements differ per package — check the table above for the exact package you install. For the @weaverse/hydrogen package:

Node.js: v20.0.0 or higher
React / React DOM: v19.0.0 or higher
React Router: v7 (not React Router DOM)
Shopify Hydrogen: 2025.5 or higher
npm: v7.0.0 or higher (or equivalent package manager)

A generated theme may require a newer Node.js version than the SDK package. The current Pilot template declares Node.js >=22.12.0.

Getting Started

For new Weaverse Hydrogen projects, the easiest way to get started is using the CLI:

# Create a new project
npx @weaverse/cli@latest create --template=pilot --project-id=YOUR_PROJECT_ID --project-name=my-store

# Navigate to project directory
cd my-store

# Start development server
npm run dev

For existing projects, you can install the required packages individually and integrate them according to your needs.

Open Source Status

The Weaverse team is actively working on improving these packages and expanding their capabilities. For the latest updates on availability and open source status, please check the official Weaverse GitHub repository.

Overview

Developer Tools

APIs

Hydrogen Themes

Hydrogen Integrations

Migration

Package Overview

`@weaverse/core`

`@weaverse/react`

`@weaverse/hydrogen`

`@weaverse/cli`

`@weaverse/biome`

Package Compatibility

System Requirements

Getting Started

Open Source Status

Additional Resources

​Package Overview

​@weaverse/core

​@weaverse/react

​@weaverse/hydrogen

​@weaverse/cli

​@weaverse/biome

​Package Compatibility

​System Requirements

​Getting Started

​Open Source Status

​Additional Resources

Package Overview

`@weaverse/core`

`@weaverse/react`

`@weaverse/hydrogen`

`@weaverse/cli`

`@weaverse/biome`

Package Compatibility

System Requirements

Getting Started

Open Source Status

Additional Resources