feat(bun-plugin): include NODE_ENV as an allowed public environment variable

[joakimbeng]

Bun already exposes process.env.NODE_ENV to the frontend and with this change it's possible to type it with ArkEnv, in same fashion as other public env vars.

Hopefully you think this is a good idea! ☺️

Summary by CodeRabbit

• New Features

  • NODE_ENV is now exposed to the frontend with type support, matching Bun’s standard behavior.

• Documentation

  • Docs updated to show NODE_ENV is included among publicly exposed environment variables alongside BUN_PUBLIC_*.

• Tests

  • Added a test ensuring NODE_ENV is not filtered out and is correctly represented in the exposed environment.

[coderabbitai]

Walkthrough

The bun-plugin now exposes NODE_ENV by default alongside BUN_PUBLIC_* variables; this updates the env filtering logic, adds a test, updates README, and adds a changeset for a minor release. (49 words)

Changes

Cohort / File(s)	Summary
Changeset .changeset/few-lights-ask.md	New changeset added declaring a minor release for @arkenv/bun-plugin and documenting NODE_ENV as publicly exposed.
Core logic & tests packages/bun-plugin/src/utils.ts, packages/bun-plugin/src/utils.test.ts	Filter in processEnvSchema expanded to include NODE_ENV in addition to BUN_PUBLIC_*; added unit test asserting NODE_ENV is preserved and JSON-stringified in the env map.
Documentation packages/bun-plugin/README.md	README examples and description updated to include NODE_ENV in the automatic client-exposed environment variables and type/schema examples.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• Add Bun plugin #439 — Directly updates processEnvSchema filtering to include NODE_ENV.
• Support standard validator mode in Bun plugin #763 — Changes processEnvSchema usage and config, touching the same module.
• docs(bun-plugin): document process.env type augmentation #464 — Documentation/type exposure changes for process.env that relate to NODE_ENV typing/exposure.

Suggested labels

@arkenv/bun-plugin

Suggested reviewers

• yamcodes

Poem

🐰
I nibble keys beneath the sun,
NODE_ENV hops out to join the fun,
PUBLIC_* pals line up in a row,
Frontend types now softly glow,
A small hop forward — off I run. 🥕

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and specifically describes the main change: adding NODE_ENV as a publicly exposed environment variable in the bun-plugin.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 2cbd2d2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@arkenv/bun-plugin	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[joakimbeng]

@all-contributors please add @joakimbeng for code, doc

[allcontributors]

@joakimbeng

I've put up a pull request to add @joakimbeng! 🎉

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

packages/bun-plugin/src/utils.ts (1)

19-21: Consider extracting "NODE_ENV" as a named constant for symmetry with prefix.

prefix is already a named const on line 19. Extracting the hardcoded "NODE_ENV" to a similar constant keeps the filter condition self-documenting and makes future additions (e.g., other Bun-exposed built-ins) easier to manage.

♻️ Proposed refactor

 	const prefix = "BUN_PUBLIC_";
