smartEnv-elsolya

Smart, Typed, Secure Environment Configuration Loader for JavaScript & Frontend Projects

smartEnv-elsolya is a library for managing environment variables in a smart, secure, and type-safe way, designed to solve the real-world problems that any Frontend or Fullstack project faces when dealing with .env files.

Why smartEnv-elsolya Exists

Managing environment variables in JavaScript projects is often:

• Unorganized
• Without validation
• Without type safety
• Prone to secret leaks
• Different from one tool to another (Vite / Next / Node)

This library solves all these problems in one place.

Core Problems This Library Solves

1. Lack of a standard for managing .env files
2. Relying on process.env without any guarantees
3. Absence of validation for env values
4. Production errors due to missing or incorrect env variables
5. Difficulty managing multiple environments (dev / staging / prod)
6. Lack of typed config in Frontend

Key Features

• Automatic environment detection - No manual configuration needed
• Typed environment variables - Full TypeScript support with autocomplete
• Schema validation - Built on Zod for runtime type checking
• Secure variable exposure - Only expose what you explicitly allow
• Frontend & Backend support - Works with any JavaScript/TypeScript project
• CLI tooling - Validate, print, and diff environments
• CI/CD friendly - Fail builds on invalid configuration
• Monorepo ready - Supports shared and per-app configurations

Installation

npm install smartEnv-elsolya

or:

yarn add smartEnv-elsolya

Project Structure Example

my-app/
├── env/
│   ├── .env.base
│   ├── .env.dev
│   ├── .env.staging
│   ├── .env.prod
│   └── .env.local
├── src/
│   ├── config/
│   │   └── env.ts
│   ├── api.ts
│   └── main.ts
├── smart-env.config.ts
└── package.json

Environment File Strategy

Supported Files

.env
.env.base
.env.{env}
.env.{env}.{region}
.env.local

Merge Order

Files are loaded and merged in this order:

1. .env
2. .env.base
3. .env.{env}
4. .env.{env}.{region}
5. .env.local (ignored in production)

Later files override earlier ones.

Environment Detection Strategy

The library automatically determines the active environment using the following priority:

1. CLI flags (--env=staging)
2. CI environment variables
3. Git branch name
4. Domain (for frontend builds)
5. NODE_ENV
6. Default fallback

No manual switching required in most cases.

Defining the Environment Schema

Example using Zod

Create a central schema file:

import { defineEnvSchema } from 'smartEnv-elsolya'
import { z } from 'zod'

export const envSchema = defineEnvSchema({
  APP_NAME: z.string(),
  APP_ENV: z.enum(['dev', 'staging', 'prod']),
  API_URL: z.string().url(),
  ENABLE_ANALYTICS: z.boolean(),
  TIMEOUT: z.number().min(1000)
})

This schema is the single source of truth for your environment configuration.

Loading the Environment

import { loadEnv } from 'smartEnv-elsolya'
import { envSchema } from './schema'

export const env = loadEnv({
  schema: envSchema,
  envDir: './env',
  expose: ['APP_NAME', 'API_URL', 'ENABLE_ANALYTICS'],
  freeze: true
})

What Happens During loadEnv

1. Detect active environment
2. Resolve applicable .env files
3. Load and merge variables
4. Parse values into correct types
5. Validate against schema
6. Block invalid or missing values
7. Freeze configuration (optional)
8. Expose only safe variables to frontend

Using the Config in Code

import { env } from './config/env'

fetch(`${env.API_URL}/users`)

TypeScript guarantees:

• env.API_URL exists
• It is a valid URL
• It cannot be undefined

Trying to access a non-existent key will fail at compile time.

Runtime Safety

Undefined Access Protection

env.NOT_EXIST

Results in a runtime error with a clear message.

Frozen Configuration

When freeze: true is enabled:

• No reassignment allowed
• No mutation possible
• Production-safe behavior

Frontend Security Model

Only variables explicitly listed in expose are available to frontend bundles.

This prevents accidental exposure of secrets.

CLI Usage

Validate Environment

npx smart-env validate

Fails the build if:

• Required variables are missing
• Values do not match schema
• Unsafe exposure detected

Print Resolved Config

npx smart-env print

Outputs resolved values with secrets masked.

Compare Environments

npx smart-env diff dev prod

Useful for debugging environment differences.

CI/CD Integration Example

GitHub Actions

- name: Validate Environment
  run: npx smart-env validate --env=production

Prevents misconfigured builds from reaching production.

Vite Integration Example

import { smartEnvPlugin } from 'smartEnv-elsolya/vite'

export default {
  plugins: [
    smartEnvPlugin({
      expose: ['API_URL']
    })
  ]
}

Monorepo Support

Supports:

• Shared env directories
• Per-app overrides
• Workspace-level validation

Error Handling Philosophy

The library follows a strict philosophy:

• Fail fast
• Fail loudly
• Never silently fallback
• Never allow unsafe production builds

Comparison with dotenv

| Feature | dotenv | smartEnv-elsolya | | ------------- | ------ | ---------------- | | Type Safety | No | Yes | | Validation | No | Yes | | Frontend Safe | No | Yes | | CLI Tools | No | Yes | | CI Friendly | No | Yes | | Schema-based | No | Yes |

Roadmap

• VSCode extension
• Remote environment syncing
• Secret manager integration
• Visual config inspector
• Web dashboard

Philosophy

smartEnv-elsolya is designed to:

• Scale with teams
• Prevent production mistakes
• Improve developer experience
• Enforce best practices

License

MIT

Final Notes

If your project relies on environment variables, and you care about:

• Stability
• Security
• Maintainability
• Developer Experience

then smartEnv-elsolya is built for you.