Environment Variables

OpenSya provides a typed environment system for defining, validating and securing runtime variables.

Instead of reading raw process.env values directly, OpenSya applications define a structured environment schema integrated into the runtime lifecycle.

Environment File

Environment variables are usually declared inside a .env file.

CORE_ENV=development
NODE_ENV=development

NEST_PORT=3000
NEST_HOST=0.0.0.0
NEST_DATABASE_URL=mongodb://localhost:27017/opensya
NEST_JWT_SECRET_KEY=my-secret-key

OpenSya automatically loads environment variables during runtime initialization.

Naming Convention

OpenSya uses naming conventions for runtime environment variables.

Example:

CORE_ENV=development
NODE_ENV=development

NEST_PORT=3000
NEST_HOST=0.0.0.0
NEST_DATABASE_URL=mongodb://localhost:27017/opensya
NEST_JWT_SECRET_KEY=my-secret-key

Defining Environment Variables

Environment variables are defined using Env.schema.

Example:

import { Env } from '#core/utils/env';

export const envDefinition = {
  NEST_PORT: Env.schema.number().default(3000),

  NEST_HOST: Env.schema.string().default('0.0.0.0'),

  NEST_DATABASE_URL: Env.schema.string(),

  NODE_ENV: Env.schema
    .enum(['development', 'production', 'test'] as const)
    .default('development'),
};

This creates a typed environment definition used by the runtime.

Supported Schemas

OpenSya provides multiple schema types.

String

Env.schema.string()

Number

Env.schema.number()

Boolean

Env.schema.boolean()

Enum

Env.schema.enum(['development', 'production'] as const)

Default Values

You can define fallback values using .default().

NEST_PORT: Env.schema.number().default(3000)

If the variable is not defined, the default value is used automatically.

Optional Variables

Environment variables can be optional.

NEST_REDIS_URL: Env.schema.string().optional()

Optional variables may be undefined at runtime.

Secret Variables

Sensitive variables can be marked as secret.

NEST_JWT_SECRET_KEY: Env.schema.string().secret()

Secret variables are intended to remain internal to the runtime.

They should not be exposed to client runtimes or external modules.

Private Variables

You can also mark variables as private.

NEST_INTERNAL_API_KEY: Env.schema.string().private()

Private variables are intended for internal runtime usage only.

Accessing Variables

Environment variables are accessed through the Env runtime helper.

Public Access

import { Env } from '#core/utils/env';

const getConfig = () => {
  return {
    port: Env.get('NEST_PORT'),
    host: Env.get('NEST_HOST'),
  };
};

export default defineService(getConfig);

Accessing Secret Variables

Secret variables should be accessed using Env.secret().

import { Env } from '#core/utils/env';

const getJwtSecret = () => {
  return Env.secret<string>('NEST_JWT_SECRET_KEY');
};

export default defineService(getJwtSecret);

This ensures sensitive runtime values remain isolated.

Type Inference

Environment variables are automatically typed from their schema definitions.

Example:

const port = Env.get('NEST_PORT');

TypeScript infers:

number

Example:

const env = Env.get('NODE_ENV');

TypeScript infers:

'development' | 'production' | 'test'

Runtime Validation

During startup, OpenSya validates all required environment variables.

If a required variable is missing or invalid, the runtime fails immediately.

Example:

Missing environment variable: NEST_DATABASE_URL

or:

Invalid value for NEST_PORT
Expected number

This prevents invalid runtime states.

Recommended Structure

A common structure is:

server/
└── env.ts

Example:

import { Env } from '#core/utils/env';

export const envDefinition = {
  NEST_PORT: Env.schema.number().default(3000),

  NEST_DATABASE_URL: Env.schema.string(),

  NEST_JWT_SECRET_KEY: Env.schema.string().secret(),
};

Runtime Lifecycle

During startup, OpenSya:

1. Loads .env files
2. Reads the environment schema
3. Validates variables
4. Generates typings
5. Registers runtime accessors

Load .env
      ↓
Read Schema
      ↓
Validate Variables
      ↓
Generate Types
      ↓
Runtime Access

Best Practices

Prefix Backend Variables

Except for CORE_ENV and NODE_ENV, backend variables should use the NEST_ prefix.

NEST_PORT=3000
NEST_DATABASE_URL=mongodb://localhost:27017/opensya

Keep Secrets Private

Always use .secret() for sensitive values.

NEST_JWT_SECRET_KEY: Env.schema.string().secret()

Use Defaults Carefully

Use defaults for development convenience, but avoid insecure defaults for production secrets.

Prefer Typed Access

Prefer:

Env.get('NEST_PORT')

instead of:

process.env.NEST_PORT

Centralize Definitions

Keep all environment definitions inside a dedicated env.ts file.

Philosophy

The OpenSya environment system is designed to make runtime configuration safer and more maintainable.

Instead of relying on untyped global variables, OpenSya provides a structured and typed runtime environment layer fully integrated into the backend runtime lifecycle.