feat(skills,cli): adapt ArkEnv skill and CLI for framework plugins

[yamcodes]

Fixes #940

This PR updates the ArkEnv skill and the CLI to follow best practices for framework plugins (Vite/Bun).

Key changes:

• SKILL.md: Updated to recommend using @arkenv/vite-plugin and @arkenv/bun-plugin, emphasizing type augmentation for import.meta.env and process.env.
• CLI Templates: Modified to export only the schema (Env) for Vite projects, discouraging the use of runtime-validated env imports in the frontend.
• CLI improvements: The schema (Env) is now exported by default in all templates to allow easy integration with plugins.

Summary by CodeRabbit

• New Features

  • Environment templates now adapt to framework: Vite and Bun receive augmentation-focused templates; Node retains runtime export behavior.

• Documentation

  • Expanded integration guide with framework-specific setup, examples, and best practices for schema export and usage.

• Tests

  • Added/extended tests covering template generation across frameworks and validators.

• Chores

  • Release changeset added; CI workflow comment behavior slightly refined.

[changeset-bot]

🦋 Changeset detected

Latest commit: 8f66e2a

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

This PR includes changesets to release 1 package

Name	Type
@arkenv/cli	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]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d4e40be9-5b12-4722-ae55-9aad54845083

📥 Commits

Reviewing files that changed from the base of the PR and between 0d17ed6 and 8f66e2a.

📒 Files selected for processing (1)

• .github/workflows/preview-www.yml

---

Walkthrough

CLI template generators were made framework-aware: Vite and Bun emit schema-only modules for plugin/augmentation use, while Node (default) emits runtime-validated env exports. Tests, docs, and a changeset were updated accordingly.

Changes

Framework-aware template generation

Layer / File(s)	Summary
Framework parameter threading packages/cli/src/env-template.ts	getEnvTemplate extracts framework from options and passes it to each validator-specific template (arktypeTemplate, zodTemplate, valibotTemplate).
ArkType template branching packages/cli/src/templates/arktype.ts	arktypeTemplate accepts an optional framework and returns Vite/Bun schema-only templates (import type only) or the default Node template that imports arkenv and exports env = arkenv(Env).
Valibot template branching packages/cli/src/templates/valibot.ts	valibotTemplate accepts framework and returns Vite/Bun branches exporting only an Env schema; default branch imports arkenv/standard and exports env = arkenv(Env).
Zod template branching packages/cli/src/templates/zod.ts	zodTemplate accepts framework and emits Vite/Bun schema-only templates (import z and export Env) or the default that includes arkenv/standard and exports env = arkenv(Env).
Test coverage for framework output packages/cli/src/env-template.test.ts	Tests extended: Node case asserts presence of export const env = arkenv(Env); Vite and Bun cases assert schema-only output and include framework-specific plugin/instructions strings.
Documentation aligned with plugins skills/arkenv/SKILL.md	"Framework Integration" section added; operational flow rewritten; examples updated to export Env = type({...}), Node example shows env = arkenv(Env), and Vite/Bun examples show augmentation snippets; CLI docs simplified.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• yamcodes/arkenv#937: Both PRs modify the same documentation file (skills/arkenv/SKILL.md) with framework-integration updates.
• yamcodes/arkenv#904: Related changes to CLI template generators and env-template logic.
• yamcodes/arkenv#897: Prior PR touching template generation and framework-aware behavior.

Poem

🐇
I hopped through templates, nibbling lines with care,
Vite and Bun now sprout schemas in the air,
Node keeps runtime checks safe and sound,
Docs sing plugins' guidance all around.
Happy hops — templates prepared!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adapting ArkEnv skill and CLI templates for framework plugins (Vite and Bun).
Linked Issues check	✅ Passed	The PR successfully addresses all coding requirements from issue #940: templates now generate plugin-aware schema exports for Vite/Bun, SKILL.md documents plugin best practices and type augmentation, and runtime env coercion is avoided in frontend contexts.
Out of Scope Changes check	✅ Passed	All changes are directly aligned with the issue #940 objectives; no out-of-scope modifications detected.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 940-adapt-arkenv-skill-for-plugins-1

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

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

[arkenv-bot]

