Environment Variables

​

Introduction

​

Essential Environment Variables

​

Shopify and Hydrogen Variables

1. SESSION_SECRET: A random secret used to sign session cookies. The Weaverse CLI/agent setup generates this automatically; if you configure a project manually, generate a random value instead of choosing a memorable one.
2. PUBLIC_STORE_DOMAIN: Your Shopify store domain, such as your-store.myshopify.com.
3. PUBLIC_STOREFRONT_API_TOKEN: Public Storefront API access token used by client-side Storefront API calls. This is not required for the mock.shop demo setup.
4. PRIVATE_STOREFRONT_API_TOKEN: Private Storefront API access token used for server-side Storefront API calls. Keep this value secret.
5. PUBLIC_STOREFRONT_ID: The numeric Hydrogen storefront ID.
6. PUBLIC_CHECKOUT_DOMAIN: Checkout domain, often your original Shopify Online Store domain. Some themes fall back to PUBLIC_STORE_DOMAIN.
7. PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID: Customer Account API client ID.
8. PUBLIC_CUSTOMER_ACCOUNT_API_URL: Customer Account API URL, usually in the format https://shopify.com/{SHOP_ID}.
9. SHOP_ID: Shopify store ID. Some Hydrogen features and theme code use this alongside Customer Account API values.

​

Weaverse Variables

1. WEAVERSE_PROJECT_ID: Unique ID for your Weaverse project. Find it in Weaverse Studio under Project Settings.
2. WEAVERSE_API_KEY: Optional API key from your Weaverse account or project settings. Only include it when your theme or automation needs direct API access.
3. WEAVERSE_HOST: Optional Weaverse service host. Default: https://studio.weaverse.io.

​

Optional Theme Variables

1. PUBLIC_STOREFRONT_API_VERSION: Storefront API version. If omitted, Hydrogen uses its configured default.
2. PUBLIC_GOOGLE_GTM_ID: Google Tag Manager ID for analytics.
3. JUDGEME_PRIVATE_API_TOKEN: API token for Judge.me reviews integration.
4. KLAVIYO_PRIVATE_API_TOKEN: API token for Klaviyo integration.
5. PUBLIC_SHOPIFY_INBOX_SHOP_ID: Shopify Inbox shop ID for chat functionality.

​

Custom Metafields and Metaobjects

1. METAOBJECT_COLORS_TYPE: Type identifier for color metaobjects.
2. CUSTOM_COLLECTION_BANNER_METAFIELD: Metafield identifier for collection banners.

​

Setting Up Environment Variables

​

Using Demo Setup (with mock.shop)

SESSION_SECRET="<generated-random-secret>"
PUBLIC_STORE_DOMAIN="mock.shop"
WEAVERSE_PROJECT_ID="YOUR_PROJECT_ID"

openssl rand -hex 32
# or
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

​

Production Setup

# Shopify and Hydrogen
SESSION_SECRET="<generated-random-secret>"
PUBLIC_STORE_DOMAIN="your-store.myshopify.com"
PUBLIC_CHECKOUT_DOMAIN="your-store.myshopify.com"
PUBLIC_STOREFRONT_API_TOKEN="your-storefront-api-token"
PRIVATE_STOREFRONT_API_TOKEN="your-private-storefront-api-token"  # Optional
PUBLIC_STOREFRONT_ID="your-storefront-id"  # Optional
PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID="your-customer-account-api-client-id"
PUBLIC_CUSTOMER_ACCOUNT_API_URL="https://shopify.com/your-shop-id"
SHOP_ID="your-shop-id"

# Weaverse
WEAVERSE_PROJECT_ID="YOUR_PROJECT_ID"
WEAVERSE_API_KEY="your-weaverse-api-key"  # Optional
WEAVERSE_HOST="https://studio.weaverse.io"  # Optional

# Optional integrations
PUBLIC_GOOGLE_GTM_ID="your-gtm-id"  # Optional
JUDGEME_PRIVATE_API_TOKEN="your-judgeme-token"  # Optional
KLAVIYO_PRIVATE_API_TOKEN="your-klaviyo-token"  # Optional
PUBLIC_SHOPIFY_INBOX_SHOP_ID="your-inbox-shop-id"  # Optional

# Optional theme-specific metafields
METAOBJECT_COLORS_TYPE="shopify--color-pattern"  # Optional
CUSTOM_COLLECTION_BANNER_METAFIELD="custom.collection_banner"  # Optional

​

TypeScript Support

interface Env extends HydrogenEnv {
  // Shopify and Hydrogen
  SESSION_SECRET: string;
  PUBLIC_STORE_DOMAIN: string;
  PUBLIC_STOREFRONT_API_TOKEN: string;
  PRIVATE_STOREFRONT_API_TOKEN?: string;
  PUBLIC_STOREFRONT_ID?: string;
  PUBLIC_CHECKOUT_DOMAIN?: string;
  PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID: string;
  PUBLIC_CUSTOMER_ACCOUNT_API_URL?: string;
  SHOP_ID: string;
  
  // Weaverse
  WEAVERSE_PROJECT_ID: string;
  WEAVERSE_API_KEY?: string;
  WEAVERSE_HOST?: string;
  
  // Optional integrations
  PUBLIC_GOOGLE_GTM_ID?: string;
  JUDGEME_PRIVATE_API_TOKEN?: string;
  KLAVIYO_PRIVATE_API_TOKEN?: string;
  PUBLIC_SHOPIFY_INBOX_SHOP_ID?: string;
  
  // Optional theme-specific metafields
  METAOBJECT_COLORS_TYPE?: string;
  CUSTOM_COLLECTION_BANNER_METAFIELD?: string;
}

​

Best Practices

1. Security:
   • Never commit .env files to version control
   • Use .env.example for required variables
   • Keep sensitive tokens private
   • Rotate tokens regularly
2. Organization:
   • Group related variables together
   • Use clear, descriptive names
   • Document all variables in your project
   • Keep development and production variables separate
3. Development:
   • Use different values for development and production
   • Validate environment variables at startup
   • Provide fallback values where appropriate
   • Use TypeScript for type safety

​

Obtaining Required Tokens

​

Recommended: Hydrogen Sales Channel

1. Install the Hydrogen sales channel.
2. Create one Hydrogen storefront project for your store.
3. From your local storefront folder, run:
   npx shopify hydrogen env pull
   
4. Choose the store, storefront, and environment when prompted.

​

Alternative: Headless Sales Channel

1. Install the Headless sales channel.
2. Create or open a storefront in the Headless channel.
3. Copy the Storefront API values into .env.
4. Request the Storefront API permissions your theme needs.

​

Weaverse Project ID

1. Log in to Weaverse Studio
2. Open your project and go to Project Settings
3. Copy your Project ID

​

Using Environment Variables

// In route loaders
export async function loader({ context }: LoaderArgs) {
  const { env } = context;
  return json({ storeDomain: env.PUBLIC_STORE_DOMAIN });
}

// In Weaverse components
export let loader = async ({ weaverse }: ComponentLoaderArgs<{}, Env>) => {
  const { env } = weaverse;
  return { projectId: env.WEAVERSE_PROJECT_ID };
}

​

Next Steps