Environment Variables

Environment Variables are a way to store sensitive information that your application needs to function. This could be anything from API keys to Database credentials. FrogBot allows you to easily use Environment Variables within your config and throughout your application.

Next.js Applications

If you are using Next.js, no additional setup is required other than creating your .env file. To use Environment Variables, add a .env file to the root of your project:

project-name/
├─ .env
├─ package.json
├─ frogbot.config.ts

Here is an example of what an .env file might look like:

SERVER_URL=localhost:3000
DATABASE_URL=mongodb://localhost:27017/my-database

To use Environment Variables in your FrogBot Config, you can access them directly from process.env:

import { buildConfig } from 'frogbot'

export default buildConfig({
  serverURL: process.env.SERVER_URL,
  // ...
})

Typed environment variables

Use defineEnv to parse and validate your server-side environment when your application starts. It reports all invalid or missing variables together and returns a typed, frozen object. Create src/env.ts:

import { defineEnv, env, frogbotEnv } from 'frogbot/env'

export const envService = defineEnv({
  ...frogbotEnv,
  emailEnabled: env.boolean().default(false),
  smtpUrl: env
    .string()
    .requiredWhen((values) => values.emailEnabled === true),
})

Then use the resolved values in your FrogBot config:

import { sqliteAdapter } from '@frogbotai/db-sqlite'
import { buildConfig } from 'frogbot'

import { envService } from './env.js'

export default buildConfig({
  secret: envService.frogbotSecret,
  db: sqliteAdapter({
    client: {
      url: envService.databaseUrl,
    },
  }),
  collections: [],
})

This replaces fallback expressions such as process.env.FROGBOT_SECRET || '' with values that have already been validated.

Builders and modifiers

The env factory provides these builders:

Builder	Type	Result
`env.string()`	`EnvBuilder<string>`	The raw string.
`env.number()`	`EnvBuilder<number>`	The value parsed with `Number()`. A value that isn’t a number fails validation.
`env.boolean()`	`EnvBuilder<boolean>`	`true` or `false`. See Names and parsing for accepted values.
`env.enum(values)`	`EnvBuilder<T[number]>`	One of the listed strings. Any other value fails validation. `values` needs at least one string.
`env.custom(parse)`	`EnvBuilder<T>`	The value returned by `parse(raw)`. If `parse` throws, the error message is reported as a validation issue.

Every builder returns an immutable builder, so each modifier returns a new one. Without a modifier, an unset variable resolves to undefined.

Modifier	Argument	Default	Behavior
`.default(value)`	`T`	—	Uses `value` when the variable is unset or empty. The resolved type no longer includes `undefined`. Throws when combined with `.required()` or `.requiredWhen()`.
`.required()`	—	—	Reports the variable as missing when it’s unset or empty. Throws when combined with `.default()` or another required modifier.
`.requiredWhen(predicate)`	`(values: Record<string, unknown>) => boolean`	—	Required only when `predicate` returns `true`. The predicate receives all values resolved during the first parsing pass. If it throws, `defineEnv` throws. Same restrictions as `.required()`.
`.name(name)`	`string`	Derived from the property name	Reads this environment variable instead. `name` must match `^[A-Z_][A-Z0-9_]*$`, and each name can be used by only one property.

frogbotEnv includes these common builders:

Property	Type	Default	Description
`nodeEnv`	`'development' \| 'production' \| 'test'`	`'production'`	Read from `NODE_ENV`.
`logLevel`	`'trace' \| 'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal' \| 'silent'`	`'info'`	Read from `LOG_LEVEL`.
`port`	`number`	`3000`	Read from `PORT`.
`frogbotSecret`	`string`	Required	Read from `FROGBOT_SECRET`.
`databaseUrl`	`string`	Required	Read from `DATABASE_URL`.

You can replace a base builder after spreading frogbotEnv:

const envService = defineEnv({
  ...frogbotEnv,
  port: env.number().default(4000),
})

Names and parsing

Property names become uppercase environment variable names with underscores before uppercase letters. For example, apiUrl becomes API_URL, gitSha1 becomes GIT_SHA1, and s3Bucket becomes S3_BUCKET. Use .name() when the environment variable follows another convention. Empty strings count as unset values. This is stricter than provider SDKs that may accept an empty API key as present. Numbers use JavaScript number parsing, so PORT=0 resolves to 0 and invalid numbers fail validation. Boolean parsing is case-insensitive and accepts:

True: 1, on, t, true, y, yes
False: 0, f, false, n, no, off

Other boolean values fail validation. When NODE_ENV=test, required checks are skipped so tests do not need every application secret. Present values are still parsed and can still produce validation errors.

Client-side Environments

For security and safety reasons, the Admin Panel does not include Environment Variables in its client-side bundle by default. Next.js provides a mechanism to expose Environment Variables to the client-side bundle when needed. If you are building a custom component and need to access Environment Variables from the client side, prefix them with NEXT_PUBLIC_.

Important: Be careful about what variables you provide to your client-side code. Analyze every single one to make sure that you’re not accidentally leaking sensitive information. Only ever include keys that are safe for the public to read in plain text.

For example, if you’ve got the following Environment Variable:

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_XXXXXXXXXXXXXXXXXX

This key will automatically be made available to the client-side FrogBot bundle and can be referenced in your Custom Component as follows:

'use client'
import React from 'react'

const stripeKey = process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY

const MyClientComponent = () => {
  // do something with the key

  return <div>My Client Component</div>
}

For more information, check out the Next.js documentation.

Outside of Next.js

If you are using FrogBot outside of Next.js, we suggest using the dotenv package to handle Environment Variables from .env files. This will automatically load your Environment Variables into process.env. To do this, import the package as high up in your application as possible:

import dotenv from 'dotenv'
dotenv.config()

import { buildConfig } from 'frogbot'

export default buildConfig({
  serverURL: process.env.SERVER_URL,
  // ...
})

Tip: Be sure that dotenv can find your .env file. By default, it will look for a file named .env in the root of your project. If you need to specify a different file, pass the path into the config options.

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Next.js Applications

Typed environment variables

Builders and modifiers

Names and parsing

Client-side Environments

Outside of Next.js

​Next.js Applications

​Typed environment variables

​Builders and modifiers

​Names and parsing

​Client-side Environments

​Outside of Next.js

Next.js Applications

Typed environment variables

Builders and modifiers

Names and parsing

Client-side Environments

Outside of Next.js