feat: add T3 Env support (needs testing) #544

waruhachi · 2025-08-26T22:12:22Z

This pull request introduces support for the T3 Env addon.

The initial implementation was created a few months ago but wasn’t fully tested at that time.
The code has now been updated to align with the latest changes in the fork.
Note: This feature is expected to work, but extensive testing is required before merging.

Next Steps

Validate the integration with existing workflows.
Confirm compatibility with current configurations.
Report any issues or edge cases during testing.

References:
[Feature Request] Add Support for t3-env package and backend static serving #253
Request for T3 ENV #422

Summary by CodeRabbit

New Features
- Introduced a “T3 Env” addon for type-safe environment variables, available in the CLI and stack builder.
- Enabled integration across Next.js and Nuxt templates, including server/client env validation.
- Included “T3 Env” by default in presets and the default stack.
Documentation
- Updated READMEs, CLI options reference, and examples to include “t3env”.
- Reflected addon in generated project READMEs and site content.
Chores
- Added “t3env” to package keywords and site metadata.
- Updated UI labels/colors to display the new addon.

…mponent

/demo.gif -- 1,188.08kb -> 1,051.18kb (11.52%) Signed-off-by: ImgBotApp <ImgBotHelp@gmail.com>

coderabbitai · 2025-08-26T22:12:30Z

Walkthrough

Introduces a new CLI addon “t3env” for type-safe environment variables. Updates CLI constants, prompts, types, addon setup flow, and adds templates for Next/Nuxt env scaffolding. Adjusts defaults/presets to include t3env, updates docs and website to surface the addon, and adds required dependency versions.

Changes

Cohort / File(s)	Summary
CLI Addon Core Integration `apps/cli/src/constants.ts`, `apps/cli/src/helpers/addons/addons-setup.ts`, `apps/cli/src/helpers/addons/t3env-setup.ts`, `apps/cli/src/prompts/addons.ts`, `apps/cli/src/types.ts`	Adds t3env addon: extends defaults and compatibility, adds dependency versions (zod, @t3-oss/env-*), integrates setup flow via `setupT3Env`, updates prompts and Addons schema.
CLI Templates: T3 Env `apps/cli/templates/addons/t3env/...`	New templates for Next/Nuxt env: server and client env validation using @t3-oss/env-* and zod; Next/Nuxt config imports to initialize env.
CLI Nuxt Base Template Touch-up `apps/cli/templates/frontend/nuxt/nuxt.config.ts.hbs`	Adds import of `./env`.
CLI Package Metadata `apps/cli/package.json`	Adds keyword "t3env".
CLI README `apps/cli/README.md`	Documents t3env addon, usage flag `--addons t3env`, and compatibility note with `none`.
Root README `README.md`	Lists “T3 Env” in Addons.
Website UI/Logic & Presets `apps/web/src/lib/constant.ts`, `apps/web/src/app/(home)/_components/stack-builder.tsx`, `apps/web/src/app/(home)/analytics/_components/types.ts`, `apps/web/src/app/layout.tsx`, `apps/web/src/app/(home)/_components/npm-package.tsx`	Adds t3env addon option, includes it in defaults/presets, enables command generation with t3env, updates analytics config and site metadata keywords; minor formatting.
Website Docs `apps/web/content/docs/index.mdx`, `apps/web/content/docs/cli/options.mdx`	Updates examples and options to include t3env; adjusts default stack command to include t3env.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor User
  participant CLI as CLI (create)
  participant Addons as setupAddons
  participant T3Env as setupT3Env
  participant FS as fs-extra
  participant Pkg as addPackageDependency

  User->>CLI: run with --addons ... t3env ...
  CLI->>Addons: setupAddons(config)
  Addons->>Addons: if addons includes "t3env"
  Addons->>T3Env: setupT3Env(config)

  rect rgba(230,230,255,0.4)
    note right of T3Env: Start spinner: "Setting up T3 Env"
    T3Env->>FS: check apps/server, apps/web existence
    alt Frontend: Next
      T3Env->>Pkg: add @t3-oss/env-nextjs (+ zod if needed)
    else Frontend: Nuxt
      T3Env->>Pkg: add @t3-oss/env-nuxt + zod
    else Other web
      T3Env->>Pkg: add @t3-oss/env-core + zod
    end
    opt Server present
      T3Env->>Pkg: add @t3-oss/env-core + zod (server)
    end
  end

  T3Env-->>Addons: success or error (spinner stop)
  Addons-->>CLI: continue other addon setups
  CLI-->>User: generated project with T3 Env scaffolding

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

