How do I handle env variable imports when building from within a Github Action?

[alexabunny]

My SvelteKit frontend is a microservice that's part of a larger application. I have a GitHub Action which builds and publishes my frontend as a Docker image. The action encounters this error while building the SvelteKit app:

Error: 'PUBLIC_SOME_VARIABLE' is not exported by $env/dynamic/public, imported by src/routes/billing/+page.svelte

It makes sense considering that I don't include a .env file in the repository. Instead I include a .env.example and create a real .env file for my dev machine and production host (it gets mounted through Docker).

How can I have an automated build step for my frontend without actually committing any env variables to my repo?

[alexabunny]

Temporary Solution

For now I've been able to get around this by moving the app build step out of the Docker image build.

dockerfile

FROM node:18-alpine AS base
WORKDIR /frontend
COPY frontend/package.json .
COPY frontend/package-lock.json .

# Builds development image
FROM base AS development
RUN npm install
ENTRYPOINT ["npm", "run", "dev"]

# Builds production image
FROM base AS production
COPY frontend/ ./
RUN npm install
# Build happens on container startup intsead of image build because: https://github.com/sveltejs/kit/discussions/7265
ENTRYPOINT ["npm", "ru
n", "serve"]

package.json scripts
I added the serve command

  "scripts": {
    "dev": "vite dev --host 0.0.0.0",
    "build": "vite build",
    "serve": "npm run build && node build/index.js",
    "preview": "vite preview",
    "check": "svelte-kit sync && svelte-check --tsconfig ./jsconfig.json",
    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./jsconfig.json --watch"
  }

Further Research / Notes

I tried playing around with the Vite Env Mode, and got build to read from an alternatively named .env file like .env.buildonly. My idea was that I could commit .env.buildonly to the repo, which would then contain the env keys but no values. Then when I ran the built application I could get it to read from a real .env file with values set.

Unfortunately I couldn't get this to work. I'm guessing that once a SvelteKit app is built the env variables are part of the built package.

I could maybe get around this by using dotenv to read from a .env file at runtime, but then that involved implementing something like $env/dynamic and $env/static for the clientside.

Idk, I'm mostly a backend dev that doesn't spend much time with JS or Vite.

[cotyhamilton]

I wouldn't use the static environment variables, you're correct that those get baked into the build, I'm not sure why that's still promoted with SSR...

Just use runtime environment variables and pass them in to the container on docker run

[iaingalloway]

Did you ever find a better solution? I have a similar problem where I've got a sveltekit app that I'm containerising with a multi-stage dockerfile. I definitely don't want to use different container images per-environment, but I'd rather not use $env/dynamic/public if there's any way I can avoid it.

I could grab application variables on startup and squirt them into a static file that I reference directly, but that seems awfully manual. It seems worth a little time searching for an easier way.

[simonnice]

Anyone that has a better solution for this? I'm currently struggling with this exact issue on my project. I've tried setting the values as Github Secrets in my workflow and other solutions but to no avail.

[miguelvalente]

Did you end up figuring out a solution? I'm also using GitHub Secrets.

[Neo-Ciber94]

I suppose you may need to do something like echo DATABASE_URL=${{ secrets.DATABASE_URL }} >> .env for each env variable, I can't think in other solution right now.

[fjukstad]

I overcame the errors by adding a .env file with a placeholder

PUBLIC_SOME_VARIABLE=

in my repository, and a local .env.development on my machine with

PUBLIC_SOME_VARIABLE=secret

[iaingalloway]

I don't think that helps in this scenario. You'd need to build env.local into the container - meaning a) you'd need those values available at build time, b) you'd need to be comfortable shipping those values as part of a container image, and c) you'd need different container images per-environment.

The problem is that static values are baked into the build, and there's nowhere "natural" to put values that we won't know until startup time. In that case either we need to defer the entire build until runtime, use dynamic, or do some work "outside" the framework to do something else.

[fjukstad]

Since the .env file only contains empty placeholder environment variables (only key names and empty values), I'm happy with adding the .env file to the container. I will use Github Secrets, Azure KeyVault etc. for storing the actual values, and pass them to the container when I run the app, so I don't see an issue with adding a placeholder .env to the repository or container. Maybe there's something that I'm missing?

[iaingalloway]

I created an MCVE here: https://github.com/iaingalloway/svelte-stores-mcve