+	const builtinPublicKeys = ["NODE_ENV"] as const;
 	const filteredEnv = Object.fromEntries(
-		Object.entries(env).filter(([key]) => key === "NODE_ENV" || key.startsWith(prefix)),
+		Object.entries(env).filter(([key]) => (builtinPublicKeys as readonly string[]).includes(key) || key.startsWith(prefix)),
 	);

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/bun-plugin/src/utils.ts` around lines 19 - 21, The filter uses the
hardcoded string "NODE_ENV" alongside the prefix constant; extract "NODE_ENV"
into a named constant (e.g., const NODE_ENV_KEY = "NODE_ENV") and update the
filter in Object.fromEntries to use that constant so the check in filteredEnv
references prefix and NODE_ENV_KEY (and makes adding other built-ins easier);
update any related references to the named constant in this module (symbols:
prefix, filteredEnv, env) for symmetry and clarity.

packages/bun-plugin/src/utils.test.ts (1)

37-49: LGTM! Consider using vi.stubEnv for safer env isolation.

The test logic, schema syntax ("'development' | 'test' | 'production'" per ArkType conventions), and assertions are all correct.

As an optional improvement, replacing the manual process.env.X = value + process.env = originalEnv teardown pattern with Vitest's built-in vi.stubEnv / vi.unstubAllEnvs() would make the isolation more robust (Vitest owns the cleanup and handles non-configurable descriptors correctly):

-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";

-	it("should not filter out NODE_ENV", () => {
-		process.env.NODE_ENV = "development";
+	it("should not filter out NODE_ENV", () => {
+		vi.stubEnv("NODE_ENV", "development");

And in afterEach:

 	afterEach(() => {
-		process.env = originalEnv;
+		vi.unstubAllEnvs();
 	});

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/bun-plugin/src/utils.test.ts` around lines 37 - 49, Replace manual
env mutation in the test that touches process.env with Vitest's environment
stubbing utilities: use vi.stubEnv to set NODE_ENV for the test case that calls
processEnvSchema and ensure cleanup by calling vi.unstubAllEnvs (or
vi.restoreAllEnvs) in the shared afterEach; update the test that references
NODE_ENV and any teardown that resets process.env to use vi.stubEnv("NODE_ENV",
"development") and remove manual process.env reassignment so Vitest handles
isolation safely for tests exercising processEnvSchema.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/bun-plugin/src/utils.ts`:
- Line 21: In the Object.entries(env).filter(...) expression replace the
single-quoted 'NODE_ENV' with a double-quoted "NODE_ENV" to comply with the
Biome rule and match existing literals (look for the
Object.entries(env).filter(([key]) => key === 'NODE_ENV' ||
key.startsWith(prefix)) usage in utils.ts and change the string literal to
"NODE_ENV").

---

Nitpick comments:
In `@packages/bun-plugin/src/utils.test.ts`:
- Around line 37-49: Replace manual env mutation in the test that touches
process.env with Vitest's environment stubbing utilities: use vi.stubEnv to set
NODE_ENV for the test case that calls processEnvSchema and ensure cleanup by
calling vi.unstubAllEnvs (or vi.restoreAllEnvs) in the shared afterEach; update
the test that references NODE_ENV and any teardown that resets process.env to
use vi.stubEnv("NODE_ENV", "development") and remove manual process.env
reassignment so Vitest handles isolation safely for tests exercising
processEnvSchema.

In `@packages/bun-plugin/src/utils.ts`:
- Around line 19-21: The filter uses the hardcoded string "NODE_ENV" alongside
the prefix constant; extract "NODE_ENV" into a named constant (e.g., const
NODE_ENV_KEY = "NODE_ENV") and update the filter in Object.fromEntries to use
that constant so the check in filteredEnv references prefix and NODE_ENV_KEY
(and makes adding other built-ins easier); update any related references to the
named constant in this module (symbols: prefix, filteredEnv, env) for symmetry
and clarity.

[coderabbitai]

🧹 Nitpick comments (1)

packages/bun-plugin/README.md (1)

63-118: Consider adding a NODE_ENV schema example to improve discoverability.

All usage examples currently only demonstrate BUN_PUBLIC_* variables. Since the entire motivation of this PR is enabling TypeScript typing for NODE_ENV, showing that pattern at least once would make the docs immediately actionable for readers.

📝 Proposed addition to the Simple Setup example

 export default type({
   BUN_PUBLIC_API_URL: 'string',
   BUN_PUBLIC_DEBUG: 'boolean',
+  NODE_ENV: "'development' | 'production' | 'test'",
 });

Based on learnings, the project convention for enumerated environment variable values is to use ArkType string literal syntax (e.g., "'development' | 'production' | 'test'").

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/bun-plugin/README.md` around lines 63 - 118, Add a NODE_ENV example
to both the Simple Setup and Advanced Setup examples by including an enumerated
ArkType string literal for NODE_ENV (e.g., "'development' | 'production' |
'test'") alongside the existing BUN_PUBLIC_* entries; update the src/env.ts
auto-discover example that calls type({ ... }) and the arkenv(type({...}))
passed into plugins so readers can see how to type NODE_ENV with the type()
helper and when passing the schema directly to the arkenv plugin.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@packages/bun-plugin/README.md`:
- Around line 63-118: Add a NODE_ENV example to both the Simple Setup and
Advanced Setup examples by including an enumerated ArkType string literal for
NODE_ENV (e.g., "'development' | 'production' | 'test'") alongside the existing
BUN_PUBLIC_* entries; update the src/env.ts auto-discover example that calls
type({ ... }) and the arkenv(type({...})) passed into plugins so readers can see
how to type NODE_ENV with the type() helper and when passing the schema directly
to the arkenv plugin.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

packages/bun-plugin/src/utils.ts (1)

20-20: Consider hoisting allowed to a module-level constant.

allowed is a fixed Set that is reconstructed on every processEnvSchema call. Since its contents never change, extracting it to the module scope avoids repeated allocation.

♻️ Proposed refactor

+const ALLOWED_KEYS = new Set(["NODE_ENV"]);
+
 export function processEnvSchema<T extends SchemaShape>(
   ...
 ) {
   const prefix = "BUN_PUBLIC_";
-  const allowed = new Set(["NODE_ENV"]);
   const filteredEnv = Object.fromEntries(
-    Object.entries(env).filter(([key]) => allowed.has(key) || key.startsWith(prefix)),
+    Object.entries(env).filter(([key]) => ALLOWED_KEYS.has(key) || key.startsWith(prefix)),
   );

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/bun-plugin/src/utils.ts` at line 20, Hoist the constant Set
currently created inside processEnvSchema to module scope to avoid
reconstructing it on every call: move the declaration const allowed = new
Set(["NODE_ENV"]) out of the processEnvSchema function and export or keep it as
a module-level const (e.g., allowed) then update processEnvSchema to reference
this module-level allowed instead of recreating it; ensure no behavior change
and run tests/type checks to validate.

packages/bun-plugin/src/utils.test.ts (1)

37-49: Add a failure-case test for an invalid NODE_ENV value.

The new test covers only the happy path. Per coding guidelines, both success and failure cases should be tested. A test for an invalid value (e.g., "staging") would confirm that createEnv (and thus processEnvSchema) throws when the schema isn't satisfied.

✅ Suggested additional test

it("should throw when NODE_ENV is an invalid value", () => {
    process.env.NODE_ENV = "staging";

    expect(() =>
        processEnvSchema({
            NODE_ENV: "'development' | 'test' | 'production'",
        } as const),
    ).toThrow();
});

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/bun-plugin/src/utils.test.ts` around lines 37 - 49, Add a
failing-case unit test that asserts processEnvSchema throws for an invalid
NODE_ENV value: set process.env.NODE_ENV = "staging" and call processEnvSchema({
NODE_ENV: "'development' | 'test' | 'production'" } as const) inside an
expect(() => ...).toThrow(); ensure the new it test name describes the failure
case (e.g., "should throw when NODE_ENV is an invalid value") so it complements
the existing happy-path test; reference the existing test harness in
utils.test.ts and keep the assertion style consistent with the other tests.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/bun-plugin/README.md`:
- Line 76: Update the ArkType string examples for NODE_ENV to use outer-double /
inner-single quotes to match the project's canonical pattern and the new test;
specifically change the example for the symbol NODE_ENV from the current
outer-single/inner-double form to the form "'development' | 'test' |
'production' = 'development'" (also update the second occurrence noted at the
same file/line range); ensure the README examples mirror the string quoting used
by utils.test.ts and project guidelines.