feat(cli): add vibe rules addon #481 — Adds another CLI addon and touches the same addon plumbing (types, compatibility, setup integration).
feat: add command #337 — Prior work on addon system structures (compatibility, prompts, setup flow) that this PR extends.
feat(cli): add alchemy and improve cli tooling and structure #520 — Modifies dependencyVersionMap, related to this PR’s added env and zod entries.

Poem

In burrows of code I nibble with glee,
A sprout named t3env grows type-safely.
Zod in my paws, I validate breeze,
Next and Nuxt forests whisper env keys.
With presets updated, I thump in delight—
Burrow secure, variables right. 🐇✨

Tip

🔌 Remote MCP (Model Context Protocol) integration is now available!

Pro plan users can now connect to remote MCP servers from the Integrations page. Connect with popular remote MCPs such as Notion and Linear to add more context to your reviews and chats.

✨ Finishing Touches

📝 Generate Docstrings

🧪 Generate unit tests

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

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

CodeRabbit Commands (Invoked using PR/Issue comments)

Type @coderabbitai help to get the list of available commands.

Other keywords and placeholders

Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (`.coderabbit.yaml`)

You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Status, Documentation and Community

Visit our Status Page to check the current availability of CodeRabbit.
Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

coderabbitai

Actionable comments posted: 11

🧹 Nitpick comments (18)

apps/web/src/app/(home)/_components/npm-package.tsx (3)
15-17: Guard against empty or unexpected GitHub releases payload

Accessing data[0].tag_name will throw if there are no releases or the payload shape changes. Add a defensive check and a safe fallback.

Apply this diff:
- const data = await res.json();
- const latestVersion = data[0].tag_name.replace(/^v/, "");
- setVersion(latestVersion);
+ const data = await res.json();
+ const tag =
+ Array.isArray(data) && data.length > 0 && typeof data[0]?.tag_name === "string"
+ ? data[0].tag_name
+ : null;
+ setVersion(tag ? tag.replace(/^v/, "") : "latest");
8-24: Prevent state update on unmounted component; add AbortController and pass signal to fetch

If the component unmounts before the request resolves, setVersion may run after unmount. Abort the fetch and avoid potential React warnings. This also sets you up to add caching or retries later.

Apply this diff:
 useEffect(() => {
- const getLatestVersion = async () => {
+ const controller = new AbortController();
+ const getLatestVersion = async () => {
 try {
- const res = await fetch(
- "https://api.github.com/repos/AmanVarshney01/create-better-t-stack/releases",
- );
+ const res = await fetch(
+ "https://api.github.com/repos/AmanVarshney01/create-better-t-stack/releases",
+ { signal: controller.signal },
+ );
 if (!res.ok) throw new Error("Failed to fetch version");
- const data = await res.json();
+ const data = await res.json();
 const latestVersion = data[0].tag_name.replace(/^v/, "");
 setVersion(latestVersion);
 } catch (error) {
 console.error("Error fetching NPM version:", error);
 setVersion("latest");
 }
 };
 getLatestVersion();
- }, []);
+ return () => controller.abort();
+ }, []);
Architecture note: For a public homepage, an unauthenticated client-side call to GitHub’s API risks rate limits. Consider moving this to a server component/route with caching (e.g., revalidate) or switching to the npm registry endpoint for the package’s dist-tags.latest, which is simpler to parse and cacheable by your edge/CDN.

19-20: Clarify log message source

The message says “NPM” but the data source is GitHub. Align the message to reduce confusion during debugging.
- console.error("Error fetching NPM version:", error);
+ console.error("Error fetching version from GitHub releases:", error);
apps/web/src/app/layout.tsx (1)
39-40: Minor SEO nit: add common synonyms for the new keyword

Adding a couple of variants can help searchability without changing behavior.

