> ## Documentation Index
> Fetch the complete documentation index at: https://weaverse.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Variables

> Set up Shopify, Hydrogen, and Weaverse environment variables for local development and production.

## Introduction

Environment variables connect your Hydrogen storefront to Shopify, Weaverse Studio, and any third-party services your theme uses. The Weaverse CLI and AI-agent setup generate most local values for you, but it is still useful to know which variables matter and where they come from.

<Tip>
  If you are starting a new project, follow the [5-Minute Quickstart](/docs/intro/quickstart) first. This page is for checking, editing, or manually creating your `.env` values.
</Tip>

## 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.

<Note>
  Variables with `PUBLIC_` can be exposed to browser code. Do not put secrets in `PUBLIC_` variables. Keep private API tokens in server-only variables such as `PRIVATE_STOREFRONT_API_TOKEN`.
</Note>

## Setting Up Environment Variables

### Using Demo Setup (with `mock.shop`)

```plaintext theme={null}
SESSION_SECRET="<generated-random-secret>"
PUBLIC_STORE_DOMAIN="mock.shop"
WEAVERSE_PROJECT_ID="YOUR_PROJECT_ID"
```

Generate a local `SESSION_SECRET` with either command:

```bash theme={null}
openssl rand -hex 32
# or
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

### Production Setup

```plaintext theme={null}
# 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

For TypeScript support, add your environment variables to `env.d.ts`:

```typescript theme={null}
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

For stores on a Shopify plan, use Shopify's Hydrogen sales channel:

1. Install the [Hydrogen sales channel](https://apps.shopify.com/hydrogen).

2. Create one Hydrogen storefront project for your store.

3. From your local storefront folder, run:

   ```bash theme={null}
   npx shopify hydrogen env pull
   ```

4. Choose the store, storefront, and environment when prompted.

The command pulls environment variables from the linked Hydrogen storefront and writes them into your local `.env` file. If the CLI cannot pull values yet, copy them manually from **Hydrogen sales channel → Storefront settings → Environments and variables**.

### Alternative: Headless Sales Channel

For development stores, stores without a Shopify plan, or custom Storefront API setups:

1. Install the [Headless sales channel](https://apps.shopify.com/headless).
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.

<Tip>
  During development, enable the Storefront API scopes required by your theme features. Missing scopes often show up later as product, collection, cart, localization, or metaobject data errors.
</Tip>

<Warning>
  If you are on the Shopify Starter plan and cannot use the Hydrogen or Headless channel flow, create a custom app to obtain Storefront API access values.
</Warning>

![API Token](https://cdn.shopify.com/s/files/1/0838/0052/3057/files/API-Token.webp?v=1743408636)

### Weaverse Project ID

1. Log in to [Weaverse Studio](https://studio.weaverse.io)
2. Open your project and go to **Project Settings**
3. Copy your Project ID

## Using Environment Variables

Access environment variables in your code:

```tsx theme={null}
// 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

Learn about creating and managing **[Weaverse Components](/docs/development-guide/weaverse-component)** – the foundational building blocks of your theme.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.