Why import.meta.env is undefined after a Vite build, and how to fix it.

Almost every case is one of these. The first three apply on any host; the last two are specific to how Canner scopes variables.

Vite’s docs say the constants are “statically replaced at build time”. There is no import.meta.env object in the browser to look things up in later. The build reads the value once and writes it into the output as text:

• vite build runs in production mode, so it loads .env, .env.local, .env.production and .env.production.local. Variables already set in the environment when Vite starts take priority over all of them.
• The same replacement happens in index.html: %VITE_API_URL% becomes the value at build time.
• Anything with the VITE_ prefix ends up in public JavaScript. Vite’s own docs say these variables should not hold API keys. Keep secrets on a server.

// src/api.ts, what you write
const base = import.meta.env.VITE_API_URL;

// dist/assets/index-<hash>.js, what ships after
// VITE_API_URL=https://api.example.ca vite build
const base = "https://api.example.ca";

// Check what a build actually contains:
grep -r "api.example.ca" dist/assets

Canner runs your build script with the project’s variables in the environment, so Vite picks them up like any other environment variable. The build log confirms it with a line such as [canner] wrote 6 env var(s) to .env.production (build phase). Set values in the project’s Env Vars tab, not in a committed .env.production. The Vite docs page covers the rest of the deploy.

A changed value applies on the next deploy, because the old bundle already contains the old string. Two less obvious points from the environment variables docs:

• Sensitive hides a value in the dashboard. It does not hide it from visitors: a sensitive VITE_ value is still written into the public bundle.
• Runtime only keeps a secret away from the build, which is exactly why a VITE_ variable with that scope is always undefined.

Vite’s define option replaces a global name with a JSON value during the build. Use it for values you choose on purpose, such as a preview banner or a version string in your error reports:

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

// CANNER_ENV is "production" or "preview" during a Canner build.
// It has no VITE_ prefix, so pass it through define, by name.
export default defineConfig({
  plugins: [react()],
  define: {
    __APP_ENV__: JSON.stringify(process.env.CANNER_ENV ?? "local"),
    __COMMIT__: JSON.stringify(process.env.CANNER_COMMIT_SHA ?? "dev"),
  },
});

Build-time values mean one build per environment. If you want to promote the exact dist/ you tested in staging into production, the values can’t be baked in. They have to be fetched or injected when the page loads.

Your deploy step writes a different config.json per environment and leaves the JavaScript alone. Check the content type: a single-page-app host answers any unknown path with index.html and a 200, so a missing config looks like a successful request.

// public/config.json is copied to dist/ untouched
{ "apiUrl": "https://api.staging.example.ca" }

// src/main.ts
const res = await fetch("/config.json", { cache: "no-store" });
const type = res.headers.get("content-type") ?? "";
if (!res.ok || !type.includes("json")) {
  // An SPA host answers a missing file with index.html
  throw new Error("config.json is missing from this deploy");
}
export const config: { apiUrl: string } = await res.json();

Put <!--app-env--> in the <head> of index.html, and a small server fills it from its own environment when it starts. Only public values go in: the script tag is readable by every visitor.

// server.mjs: serves dist/ and writes public values into index.html
import express from "express";
import { readFileSync } from "node:fs";

const env = { apiUrl: process.env.API_URL }; // public values only
const html = readFileSync("dist/index.html", "utf8").replace(
  "<!--app-env-->",
  "<script>window.__ENV=" + JSON.stringify(env).replace(/</g, "\\u003c") + "</script>",
);

const app = express();
app.use(express.static("dist", { index: false }));
app.use((_req, res) => res.type("html").send(html));
app.listen(process.env.PORT || 3000);

On Canner every variable change applies on the next deploy, and every deploy runs the build. Runtime config doesn’t save you a build here. It is worth it when the same artifact also ships somewhere else, or when your app already has a Node server.

The simpler path is one Canner project per environment: a staging project and a production project, which may be connected to the same repository, each with its own VITE_ values. Starter includes unlimited projects. Note that a Starter project sleeps after three hours idle, which is usually fine for staging.

If you go with Pattern 2, Canner detects a project that ships its own Node server alongside the built client and runs the server instead of serving dist/ statically. More framework guides are in hosting by framework.