envified library

envified — Runtime environment switching for Flutter.

Load .env files, switch dev/staging/prod/custom at runtime, override base URLs, and lock production config — no rebuild required.

Quick start

import 'package:envified/envified.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await EnvConfigService.instance.init(
    defaultEnv: Env.dev,
    persistSelection: true,
    allowProdSwitch: false,
    verifyIntegrity: true,
    onBeforeSwitch: (from, to) async {
      debugPrint('Switching: ${from.name} → ${to.name}');
    },
    onAfterSwitch: (config) {
      debugPrint('Active env: ${config.env.longLabel}');
    },
  );

  runApp(
    MaterialApp(
      builder: (context, child) => EnvifiedOverlay(
        service: EnvConfigService.instance,
        enabled: kDebugMode,
        gate: EnvGate(pin: '1234'),
        trigger: const EnvTrigger.tap(count: 7),
        child: child ?? const SizedBox.shrink(),
      ),
    ),
  );
}

Public API

Symbol	Purpose
Env	Enum of supported environments
EnvConfig	Immutable snapshot of the active configuration
EnvConfigService	Singleton service — init, switch, get, setBaseUrl
EnvifiedLockException	Thrown when the production lock blocks an action
EnvifiedTamperException	Thrown when a .env file hash mismatches baseline
EnvifiedUrlNotAllowedException	Thrown when setBaseUrl rejects a non-allowlisted URL
AuditEntry	A single record in the encrypted audit log
EnvDebugPanel	Standalone debug widget for manual placement
EnvifiedOverlay	Floating-button overlay wrapper
EnvStatusBadge	Persistent env indicator badge with pulse animation
EnvGate	PIN / biometric access gate for the debug panel
EnvTrigger	Sealed class defining the gesture to open the panel

Classes

AuditEntry

An immutable record of a single action performed by EnvConfigService.

Env

Represents a deployment environment.

EnvConfig

An immutable snapshot of the active environment configuration.

EnvConfigService

The central singleton service for runtime environment management.

EnvDebugPanel

A self-contained debug panel widget for inspecting and modifying the active environment configuration at runtime.

EnvGate

Gate for accessing the debug panel.

EnvifiedOverlay

A transparent wrapper widget that optionally injects a floating debug button into the app's Overlay, allowing EnvDebugPanel to be opened at any time.

EnvStatusBadge

A persistent, lightweight environment indicator badge.

EnvTrigger

Defines the gesture that opens the EnvifiedOverlay debug panel.

Exceptions / Errors

EnvifiedLockException

Exception thrown when an action is blocked by the production lock.

EnvifiedTamperException

Exception thrown when an .env* asset file fails an integrity check.

EnvifiedUrlNotAllowedException

Exception thrown when EnvConfigService.setBaseUrl is called with a URL that is not in the optional allowlist provided during EnvConfigService.init.