Infer the import.meta.env type

[yamcodes]

TODO

• add/update docs, including setup+usage. for the setup we should credit https://github.com/Julien-R44/vite-plugin-validate-env#typing-importmetaenv

Summary by CodeRabbit

• New Features

  • Added a public type helper to provide typesafe, autocompleted access to VITE_* environment variables in TypeScript projects.
  • Vite plugin now exposes schema-aware typings to derive client env types from your Env schema.

• Documentation

  • New guide on typing import.meta.env with ArkEnv schemas.
  • Vite plugin docs updated with clearer notes and instructions for enabling type-safe import.meta.env.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 40d7795

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

This PR includes changesets to release 1 package

Name	Type
@arkenv/vite-plugin	Patch

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

[coderabbitai]

Walkthrough

Adds exported typing utilities and a public ImportMetaEnvAugmented helper to provide typesafe augmentation of import.meta.env for Vite projects; includes types, plugin API overloads, playground example, docs, and related tooling/config updates.

Changes

Cohort / File(s)	Summary
Type helpers & plugin API packages/vite-plugin/src/types.ts, packages/vite-plugin/src/index.ts	Added InferType, FilterByPrefix, and exported ImportMetaEnvAugmented types; added overloads for arkenv to accept EnvSchema<T> and type.Any, unified runtime signature.
Vite playground example apps/playgrounds/vite/src/vite-env.d.ts, apps/playgrounds/vite/vite.config.ts, apps/playgrounds/vite/tsconfig.json, apps/playgrounds/vite/package.json	Added ambient augmentation that uses ImportMetaEnvAugmented, exported Env schema with additional VITE_MY_BOOLEAN, tsconfig path alias, and vite-tsconfig-paths devDependency.
Documentation & manifest apps/www/content/docs/vite-plugin/index.mdx, apps/www/content/docs/vite-plugin/typing-import-meta-env.mdx, apps/www/content/docs/vite-plugin/meta.json	Added "Type-safe import.meta.env" docs page and guide, updated main docs wording and registered new page in manifest.
Changelog .changeset/free-oranges-bow.md	New changelog entry announcing the ImportMetaEnvAugmented export.
Tooling & config arkenv.code-workspace, biome.jsonc	VSCode workspace file association widened to tsconfig*.json; Biome linter override added to relax unused-variable checks in *.d.ts.
Spec wording normalization openspec/.../spec.md, openspec/.../tasks.md	Normalized "type-safe" → "typesafe" wording across spec and task docs.

Sequence Diagram(s)

sequenceDiagram
    autonumber
    participant Dev as Developer
    participant ViteCfg as vite.config.ts
    participant Plugin as arkenv Plugin
    participant Types as ImportMetaEnvAugmented
    participant MetaEnv as import.meta.env

    Dev->>ViteCfg: Define/export Env schema (VITE_* fields)
    ViteCfg->>Plugin: arkenvVitePlugin(Env)
    Plugin->>Types: Infer types from schema
    Types->>Types: FilterByPrefix "VITE_"
    Plugin->>MetaEnv: Expose only filtered, typed keys

    rect rgb(220,240,220)
    Note over Dev,MetaEnv: Usage
    Dev->>MetaEnv: Access import.meta.env.VITE_*
    MetaEnv-->>Dev: Typed value (autocomplete)
    Dev->>MetaEnv: Access import.meta.env.PORT
    MetaEnv-->>Dev: Not present / type error
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Focus review on packages/vite-plugin/src/types.ts (complex conditional types) and packages/vite-plugin/src/index.ts (overloads + exported types).
• Verify apps/playgrounds/vite/src/vite-env.d.ts augmentation matches Vite version expectations and that Env export in vite.config.ts aligns with usage.

Possibly related issues

• Issue #195: Adds the requested import.meta.env typings — this PR directly implements ImportMetaEnvAugmented and helpers addressing that need.

Possibly related PRs

• PR #382: Also modifies vite-plugin API and type inference; strongly related to the overloads and InferType work.
• PR #386: Related to vite-plugin behavior and typings; intersects with export/typing changes in the plugin.
• PR #224: Related updates in the playground/config that align with the new Env schema and examples.

Suggested labels

example

Poem

🐇
I nibble keys and types with cheer,
VITE_ names now crystal clear.
InferType hops, filters true,
import.meta.env — typed for you. ✨

Pre-merge checks and finishing touches

