​

Custom Templates in Weaverse

​

Overview

• Create distinct designs for specific products (e.g., a pre-order layout).
• Design unique collection pages (e.g., a lookbook style).
• Apply special layouts to certain standard pages or blog posts/articles.
• Maintain consistent branding while tailoring the user experience for specific content.

• Product
• Collection
• Page (Standard Shopify Pages)
• Blog
• Article

​

Prerequisites

• Familiarity with Weaverse Studio and Hydrogen development.
• Weaverse Hydrogen package integrated into your storefront.
• Understanding of Shopify resources (Products, Collections, etc.).

​

Step 1: Creating a Custom Template in Weaverse Studio

1. Open Weaverse Studio.
2. In the Studio topbar, click the page navigation dropdown.
3. Choose the resource group you want, such as Products, then click Create template. The selected group determines the template type.
4. Enter the Template name (e.g., Product - Preorder, Collection - Lookbook Grid) and select an existing template under Based on, if available.
5. Optionally select resources under Assignments, or leave it empty to create a draft.
6. Click Create template or Create draft as shown. The new template starts with the selected base template’s content, rather than necessarily starting blank.

​

Step 2: Assigning the Template to a Shopify Resource

1. Locate Assignment Options: You have two main ways to open the template assignment panel:
   • Left Panel: In the left-hand panel, under the template name, find the Assign button next to “Custom template”.
   • Settings Panel (Right): Alternatively, look for the Template assignments button in the Settings panel on the right side of the Studio. It might be grouped under sections like “Layout”.
2. Open Assignment Panel: Click either the Assign button or the Template assignments button.
3. Select Resources: A panel will appear displaying a list of available resources (e.g., products) that match the template type. Check the box next to each resource you want to apply this custom template to.
4. Save Assignments: After selecting the resources, click the main Save button in the Studio’s top bar to save your template assignments.

​

Step 3: Configuring Hydrogen Routing for Custom Templates

// app/routes/products/product.tsx
// Registered in app/routes.ts — a file under app/routes/ is not a route by itself.
import type { LoaderFunctionArgs } from "react-router";
import { CACHE_DEFAULT } from "~/utils/cache";
import { unwrapStorefront } from "~/utils/storefront";
import { validateWeaverseData, WeaverseContent } from "~/weaverse";
// ... other imports (PRODUCT_QUERY, etc.)

export async function loader({ params, context }: LoaderFunctionArgs) {
  const { productHandle } = params;
  const { storefront, weaverse } = context;

  // 1. Fetch product data from Shopify. `storefront.graphql` returns
  //    `{ data, errors }`; `unwrapStorefront` throws on errors, so wrap it
  //    in try/catch if you need to.
  const { product } = unwrapStorefront(
    await storefront.graphql(PRODUCT_QUERY, {
      variables: { handle: productHandle /* ... */ },
      cache: CACHE_DEFAULT,
    }),
  );

  if (!product) { throw new Response(null, { status: 404 }); }

  // 2. Load Weaverse Page Data (Handles Custom Templates Automatically)
  //    Simply provide the type and handle. Weaverse checks for assignments.
  const weaverseData = await weaverse.loadPage({
    type: "PRODUCT",
    handle: productHandle,
  });

  // 3. `loadPage()` returns `WeaverseLoaderData | null` — on failure it
  //    resolves to `null` rather than throwing, so a try/catch around it
  //    would never fire. Check the result instead; Pilot's
  //    `validateWeaverseData` helper throws a 404 for a missing page.
  validateWeaverseData(weaverseData);

  // 4. Return all necessary data (a plain object — no `json()`)
  return { product, weaverseData /* ... other data */ };
}

export default function ProductRoute() {
  // Render <WeaverseContent /> using data from useLoaderData()
  // ...
  return <WeaverseContent />;
}

​

Step 4: Customizing the Template in Weaverse Studio

1. Open the custom template in Weaverse Studio (select it from the template list).
2. Click Add Section to add banners, product details blocks, related items, etc.
3. Configure section settings, layouts, and styles specifically for this template.
4. Important: Sections added here define the structure for all resources using this template. Content specific to the resource (like product title, images) will populate automatically based on the data passed from the loader.
5. Use global theme settings and reuse global sections for consistency, or create unique sections just for this template.
6. Save and Publish the template in Weaverse Studio. Preview it by visiting a resource assigned to this template on your storefront.

​

Best Practices

• Naming: Use clear, descriptive names for your templates (e.g., Product - Landing Page Style, Collection - Minimal Grid).
• Scope: Use custom templates when you need a distinct layout for multiple items of the same type. For one-off pages or unique routes, consider a Custom Page.
• Organization: Keep your template list tidy. Delete unused templates.
• Consistency: Leverage global sections and theme settings where possible to maintain brand consistency even within custom templates.

​

Troubleshooting

• Template Not Applying:
  • Verify the template is correctly assigned to the resource (check Metafield value or assignment setting).
  • Ensure the template is Published in Weaverse Studio.
  • Double-check the Hydrogen route loader logic – is it correctly identifying the assigned template and calling loadPage with the right parameters?
  • Check for typos in template handles/IDs entered in Metafields.
  • Clear browser cache or test in incognito mode.
• Sections Missing/Incorrect:
  • Confirm sections were added and saved to the template in Weaverse Studio.
  • Check if the necessary data is being passed from the loader if sections rely on it (e.g., ensure the product object is available).
  • Ensure there are no JavaScript errors in the browser console related to rendering.