Aspen - Shopify Hydrogen Theme
Aspen is a sophisticated Shopify theme crafted specifically for home furniture and interior design stores. Powered by Hydrogen, React Router, and Weaverse, this theme delivers lightning-fast storefronts with exceptional performance and elegant design aesthetics perfect for showcasing furniture collections, home decor, and interior design services.
Demo
What's included
- React Router v7
- Hydrogen 2026.4
- Oxygen
- Shopify CLI
- Biome (ESLint, Prettier alternative)
- GraphQL generator
- TypeScript and JavaScript flavors
- Tailwind CSS v4 (via Vite)
- Radix UI components
- New Shopify customer account API
- Full-featured setup of components and routes
- Furniture-specific sections and layouts
- Fully customizable inside Weaverse Studio
Deployment
Getting started
For complete local setup, Shopify and Weaverse connection, environment
variables, theme customization, Oxygen deployment, and troubleshooting, see
the Aspen setup and usage guide.
Requirements:
- Node.js
^22.18.0 || ^24.11.0; prefer a current patched release (see Node compatibility)
- npm package manager
Follow these steps to get started with Aspen and begin crafting your furniture store:
- Install Weaverse Hydrogen Customizer from Shopify App Store.
- Create new Hydrogen storefront inside Weaverse and select the Aspen theme.
- Initialize the project and start a local dev server with
@weaverse/cli tool as instructed in the Weaverse Studio.
- Open Weaverse Studio to start customizing your furniture store with specialized sections for product showcases, room inspirations, and interior design content.
Quick Start Commands
# Install dependencies
npm install
# Start development server on port 3456
npm run dev
# Run code quality checks before committing
npm run biome:fix
npm run typecheck
# Build for production
npm run build
# Run E2E tests
npm run e2e
bashFeatures overview
Fetching page data with parallel loading
Aspen uses parallel data loading for optimal performance. Every route loads Weaverse data alongside GraphQL queries using Promise.all():
import { data } from 'react-router';
import { type LoaderFunctionArgs } from 'react-router';
export async function loader({ context }: LoaderFunctionArgs) {
const { storefront, weaverse } = context;
const [collections, weaverseData] = await Promise.all([
storefront.query(COLLECTIONS_QUERY),
weaverse.loadPage({ type: 'INDEX' }),
]);
return data({
collections,
weaverseData,
});
}
tsweaverse is a WeaverseClient instance that has been injected into the app context by Weaverse. It provides a set of methods to interact with the Weaverse API.
const hydrogenContext = createHydrogenContext(
{
env,
request,
cache,
waitUntil,
session,
i18n: getLocaleFromRequest(request),
cart: {
queryFragment: CART_QUERY_FRAGMENT,
},
},
{},
);
const weaverse = new WeaverseClient({
...hydrogenContext,
request,
cache,
themeSchema,
components,
});
Object.assign(hydrogenContext, { weaverse });
return hydrogenContext;
tsRendering page content
Weaverse pages is rendered using <WeaverseContent /> component.
import { WeaverseHydrogenRoot } from '@weaverse/hydrogen';
import { GenericError } from '~/components/generic-error';
import { components } from './components';
export function WeaverseContent() {
return (
<WeaverseHydrogenRoot
components={components}
errorComponent={GenericError}
/>
);
}
tsxAnd in your route:
export default function Homepage() {
return <WeaverseContent />;
}
tsxDead simple, right?
Global theme settings
Weaverse global theme settings is loaded in the root's loader with context.weaverse.loadThemeSettings function.
export async function loader({request, context}: RouteLoaderArgs) {
return defer({
weaverseTheme: await context.weaverse.loadThemeSettings(),
});
}
tsxAnd then you can use it in your components with useThemeSettings hook.
import { useThemeSettings } from '@weaverse/hydrogen';
function Logo() {
let {logo} = useThemeSettings();
return (
<div className="flex items-center">
<img src={logo} alt="Logo" />
</div>
);
}
tsxThe App component is wrapped with withWeaverse HoC in order to SSR the theme settings.
import { withWeaverse } from '@weaverse/hydrogen';
function App() {
return (
<html lang={locale.language}>
// App markup
</html>
);
}
export default withWeaverse(App);
tsxCreate a Weaverse section
To create a section, you need to create a new file in app/sections directory and register it in app/weaverse/components.ts file.
Important: All Weaverse sections must use forwardRef and extend HydrogenComponentProps.
import type {
HydrogenComponentProps,
createSchema,
} from '@weaverse/hydrogen';
import { forwardRef } from 'react';
interface VideoProps extends HydrogenComponentProps {
heading: string;
description: string;
videoUrl: string;
}
const Video = forwardRef<HTMLElement, VideoProps>((props, ref) => {
const { heading, description, videoUrl, ...rest } = props;
return (
<section ref={ref} {...rest}>
<div className="mx-auto max-w-7xl px-4 py-8 lg:px-12 lg:py-16 sm:text-center">
<h2 className="mb-4 text-4xl font-extrabold tracking-tight text-gray-900">
{heading}
</h2>
<p className="font-light text-gray-500 sm:text-lg md:px-20 lg:px-38 xl:px-48">
{description}
</p>
<iframe
className="mx-auto mt-8 h-64 w-full max-w-2xl rounded-lg lg:mt-12 sm:h-96"
src={videoUrl}
title="YouTube video player"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
/>
</div>
</section>
);
});
export default Video;
tsxExport a schema object from the file to define the component's schema with default data and settings to be used in the Weaverse Studio.
export const schema = createSchema({
type: 'video',
title: 'Video',
settings: [
{
group: 'Video',
inputs: [
{
type: 'text',
name: 'heading',
label: 'Heading',
defaultValue: 'Learn More About Our Products',
placeholder: 'Learn More About Our Products',
},
{
type: 'textarea',
name: 'description',
label: 'Description',
defaultValue: `Watch these short videos to see our products in action. Learn how to use them and what makes them special. See demos of our products being used in real-life situations. The videos provide extra details and showcase the full capabilities of what we offer. If you're interested in learning more before you buy, be sure to check out these informative product videos.`,
placeholder: 'Video description',
},
{
type: 'text',
name: 'videoUrl',
label: 'Video URL',
defaultValue: 'https://www.youtube.com/embed/-akQyQN8rYM',
placeholder: 'https://www.youtube.com/embed/-akQyQN8rYM',
},
],
},
],
});
tsxWhat if your component needs to fetch data from Shopify API or any third-party API?
Weaverse provide a powerful loader function to fetch data from any API, and it's run on the server-side 🤯😎.
Just export a loader function from your component:
import type { ComponentLoaderArgs } from '@weaverse/hydrogen';
export const loader = async ({ weaverse, data }: ComponentLoaderArgs) => {
const result = await weaverse.storefront.query<SeoCollectionContentQuery>(
HOMEPAGE_SEO_QUERY,
{
variables: { handle: data.collection.handle || 'frontpage' },
},
);
return result.data;
};
tsxAnd then you can use the data in your component with Component.props.loaderData 🤗
Don't forget to register your new section in app/weaverse/components.ts:
import * as Video from "~/sections/video";
export const components: HydrogenComponent[] = [
Video,
];
typescriptManage content and style your pages within Weaverse Studio
Weaverse provides a convenient way to customize your theme inside the Weaverse Studio. You can add new sections, customize existing ones, and change the theme settings.
Project Structure
app/
├── components/ # Reusable UI components
│ ├── layout/ # Header, footer, navigation
│ ├── product/ # Product-specific components
│ └── cart/ # Cart components
├── sections/ # Weaverse page builder sections
├── routes/ # React Router routes (with locale prefix)
├── graphql/ # GraphQL queries and fragments
├── utils/ # Helper functions
└── weaverse/ # Weaverse configuration
Key configuration files:
- biome.json # Code formatting and linting
- codegen.ts # GraphQL code generation
- react-router.config.ts # React Router configuration
- vite.config.ts # Vite bundler configuration
typescriptDevelopment Tools
Code Quality
Before committing, always run:
npm run biome:fix # Fix linting/formatting
npm run typecheck # Check TypeScript types
npm run codegen # Update GraphQL types
bashReferences
License
This project is provided under the MIT License.
Let Weaverse & Aspen empower your furniture store with top-notch performance, elegant design, and unmatched customization possibilities perfectly tailored for the home furniture and interior design industry! 🪑🏠