✅ 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 describes the main change: introducing type inference for import.meta.env through new type helpers and documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch 195-bug-vite-typescript-does-not-infer-the-environment-variables-type

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1eda22f and 40d7795.

📒 Files selected for processing (2)

• apps/playgrounds/vite/src/vite-env.d.ts (1 hunks)
• apps/www/content/docs/vite-plugin/typing-import-meta-env.mdx (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (2)

• apps/www/content/docs/vite-plugin/typing-import-meta-env.mdx
• apps/playgrounds/vite/src/vite-env.d.ts

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: test-e2e (e2e)
• GitHub Check: test-e2e (a11y)

---

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.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
arkenv	Ready	Preview	Comment	Nov 23, 2025 4:14pm

[pkg-pr-new]

Open in StackBlitz

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

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

commit: 40d7795

[arkenv-bot]

📦 Bundle Size Report

No results found

✅ All size limits passed!

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (7)

apps/www/content/docs/vite-plugin/meta.json (1)

6-6: Add new docs route to Playwright navigation test for coverage

The new "typing-import-meta-env" page looks correct here, but tooling/playwright-www/tests/docs-navigation.test.ts still only navigates to:

const vitePluginPages = [
  "/docs/vite-plugin",
  "/docs/vite-plugin/arkenv-in-viteconfig",
];

Consider adding "/docs/vite-plugin/typing-import-meta-env" to this list so the new page is exercised by the docs navigation E2E test.

apps/www/content/docs/vite-plugin/typing-import-meta-env.mdx (2)

51-57: Clarify how the prefix is chosen for ImportMetaEnvAugmented

The “How it works” bullet 2 says:

Filters to only include variables matching the Vite prefix (defaults to "VITE_")

From the helper type:

export type ImportMetaEnvAugmented<
  TSchema extends type.Any,
  Prefix extends string = "VITE_",
> = FilterByPrefix<InferType<TSchema>, Prefix>;

the compile-time prefix is actually driven by the Prefix generic (defaulting to "VITE_"), not dynamically by Vite’s envPrefix config.

To avoid confusion for users who change the Vite prefix, consider clarifying that:

• By default it filters to keys starting with "VITE_".
• If they use a custom prefix in Vite, they should pass it as the second generic parameter, e.g.:

type ImportMetaEnvAugmented =
  import("@arkenv/vite-plugin").ImportMetaEnvAugmented<
    typeof import("../vite.config").Env,
    "APP_"
  >;

---

61-75: Link to a concrete Vite example and consider less ambiguous type naming

The “Example with separate env file” is great, but two small improvements would make it easier to follow:

1. Link to a real example
   Given you already have a Vite playground/example in this repo, consider adding a short note like:

   See the Vite example in this repo for a full working setup.

   and link to the appropriate example (e.g. the Vite playground) so readers can inspect a complete project structure. Based on learnings

2. Optional: avoid reusing Env for both value and type
   In this snippet:

   export const Env = type({ ... });
   
   export type Env = typeof Env.infer;

   it’s valid to have a value and type with the same name, but can be slightly confusing in docs. You might prefer something like:

   export const Env = type({ ... });
   
   export type EnvType = typeof Env.infer;

   and then reference EnvType in places where only the type is needed.

apps/playgrounds/vite/vite.config.ts (1)

22-26: Consider dropping the debug console.log from the playground config

The console.log(\${env.VITE_MY_NUMBER} ${typeof env.VITE_MY_NUMBER}`);` is useful while developing the example, but it will run on every dev/build config evaluation.

Since the playground already demonstrates the values in App.tsx, consider removing this log (or gating it behind a debug flag) to keep the sample config minimal:

- console.log(`${env.VITE_MY_NUMBER} ${typeof env.VITE_MY_NUMBER}`);
  return {
    plugins: [
      tsconfigPaths(),
      reactPlugin(),
      arkenvVitePlugin(Env),
    ],

packages/vite-plugin/src/index.ts (1)

13-45: JSDoc accurately reflects plugin behavior; consider tying it to the new typing helper.

The description and examples line up with the implementation (validation via ArkEnv, filtering by envPrefix, exposure through import.meta.env.*). You might optionally add a short note pointing to ImportMetaEnvAugmented here so readers immediately see how to get type-safe import.meta.env augmentation, especially when using a custom envPrefix.

packages/vite-plugin/src/types.ts (2)

1-16: Refine InferType to more robustly drop type.errors.

If the validator’s return type is a union like Value | type.errors, the conditional R extends type.errors ? never : R won’t actually remove type.errors from the union. To guarantee you only keep the validated value type, consider:

type InferType<T> = T extends (
  value: Record<string, string | undefined>,
) => infer R
  ? Exclude<R, type.errors>
  : T extends type.Any<infer U, infer _Scope>
    ? U
    : never;

This keeps the intent while avoiding type.errors leaking into the inferred ImportMetaEnv shape. It’s also worth double-checking this against the current arktype typings so it matches the real validator signature.

---

28-72: ImportMetaEnvAugmented cleanly links ArkType schemas to import.meta.env; consider a small doc tweak.

Combining InferType<TSchema> with FilterByPrefix is a good fit for the plugin’s behavior (validate whole env, then only expose prefixed keys). The examples are clear and align with the public API. You might optionally:

• Call out in the docs that Prefix should mirror Vite’s envPrefix when customized.
• Mention that a union Prefix can model multiple prefixes if users configure Vite that way.

Otherwise the type surface and examples look solid.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1c2c526 and 1eda22f.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (15)

• .changeset/free-oranges-bow.md (1 hunks)
• apps/playgrounds/vite/package.json (1 hunks)
• apps/playgrounds/vite/src/vite-env.d.ts (1 hunks)
• apps/playgrounds/vite/tsconfig.json (1 hunks)
• apps/playgrounds/vite/vite.config.ts (2 hunks)
• apps/www/content/docs/vite-plugin/index.mdx (1 hunks)
• apps/www/content/docs/vite-plugin/meta.json (1 hunks)
• apps/www/content/docs/vite-plugin/typing-import-meta-env.mdx (1 hunks)
• arkenv.code-workspace (1 hunks)
• biome.jsonc (1 hunks)
• openspec/changes/archive/2025-11-20-add-arkenv-vite-config/specs/vite-config-usage/spec.md (3 hunks)
• openspec/changes/archive/2025-11-20-add-arkenv-vite-config/tasks.md (1 hunks)
• openspec/specs/vite-config-usage/spec.md (3 hunks)
• packages/vite-plugin/src/index.ts (1 hunks)
• packages/vite-plugin/src/types.ts (1 hunks)

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2025-09-09T17:37:19.650Z

Learnt from: yamcodes
Repo: yamcodes/arkenv PR: 132
File: packages/arkenv/README.md:13-14
Timestamp: 2025-09-09T17:37:19.650Z
Learning: For yamcodes/arkenv project: Runtime support documentation should link to specific examples: Node.js (examples/basic), Bun (examples/with-bun), Vite (examples/with-vite-react-ts).

Applied to files:

• openspec/specs/vite-config-usage/spec.md
• apps/www/content/docs/vite-plugin/typing-import-meta-env.mdx
• openspec/changes/archive/2025-11-20-add-arkenv-vite-config/specs/vite-config-usage/spec.md

🧬 Code graph analysis (7)

.changeset/free-oranges-bow.md (2)

packages/vite-plugin/src/index.test.ts (6)

• mockTransformedEnv (135-182)
• mockTransformedEnv (184-230)
• mockCreateEnv (232-259)
• pluginInstance (95-100)
• vi (81-84)
• config (39-75)

apps/playgrounds/vite/src/App.tsx (1)

• App (6-46)

packages/vite-plugin/src/types.ts (3)

packages/arkenv/src/type.ts (1)

• type (3-3)

packages/vite-plugin/src/index.ts (1)

• ImportMetaEnvAugmented (6-6)

packages/vite-plugin/src/index.test.ts (3)

• mockTransformedEnv (184-230)
• mockTransformedEnv (135-182)
• pluginInstance (95-100)

apps/www/content/docs/vite-plugin/typing-import-meta-env.mdx (2)

packages/vite-plugin/src/index.test.ts (3)

• mockTransformedEnv (184-230)
• mockTransformedEnv (135-182)
• mockCreateEnv (232-259)

apps/playgrounds/vite/src/App.tsx (1)

• App (6-46)

apps/playgrounds/vite/src/vite-env.d.ts (3)

packages/vite-plugin/src/types.ts (1)

• ImportMetaEnvAugmented (69-72)

packages/vite-plugin/src/index.test.ts (4)

• mockTransformedEnv (184-230)
• mockTransformedEnv (135-182)
• mockCreateEnv (232-259)
• vi (81-84)

apps/playgrounds/vite/src/App.tsx (1)

• App (6-46)

packages/vite-plugin/src/index.ts (1)

packages/vite-plugin/src/index.test.ts (5)

• mockTransformedEnv (184-230)
• mockTransformedEnv (135-182)
• mockCreateEnv (232-259)
• pluginInstance (95-100)
• error (308-340)

apps/www/content/docs/vite-plugin/meta.json (1)

tooling/playwright-www/tests/docs-navigation.test.ts (1)

• vitePluginPages (58-74)

apps/playgrounds/vite/vite.config.ts (2)

packages/vite-plugin/src/__fixtures__/basic/config.ts (1)

• Env (3-6)

packages/arkenv/src/type.ts (1)

• type (3-3)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: test-e2e (e2e)
• GitHub Check: test-e2e (a11y)

🔇 Additional comments (11)

apps/playgrounds/vite/package.json (1)

28-29: Dev dependency updates align with TS path alias usage

Pointing vite at npm:rolldown-vite@latest and adding vite-tsconfig-paths matches the TS baseUrl/paths setup in the playground; no issues from my side. Please just confirm pnpm dev/build run cleanly with this combo in your environment.

arkenv.code-workspace (1)

5-5: VS Code association for tsconfig*.json looks good

Mapping all tsconfig*.json files to jsonc is a nice quality-of-life tweak and has no runtime impact.

apps/playgrounds/vite/tsconfig.json (1)

3-8: TS baseUrl/paths setup is standard for Vite and matches the plugin usage

Defining baseUrl: "." with an "@/*": ["./src/*"] path alias is a conventional setup and pairs well with vite-tsconfig-paths; the expanded references objects preserve the original paths. Please just re-run tsc -b for the playground to confirm project references still build as expected.

Also applies to: 10-15

openspec/changes/archive/2025-11-20-add-arkenv-vite-config/specs/vite-config-usage/spec.md (1)

13-13: 'typesafe' terminology normalization in archived spec is consistent

Updating the archived spec to use “typesafe”/“typesafe patterns” keeps wording aligned with the active spec and docs without changing any requirements or scenarios.

Also applies to: 51-52, 57-57, 61-61, 70-71

openspec/changes/archive/2025-11-20-add-arkenv-vite-config/tasks.md (1)

14-15: Checklist wording now matches 'typesafe' terminology

Changing the wrapper requirement note to “typesafe return values” aligns this task file with the spec/docs language; no further changes needed.

biome.jsonc (1)

117-126: Disabling noUnusedVariables for .d.ts is a sensible noise reduction

Turning off correctness.noUnusedVariables specifically for **/*.d.ts avoids false positives in declaration files while leaving the main codebase rules intact. Please re-run Biome to ensure the override only affects .d.ts files as intended.

openspec/specs/vite-config-usage/spec.md (1)

16-16: Active spec now uses 'typesafe' consistently with the archived change

The shift to “typesafe” in the main vite-config-usage spec keeps language consistent with the archived spec and related docs while preserving the same constraints around validation and forbidden patterns.

Also applies to: 54-54, 60-60, 64-64, 73-73

.changeset/free-oranges-bow.md (1)

1-9: Changeset accurately captures the new ImportMetaEnvAugmented helper

The patch entry clearly describes the new type helper for a typesafe import.meta.env and properly attributes the inspiration to vite-plugin-validate-env; this should generate an appropriate patch release for @arkenv/vite-plugin.

apps/www/content/docs/vite-plugin/index.mdx (1)

22-27: Note + new typing section read cleanly and match routing

The updated [!NOTE] and the “Type-safe import.meta.env” section are consistent with the plugin behavior (VITE_ prefix, server-only vars excluded) and correctly link to /docs/vite-plugin/typing-import-meta-env. No changes needed.

packages/vite-plugin/src/index.ts (1)

6-6: Public re-export of ImportMetaEnvAugmented looks good.

Type-only re-export from the plugin entrypoint is a clean DX improvement and has no runtime impact; avoids consumers deep-importing from "./types".

packages/vite-plugin/src/types.ts (1)

21-26: Prefix filter utility is sound and matches the intended env-prefix behavior.

FilterByPrefix correctly narrows to keys starting with Prefix, and will naturally support multiple prefixes if callers pass a union (e.g. "VITE_" | "PUBLIC_") for Prefix. No changes needed.