Build variables

A build variable is an environment variable available to your install and build commands. Frontend frameworks read their configuration at build time and write it into the files they produce, so a static site gets its API URL or feature flags this way.

Reading them

They're ordinary environment variables of the build's process.

• Vite: import.meta.env.VITE_API_URL in your code. Only VITE_-prefixed keys reach it (Vite's envPrefix).
• Rasengan.js: import.meta.env.RASENGAN_API_URL. Only RASENGAN_-prefixed keys reach your code.
• Config files and scripts: any key, through process.env (in vite.config.ts, a prebuild script).

The install command gets them too, so a variable can configure it: NODE_OPTIONS, a package manager setting.

export const apiUrl = import.meta.env.VITE_API_URL;

The dashboard warns when a build variable on a Vite or Rasengan.js project lacks the prefix: the code wouldn't see it.

Build, runtime, or both

A variable can be available at both: a server-rendered Rasengan.js app may need the same API_URL while it's built and while it runs. Choose Build and Runtime when you add it, or change it later from the variable's editor. A build-only variable isn't attached to your Worker.

No secrets

Whatever a framework inlines is in the files every visitor downloads, and Hiraiship can't tell what was inlined from what wasn't. So a secret is runtime only:

• creating a secret with Build is refused;
• adding Build to a secret is refused;
• turning a build variable into a secret is refused until you remove Build.

Values a build must keep private (a token for a private package registry) don't have a place yet.

One deployment only

The CLI can add build variables to a single deployment, over the project's own:

hiraiship deploy --build-env VITE_API_URL=https://staging-api.example.com --build-env VITE_DEBUG=true
hiraiship deploy --build-env-file .env.staging

--build-env-file reads a .env-format file on your machine (.env files are never uploaded with your source). --build-env wins over the file. Through the API, send them as buildEnv when you create a deployment. They're kept, encrypted, only until the build ends.

When the same key is set more than once, the deployment's own value wins over the project's, and Hiraiship's system variables can't be overridden.

When changes apply

A build variable is part of the build's output, so a change applies from the next build. Redeploying from the dashboard builds again (a deployment from GitHub); for one deployed with the CLI, run hiraiship deploy again. A rollback publishes an older build as it was, with the values it was built with.

What a build got

A deployment's page lists the build variables it received, keys only, and the build log's Preparing step starts with the same list:

Build environment: 9 variables (HIRAISHIP_*, VITE_API_URL, VITE_DEBUG)