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. Once your Helium application is authenticated, you can define environment variables in a .env file and reference them within Page components and their imported modules. The Helium application lifecycle scripts handle parsing and transforming these variables appropriately for the target environment.

Use Cases

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

Public Variables

• Use public variables when exposing non-sensitive configuration values—such as application titles or feature flags—that are safe to embed in the frontend bundle. These should be accessed via the import.meta.env interface.

• When building for production, these variables are statically replaced during the build process, and their values are included directly in the final bundle.

• Example use case: Displaying the app title in the browser tab using 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. These should be accessed via the process.env interface.

• Private variables remain untouched during the build process and are injected at runtime in the deployed environment. This ensures sensitive information is not exposed in client-side bundles.

• Example use case: Fetching data from a secure backend API using process.env.HELIUM_PRIVATE_SECRET_API_KEY.

Example

Step 1

Once the Helium application is authenticated, add the environment variable to the ‘.env’ file at the root of the project. For public variables, define the variable name with the prefix HELIUM_PUBLIC_. For private variables, define the variable name with the prefix HELIUM_PRIVATE_.

See example ‘.env’ file below with one public variable and one private variable. An example file ‘.env.example’ is also included in the package for helium template.

# Example public variables
HELIUM_PUBLIC_APP_VERSION='v1'

# Example private variables
HELIUM_PRIVATE_SECRET='secret value'

Step 2

In the ‘Page’ components and their imports, reference the public variable with import.meta.env.HELIUM_PUBLIC_APP_VERSION.

See example below for the configuration of a ‘Page’ component.

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

export { Page };

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

The sample page will render text ‘Hello! App version: v1’.

Step 3

In the server ‘Page’ components and their imports, reference the private variable with process.env.HELIUM_PRIVATE_SECRET.

See example below for the configuration of a server ‘Page’ component. The server ‘Page’ component will fetch data with the private variable and will make the response data available in page context.

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

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

Step 4

To use TypeScript IntelliSense for the public variables, use an ‘env.d.ts’ file to augment ‘ImportMetaEnv’.

See example ‘.env.d.ts’ file below with the public variable defined in the sample ‘.env’ file. An existing file ‘.env.d.ts’ is also included in the package for helium template.

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

interface ImportMetaEnv {
  // public env variables...
  readonly HELIUM_PUBLIC_APP_VERSION: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

Flow Under the Hood

When developers run the deployment scripts for a Helium application, the process involves two key phases: build and deploy.

During the build phase:

• References to public variables (import.meta.env) are statically replaced with their actual values. These values are embedded directly into the final bundle.
• References to private variables (process.env) are left intact, preserving them for transformation at runtime.

During the deploy phase:

• Only private variables are processed further. They are transformed into global runtime variables, and the corresponding secrets are securely created and attached to the Cloudflare Worker.