Notice that the values in $env/static/public aren't set when run from the container, because the (empty) placeholder values from .env were baked into the build.

To get around this we need to do one of:

1. Make the value available to docker build at build time, meaning we need a different container image for each environment
2. Use $env/dynamic/public instead of $env/static/public
3. Run npm run build inside our actual production container, meaning we have a much larger, much more complicated, and much more vulnerable container image
4. Something else?

It might be that using $env/dynamic/public is fine, and that I've misunderstood or been misled by the documentation regarding what it's for. It might be that there's a better way that I'm missing.

[jyrive]

I had similar kind of problem, when with $env/static/public variables which are passed on build time. Locally I use .env file obviously, but didn't want to push it to repo. In my application I use sveltekit, github actions to build it and deploy as azure static web app.

I came up with following solution:

1. I added the environment variables as github secrets, more info here: https://docs.github.com/en/actions/security-guides/encrypted-secrets
2. then in github action yaml file added them as environment variables, more info here: https://docs.github.com/en/actions/security-guides/encrypted-secrets#using-encrypted-secrets-in-a-workflow

Following is example in practice what yaml file looks like on build section (example environment variable is named PUBLIC_ERROR_MESSAGE)

[DougAnderson444]

THIS works.

[DougAnderson444]

If it's not a secret, you can also use ${{ vars.NAME }} too

[shahin-salehi]

This actually saved my life

[SFGMorales]

This was so obvious, thanks that solves my problem.

[Neo-Ciber94]

This doesn't fail because prerendering? I cannot set them in the env field of the CI:

Cannot read values from $env/dynamic/private while prerendering (attempted to read env.DATABASE_URL). Use $env/static/private instead

[FernandoArteaga]

In my workflow, I have a step that copies a .env.ci file which contains placeholders, as the .env file.
Then I do an envsubst for substituting the placeholders with my environment and secrets variables.

.env.ci file

PUBLIC_ENV=${APP_ENV}
PUBLIC_API_KEY=${API_KEY}

build workflow

name: "Build sveltekit app"

on:
  workflow_call:

jobs:
  install_build:
    name: "Build app config"
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: "Setup pnpm"
         uses: pnpm/action-setup@v3
         with:
           version: 8
           run_install: false
      - name: "Setup Node"
         uses: actions/setup-node@v4
         with:
           node-version: 18
           cache: "pnpm"

      - name: "Replace env variables (dev)"
         uses: danielr1996/envsubst-action@1.0.0
         env:
            APP_ENV: ${{ vars.APP_ENV }}
            API_KEY: ${{ secrets.API_KEY }}
         with:
            input: .env.ci
            output: .env

      - name: "Install dependencies"
         run: pnpm install

      - name: "Build app"
         run: pnpm build

[anly2]

All of the above approaches, as far as I can see, still end up baking in the secrets in the docker image.
Sure, they are not committed in git/vcs, but if I get the docker image, I can see the secrets in it. Which in my case is not acceptable.

---

