Getting Started

penv requires Dart SDK ^3.5.0.

1. Install the package

dart pub add penv

Or add it to pubspec.yaml directly, then run dart pub get:

dependencies:
  penv: ^1.1.0

2. Create a .env file

Next to your entrypoint (or wherever you plan to load it from):

API_KEY=your-key-here
BASE_URL=https://example.com
PORT=8080

Add .env to .gitignore — it’s meant for values that don’t belong in version control.

3. Load it

import 'package:penv/penv.dart';

void main() {
  final env = penvload('.env');
  print(env['API_KEY']);
}

penvload returns a plain Map<String, String> — index into it directly, or use the typed accessors for anything that isn’t already a string:

final port = env.getInt('PORT', defaultValue: 8080);

4. Handle a missing file gracefully (optional)

By default, if .env doesn’t exist, penvload writes a placeholder file and throws EnvFileNotFoundException so you notice and fill it in:

try {
  final env = penvload('.env');
} on EnvFileNotFoundException catch (e) {
  print('${e.path} was just created — fill it in and run again.');
  rethrow;
}

Use penvloadOrNull instead if a missing file should just mean “use defaults” rather than an error.

5. Run it

dart run bin/my_app.dart

Next steps

• See Env File Syntax for the full rules — quoting, escaping, comments, and variable expansion.
• Browse the Examples for required-key validation, the process-environment overlay, and async loading.
• Look up every parameter in the API Reference.