---

Nitpick comments:
In `@packages/bun-plugin/src/utils.test.ts`:
- Around line 37-49: Add a failing-case unit test that asserts processEnvSchema
throws for an invalid NODE_ENV value: set process.env.NODE_ENV = "staging" and
call processEnvSchema({ NODE_ENV: "'development' | 'test' | 'production'" } as
const) inside an expect(() => ...).toThrow(); ensure the new it test name
describes the failure case (e.g., "should throw when NODE_ENV is an invalid
value") so it complements the existing happy-path test; reference the existing
test harness in utils.test.ts and keep the assertion style consistent with the
other tests.

In `@packages/bun-plugin/src/utils.ts`:
- Line 20: Hoist the constant Set currently created inside processEnvSchema to
module scope to avoid reconstructing it on every call: move the declaration
const allowed = new Set(["NODE_ENV"]) out of the processEnvSchema function and
export or keep it as a module-level const (e.g., allowed) then update
processEnvSchema to reference this module-level allowed instead of recreating
it; ensure no behavior change and run tests/type checks to validate.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/arkenv@804

npm i https://pkg.pr.new/@arkenv/bun-plugin@804

npm i https://pkg.pr.new/@arkenv/fumadocs-ui@804

npm i https://pkg.pr.new/@arkenv/vite-plugin@804

commit: 2cbd2d2

[yamcodes]

Hey @joakimbeng! This is a great idea! Instant approve!