Core

The core package can be used in any framework of your choice. To use it, figure out what prefix your framework uses for exposing environment variables to the client. For example, Astro uses PUBLIC_, while Vite uses VITE_. You should be able to find this in the frameworks documentation.

Install dependencies

First, install the core package:

npm install @nobara/core valibot

@nobara/corerequires a minimum of typescript@4.7.2.

Create your schema

Then, you can create your schema like so:

The file below is named env.ts, but you can name it whatever you want. Some frameworks even generate a env.d.ts file that will collide with env.ts, which means you will have to name it something else.

src/env.ts

import { createEnv } from "@nobara/core";
import { string, url, minLength } from "valibot";

export const env = createEnv({
  server: {
    DATABASE_URL: string([url()]),
    OPEN_AI_API_KEY: string([minLength(1)]),
  },

  /**
   * The prefix that client-side variables must have. This is enforced both at
   * a type-level and at runtime.
   */
  clientPrefix: "PUBLIC_",

  client: {
    PUBLIC_CLERK_PUBLISHABLE_KEY: string([minLength(1)]),
  },

  /**
   * What object holds the environment variables at runtime. This is usually
   * `process.env` or `import.meta.env`.
   */
  runtimeEnv: process.env,

  /**
   * By default, this library will feed the environment variables directly to
   * the valibot validator.
   *
   * This means that if you have an empty string for a value that is supposed
   * to be a number (e.g. `PORT=` in a ".env" file), valibot will incorrectly flag
   * it as a type mismatch violation. Additionally, if you have an empty string
   * for a value that is supposed to be a string with a default value (e.g.
   * `DOMAIN=` in an ".env" file), the default value will never be applied.
   *
   * In order to solve these issues, we recommend that all new projects
   * explicitly specify this option as true.
   */
  emptyStringAsUndefined: true,
});

Remove the clientPrefix and client properties if you only want the environment variables to exist on the server.

While defining both the client and server schemas in a single file provides the best developer experience, it also means that your validation schemas for the server variables will be shipped to the client. If you consider the names of your variables sensitive, you should split your schemas into two files.

src/env/server.ts

import { createEnv } from "@nobara/core";
import { string, url, minLength } from "valibot";

export const env = createEnv({
  server: {
    DATABASE_URL: string([url()]),
    OPEN_AI_API_KEY: string([minLength(1)]),
  },
  runtimeEnv: process.env,
});

src/env/client.ts

import { createEnv } from "@nobara/core";
import { string, minLength } from "valibot";

export const env = createEnv({
  clientPrefix: "PUBLIC_",
  client: {
    PUBLIC_CLERK_PUBLISHABLE_KEY: string([minLength(1)]),
  },
  runtimeEnv: process.env,
});

For all available options, see Customization.

You'll notice that if your clientPrefix is PUBLIC_, you won't be allowed to enter any other keys in the client object without getting type-errors. Below you can see we get a descriptive error when we set VITE_PUBLIC_API_URL instead of PUBLIC_API_URL:

invalid client prefix

This client prefix is also enforced at runtime to make sure validation works on both the server and client.

Validate schema on build (recommended)

The steps required to validate your schema on build will vary from framework to framework, but you'll usually be able to import the env file in your configuration file, or in any file that's pulled in the beginning of the build process.

Note that some frameworks don't import their environment variables in their configuration file.

Use your schema

Then, import the env object in your application and use it, taking advantage of type-safety and auto-completion:

some-api-endpoint.ts

import { env } from "~/env"; // On server

export const GET = async () => {
  // do fancy ai stuff
  const magic = await fetch("...", {
    headers: { Authorization: env.OPEN_AI_API_KEY },
  });
  // ...
};

Additional strictness for `runtimeEnv`

Exactly one of runtimeEnv and runtimeEnvStrict should be specified.

If your framework doesn't bundle all environment variables by default, but instead only bundles the ones you use, you can use the runtimeEnvStrict option to make sure you don't forget to add any variables to your runtime.

src/env.ts

import { createEnv } from "@nobara/core";

export const env = createEnv({
  clientPrefix: "PUBLIC_",
  server: {
    DATABASE_URL: z.string().url(),
    OPEN_AI_API_KEY: z.string().min(1),
  },
  client: {
    PUBLIC_PUBLISHABLE_KEY: z.string().min(1),
  },
  /**
   * Makes sure you explicitly access **all** environment variables
   * from `server` and `client` in your `runtimeEnv`.
   */
  runtimeEnvStrict: {
    DATABASE_URL: process.env.DATABASE_URL,
    OPEN_AI_API_KEY: process.env.OPEN_AI_API_KEY,
    PUBLIC_PUBLISHABLE_KEY: process.env.PUBLIC_PUBLISHABLE_KEY,
  },
});

When using the strict option, missing any of the variables in runtimeEnvStrict will result in a type error:

missing runtimeEnv