1. Docs
  2. Build a Weaverse Hydrogen Theme

Project Structure

Published on Nov 20, 2023, updated a month ago

Basic Structure Overview

Before getting into the finer details, let's get a top-level overview of the project:

🌳 <root>├── 📁 app│   ├── 📁 ...│   ├── 📁 routes│   ├── 📁 sections│   ├── 📁 weaverse│   ├── 📄 entry.client.tsx│   ├── 📄 entry.server.tsx│   └── 📄 root.tsx├── 📁 dist│   ├── 📁 client│   └── 📁 worker├── 📁 public│   └── 📄 favicon.svg├── 📄 .editorconfig├── 📄 .env├── 📄 package.json├── 📄 remix.config.js├── 📄 remix.env.d.ts├── 📄 server.ts├── 📄 sync-project.md└── 📄 tailwind.config.js└── 📄 ...

Base Files Explained

  • server.ts: This is the main server entry point. Among other responsibilities, it injects the weaverseClient into the app load context, ensuring that Weaverse functionalities are available throughout your application.
// <root>/server.ts
import { createWeaverseClient } from '~/weaverse/create-weaverse.server'
const handleRequest = createRequestHandler({  // ...  getLoadContext: () => ({    // Injecting the Weaverse client into the loader context.    weaverse: createWeaverseClient({      storefront,      request,      env,      cache,      waitUntil,    }),    // ... more app context properties  }),})
  • .env: This file holds your project-specific environment variables. Always keep this file secure and never expose sensitive data. For a detailed guide on setting up and managing environment variables, refer to the Environment Variables article.

  • tailwind.config.js: This file configures TailwindCSS, a utility-first CSS framework that developers love 💚. Using TailwindCSS, you can quickly design and customize your theme components.

  • remix.env.d.ts: This TypeScript definition file is where we define global types, including environment variables and additions to the Remix loader context

// <root>/remix.env.d.ts
import type { WeaverseClient } from '@weaverse/hydrogen'
/** * Declare expected Env parameter in fetch handler. */interface Env {  SESSION_SECRET: string  PUBLIC_STOREFRONT_API_TOKEN: string  PRIVATE_STOREFRONT_API_TOKEN: string  PUBLIC_STORE_DOMAIN: string  PUBLIC_STOREFRONT_ID: string  /**   * Include the Weaverse Project's ID - you'll find this in the Weaverse Editor under Project Settings.   * And the optional Weaverse Host - which value is https://weaverse.io by default.   */  WEAVERSE_PROJECT_ID: string  WEAVERSE_HOST: string}
/** * Declare local additions to the Remix loader context. */export interface AppLoadContext {  waitUntil: ExecutionContext['waitUntil']  session: HydrogenSession  storefront: Storefront  cart: HydrogenCart  env: Env  // Include the Weaverse Client in the Remix loader context.  weaverse: WeaverseClient}
  • remix.config.js: This configuration file is central to the operation of your Remix application. For a comprehensive understanding of its contents and purpose, refer to the Remix documentation.

  • sync-project.md: If you ever need to sync your project with the latest version of Pilot, this markdown file will guide you through the process.

Key Files and Directories within app

  • root.tsx: This is the root route of any Remix application. Within this file, global theme settings are loaded and rendered. Dive deeper into how global theme settings are handled in the Global Theme Settings article.

  • entry.server.tsx: This is the server-side entry to your application. Not only does it handle the initial rendering of your app, but it also manages server-side functionalities like setting up a custom Content Security Policy (CSP). For more details on configuring and understanding CSP, refer to the CSP article.

  • /routes: This directory contains your app's routes. Each file inside this directory becomes a page in your app that Remix will load and render. Learn about the intricate details of how Weaverse pages are loaded and rendered in the Rendering a Page article.

  • /sections: Here, you write the code for different sections of your theme. Once the section code is crafted, you also need to register the section. For a comprehensive understanding of section crafting and registration, refer to the Weaverse Hydrogen Component article.

  • /weaverse:

📁 weaverse├── 📄 components.ts├── 📄 create-weaverse.server.ts├── 📄 index.tsx├── 📄 schema.server.ts└── 📄 style.tsx
// <root>/app/weaverse/create-weaverse.server.ts
import { Storefront } from '@shopify/hydrogen'import { I18nLocale, WeaverseClient } from '@weaverse/hydrogen'import { countries } from '~/data/countries'import { components } from '~/weaverse/components'import { themeSchema } from '~/weaverse/schema.server'
type CreateWeaverseArgs = {  storefront: Storefront<I18nLocale>  request: Request  env: Env  cache: Cache  waitUntil: ExecutionContext['waitUntil']}
export function createWeaverseClient(args: CreateWeaverseArgs) {  return new WeaverseClient({    ...args,    countries,    themeSchema,    components,  })}

Next Steps

Now that you're familiar with the project structure, it's crucial to understand how to set up and manage Environment Variables.

Was this article helpful?