I ended up using $env/dynamic/* everywhere.
But I had to add "fallbacks":

Basically, added this code as early as possible:

try {
  const { env: dynamicEnv } = await import("$env/dynamic/private");
  const staticEnv = await import("$env/static/private");
  // Iterate these objects as PUBLIC_ vars are split out already
  Object.keys(staticEnv ?? {}).forEach(k => dynamicEnv[k] ??= process.env[k] ?? staticEnv[k])
  // ^^^ SAME for public vars
} catch () {}

The process.env[k] part is necessary if loading config with a call like dotenv.config({ path: ".env.local" });.
That is because that call will only load values in process.env and none of the $env modules.

---

Separately, because I didn't want to update the usages everywhere in code to be prefixed with env., I used destructuring right after the import statement:

import { env } from "$env/dynamic/private";
const {
	API_KEY,
} = env;

I wish I didn't have to do this :(
But $env/static/ is immutable.
And cannot destructure as part of the import statement itself, as far as I know.

[ryanovas]

The way environment variables seem to be handled in sveltekit is very odd to me because it almost forces you to bake all your env vars and secrets right into the build, which is kind of a big nono for both security and the ability to reuse Docker images in different environments...

For example, if I wanted to have an automated pipeline that deploys a docker image to a staging environment, run e2e tests on it, then take that same image and deploy it to production I can't - I'm forced to rebuild the entire image and inject a different set of variables right into the container.

Also, if anyone got a hold of my container all the secrets are cached in the build.

On top of all that, I still have to use dotenv in order to build/deploy the images since the node adapter doesn't seem to support env vars out of the box, so we're not even getting huge value from using this built-in version of env var handling?

I don't understand why we have regressed on a solved problem here? Why can't we have a simple interface to get an env var from a .env first then fallback to process.env on the backend, and do the same but pre-render public env vars for the front end? I don't understand why they have to be considered extra network cost when none of the other variables that sveltekit is pre-rendering are? It kind of just seems like the authors like .env files and want to force us to use them? It kind of seems like the only solution here is to use dynamic env vars and eat whatever this extra network cost is on the front end...

[Neo-Ciber94]

I think maybe we tried to be too smart about injecting the env variables, I agree with @ryanovas this feels like a regression, this was a solved problem, OR the docs need to be updated to explain how to setup env for CI, Docker, or just a better explanation to adapt to this way of doing it, because it doesn't feel right.

The way I solve it was coping my .env.example to .env

name: CI

on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["main"]
  workflow_dispatch:

jobs:
  ci:
    runs-on: ubuntu-latest
    name: Test and Build
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: 1.0.17

      - name: 🚧 Install
        run: bun install

      - name: 🏗️ Build
        run: |
          cp ./.env.example ./.env
          bun run build

I still not convinced, I want to just setup the env variables on the CI but is not possible because the prerendering throws an error, so I suppose I need to do this echo "DATABASE_URL='test'" >> .env for each environment variable

[noboomu]

Any movement on this? This is the last thing I expected to be struggling with.

[dawidmachon]

Maybe use this?
https://docs.docker.com/reference/dockerfile/#run---mounttypesecret

This mount type allows the build container to access secret values, such as tokens or private keys, without baking them into the image.
By default, the secret is mounted as a file. You can also mount the secret as an environment variable by setting the env option.

[rraihansaputra]

I agree with @ryanovas. It's still a struggle.

My approach when having a container based deployment is:

• Built Container Images should have the same secrets/sensitivity as the code repository. If you don't check it in the repository because it should be secret, then it shouldn't be in the built image
• env will be supplied on runtime, the application will check for these variables on boot/startup, and emit the appropriate errors if the variables are not found.
• Building the container image should not depend on any of the environment variable to exist on build time

Currently with these limitations it's hard to reason about building and deploying SvelteKit containers.

I understand that .env for "public" values is an easy abstraction to pick when developing for Front End (and what i used when developing pure FrontEnd apps), but now SvelteKit has a Front End and Back End part and that means secrets and their usage throughout the whole chain need to be in the consideration too.

[jacksonthall22]

Agreed with @ryanovas. Should this be made into a separate issue? How can we get movement here? Isn't this, like, a super common use case and a pretty big security concern?

[eurlexa]

Run into the exact problems when trying to deploy with Dokploy.

EDIT: Importing env as a dynamic and getting secretes via env object helped.

// import { PRIVATE_PASSWORD, ..., ... } from '$env/dynamic/private';
import { env } from '$env/dynamic/private'; 
....
// usingsecret(PRIVATE_PASSWORD)
usingsecret(env.PRIVATE_PASSWORD)

For docker I use Dokploy, so env secretes can be stored in "Environment" section as "Environment Settings" and "Build-time Secrets".

My Dockerfile looks like this:

# ---------- Build stage ----------
FROM node:22-alpine AS build

WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci

COPY . .
RUN npm run build

# ---------- Run stage ----------
FROM node:22-alpine AS run

WORKDIR /app

ENV NODE_ENV=production
ENV PORT=3000

COPY --from=build /app/package.json ./
COPY --from=build /app/build ./build
COPY --from=build /app/node_modules ./node_modules

EXPOSE 3000

CMD ["node", "build"]

[teemingc]

If your environment variable is referenced during analysis or prerendering for a build (typically at the top level of a server file), you'll want to guard its access with if (!building) https://svelte.dev/docs/kit/$app-env#building to prevent it from being evaluated

#16267 will probably make this more noticeable since you'll have to specify if your environment variable is runtime only, build only, etc.

[Rich-Harris]

You still need .env files. The config file defines which environment variables are needed by the app; the .env file populates them with values.

By default, environment variables are dynamic, exactly as you expect them to be. Their values are determined when the app runs, not when it is built. SvelteKit does however evaluate them at build time, because it runs your app at build time — that's how it (for example) generates a more optimized client build, and how it prerenders the parts of your app that are capable of being prerendered.

In SvelteKit 3, explicit environment variables (i.e. the env.ts config file) will be a requirement rather than an opt-in experimental option, and you will be able to specify that a particular variable is not available at build time.

You can also configure env vars to be static, i.e. inlined into the build — these are what you imagine we're doing by default when you speak of 'constants'. Having said that...

If we wanted that, we would just declare a normal variable: export const SHOUTY is all you ever need

...you seem to be implying that values should be hardcoded in the app, rather than it being possible to create different builds by building with different environment variables. You're free to think that's a bad idea for whatever reason but your view is not universal!

[Rich-Harris]

Please don't quote the entire message in your reply, it makes threads unnecessarily hard to follow. I've edited your comment.

The key trait of a dynamic variable is that it shouldn't be evaluated at build time, or if it is, no value it had would possibly affect the build.

Consider a prerendered page that pulls content from a CMS. The API key for the CMS is very much needed at build time.

Does that get optimized/tree shaken away if SOMETHING isn't defined?

No.

Also, I've filed a bug, because the type of env.SOMETHING is string when checked with tsc but in reality it is SOMETHING?: string due to this weird behavior where it is shrodingers maybe-defined ENV

The issue has been closed, because as mentioned above we are replacing the $env/* modules with the new env.ts feature.

[Rich-Harris]

What the fuck are you talking about?

[anly2]

You still need .env files.

I was referring to the .env file without affixes, which could hold "defaults" / no sensitive values - not to the ones actually supplying the values like .env.local

I know that that name actually comes from vite, but if there is a way to achieve a "rename" and have something like defaults.env (no sensitive info, just declarations with defaults), I think that would be way more obvious and intuitive.
(No need to change formats/"types" into ".ts")

I can stomach the ever-growing pile of .ts config files in the root of the project, when they are meant to be done once "at setup" and then not expected to change much later.
But this env.ts will reasonably change throughout the project's lifetime.

SvelteKit does however evaluate them at build time, because it runs your app at build time

You say that as if it's a justification for the specialness and complexity of "static"/"build-time" variables.
In that run of the app, the env vars should not be special at all - they are (dynamic) env vars that happen to have a value you injected at build time - like the CMS API key you mention.
There is absolutely no problem with running extra phases in the build job.
But don't bloat the setup/config unnecessarily or make things confusing because of it.

...you seem to be implying that values should be hardcoded in the app, rather than it being possible to create different builds by building with different environment variables

That's not what I am implying.
You can want different builds - no problem - but there are other ways to customize these.
And conflating "build options" with "app env vars" is just confusing.
(You can say "This comes from vite", but it's not the same)

Your logical leap should serve as a point against "static env vars":
"Values hardcoded in the app" are taboo, and yet "automating the hardcoding" via the build job is acceptable?

In your example of a "CMS with prerendering", the needed API key is just a (dynamic) env var with nothing special about it.
It is not a "static" one, and you don't want it to be one, so it doesn't get baked into the final bundle.

So what I am saying is that "static env vars" are pointless.
In all the examples so far, "dynamic" env vars are what is needed.

The parts talking about "optimisations" belong in obvious build system flags/options, which are less likely to get misunderstood by users/developers.
Although I am yet to see a good example of why you want "static" variables, if you really wanted to support those (for say, "user-driven build flags"), then why not make it painfully obvious by requiring a staticPrefix like STATIC_. You are already handling prefixes.

Everything else has "simpler"* alternatives, like constants.ts or static-data.json or assets/contacts.csv.
Any of these can be mounted/injected into the build job's container. The first two can even be imported without extra hassle. And they can be static from-there-on but can still have a "dynamic nature" during building (like pulling some CMS contents).
(* If not "simpler", for sure "less footguns")

Does that get optimized/tree shaken away if SOMETHING isn't defined?

No.

While you are technically correct because of the explicit import in @mdierolf's example,
you are answering according to the letter and not the spirit of the question.

It is easy to imagine someone importing from $env/static/private instead.
Whether by mistake, they don't notice, don't think about it, or don't know the difference - it doesn't matter.
With the new implementation, it's not hidden in the imports, but unless people already know to look for it in the config file, it is just as easy to mess up. (Will be the first thing overlooked during a review)

So if you didn't have the import line, then the answer is "it depends".

And as documented here, it can actually get optimized away:
https://svelte.dev/docs/kit/environment-variables#Explicit-environment-variables

Because this variable is static, the component shown here will be excluded from the JavaScript bundle unless SHOW_DEBUG_OVERLAY is truthy

{#if SHOW_DEBUG_OVERLAY}
    <DebugOverlay />
{/if}

I personally think this is a bad example, because I would not want to rebuild the whole app to turn "debug mode" on...
SHOW_DEBUG_OVERLAY is a "feature flag" and as such should be dynamic and not static. And to prevent debug code from loading all the time, I should be able to use dynamic imports.

But to my previous point - if you still want "build flags" for some reason, make them obviously different, like with a STATIC_ prefix, and don't affect "normal" env vars. No special imports or declaration options to watch out for...

---

All that I expect from an "$env" module is:

• an easier way to import from it, or as easy as using process.env
• effortless name checking
  (so I am warned when I mistype PUBIC)
• a mechanisms to prevent leaking PRIVATEs to browsers
  (like the separation with PUBLIC_ prefixing and the forbidden imports in frontend source code)
• no new burdens - nothing new to remember / edit / maintain

You mostly had the easy imports.
If they weren't partitioned into 4 categories (dynamic|static)/(private|public), that would have been it.
I wish the public vars were accessible via the "private" namespace, so to effectively have "ALL" and "PUBLIC". But that's a minor squabble compared to the confusion added by "static env vars".
(Also, running tests with these virtual modules is painful, but that's an entirely separate issue)

You had effortless name checking.
The use of .env (just that) to feed the var names, defaults, and descriptions (comments) - that was convenient.
(In an ideal world, it would be called something like defaults.env)
But I would not have introduced the (corrupting) full power of javascript by going to a .ts file.

You had a mechanism to prevent leaking PRIVATEs to browsers.
The convention of prefixing the vars with something like PUBLIC_ is obvious and understood.
The forbidden importing is great.
In the new implementation I can call them whatever I want, but I have to remember to declare in the .ts file with public: true.
And I will anyway still prefix them with PUBLIC_ because I want the "obviousness"...

[Rich-Harris]

But this env.ts will reasonably change throughout the project's lifetime.

Exactly — it deserves to be treated as source code, and subject to version control etc.

You say that as if it's a justification for the specialness and complexity of "static"/"build-time" variables.

You're conflating different things. The CMS API key is a regular dynamic variable that you need to make available at build time if you want to use it at build time. The exact same thing happens with $env/dynamic/private. It is not a static variable. You can of course have static variables — in SvelteKit 2 you do so by importing from $env/static/private, in SvelteKit 3 you do so by configuring the variable itself as static. But that's a thing you have to opt into.

"Values hardcoded in the app" are taboo, and yet "automating the hardcoding" via the build job is acceptable?

Hardcoded in the app's source code is a taboo, yes. Evaluating the value at bundle time (again, in the cases where you have opted into that) is no more a taboo than dead-code-eliminating an if (dev) doSomeExtraChecks() block in production.

So what I am saying is that "static env vars" are pointless.

And I am saying you are entitled to your opinion! Others, including me, do not share it. You are free to simply not use this feature.

I personally think this is a bad example, because I would not want to rebuild the whole app to turn "debug mode" on...

Debug builds are not a new concept!

The use of .env (just that) to feed the var names, defaults, and descriptions (comments) - that was convenient.

It's also unreliable — lots of teams forbid .env files being checked into version control. Separating definitions from values solves it for everyone.

The new system gives you

• effortless auto-importing (from two modules, instead of four)
• name checking/type safety
• public/private separation (you cannot import private vars into client code, same as before)
• optional validation, beyond 'this exists'
• choice over whether you want the PUBLIC_ prefix or not. Before it was necessary so that the system could differentiate them, but now it's only necessary if you want to differentiate them, and given that it'll just auto-import from the right place and prevent accidental leakage without you having to think about it, I would expect most people not to bother. It's needless ceremony
• choice at the variable level over whether something is evaluated at runtime or treated as a constant

The one tradeoff is that you now have to explicitly configure the environment variables, in a file that you will likely update at most once every few months. In exchange you get an environment variable system that's more powerful than the ones I've seen in any other framework (most of which seem to forgo type safety, and disallow public dynamic env vars, and so on).

Truly baffled that people in this thread are complaining.