Play+ Environment Helper: playenv

🌱 Introduction

In the Play+ ecosystem, applications must seamlessly adapt to varying runtime contexts—from local development to staging and production. playenv supports this through environment-aware configuration, delivering a secure, consistent, and reliable way to manage environment-specific variables.

A robust environment management system enhances both security and maintainability. playenv ensures that API keys, feature flags, and contextual settings are loaded correctly without being hardcoded.

---

📦 Package Info

Distribution Path	Description
Golden Path	Pre-installed at /system/play.env.ts
Uplift Path	npm install @playplus/env

---

📁 Folder Reference

Environment variables are managed using .env files at the project root:

File / Directory	Purpose & Guidelines
.env	Default values for all environments. Committed to version control.
.env.local	Local overrides for development. Must not be committed.
.env.development	Optional environment-specific file.
.env.production	Used in production deployment.
/system/play.env.ts	Core helper exposing type-safe access to environment variables.

---

🧠 Pillar Alignment

Pillar	Alignment Description
Adaptive	Enables dynamic behavior across environments (e.g., API endpoints, logging levels).
Intuitive	Offers a simple, type-safe get() interface with built-in coercion.
Distinct	Promotes consistent, repeatable config practices across Play+ projects.
Inclusive	Reduces cognitive load for new or experienced developers.
Engaging	Encourages best practices like secret segregation and fallback defaults.

---

⚙️ Helper Overview

playenv is a secure, type-safe abstraction over process.env. It simplifies and automates:

• Variable Loading: Automatically reads from .env, .env.[env], and .env.local in priority order.
• Override Strategy: .env.local > .env.[env] > .env
• Type Parsing: Coerces values to string, number, or boolean.
• Validation: Optionally checks required variables at startup.
• Security: Separates secrets into .env.local, helping avoid accidental commits.

---

🧾 Configuration Options

All configuration is done via .env files. No separate JSON config is needed.

Variable Name	Example Value	Description
NODE_ENV	"development"	Current runtime environment.
API_URL	"https://api.playplus.io"	Backend API base URL.
FEATURE_FLAG_CLIENT_KEY	"sdk-123-abc"	Client-side key for feature flag service.
ENABLE_ANALYTICS	true	Boolean toggle for analytics scripts.

---

🧪 Helper Methods

get<T = string>(key: string, defaultValue?: T): T

🔄 Type Coercion Logic:

• If T is boolean, parses 'true'/'false'
• If T is number, attempts parseFloat
• Returns defaultValue if key is undefined

---

🧩 Usage Examples

🔧 React: Configure an API Service

// system/api/apiService.ts
import { playenv } from '../system/play.env';

const API_BASE_URL = playenv.get('API_URL', 'http://localhost:3001');

export const apiService = {
  // ...methods using API_BASE_URL
};

🛠️ React: Conditional Component

// components/DevNotice.tsx
import { playenv } from '../system/play.env';

function DevNotice() {
  if (playenv.get('NODE_ENV') !== 'development') return null;
  return <div>Development Mode</div>;
}

🧪 Angular: Injectable Config Service

// core/services/config.service.ts
import { Injectable } from '@angular/core';
import { playenv } from '@playplus/env';

@Injectable({ providedIn: 'root' })
export class ConfigService {
  public readonly apiUrl: string;
  public readonly enableAnalytics: boolean;

  constructor() {
    this.apiUrl = playenv.get('API_URL', 'http://localhost:3001');
    this.enableAnalytics = playenv.get<boolean>('ENABLE_ANALYTICS', false);
  }
}

// some.component.ts
@Component(/*...*/)
export class SomeComponent {
  constructor(private config: ConfigService) {
    console.log('API will be called at:', this.config.apiUrl);
  }
}

---

🧰 Developer Checklist

✅ Before You Commit:

• Added all non-secret keys to .env with sensible defaults?
• Stored secrets in .env.local (not .env)?
• Confirmed .env.local is in .gitignore?
• Using playenv.get() instead of process.env?
• Provided fallback defaultValue in get() calls?
• (Optional) Configured required key validation?

---

✨ Why We Created This Helper

Accessing configuration via process.env is common but problematic:

• ❌ Not type-safe — values are strings by default
• ❌ Scattered — fallback logic lives across many files
• ❌ Insecure — secrets can be committed by mistake
• ❌ Opaque — missing keys cause silent failures

✅ playenv solves all of these:

• Centralized, predictable, validated config access
• Built-in type safety
• Strong separation of code and secrets

---

🔚 Closing Note

Environment awareness is not just a backend concern — it's a foundation for resilient frontends too. playenv empowers developers to ship confidently across contexts, knowing that their applications are secure, reliable, and configuration-smart.

It’s another way Play+ helps you focus on what matters — the experience.