From 0eccdc9c5f2da6bb7dd02aeec5041c391d595146 Mon Sep 17 00:00:00 2001
From: shadcn <m@shadcn.com>
Date: Wed, 30 Jul 2025 12:22:40 +0400
Subject: [PATCH] docs: add docs for envVars

---
 apps/v4/content/docs/registry/examples.mdx    | 25 +++++++++++++++++++
 .../docs/registry/registry-item-json.mdx      | 24 +++++++++++++++++-
 2 files changed, 48 insertions(+), 1 deletion(-)

diff --git a/apps/v4/content/docs/registry/examples.mdx b/apps/v4/content/docs/registry/examples.mdx
index c2cde08d74..ea02c078c9 100644
--- a/apps/v4/content/docs/registry/examples.mdx
+++ b/apps/v4/content/docs/registry/examples.mdx
@@ -369,6 +369,31 @@ Note: you need to define both `@keyframes` in css and `theme` in cssVars to use
 }
 ```
 
+## Add environment variables
+
+You can add environment variables using the `envVars` field.
+
+```json title="example-item.json" showLineNumbers {5-9}
+{»
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "custom-item",
+  "type": "registry:item",
+  "envVars": {
+    "NEXT_PUBLIC_APP_URL": "http://localhost:4000",
+    "DATABASE_URL": "postgresql://postgres:postgres@localhost:5432/postgres",
+    "OPENAI_API_KEY": ""
+  }
+}
+```
+
+Environment variables are added to the `.env.local` or `.env` file. Existing variables are not overwritten.
+
+<Callout>
+
+**IMPORTANT:** Use `envVars` to add development or example variables. Do NOT use it to add production variables.
+
+</Callout>
+
 ## Universal Items
 
 As of `2.9.0`, you can create universal items that can be installed without framework detection or components.json.
diff --git a/apps/v4/content/docs/registry/registry-item-json.mdx b/apps/v4/content/docs/registry/registry-item-json.mdx
index 6942ec854f..c766aaec86 100644
--- a/apps/v4/content/docs/registry/registry-item-json.mdx
+++ b/apps/v4/content/docs/registry/registry-item-json.mdx
@@ -296,13 +296,35 @@ Use `css` to add new rules to the project's CSS file eg. `@layer base`, `@layer
 }
 ```
 
+### envVars
+
+Use `envVars` to add environment variables to your registry item.
+
+```json title="registry-item.json" showLineNumbers
+{
+  "envVars": {
+    "NEXT_PUBLIC_APP_URL": "http://localhost:4000",
+    "DATABASE_URL": "postgresql://postgres:postgres@localhost:5432/postgres",
+    "OPENAI_API_KEY": ""
+  }
+}
+```
+
+Environment variables are added to the `.env.local` or `.env` file. Existing variables are not overwritten.
+
+<Callout>
+
+**IMPORTANT:** Use `envVars` to add development or example variables. Do NOT use it to add production variables.
+
+</Callout>
+
 ### docs
 
 Use `docs` to show custom documentation or message when installing your registry item via the CLI.
 
 ```json title="registry-item.json" showLineNumbers
 {
-  "docs": "Remember to add the FOO_BAR environment variable to your .env file."
+  "docs": "To get an OPENAI_API_KEY, sign up for an account at https://platform.openai.com."
 }
 ```