lute-dotenv

lute-dotenv is a dotenv-style package for Luau projects running on Lute.

It provides helpers for parsing .env files, loading them from disk, applying them to process.env, and serializing them back to text.

Install

Add a dependency to your project's loom.config.luau:

return {
    package = {
        name = "my-project",
        version = "0.1.0",
        dependencies = {
            dotenv = {
                sourceKind = "github",
                source = "https://github.com/erlcx/lute-dotenv",
                rev = "v0.1.1",
            },
        },
    },
}

Then install it with:

lute pkg install

Usage

local dotenv = require("@dotenv")
local process = require("@std/process")

dotenv.config()
print(process.env.YOUR_ENV_VAR)

config() loads .env from the current working directory by default, applies the parsed values to process.env, and returns the parsed table.

API

• dotenv.parse(input, options?)
• dotenv.load(path, options?)
• dotenv.apply(values, options?)
• dotenv.serialize(values, options?)
• dotenv.config(options?)

Options

parse and load support:

• expand: expand $VAR and ${VAR} style references
• strict: error on invalid assignment lines
• env: base environment table used during expansion
• override: when loading multiple files, let later files replace earlier values

apply and config support:

• path: use a single path or an array of paths
• target: environment table to write into
• override: replace existing values instead of preserving them

Examples

See the examples directory for:

• basic: load a sibling .env file and print values
• config: load environment variables into a small config table
• functions: use load, apply, and serialize directly
• multiple-files: merge .env and .env.local in order

Benchmarks

Parse-only benchmarks live in benchmarks. They compare this package against the JavaScript dotenv package using equivalent generated fixtures and no file I/O.

npm --prefix benchmarks install
luu run bench

Run one side at a time with luu run bench:luau or luu run bench:js.

Latest local parse benchmark, run on April 24, 2026:

Fixture	lute-dotenv	JS dotenv	Comparison
basic-128	4,403 ops/s	13,539 ops/s	JS dotenv is 3.08x faster
quoted-128	919 ops/s	2,319 ops/s	JS dotenv is 2.52x faster
mixed-128	970 ops/s	3,191 ops/s	JS dotenv is 3.29x faster

License

This project is licensed under the MIT License. See the LICENSE file for details.