DEV Community: Samuel Fontebasso

Stop trusting environment variables in your TypeScript apps

Samuel Fontebasso — Sun, 28 Jun 2026 06:04:11 +0000

Environment variables look simple until one of them is missing, empty, malformed, or interpreted in a way your application did not expect.

In TypeScript projects, this can be easy to overlook. The code may be typed, the build may pass, and the app may still ship with broken configuration.

This is especially common in frontend builds, server-side rendering, backend services, CLI tools, Docker images, and CI/CD pipelines, where configuration is injected from outside the codebase.

That is the problem valitype is designed to address: strict, type-safe validation of environment variables with zero dependencies.

The problem with environment variables

Environment variables are always external input.

They can come from:

.env files
CI/CD variables
Docker or container platforms
hosting providers
build scripts
deployment environments

TypeScript can describe what your code expects, but it cannot guarantee that the environment actually contains valid values.

This looks harmless:

const apiUrl = import.meta.env.VITE_API_URL
const debug = Boolean(import.meta.env.VITE_DEBUG)
const port = Number(process.env.PORT)

But simple casting can hide invalid configuration:

Boolean('false') // true
Boolean('0')     // true

Number('0xff') // 255
Number('1e5')  // 100000
Number('')     // 0

For application configuration, “parseable” is not the same as “valid”.

Invalid configuration should be caught before deployment, either during build, CI, server startup, or a dedicated validation step.

The problem in React and frontend builds

React applications usually do not read environment variables directly at runtime in the browser. Instead, tools like Vite and frameworks like Next.js inject selected values during build time.

That makes validation important.

Once the frontend bundle is built and deployed, changing a bad environment variable usually means rebuilding and redeploying the application.

For frontend apps, validation should answer a few basic questions before shipping:

Is the variable present when required?
Is the value non-empty?
Is the URL really an http or https URL?
Is the environment one of the allowed values?
Is a numeric value actually written as a decimal number?

A small validation layer can catch these problems early and fail clearly.

Vite environment variables

Vite exposes environment variables through import.meta.env.

By default, only variables prefixed with VITE_ are exposed to client-side code.

Example:

VITE_API_URL=https://api.example.com
VITE_APP_ENV=production
API_SECRET=super-secret-value

In application code:

const apiUrl = import.meta.env.VITE_API_URL
const appEnv = import.meta.env.VITE_APP_ENV

VITE_API_URL and VITE_APP_ENV are available to the frontend bundle. API_SECRET is not exposed because it does not use the VITE_ prefix.

That prefix rule is useful, but it is not validation.

Vite decides what can be exposed. It does not guarantee that the exposed values are present, valid, or safe for your application logic.

With valitype, you can create a small config module:

import { validateValue } from 'valitype'

export const config = {
  apiUrl: validateValue('VITE_API_URL', import.meta.env.VITE_API_URL, {
    type: 'url',
    required: true,
  }),

  appEnv: validateValue('VITE_APP_ENV', import.meta.env.VITE_APP_ENV, {
    type: { enum: ['development', 'staging', 'production'] },
    default: 'development',
  }),
}

Now the application has a clear configuration boundary.

Vite controls exposure. valitype controls validity.

This validation runs when the config module is executed. In frontend-only builds, use this pattern together with a prebuild validation step, CI check, or a tool like envguardr if you want the build itself to fail before deployment.

One rule still applies: never put secrets in VITE_ variables. Anything exposed through import.meta.env.VITE_* should be treated as public configuration.

Next.js environment variables

Next.js has both server-side and public environment variables.

Server-side variables can be read from process.env:

const apiUrl = process.env.API_URL

Public variables use the NEXT_PUBLIC_ prefix and can be exposed to the browser:

const appUrl = process.env.NEXT_PUBLIC_APP_URL

This separation is important, but it does not validate the values.

A safer approach is to create explicit config modules.

For server-side configuration:

import { validateValue } from 'valitype'

export const serverConfig = {
  apiUrl: validateValue('API_URL', process.env.API_URL, {
    type: 'url',
    required: true,
  }),

  nodeEnv: validateValue('NODE_ENV', process.env.NODE_ENV, {
    type: { enum: ['development', 'production', 'test'] },
    default: 'development',
  }),
}

For public configuration:

import { validateValue } from 'valitype'

export const publicConfig = {
  appUrl: validateValue('NEXT_PUBLIC_APP_URL', process.env.NEXT_PUBLIC_APP_URL, {
    type: 'url',
    required: true,
  }),
}

This keeps server-only values and browser-exposed values separate, while still validating both.

