Environment Variables

Akan.js provides a centralized environment configuration system through baseEnv and baseClientEnv. These objects contain essential runtime information that determines how your application operates across different environments (local, debug, develop, main) and contexts (server, client).

🔧baseEnv

Core environment variables shared across server and client. Contains app identity, environment type, operation mode, and network configuration.

🌐baseClientEnv

Extended environment for client-side operations. Includes all baseEnv properties plus client/server connection URIs, protocols, and render mode configuration.

Root Environment Variables (.env)

You can configure environment variables in the .env file at the workspace root. These variables are accessible via process.env in Node.js environment and are used to initialize baseEnv and baseClientEnv.

.env (Root)

Variables prefixed with NEXT_PUBLIC_ are exposed to the browser. Never put sensitive data (API keys, passwords) in NEXT_PUBLIC_ variables.

⚠️Required Variables

NEXT_PUBLIC_APP_NAME, NEXT_PUBLIC_REPO_NAME, and NEXT_PUBLIC_SERVE_DOMAIN are required. The application will throw an error if these are not set.

baseEnv

baseEnv contains core environment variables that are shared across the entire application. It automatically reads from process.env and provides typed access to environment configuration.

BaseEnv Interface

Property Details:

environment

local: Local development environment
debug: Debug server environment for testing
develop: Development/staging environment
main: Production environment
testing: Automated testing environment

operationMode

local: Running locally with local services
edge: Edge deployment (Vercel Edge, etc.)
cloud: Cloud/Kubernetes deployment
module: Running as a module/library

networkType

mainnet: Production network (auto-selected when environment is 'main')
testnet: Test network (auto-selected when environment is 'develop')
debugnet: Debug network (default for other environments)

baseClientEnv

baseClientEnv extends baseEnv with client-specific configuration. It provides automatic detection of client/server context and generates appropriate connection URIs.

BaseClientEnv Interface

Auto-Generated URIs:

🖥️Local Environment Example

clientHttpUri: "http://localhost:4200"
serverHttpUri: "http://localhost:8080/backend"
serverGraphqlUri: "http://localhost:8080/backend/graphql"
serverWsUri: "ws://localhost:8080"

☁️Cloud Environment Example

clientHttpUri: "https://myapp-debug.example.com"
serverHttpUri: "https://myapp-debug.example.com/backend"
serverGraphqlUri: "https://myapp-debug.example.com/backend/graphql"
serverWsUri: "wss://myapp-debug.example.com"

Usage Examples

Here are practical examples of how baseEnv and baseClientEnv are used throughout the framework:

Backend Server Configuration

boot.ts - Server Initialization

Client API Connection

client.ts - API Client Setup

Router with SSR/CSR Detection

router.ts - Navigation with Context Detection

Environment Config

Each application extends baseEnv/baseClientEnv with app-specific configuration. The env folder contains environment-specific files that are selected based on NEXT_PUBLIC_ENV.

env/env.client.ts - Client Environment Router

env/env.client.local.ts - Local Client Config

env/env.server.local.ts - Local Server Config

📁Environment File Structure

apps/myapp/env/
├── env.client.ts          # Client env router
├── env.client.type.ts     # Client env type
├── env.client.local.ts    # Local client config
├── env.client.debug.ts    # Debug client config
├── env.client.develop.ts  # Develop client config
├── env.client.main.ts     # Production client config
├── env.server.ts          # Server env router
├── env.server.type.ts     # Server env type
├── env.server.local.ts    # Local server config
├── env.server.debug.ts    # Debug server config
├── env.server.develop.ts  # Develop server config
└── env.server.main.ts     # Production server config

Environment Best Practices

1️⃣Use Environment Checks

Use baseEnv.environment to conditionally enable features. Disable introspection, verbose logging, and debug tools in production (main).

2️⃣Check Side Before DOM Operations

Always check baseClientEnv.side before accessing window, document, or browser-only APIs. Use baseClientEnv.side === "client" guard.

3️⃣Separate Sensitive Config

Put API keys, passwords, and secrets only in env.server.*.ts files. Never include sensitive data in env.client.*.ts or NEXT_PUBLIC_ variables.

4️⃣Use Auto-Generated URIs

Prefer baseClientEnv.serverHttpUri and serverGraphqlUri over hardcoding URLs. They automatically adjust based on environment and deployment context.

🎉 What You've Learned:

✓ Root .env file configuration for Node.js process.env
✓ baseEnv for core environment variables (appName, environment, operationMode, networkType)
✓ baseClientEnv for client/server context detection and auto-generated connection URIs
✓ Application-specific env configuration with environment-based file selection
✓ Best practices for secure and context-aware environment usage

Environment Variables

Root Environment Variables (.env)

Environment Best Practices

Quick Start

Released under the MIT License

Official Akan.js Consulting onAkansoft

System managed bybassman