feat: deprecate Astro in getStaticPaths (#14432)

Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com>
Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com>

Author: 3 people

.changeset/fast-bushes-fall.md

@@ -0,0 +1,27 @@
+---
+'astro': major
+---
+
+Deprecates `Astro` in `getStaticPaths()`
+
+In Astro 5.x, it was possible to access an `Astro` object inside `getStaticPaths()`. However, despite being typed the same as the `Astro` object accessible in the frontmatter, this object only had `site` and `generator` properties. This could lead to confusion about which `Astro` object properties were available inside `getStaticPaths()`.
+
+Astro 6.0 deprecates this object for `getStaticPaths()` to avoid confusion and improves error handling when attempting to access `Astro` values that are unavailable. Using `Astro.site` or `Astro.generator` within `getStaticPaths()` will now log a deprecation warning, and accessing any other property will throw a specific error with a helpful message. In a future major version, this object will be removed entirely, and accessing `Astro.site` or `Astro.generator` will also throw an error.
+
+#### What should I do?
+
+Update your `getStaticPaths()` function if you were attempting to access any `Astro` properties inside its scope. Remove `Astro.generator` entirely, and replace all occurrences of `Astro.site()` with `import.meta.env.SITE`:
+
+```diff
+---
+// src/pages/blog/[slug].astro
+import { getPages } from "../../../utils/data";
+
+export async function getStaticPaths() {
+-    console.log(Astro.generator);
+-    return getPages(Astro.site);
++    return getPages(import.meta.env.SITE);
+}
+---
+```
+

packages/astro/package.json

@@ -106,7 +106,7 @@
     "test:integration": "astro-scripts test \"test/*.test.js\""
   },
   "dependencies": {
-    "@astrojs/compiler": "^2.12.2",
+    "@astrojs/compiler": "0.0.0-next-result-create-astro-20250926081949",
     "@astrojs/internal-helpers": "workspace:*",
     "@astrojs/markdown-remark": "workspace:*",
     "@astrojs/telemetry": "workspace:*",

packages/astro/src/core/constants.ts

@@ -1,6 +1,8 @@
 // process.env.PACKAGE_VERSION is injected when we build and publish the astro package.
 export const ASTRO_VERSION = process.env.PACKAGE_VERSION ?? 'development';
 
+export const ASTRO_GENERATOR = `Astro v${ASTRO_VERSION}`;
+
 /**
  * The name for the header used to help rerouting behavior.
  * When set to "no", astro will NOT try to reroute an error response to the corresponding error page, which is the default behavior that can sometimes lead to loops.

packages/astro/src/core/errors/errors-data.ts

@@ -1417,6 +1417,19 @@ export const CspNotEnabled = {
 	message: "The `experimental.csp` configuration isn't enabled.",
 } satisfies ErrorData;
 
+/**
+ * @docs
+ * @description
+ * Unavailable Astro global in getStaticPaths
+ * @message
+ * The Astro global is not available in getStaticPaths().
+ */
+export const UnavailableAstroGlobal = {
+	name: 'UnavailableAstroGlobal',
+	title: 'Unavailable Astro global in getStaticPaths()',
+	message: (name: string) => `The Astro global is not available in this scope. Please remove "Astro.${name}" from your getStaticPaths() function.`,
+} satisfies ErrorData;
+
 /**
  * @docs
  * @kind heading

packages/astro/src/core/middleware/index.ts

@@ -6,7 +6,7 @@ import {
 } from '../../i18n/utils.js';
 import type { MiddlewareHandler, Params, RewritePayload } from '../../types/public/common.js';
 import type { APIContext, AstroSharedContextCsp } from '../../types/public/context.js';
-import { ASTRO_VERSION } from '../constants.js';
+import { ASTRO_GENERATOR } from '../constants.js';
 import { AstroCookies } from '../cookies/index.js';
 import { AstroError, AstroErrorData } from '../errors/index.js';
 import { getClientIpAddress } from '../routing/request.js';
@@ -73,7 +73,7 @@ function createContext({
 		request,
 		params,
 		site: undefined,
-		generator: `Astro v${ASTRO_VERSION}`,
+		generator: ASTRO_GENERATOR,
 		props: {},
 		rewrite,
 		routePattern: '',

packages/astro/src/core/render-context.ts

@@ -12,16 +12,11 @@ import { renderEndpoint } from '../runtime/server/endpoint.js';
 import { renderPage } from '../runtime/server/index.js';
 import type { ComponentInstance } from '../types/astro.js';
 import type { MiddlewareHandler, Props, RewritePayload } from '../types/public/common.js';
-import type {
-	APIContext,
-	AstroGlobal,
-	AstroGlobalPartial,
-	AstroSharedContextCsp,
-} from '../types/public/context.js';
+import type { APIContext, AstroGlobal, AstroSharedContextCsp } from '../types/public/context.js';
 import type { RouteData, SSRResult } from '../types/public/internal.js';
 import type { SSRActions } from './app/types.js';
 import {
-	ASTRO_VERSION,
+	ASTRO_GENERATOR,
 	REROUTE_DIRECTIVE_HEADER,
 	REWRITE_DIRECTIVE_HEADER_KEY,
 	REWRITE_DIRECTIVE_HEADER_VALUE,
@@ -384,7 +379,6 @@ export class RenderContext {
 	createActionAPIContext(): ActionAPIContext {
 		const renderContext = this;
 		const { params, pipeline, url } = this;
-		const generator = `Astro v${ASTRO_VERSION}`;
 
 		const rewrite = async (reroutePayload: RewritePayload) => {
 			return await this.#executeRewrite(reroutePayload);
@@ -403,7 +397,7 @@ export class RenderContext {
 			get currentLocale() {
 				return renderContext.computeCurrentLocale();
 			},
-			generator,
+			generator: ASTRO_GENERATOR,
 			get locals() {
 				return renderContext.locals;
 			},
@@ -532,8 +526,7 @@ export class RenderContext {
 			compressHTML,
 			cookies,
 			/** This function returns the `Astro` faux-global */
-			createAstro: (astroGlobal, props, slots) =>
-				this.createAstro(result, astroGlobal, props, slots, ctx),
+			createAstro: (props, slots) => this.createAstro(result, props, slots, ctx),
 			links,
 			params: this.params,
 			partial,
@@ -588,26 +581,17 @@ export class RenderContext {
 	 */
 	createAstro(
 		result: SSRResult,
-		astroStaticPartial: AstroGlobalPartial,
 		props: Record<string, any>,
 		slotValues: Record<string, any> | null,
 		apiContext: ActionAPIContext,
 	): AstroGlobal {
 		let astroPagePartial;
 		// During rewriting, we must recompute the Astro global, because we need to purge the previous params/props/etc.
 		if (this.isRewriting) {
-			astroPagePartial = this.#astroPagePartial = this.createAstroPagePartial(
-				result,
-				astroStaticPartial,
-				apiContext,
-			);
+			astroPagePartial = this.#astroPagePartial = this.createAstroPagePartial(result, apiContext);
 		} else {
 			// Create page partial with static partial so they can be cached together.
-			astroPagePartial = this.#astroPagePartial ??= this.createAstroPagePartial(
-				result,
-				astroStaticPartial,
-				apiContext,
-			);
+			astroPagePartial = this.#astroPagePartial ??= this.createAstroPagePartial(result, apiContext);
 		}
 		// Create component-level partials. `Astro.self` is added by the compiler.
 		const astroComponentPartial = { props, self: null };
@@ -638,7 +622,6 @@ export class RenderContext {
 
 	createAstroPagePartial(
 		result: SSRResult,
-		astroStaticPartial: AstroGlobalPartial,
 		apiContext: ActionAPIContext,
 	): Omit<AstroGlobal, 'props' | 'self' | 'slots'> {
 		const renderContext = this;
@@ -661,7 +644,7 @@ export class RenderContext {
 		const callAction = createCallAction(apiContext);
 
 		return {
-			generator: astroStaticPartial.generator,
+			generator: ASTRO_GENERATOR,
 			routePattern: this.routeData.route,
 			isPrerendered: this.routeData.prerender,
 			cookies,

packages/astro/src/runtime/server/astro-global.ts

@@ -1,11 +1,99 @@
-import { ASTRO_VERSION } from '../../core/constants.js';
-import type { AstroGlobalPartial } from '../../types/public/context.js';
+import { ASTRO_GENERATOR } from '../../core/constants.js';
+import { AstroError, AstroErrorData } from '../../core/errors/index.js';
+import type { AstroGlobal } from '../../types/public/context.js';
+
+function createError(name: string) {
+	return new AstroError({
+		...AstroErrorData.UnavailableAstroGlobal,
+		message: AstroErrorData.UnavailableAstroGlobal.message(name),
+	});
+}
 
 // This is used to create the top-level Astro global; the one that you can use
 // inside of getStaticPaths. See the `astroGlobalArgs` option for parameter type.
-export function createAstro(site: string | undefined): AstroGlobalPartial {
+export function createAstro(site: string | undefined): AstroGlobal {
 	return {
-		site: site ? new URL(site) : undefined,
-		generator: `Astro v${ASTRO_VERSION}`,
+		// TODO: throw in Astro 7
+		get site() {
+			// This is created inside of the runtime so we don't have access to the Astro logger.
+			console.warn(
+				`Astro.site inside getStaticPaths is deprecated and will be removed in a future major version of Astro. Use import.meta.env.SITE instead`,
+			);
+			return site ? new URL(site) : undefined;
+		},
+		// TODO: throw in Astro 7
+		get generator() {
+			// This is created inside of the runtime so we don't have access to the Astro logger.
+			console.warn(
+				`Astro.generator inside getStaticPaths is deprecated and will be removed in a future major version of Astro.`,
+			);
+			return ASTRO_GENERATOR;
+		},
+		get callAction(): any {
+			throw createError('callAction');
+		},
+		get clientAddress(): any {
+			throw createError('clientAddress');
+		},
+		get cookies(): any {
+			throw createError('cookies');
+		},
+		get csp(): any {
+			throw createError('csp');
+		},
+		get currentLocale(): any {
+			throw createError('currentLocale');
+		},
+		get getActionResult(): any {
+			throw createError('getActionResult');
+		},
+		get isPrerendered(): any {
+			throw createError('isPrerendered');
+		},
+		get locals(): any {
+			throw createError('locals');
+		},
+		get originPathname(): any {
+			throw createError('originPathname');
+		},
+		get params(): any {
+			throw createError('params');
+		},
+		get preferredLocale(): any {
+			throw createError('preferredLocale');
+		},
+		get preferredLocaleList(): any {
+			throw createError('preferredLocaleList');
+		},
+		get props(): any {
+			throw createError('props');
+		},
+		get redirect(): any {
+			throw createError('redirect');
+		},
+		get request(): any {
+			throw createError('request');
+		},
+		get response(): any {
+			throw createError('response');
+		},
+		get rewrite(): any {
+			throw createError('rewrite');
+		},
+		get routePattern(): any {
+			throw createError('routePattern');
+		},
+		get self(): any {
+			throw createError('self');
+		},
+		get slots(): any {
+			throw createError('slots');
+		},
+		get url(): any {
+			throw createError('url');
+		},
+		get session(): any {
+			throw createError('session');
+		},
 	};
 }

packages/astro/src/types/public/context.ts

@@ -21,8 +21,23 @@ export interface AstroGlobal<
 	Self = AstroComponentFactory,
 	// eslint-disable-next-line @typescript-eslint/no-shadow
 	Params extends Record<string, string | undefined> = Record<string, string | undefined>,
-> extends AstroGlobalPartial,
-		AstroSharedContext<Props, Params> {
+> extends AstroSharedContext<Props, Params> {
+	/**
+	 * Returns a [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) object built from the [site](https://docs.astro.build/en/reference/configuration-reference/#site) config option
+	 *
+	 * [Astro reference](https://docs.astro.build/en/reference/api-reference/#astrosite)
+	 */
+	site: URL | undefined;
+	/**
+	 * Returns a string with the current version of Astro.
+	 *
+	 * Useful for using `<meta name="generator" content={Astro.generator} />` or crediting Astro in a site footer.
+	 *
+	 * [HTML Specification for `generator`](https://html.spec.whatwg.org/multipage/semantics.html#meta-generator)
+	 *
+	 * [Astro reference](https://docs.astro.build/en/reference/api-reference/#astrogenerator)
+	 */
+	generator: string;
 	/**
 	 * A full URL object of the request URL.
 	 * Equivalent to: `new URL(Astro.request.url)`
@@ -206,25 +221,6 @@ export interface AstroGlobal<
 	};
 }
 
-export interface AstroGlobalPartial {
-	/**
-	 * Returns a [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) object built from the [site](https://docs.astro.build/en/reference/configuration-reference/#site) config option
-	 *
-	 * [Astro reference](https://docs.astro.build/en/reference/api-reference/#astrosite)
-	 */
-	site: URL | undefined;
-	/**
-	 * Returns a string with the current version of Astro.
-	 *
-	 * Useful for using `<meta name="generator" content={Astro.generator} />` or crediting Astro in a site footer.
-	 *
-	 * [HTML Specification for `generator`](https://html.spec.whatwg.org/multipage/semantics.html#meta-generator)
-	 *
-	 * [Astro reference](https://docs.astro.build/en/reference/api-reference/#astrogenerator)
-	 */
-	generator: string;
-}
-
 // Shared types between `Astro` global and API context object
 export interface AstroSharedContext<
 	Props extends Record<string, any> = Record<string, any>,

packages/astro/src/types/public/internal.ts

@@ -6,7 +6,7 @@ import type { AstroCookies } from '../../core/cookies/cookies.js';
 import type { AstroComponentInstance, ServerIslandComponent } from '../../runtime/server/index.js';
 import type { Params } from './common.js';
 import type { AstroConfig, RedirectConfig } from './config.js';
-import type { AstroGlobal, AstroGlobalPartial } from './context.js';
+import type { AstroGlobal } from './context.js';
 import type { AstroRenderer } from './integrations.js';
 
 export type { SSRActions, SSRManifest, SSRManifestCSP } from '../../core/app/types.js';
@@ -221,11 +221,7 @@ export interface SSRResult {
 	links: Set<SSRElement>;
 	componentMetadata: Map<string, SSRComponentMetadata>;
 	inlinedScripts: Map<string, string>;
-	createAstro(
-		Astro: AstroGlobalPartial,
-		props: Record<string, any>,
-		slots: Record<string, any> | null,
-	): AstroGlobal;
+	createAstro(props: Record<string, any>, slots: Record<string, any> | null): AstroGlobal;
 	params: Params;
 	resolve: (s: string) => Promise<string>;
 	response: AstroGlobal['response'];