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

A single record in the encrypted audit log.

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.

EnvStorage

Internal wrapper for FlutterSecureStorage to persist environment settings.

EnvTrigger

Defines the gesture that opens the EnvifiedOverlay debug panel.

EnvTriggerDetector

Interface for custom trigger detectors (e.g. shake, volume buttons).

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.