Secrets Management

This document introduces the support for environment variables in the Helium project. The support for environment variables relies on the technology used to build and bundle the Helium application, and is adapted to the technology used to publish the application. Once the Helium application is authenticated, developers can store the environment variables in an ‘.env’ file and reference the variables in ‘Page’ components and their imports. The Helium application lifecycle scripts will take care of parsing and transforming these variables accordingly.

Use Cases

There are two use cases to use environment variables.

If you are defining variables for public use, consider using the public variables. For example: a title for the Helium application. The public variables can be referenced from interface ‘import.meta.env’. When building for production, these variables are statically replaced and their values will be included in the bundles.

If you are defining variables for private use, consider using the private variables. For example: server side data-fetching from a private server (with secrets). The private variables can be referenced from interface ‘process.env’. These variables will remain as-is during build for production. When publishing for production, these variables are transformed to runtime secrets and their values will not be included in the bundles.

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 ‘HELIUMPUBLIC’. For private variables, define the variable name with the prefix ‘HELIUMPRIVATE’.

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 scripts to deploy the Helium application, the script builds the bundle first then deploys the bundle to Cloudflare Worker.

During build: references to public variables are statically replaced and their values will be included in the bundle; references to private variables remain as-is in the bundle.

During deploy: only references to private variables are transformed to global variables and relevant secrets are created for Cloudflare Worker.

Still have a question?

Get your questions answered in our Developer Discord.