Apply this diff to extend the keywords list:
-		"t3env",
+		"t3env",
+		"t3 env",
+		"t3-oss/env",
apps/web/src/app/(home)/_components/stack-builder.tsx (1)
1166-1179: Avoid hardcoding addon ids; derive from TECH_OPTIONS to prevent future drift

validAddons is a hardcoded whitelist. It can silently drift from TECH_OPTIONS or the CLI if new addons are added later. Use TECH_OPTIONS.addons to derive the allowed set and filter out "none".

Apply this diff to make the list source-of-truth driven:
-			const validAddons = stackState.addons.filter((addon) =>
-				[
-					"pwa",
-					"tauri",
-					"starlight",
-					"biome",
-					"husky",
-					"turborepo",
-					"ultracite",
-					"fumadocs",
-					"oxlint",
-					"ruler",
-					"t3env",
-				].includes(addon),
-			);
+			const knownAddons =
+				(TECH_OPTIONS.addons ?? [])
+					.map((opt) => opt.id)
+					.filter((id) => id !== "none");
+			const validAddons = stackState.addons.filter((addon) =>
+				knownAddons.includes(addon),
+			);
apps/cli/package.json (1)
52-59: Optional: consider migrating tests to Bun’s built-in runner

Per project guidelines, prefer “bun test” over external runners. This is out-of-scope for this PR but worth a follow-up to simplify toolchain and devDependencies.

Example scripts section using Bun’s runner:
{
 "scripts": {
 "build": "tsdown",
 "dev": "tsdown --watch",
 "check-types": "tsc --noEmit",
 "check": "biome check --write .",
 "test": "bun test",
 "test:ui": "bun test --watch",
 "prepublishOnly": "npm run build"
 }
}
I can open a small follow-up PR to migrate tests and remove unused deps if you’d like.
apps/web/content/docs/cli/options.mdx (1)

248-248: Docs LGTM: Addons list now includes t3env

Reads well and matches the CLI flag. Consider adding a one-liner note that the CLI wires T3 Env with zod and provides Next/Nuxt env templates so users know what to expect.

Possible clarification right under the bullet:

“The CLI sets up T3 Env with zod. Client/server templates are provided for Next/Nuxt; server-only uses env-core.”

If helpful, I can add a short “Usage” snippet showing --addons t3env in a full command.
apps/cli/README.md (3)
44-44: Keep feature list in sync with CLI options (missing addons in table).

The Addons row omits several options present in the CLI (fumadocs, ultracite, oxlint, ruler). Add them for consistency.
-| **Addons** | • PWA support • Tauri (desktop applications) • Starlight (documentation site) • Biome (linting and formatting) • Husky (Git hooks) • Turborepo (optimized builds) • T3 Env (Type-safe environment variables) |
+| **Addons** | • PWA support • Tauri (desktop applications) • Starlight (documentation site) • Biome (linting and formatting) • Husky (Git hooks) • Turborepo (optimized builds) • T3 Env (Type-safe environment variables) • Fumadocs (documentation site) • Ultracite (Biome preset + AI) • Oxlint (Rust linter) • Ruler (AI rules) |
61-61: Add missing addon "ruler" to the CLI flag help.

The --addons list is missing ruler, which exists in code (ADDON_COMPATIBILITY and web constants). Add it to prevent confusion.
- --addons <types...> Additional addons (pwa, tauri, starlight, biome, husky, turborepo, fumadocs, ultracite, oxlint, t3env, none)
+ --addons <types...> Additional addons (pwa, tauri, starlight, biome, husky, turborepo, fumadocs, ultracite, oxlint, ruler, t3env, none)
195-195: Generalize or update the "Addons 'none'" note to include all addons.

Currently lists a subset; either remove the parenthetical or include all addons to avoid drift.
-- **Addons 'none'**: Skips all addons (PWA, Tauri, Starlight, Biome, Husky, Turborepo, T3 Env).
+- **Addons 'none'**: Skips all addons (e.g., PWA, Tauri, Starlight, Biome, Husky, Turborepo, T3 Env, Fumadocs, Ultracite, Oxlint, Ruler).
apps/cli/src/helpers/addons/t3env-setup.ts (3)
23-29: Server deps: LGTM, but gate on backend existence.