🤖 Hi @yamcodes, I've received your request, and I'm working on it now! You can track my progress in the logs for more details.

[arkenv-bot]

🤖 I'm sorry @yamcodes, but I was unable to process your request. Please see the logs for more details.

[pkg-pr-new]

Open in StackBlitz

arkenv

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

@arkenv/bun-plugin

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

@arkenv/cli

npm i https://pkg.pr.new/@arkenv/cli@943

@arkenv/fumadocs-ui

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

@arkenv/vite-plugin

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

commit: 0d17ed6

[arkenv-bot]

📦 Bundle Size Report

No results found

✅ All size limits passed!

[coderabbitai]

🧹 Nitpick comments (1)

packages/cli/src/env-template.test.ts (1)

35-59: ⚡ Quick win

Consider adding Vite-specific test coverage for Zod and Valibot.

The new Vite template generation logic is only tested for the arktype validator (lines 20-33). The Zod and Valibot templates also have Vite-specific branches (in zod.ts and valibot.ts) that generate schema-only exports, but these aren't covered by tests.

🧪 Suggested test additions

Add similar test cases for Zod and Valibot:

it("returns zod template for vite when validator is zod", () => {
	const options = {
		validator: "zod" as any,
		framework: "vite" as any,
		path: ".env.config.ts",
		language: "ts" as const,
		shouldUpdateTsConfig: false,
		shouldInstall: false,
	};
	const template = getEnvTemplate(options);
	expect(template).toContain('import { z } from "zod"');
	expect(template).not.toContain("export const env = arkenv(Env)");
	expect(template).toContain("export const Env = z.object({");
});

it("returns valibot template for vite when validator is valibot", () => {
	const options = {
		validator: "valibot" as any,
		framework: "vite" as any,
		path: ".env.config.ts",
		language: "ts" as const,
		shouldUpdateTsConfig: false,
		shouldInstall: false,
	};
	const template = getEnvTemplate(options);
	expect(template).toContain('import * as v from "valibot"');
	expect(template).not.toContain("export const env = arkenv(Env)");
	expect(template).toContain("export const Env = v.object({");
});

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/cli/src/env-template.test.ts` around lines 35 - 59, Add
Vite-specific test cases for Zod and Valibot in the same test file where
getEnvTemplate is exercised: create two new tests that call getEnvTemplate with
options.validator set to "zod" and "valibot" respectively and framework set to
"vite" (same shape as existing tests), then assert the template contains the
respective import strings ('import { z } from "zod"' and 'import * as v from
"valibot"'), assert it does NOT contain the runtime export 'export const env =
arkenv(Env)', and assert it contains the schema-only export lines ('export const
Env = z.object({' for zod and 'export const Env = v.object({' for valibot) to
cover the Vite branches implemented in zod.ts and valibot.ts when invoking
getEnvTemplate.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@packages/cli/src/env-template.test.ts`:
- Around line 35-59: Add Vite-specific test cases for Zod and Valibot in the
same test file where getEnvTemplate is exercised: create two new tests that call
getEnvTemplate with options.validator set to "zod" and "valibot" respectively
and framework set to "vite" (same shape as existing tests), then assert the
template contains the respective import strings ('import { z } from "zod"' and
'import * as v from "valibot"'), assert it does NOT contain the runtime export
'export const env = arkenv(Env)', and assert it contains the schema-only export
lines ('export const Env = z.object({' for zod and 'export const Env =
v.object({' for valibot) to cover the Vite branches implemented in zod.ts and
valibot.ts when invoking getEnvTemplate.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7f30b4b0-0a0f-47c6-b096-67e77e038829

📥 Commits

Reviewing files that changed from the base of the PR and between e6168f3 and fe57b62.

📒 Files selected for processing (6)

• packages/cli/src/env-template.test.ts
• packages/cli/src/env-template.ts
• packages/cli/src/templates/arktype.ts
• packages/cli/src/templates/valibot.ts
• packages/cli/src/templates/zod.ts
• skills/arkenv/SKILL.md

[arkenv-bot]

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

Warning

Rate limit exceeded

@yamcodes has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 12 minutes and 35 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered by pushing new commits to this PR or by re-running the workflow.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

We enforce hourly and daily rate limits to ensure stability and fair usage of resources.