Guides

Environment Variables

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

Zudoku 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(sh)
 
ZUDOKU_PUBLIC_PAGE_TITLE=My Page Title

You can access this variable in your application like this:

Code(ts)
 
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(ts)
 
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(tsx)
 
import React from "react";

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

IntelliSense for TypeScript

By default, Zudoku 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(typescript)
 
/// <reference types="zudoku/client" />

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

interface ImportMeta {
  readonly env: ImportMetaEnv;
}