The important point is not to validate everything in one place blindly. Public config and server config have different security boundaries.

Node.js backend and CLI usage

Backend services and CLI tools often depend heavily on environment variables.

Examples:

const port = process.env.PORT
const logLevel = process.env.LOG_LEVEL
const region = process.env.AWS_REGION
const queueArn = process.env.QUEUE_ARN

If these values are wrong, the application may start incorrectly, connect to the wrong service, or fail later during execution.

With valitype, you can validate them at startup:

import { validateValue, validators } from 'valitype'

export const config = {
  port: validateValue('PORT', process.env.PORT, {
    type: 'number',
    default: 3000,
  }),

  logLevel: validateValue('LOG_LEVEL', process.env.LOG_LEVEL, {
    type: { enum: ['debug', 'info', 'warn', 'error'] },
    default: 'info',
  }),

  awsRegion: validateValue('AWS_REGION', process.env.AWS_REGION, {
    type: 'custom',
    validator: validators.oneOf([
      'us-east-1',
      'us-east-2',
      'us-west-1',
      'us-west-2',
      'eu-west-1',
      'eu-central-1',
      'ap-southeast-1',
      'ap-southeast-2',
    ]),
    required: true,
  }),

  queueArn: validateValue('QUEUE_ARN', process.env.QUEUE_ARN, {
    type: 'custom',
    validator: validators.awsArn('sqs'),
    required: true,
  }),
}

This is useful for:

Node.js APIs
workers
queue consumers
scheduled jobs
CLI tools
Dockerized services
CI/CD scripts

The application either starts with valid configuration or fails early with a clear error.

Validating config with valitype

valitype is a small TypeScript library for validating environment variables and configuration values.

It is not trying to replace full schema validation libraries. If you need complex object parsing, nested schemas, form validation, or full data validation, tools like Zod, Valibot, Joi, or Yup may be a better fit.

valitype focuses on a narrower problem:

validate environment variables
return typed values
avoid runtime dependencies
fail early with structured errors
keep configuration code easy to read

Example:

import { validateValue } from 'valitype'

const port = validateValue('PORT', process.env.PORT, {
  type: 'number',
  required: true,
})

The return type is inferred from the rule. In this case, port is a number.

For booleans:

const debug = validateValue('DEBUG', process.env.DEBUG, {
  type: 'boolean',
  default: false,
})

For enums:

const environment = validateValue('APP_ENV', process.env.APP_ENV, {
  type: { enum: ['development', 'staging', 'production'] },
  default: 'development',
})

For custom validation:

import { validateValue, validators } from 'valitype'

const apiKey = validateValue('API_KEY', process.env.API_KEY, {
  type: 'custom',
  validator: validators.regex(/^[a-z0-9]{32}$/),
  required: true,
})

Structured error handling

When validation fails, valitype throws a ValidationError.

import { validateValue, ValidationError } from 'valitype'

try {
  validateValue('PORT', '0xff', {
    type: 'number',
    required: true,
  })
} catch (err) {
  if (err instanceof ValidationError) {
    console.log(err.code)
    console.log(err.key)
    console.log(err.value)
    console.log(err.message)
  }
}

This makes errors easier to handle programmatically.

Available error codes include:

REQUIRED
INVALID_NUMBER
INVALID_BOOLEAN
INVALID_URL
INVALID_ENUM
INVALID_CUSTOM
UNKNOWN_RULE

That is useful when you want to format errors differently in a CLI, fail a validation step in CI, or return consistent diagnostics in tooling.

Why strict validation matters

Some JavaScript conversions are convenient, but too permissive for configuration.

For example, valitype rejects values like:

0xff
1e5
''
'   '

for number validation.

It also requires URL values to use http or https, avoiding accidental acceptance of schemes like:

file://
ftp://

For environment variables, strict behavior is usually safer than permissive parsing.

Configuration should be explicit.

Where valitype came from

valitype started as the validation layer behind envguardr, a CLI tool for validating environment variables using a JavaScript or TypeScript schema.

The first version was created while building envguardr for the Amazon Q Developer “Quack The Code” challenge.

Since then, valitype has continued as a standalone open source library focused on strict, dependency-free environment validation for TypeScript projects.

Installation

npm install valitype

Final thoughts

Environment variables are part of your application boundary.

They come from outside your code, so they deserve validation before your app depends on them.

For TypeScript projects, the goal is not just to make configuration typed after reading it. The goal is to reject invalid configuration before it reaches production.

That is where a small tool like valitype can help.

Validate Your Env at Build Time — with Custom Rules Powered by Amazon Q Developer

