Environment Variables

​

Introduction

​

Essential Environment Variables

​

Core Variables

1. SESSION_SECRET: A secret key used to sign session cookies. For more details, refer to the Remix documentation on using sessions.
2. PUBLIC_STOREFRONT_API_TOKEN: The public access token for the Storefront API. This is not required if you are using the mock.shop demo setup.
3. PUBLIC_STORE_DOMAIN: The domain of the store used to communicate with the Storefront API.
4. PUBLIC_CHECKOUT_DOMAIN: The domain of the checkout page (or the original Online Store domain).
5. PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID: The public access token for the Customer Account API.
6. PUBLIC_CUSTOMER_ACCOUNT_API_URL: The API URL for the Customer Account API, format: https://shopify.com/{SHOP_ID}.
7. SHOP_ID: Your Shopify store ID.

​

Weaverse Specific Variables

1. WEAVERSE_PROJECT_ID: A unique ID representing your specific Weaverse project. You can find this ID inside the Weaverse Studio under Project Settings.
2. WEAVERSE_API_KEY (optional): Weaverse API Key retrieved from your Weaverse Account settings.
3. WEAVERSE_HOST (optional): The host URL for Weaverse services. Default: https://studio.weaverse.io.

​

Optional Variables

1. PUBLIC_STOREFRONT_ID: The ID of your storefront.
2. PRIVATE_STOREFRONT_API_TOKEN: The private access token for the Storefront API.
3. PUBLIC_STOREFRONT_API_VERSION: The Storefront API version. Defaults to the version used by Hydrogen.

​

Third-Party Integration Variables

1. PUBLIC_GOOGLE_GTM_ID: Google Tag Manager ID for analytics.
2. JUDGEME_PRIVATE_API_TOKEN: API token for Judge.me reviews integration.
3. KLAVIYO_PRIVATE_API_TOKEN: API token for Klaviyo integration.
4. PUBLIC_SHOPIFY_INBOX_SHOP_ID: Shopify Inbox shop ID for chat functionality.

​

Custom Metafields & 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="my-secret-key"
PUBLIC_STORE_DOMAIN="mock.shop"
WEAVERSE_PROJECT_ID="weaverse-project-id"

​

Production Setup

# Core Variables
SESSION_SECRET="your-session-secret"
PUBLIC_STORE_DOMAIN="your-store.myshopify.com"
PUBLIC_CHECKOUT_DOMAIN="your-store.myshopify.com"
PUBLIC_STOREFRONT_API_TOKEN="your-storefront-api-token"
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 Variables
WEAVERSE_PROJECT_ID="your-weaverse-project-id"
WEAVERSE_API_KEY="your-weaverse-api-key"  # Optional
WEAVERSE_HOST="https://studio.weaverse.io"  # Optional

# Optional Variables
PUBLIC_STOREFRONT_ID="your-storefront-id"  # Optional
PRIVATE_STOREFRONT_API_TOKEN="your-private-storefront-api-token"  # Optional

# Third-Party 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

# Custom Metafields
METAOBJECT_COLORS_TYPE="shopify--color-pattern"  # Optional
CUSTOM_COLLECTION_BANNER_METAFIELD="custom.collection_banner"  # Optional

​

TypeScript Support

interface Env extends HydrogenEnv {
  // Core Variables
  PUBLIC_STORE_DOMAIN: string;
  PUBLIC_STOREFRONT_API_TOKEN: string;
  PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID: string;
  SHOP_ID: string;
  
  // Weaverse Variables
  WEAVERSE_PROJECT_ID: string;
  WEAVERSE_API_KEY?: string;
  WEAVERSE_HOST?: string;
  
  // Optional Variables
  PUBLIC_STOREFRONT_ID?: string;
  PRIVATE_STOREFRONT_API_TOKEN?: string;
  
  // Third-Party Integrations
  PUBLIC_GOOGLE_GTM_ID?: string;
  JUDGEME_PRIVATE_API_TOKEN?: string;
  KLAVIYO_PRIVATE_API_TOKEN?: string;
  PUBLIC_SHOPIFY_INBOX_SHOP_ID?: string;
  
  // Custom 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

​

Storefront API Token

1. Install the Headless or Hydrogen app
2. Follow these instructions to obtain the Storefront API Token
3. When setting permissions, enable all Storefront API access scopes to avoid unexpected errors during development

💡 Tip: Always enable all Storefront API permissions when generating your token. This prevents access-related errors that can be difficult to troubleshoot during development.

​

Weaverse Project ID

1. Log in to Weaverse Studio
2. Navigate 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