Copy page

Guides

Environment Variables

Dev Portal is built on top of Vite and uses their approach for managing environment variables.

Dev Portal exposes environment variables under the import.meta.env object as strings automatically.

To prevent accidentally leaking environment variables to the client, only variables prefixed with ZUDOKU_PUBLIC_ are exposed to your Zudoku-processed code.

Local Env Files

When developing locally, you can create a .env file in the root of your project and add environment-specific variables. See the Vite documentation for more information on supported files.

Here is an example of a .env.local file:

Code
ZUDOKU_PUBLIC_PAGE_TITLE=My Page Title

You can access this variable in your application like this:

Code
const title = import.meta.env.ZUDOKU_PUBLIC_PAGE_TITLE;

Configuration Files

Environment variables can also be used in your configuration files. When referencing environment variables in your configuration files, you can use process.env directly.

Code
import type { ZudokuConfig } from "zudoku";

const config: ZudokuConfig = {
  authentication: {
    type: "auth0",
    clientId: process.env.ZUDOKU_PUBLIC_AUTH_CLIENT_ID,
    domain: process.env.ZUDOKU_PUBLIC_AUTH_DOMAIN,
  },
};

React Components

If you need to access environment variables inside a custom react component, you can access them via import.meta.env. Public environment variables are inlined during the build process.

Code
import React from "react";

export const MyComponent = () => {
  return <h1>{import.meta.env.ZUDOKU_PUBLIC_PAGE_TITLE}</h1>;
};

IntelliSense for TypeScript

By default, Dev Portal provides type definitions for import.meta.env in zudoku/client.d.ts. While you can define more custom env variables in .env.[mode] files, you may want to get TypeScript IntelliSense for user-defined env variables that are prefixed with ZUDOKU_PUBLIC_.

To achieve this, you can create a zudoku-env.d.ts in the src directory, then augment ImportMetaEnv like this:

Code
/// <reference types="zudoku/client" />

interface ImportMetaEnv {
  readonly ZUDOKU_PUBLIC_APP_TITLE: string;
  // more env variables...
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

Environment Variables in Zuplo

Set Dev Portal variables in the Zuplo Portal under Settings > Environment Variables, the same place you set gateway variables. For the Dev Portal:

• Only variables whose names start with ZUPLO_PUBLIC_ or ZUDOKU_PUBLIC_ are available. Both prefixes work the same way.
• Only configuration variables are available. Zuplo never sends secret variables to the Dev Portal build, even if their names have a public prefix.
• Values are read when the portal is built and are embedded in the published site. Redeploy the environment after you change a value.

For how Dev Portal variables differ from gateway variables, see Configuring Environment Variables.

Zuplo Build Variables

When Zuplo builds your Dev Portal, it sets the following variables. You don't need to create them.

Read these variables with import.meta.env in your custom components and plugins:

Code
export const EnvironmentBadge = () => (
  <span>{import.meta.env.ZUPLO_ENVIRONMENT_TYPE}</span>
);

ZUPLO_ENVIRONMENT_TYPE in the Dev Portal build uses different values than the ZUPLO_ENVIRONMENT_TYPE and ZUPLO_ENVIRONMENT_STAGE variables available to your gateway. See System Environment Variables for the gateway values.

Check the Environment in zudoku.config.tsx

The configuration file runs twice: once in Node.js when the build starts, and again as part of the built site, which renders your pages and <head> tags. In the built site, process.env only resolves variables that start with ZUPLO_PUBLIC_ or ZUDOKU_PUBLIC_, so process.env.ZUPLO_ENVIRONMENT_TYPE is undefined there. Read import.meta.env first and fall back to process.env to get the same value in both places:

zudoku.config.tsx
const environmentType =
  import.meta.env?.ZUPLO_ENVIRONMENT_TYPE ?? process.env.ZUPLO_ENVIRONMENT_TYPE;

const isProduction = environmentType === "PRODUCTION";

The build logs a warning that process.env.ZUPLO_ENVIRONMENT_TYPE isn't prefixed with ZUPLO_PUBLIC_ or ZUDOKU_PUBLIC_. You can ignore it.

To avoid the warning, create a ZUPLO_PUBLIC_ variable with a different value for each environment instead. Both approaches include the value in the client-side bundle, so use them only for values that aren't secret.

Local Development

Locally, put ZUPLO_PUBLIC_ and ZUDOKU_PUBLIC_ variables in a .env file in your Dev Portal folder, as described in Local Env Files. Variables you set in the Zuplo Portal aren't available locally.

zuplo dev sets ZUPLO_SERVER_URL to your local gateway, for example http://localhost:9000. ZUPLO_ENVIRONMENT_TYPE is never PRODUCTION locally, so isProduction in the previous example is false.