☰

zig-dotenv

zig-dotenv

A powerful Zig library for loading, parsing, and managing environment variables from `.env` files. [![Version](https://img.shields.io/badge/Zig_Version-0.16.0-orange.svg?logo=zig)](README.md) [![MIT](https://img.shields.io/badge/License-MIT-lightgrey.svg?logo=cachet)](LICENSE) [![Version](https://img.shields.io/badge/dotenv-v0.9.0-green)](https://github.com/xcaeser/zig-dotenv/releases)

Docs:

dotenv reference docs

✅ Features

  • Load environment variables from .env files
  • Type-safe access using enums
  • Read from and copy the current process environment map
  • Modify the current process environment with setProcessEnv
  • Supports comments, quoted values, and whitespace trimming
  • Supports $KEY and ${KEY} interpolation from the process environment map
  • Missing keys return an empty string
  • Clean, testable API

🚀 Usage

const std = @import("std");
const dotenv = @import("dotenv");

pub const EnvKeys = enum {
    OPENAI_API_KEY,
    AWS_ACCESS_KEY_ID,
    COGNITO_CLIENT_SECRET,
    S3_BUCKET,
};

pub fn main(process_init: std.process.Init) !void {
    var env = dotenv.init(process_init, EnvKeys);
    defer env.deinit();

    try env.load(.{
        .filename = ".env.local",
        .include_current_process_envs = true,
    });

    const openai = env.key(.OPENAI_API_KEY);
    std.debug.print("OPENAI_API_KEY={s}\n", .{openai});

    const aws_key = env.get("AWS_ACCESS_KEY_ID");
    std.debug.print("AWS_ACCESS_KEY_ID={s}\n", .{aws_key});
}

📄 Example .env File

OPENAI_API_KEY=sk-your-api-key-here
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
S3_BUCKET="my-bucket"
COGNITO_CLIENT_SECRET='abcdef123456'
HOME_DIR=$HOME
USER_NAME=${USER}

📦 Installation

using zig fetch

zig fetch --save=dotenv https://github.com/xcaeser/zig-dotenv/archive/v0.9.0.tar.gz

Add to build.zig

const dotenv_dep = b.dependency("dotenv", .{ .target = target, .optimize = optimize });

exe.root_module.addImport("dotenv", dotenv_dep.module("dotenv"));

// Optional: add for unit tests
exe_unit_tests.root_module.addImport("dotenv", dotenv_dep.module("dotenv"));

📚 API Summary

Initialization

zig-dotenv uses Zig 0.16.0’s std.process.Init API. Accept it in main, then create an env manager with your enum type:

pub fn main(process_init: std.process.Init) !void {
    var env = dotenv.init(process_init, EnvKeys);
    defer env.deinit();
}

Env API

Method Description
dotenv.init(process_init, EnvKey) Initializes a new Env manager
deinit() Frees all allocated memory
load(.{ .filename, .include_current_process_envs }) Loads variables from a .env file
loadCurrentProcessEnvs() Copies process variables into the internal map
parse(content) Parses raw .env-formatted text
get("KEY") Gets a value by string key, or "" if missing
key(.ENUM_KEY) Gets a value by enum key, or "" if missing
setProcessEnv("KEY", "VALUE") Sets a process environment variable
setProcessEnv("KEY", null) Unsets a process environment variable

Load Options

Option Default Description
filename .env File to load
include_current_process_envs false Copies process_init.environ_map into the map
export_to_process_env false Reserved; not currently implemented

🧪 Testing

Run:

zig build test

Includes tests for parsing, file I/O, interpolation, process environment loading, and lookup behavior.

🤝 Contributing

Issues and PRs welcome! Star the repo if it helped you.

📝 License

MIT – see LICENSE.

Install 
zig f -S zub.sh/zig-dotenv
Repository
License
MIT
Category

Not categorized yet.

Author
xcaeser
xcaeser
Dependencies

No explicit dependencies.

On this page