Install @t3-oss/env-core + zod only if a server app exists and backend !== "none".
-		const serverDir = path.join(projectDir, "apps/server");
-		if (await fs.pathExists(serverDir)) {
+		const serverDir = path.join(projectDir, "apps/server");
+		if (backend !== "none" && (await fs.pathExists(serverDir))) {
43-47: Fix misleading comment for Nuxt branch.

The comment says “use the core package” but you install @t3-oss/env-nuxt. Update the comment.
-				// For Nuxt, we'll use the core package
+				// For Nuxt, use the Nuxt-specific package
57-63: Success/error messaging: enhance clarity.

Consider coloring success with pc.green and include which apps were configured (server/web) to aid debugging in multi-app repos.
-		s.stop("T3 Env configured successfully!");
+		s.stop(pc.green("T3 Env configured successfully!"));
apps/web/src/lib/constant.ts (1)
513-520: Icon path consistency for t3env.

Most icons use ICON_BASE_URL; t3env points to a local /icon/t3env.svg. Prefer a consistent source (or confirm the asset exists in public/icon/ and is deployed).
-			icon: "/icon/t3env.svg",
+			icon: `${ICON_BASE_URL}/t3env.svg`,
If the remote asset doesn’t exist yet, add it to the CDN or keep the local path and ensure the file is present in the web app’s public assets.
apps/cli/src/helpers/addons/addons-setup.ts (1)

63-65: Consider allowing T3 Env without a backend

setupT3Env exits early when backend === "none". T3 Env can still be valuable for Next-only apps (client/public env validation). Consider relaxing the restriction and running the web dependency/setup path even without a backend.

If you choose to keep the restriction, make sure the prompt/README explicitly calls it out to avoid user confusion.
apps/cli/templates/addons/t3env/apps/server/next/src/env/server.ts.hbs (1)
1-15: Tighten runtimeEnv mapping and add opt-out for validation in CI

Current config passes experimental__runtimeEnv: process.env but doesn’t explicitly scope runtimeEnv. To prevent accidental exposure and to improve treeshaking, explicitly map only the keys you declare. Also, add a skipValidation flag controlled by SKIP_ENV_VALIDATION (commonly used in CI).

Apply this diff:
 export const env = createEnv({
 server: {
 DATABASE_URL: z.string().url(),
 BETTER_AUTH_SECRET: z.string().min(1),
 BETTER_AUTH_URL: z.string().url(),
 CORS_ORIGIN: z.string().url(),
 {{#if (includes examples 'ai')}}
 GOOGLE_GENERATIVE_AI_API_KEY: z.string().min(1),
 {{/if}}
 },
- experimental__runtimeEnv: process.env,
+ // Only provide the vars you defined above to the runtime mapping
+ runtimeEnv: {
+ DATABASE_URL: process.env.DATABASE_URL,
+ BETTER_AUTH_SECRET: process.env.BETTER_AUTH_SECRET,
+ BETTER_AUTH_URL: process.env.BETTER_AUTH_URL,
+ CORS_ORIGIN: process.env.CORS_ORIGIN,
+ {{#if (includes examples 'ai')}}
+ GOOGLE_GENERATIVE_AI_API_KEY: process.env.GOOGLE_GENERATIVE_AI_API_KEY,
+ {{/if}}
+ },
+ // Optional: allow skipping validation in CI/local scripts
+ skipValidation: !!process.env.SKIP_ENV_VALIDATION,
+ experimental__runtimeEnv: process.env,
 });
Please confirm the targeted @t3-oss/env-nextjs version still recommends experimental__runtimeEnv with Next.js, and whether you want CORS_ORIGIN to support multiple origins (array or CSV). If yes, we can tweak the schema accordingly.
apps/cli/templates/addons/t3env/apps/web/next/src/env/client.ts.hbs (2)
4-17: Add skipValidation and emptyStringAsUndefined for better DX and CI ergonomics.

This prevents noisy failures in CI or on platforms that inject empty strings. It’s a common pattern across T3 Env templates.

Apply this diff:
 export const env = createEnv({
 client: {
 NEXT_PUBLIC_SERVER_URL: z.string().url(),
 {{#if (eq backend 'convex')}}
 NEXT_PUBLIC_CONVEX_URL: z.string().url(),
 {{/if}}
 },
 runtimeEnv: {
 NEXT_PUBLIC_SERVER_URL: process.env.NEXT_PUBLIC_SERVER_URL,
 {{#if (eq backend 'convex')}}
 NEXT_PUBLIC_CONVEX_URL: process.env.NEXT_PUBLIC_CONVEX_URL,
 {{/if}}
- },
+ },
+ // Skip validation in CI or when explicitly requested.
+ skipValidation:
+ process.env.CI === "true" || process.env.SKIP_ENV_VALIDATION === "true",
+ // Treat empty strings as undefined to avoid false positives on some hosts.
+ emptyStringAsUndefined: true,
 });
7-9: Convex key naming LGTM; confirm docs alignment.

NEXT_PUBLIC_CONVEX_URL matches typical Convex examples. Just ensure the CLI scaffold also writes this key into .env (local) and docs/readme so users don’t miss it.

If helpful, I can add .env(.example) insertion and a short README section for Convex with a checklist.

Also applies to: 13-15

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

MCP integration is disabled by default for public repositories
Jira integration is disabled by default for public repositories
Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 77b3b72 and 1f8afc7.

⛔ Files ignored due to path filters (2)

apps/web/public/icon/t3env.svg is excluded by !**/*.svg
demo.gif is excluded by !**/*.gif

📒 Files selected for processing (22)

README.md (1 hunks)
apps/cli/README.md (3 hunks)
apps/cli/package.json (1 hunks)
apps/cli/src/constants.ts (3 hunks)
apps/cli/src/helpers/addons/addons-setup.ts (2 hunks)
apps/cli/src/helpers/addons/t3env-setup.ts (1 hunks)
apps/cli/src/helpers/core/create-readme.ts (1 hunks)
apps/cli/src/prompts/addons.ts (2 hunks)
apps/cli/src/types.ts (1 hunks)
apps/cli/templates/addons/t3env/apps/server/next/next.config.ts (1 hunks)
apps/cli/templates/addons/t3env/apps/server/next/src/env/server.ts.hbs (1 hunks)
apps/cli/templates/addons/t3env/apps/web/next/src/env/client.ts.hbs (1 hunks)
apps/cli/templates/addons/t3env/apps/web/next/src/next.config.ts.hbs (1 hunks)
apps/cli/templates/addons/t3env/apps/web/nuxt/src/env/client.ts.hbs (1 hunks)
apps/cli/templates/frontend/nuxt/nuxt.config.ts.hbs (1 hunks)
apps/web/content/docs/cli/options.mdx (1 hunks)
apps/web/content/docs/index.mdx (1 hunks)
apps/web/src/app/(home)/_components/npm-package.tsx (1 hunks)
apps/web/src/app/(home)/_components/stack-builder.tsx (1 hunks)
apps/web/src/app/(home)/analytics/_components/types.ts (1 hunks)
apps/web/src/app/layout.tsx (1 hunks)
apps/web/src/lib/constant.ts (7 hunks)

🧰 Additional context used

📓 Path-based instructions (6)

**/*.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/convex_rules.mdc)

**/*.{ts,tsx}: Use Id from './_generated/dataModel' to type document ids (e.g., Id<'users'>)
Ensure Record key/value types align with validators (e.g., v.record(v.id('users'), v.string()) => Record<Id<'users'>, string>)
Be strict with types for document ids; prefer Id<'table'> over string
Use 'as const' for string literals in discriminated unions
When using Array and Record types, declare with explicit generic types (e.g., const arr: Array = ...)

Files:

apps/cli/templates/addons/t3env/apps/server/next/next.config.ts
apps/cli/src/prompts/addons.ts
apps/cli/src/types.ts
apps/web/src/app/(home)/_components/stack-builder.tsx
apps/cli/src/helpers/core/create-readme.ts
apps/web/src/app/(home)/_components/npm-package.tsx
apps/cli/src/helpers/addons/t3env-setup.ts
apps/cli/src/helpers/addons/addons-setup.ts
apps/web/src/app/layout.tsx
apps/web/src/app/(home)/analytics/_components/types.ts
apps/cli/src/constants.ts
apps/web/src/lib/constant.ts

**/*.{js,jsx,ts,tsx,mjs,cjs}