From 31a185cbf0c6bed7503c45eefc5e4d032f48ccfd Mon Sep 17 00:00:00 2001
From: Em Poulter <epoulter@uclan.ac.uk>
Date: Tue, 21 Apr 2026 13:58:43 +0100
Subject: [PATCH 1/3] feat(env): Allow setting description on env schema config

---
 packages/astro/src/env/schema.ts | 4 ++++
 packages/astro/src/env/sync.ts   | 9 ++++++++-
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/packages/astro/src/env/schema.ts b/packages/astro/src/env/schema.ts
index 87943b27bd1d..081920e9f246 100644
--- a/packages/astro/src/env/schema.ts
+++ b/packages/astro/src/env/schema.ts
@@ -11,6 +11,7 @@ const StringSchema = z.object({
 	includes: z.string().optional(),
 	startsWith: z.string().optional(),
 	endsWith: z.string().optional(),
+	description: z.string().optional(),
 });
 export type StringSchema = z.infer<typeof StringSchema>;
 const NumberSchema = z.object({
@@ -22,12 +23,14 @@ const NumberSchema = z.object({
 	lt: z.number().optional(),
 	max: z.number().optional(),
 	int: z.boolean().optional(),
+	description: z.string().optional(),
 });
 export type NumberSchema = z.infer<typeof NumberSchema>;
 const BooleanSchema = z.object({
 	type: z.literal('boolean'),
 	optional: z.boolean().optional(),
 	default: z.boolean().optional(),
+	description: z.string().optional(),
 });
 const EnumSchema = z.object({
 	type: z.literal('enum'),
@@ -39,6 +42,7 @@ const EnumSchema = z.object({
 	),
 	optional: z.boolean().optional(),
 	default: z.string().optional(),
+	description: z.string().optional(),
 });
 export type EnumSchema = z.infer<typeof EnumSchema>;
 
diff --git a/packages/astro/src/env/sync.ts b/packages/astro/src/env/sync.ts
index 5949a476667b..e1f47db4f316 100644
--- a/packages/astro/src/env/sync.ts
+++ b/packages/astro/src/env/sync.ts
@@ -7,7 +7,11 @@ export function syncAstroEnv(settings: AstroSettings): void {
 	let server = '';
 
 	for (const [key, options] of Object.entries(settings.config.env.schema)) {
-		const str = `	export const ${key}: ${getEnvFieldType(options)};	\n`;
+		let str = '';
+		if(options.description) {
+			str += `	/** ${options.description} */`;
+		}
+		str += `	export const ${key}: ${getEnvFieldType(options)};\n`;
 		if (options.context === 'client') {
 			client += str;
 		} else {
@@ -21,6 +25,9 @@ export function syncAstroEnv(settings: AstroSettings): void {
 ${client}}`;
 	}
 	if (server !== '') {
+		if(content !== '') {
+			content += '\n';
+		}
 		content += `declare module 'astro:env/server' {
 ${server}}`;
 	}

From e6fef37e7f29914ef4e661e74175f6248a53822a Mon Sep 17 00:00:00 2001
From: Em Poulter <epoulter@uclan.ac.uk>
Date: Tue, 21 Apr 2026 14:19:35 +0100
Subject: [PATCH 2/3] feat(env): Add test config for env description

---
 packages/astro/src/env/sync.ts                          | 6 +++---
 packages/astro/test/fixtures/astro-env/astro.config.mjs | 4 ++--
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/astro/src/env/sync.ts b/packages/astro/src/env/sync.ts
index e1f47db4f316..1af6ad464d86 100644
--- a/packages/astro/src/env/sync.ts
+++ b/packages/astro/src/env/sync.ts
@@ -8,8 +8,8 @@ export function syncAstroEnv(settings: AstroSettings): void {
 
 	for (const [key, options] of Object.entries(settings.config.env.schema)) {
 		let str = '';
-		if(options.description) {
-			str += `	/** ${options.description} */`;
+		if (options.description) {
+			str += `	/** ${options.description} */\n`;
 		}
 		str += `	export const ${key}: ${getEnvFieldType(options)};\n`;
 		if (options.context === 'client') {
@@ -25,7 +25,7 @@ export function syncAstroEnv(settings: AstroSettings): void {
 ${client}}`;
 	}
 	if (server !== '') {
-		if(content !== '') {
+		if (content !== '') {
 			content += '\n';
 		}
 		content += `declare module 'astro:env/server' {
diff --git a/packages/astro/test/fixtures/astro-env/astro.config.mjs b/packages/astro/test/fixtures/astro-env/astro.config.mjs
index fbd76c522aa3..982f46a5abfd 100644
--- a/packages/astro/test/fixtures/astro-env/astro.config.mjs
+++ b/packages/astro/test/fixtures/astro-env/astro.config.mjs
@@ -4,9 +4,9 @@ import { defineConfig, envField } from 'astro/config';
 export default defineConfig({
 	env: {
 		schema: {
-			FOO: envField.string({ context: "client", access: "public", optional: true, default: "ABC" }),
+			FOO: envField.string({ context: "client", access: "public", optional: true, default: "ABC", description: "The FOO variable", }),
 			BAR: envField.string({ context: "client", access: "public", optional: true, default: "DEF" }),
-			BAZ: envField.string({ context: "server", access: "public", optional: true, default: "GHI" }),
+			BAZ: envField.string({ context: "server", access: "public", optional: true, default: "GHI", description: "The BAZ variable" }),
 		}
 	}
 });

From 3c35be602692602dbfacc559a9febe14d2aee2da Mon Sep 17 00:00:00 2001
From: Em Poulter <epoulter@uclan.ac.uk>
Date: Tue, 21 Apr 2026 14:19:49 +0100
Subject: [PATCH 3/3] chore(env): Add changeset

---
 .changeset/shy-dingos-tease.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/shy-dingos-tease.md

diff --git a/.changeset/shy-dingos-tease.md b/.changeset/shy-dingos-tease.md
new file mode 100644
index 000000000000..7f9f35fc04fb
--- /dev/null
+++ b/.changeset/shy-dingos-tease.md
@@ -0,0 +1,5 @@
+---
+'astro': patch
+---
+
+Allow setting descriptions on env schema config