Samuel Fontebasso — Sun, 11 May 2025 22:21:22 +0000

This is a submission for the Amazon Q Developer "Quack The Code" Challenge: Crushing the Command Line

What I Built

I created envguardr, a CLI tool that validates environment variables at build time. It’s useful for projects where .env files or runtime checks aren't enough. It handles types, required fields, and default values, but I felt it needed more flexibility.

To address that, I enhanced the underlying validation package valitype by adding support for custom validators. This was one of the ideas suggested by Amazon Q Developer during the challenge. That single improvement unlocked a range of advanced use cases.

Demo

Step-by-step

Install envguardr globally:

$ npm install -g envguardr

Create an env.schema.js file with custom validation logic:

module.exports = {
  API_KEY: {
    type: 'custom',
    validator: (v) => /^[a-z0-9]{16}$/.test(v || ''),
    errorMessage: 'API_KEY must be 16 alphanumeric characters',
    required: true
  }
}

Then run:

$ envguardr validate env.schema.js

Terminal demo: running `envguardr` with a custom schema validation for `API_KEY`:

Code Repository

https://github.com/fontebasso/valitype

https://github.com/fontebasso/envguardr

How I Used Amazon Q Developer

This challenge was my first experience with Amazon Q Developer, and I was genuinely impressed. It’s exactly the kind of tool I always felt was missing for developers working with AI.

Amazon Q Developer was able to read my codebase, understand its context, and assist in meaningful ways. It helped me improve typing, write better tests, fix subtle lint issues, and explore useful new features.

From the several improvements it suggested for valitype, I chose to implement custom validators. That feature alone made envguardr much more powerful, giving it the flexibility needed for advanced configuration validation.

Stop trusting your .env file

Samuel Fontebasso — Sat, 10 May 2025 17:30:38 +0000

A personal take on how I stopped shipping broken Vite builds by validating environment variables before the build even starts. No JSON schema, no magic — just JavaScript and clear rules.

A blunt tool for a stupidly common problem

After building more React apps with Vite than I care to admit, I noticed a recurring theme: most of the time, what broke wasn't the code — it was the environment.

A missing VITE_ variable. A malformed URL. A boolean that was actually a string. A Docker ARG that never made it to the final build. And of course, the worst kind: it didn't crash the build... it crashed the user experience.

I got tired of catching these bugs in staging (or worse, production), so I built a tool that would blow up my build early — on purpose.

It's called envguardr, and it's dead simple.

The problem with Vite and environment variables

Vite helpfully injects any variable prefixed with VITE_ into import.meta.env, but:

It doesn't check if the variable is actually defined.
It doesn't validate types.
It assumes everything is a string, and that's your problem now.

You can write if (VITE_ENABLE_FEATURE) and end up with true, "true", "banana", or undefined — and Vite will happily compile it.

What I use now (and why it finally works)

My stack: React + Vite frontend, Nginx for static serving, Docker multistage for builds. Nothing exotic. What changed was the discipline — and the tooling.

Here’s how I validate my environment before anything gets built:

// env.schema.js
export default {
  VITE_API_URL: { type: 'url', required: true },
  VITE_APP_VERSION: { type: 'string', required: true },
  VITE_APP_ENV: { 
    type: { enum: ['staging', 'production'] },
    default: 'production' 
  },
}

That’s it. No YAML, no JSON schema. Just JavaScript and some rules that make sense.

The Dockerfile

FROM node:18 AS builder

ARG VITE_API_URL
ARG VITE_APP_VERSION
ARG VITE_APP_ENV

ENV VITE_API_URL=$VITE_API_URL
ENV VITE_APP_VERSION=$VITE_APP_VERSION
ENV VITE_APP_ENV=$VITE_APP_ENV

WORKDIR /app
COPY . .

RUN npm ci
RUN npx envguardr validate ./env.schema.js
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html

Validation happens before the build. If anything’s missing or wrong, it fails fast — as it should.

What changed

Since I added envguardr:

I haven’t shipped a broken build.
I don’t debug missing env vars in production anymore.
My CI logs finally tell me what’s wrong instead of silently succeeding.

No magic. Just boundaries.

For anyone who's ever dealt with process.env in Docker

This isn't another generic linter. It's a purpose-built CLI for one thing: making sure your environment is what your app actually needs.

You write a schema. You run envguardr. It validates your env. If something's wrong, it kills the build.

That's the whole point.

Try it

npm install --save-dev envguardr
npx envguardr validate ./env.schema.js

I built envguardr to protect myself from careless builds. It just happens to work for other people too.