Secrets Management

This document outlines how environment variables are supported and managed in the Helium project. Environment variable support depends on both the build toolchain and the publishing infrastructure used by Helium.

Use Cases

There are two primary use cases for environment variables in Helium: public and private.

Public Variables

• Use public variables for non-sensitive configuration values—such as application titles or feature flags—that are safe to embed in the frontend bundle. Access via import.meta.env.
• During build, these variables are statically replaced with their actual values and embedded in the final bundle.
• Example: import.meta.env.HELIUM_PUBLIC_APP_TITLE

Private Variables

• Use private variables for sensitive values such as API keys or credentials used in server-side data fetching. Access via process.env.
• Private variables remain untouched during build and are injected at runtime in the deployed environment.
• Example: process.env.HELIUM_PRIVATE_SECRET_API_KEY

Step 1: Define Environment Variables

Once authenticated, add environment variables to the .env file at the root of your project. Use HELIUM_PUBLIC_ prefix for public and HELIUM_PRIVATE_ for private variables.

# Example public variables
HELIUM_PUBLIC_APP_VERSION='v1'

# Example private variables
HELIUM_PRIVATE_SECRET='secret value'

Step 2: Reference Public Variables

In Page components and their imports, reference public variables with import.meta.env:

// in pages/hello.page.ts
const appVersion = import.meta.env.HELIUM_PUBLIC_APP_VERSION;

export { Page };

function Page() {
  return <>`Hello! App version: ${appVersion}`</>;
}

Step 3: Reference Private Variables

In server Page components, reference private variables with process.env:

// in page/data.page.server.ts
export { onBeforeRender };

async function onBeforeRender(pageContext) {
  const secretValue = process.env.HELIUM_PRIVATE_SECRET;
  const response = await fetch('<remote_server_url>', {
    headers: { secret: secretValue }
  });
  const { data } = await response.json();
  return { pageContext: { data } };
}

Step 4: TypeScript IntelliSense

Use an env.d.ts file to augment ImportMetaEnv:

/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly HELIUM_PUBLIC_APP_VERSION: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

How It Works Under the Hood

Build Phase

• Public variables (import.meta.env) are statically replaced with actual values
• Private variables (process.env) are left intact

Deploy Phase

• Private variables are transformed into global runtime variables
• Secrets are securely created and attached to the Cloudflare Worker