`astro:` namespace for middleware and components (#8101)

* `astro:` namespace for middleware and components

* Update errors to use namespace

* Create a namespace module just for the astro: stuff

23 files changed, 55 insertions, 20 deletions

diff --git a/.changeset/neat-mugs-end.md b/.changeset/neat-mugs-end.md
new file mode 100644
index 000000000..dd65708a7
--- /dev/null
+++ b/.changeset/neat-mugs-end.md
@@ -0,0 +1,8 @@
+---
+'astro': minor
+---
+
+
+`astro:`namespace aliases for middleware and components
+
+This adds aliases of `astro:middleware` and `astro:components` for the middleware and components modules. This is to make our documentation consistent between are various modules, where some are virtual modules and others are not. Going forward new built-in modules will use this namespace.
diff --git a/examples/middleware/src/middleware.ts b/examples/middleware/src/middleware.ts
index 9871e9d01..eb7644535 100644
--- a/examples/middleware/src/middleware.ts
+++ b/examples/middleware/src/middleware.ts
@@ -1,4 +1,4 @@
-import { defineMiddleware, sequence } from 'astro/middleware';
+import { defineMiddleware, sequence } from 'astro:middleware';
 import htmlMinifier from 'html-minifier';
 
 const limit = 50;
diff --git a/packages/astro/client.d.ts b/packages/astro/client.d.ts
index 7f701b0c0..e6389d415 100644
--- a/packages/astro/client.d.ts
+++ b/packages/astro/client.d.ts
@@ -119,6 +119,14 @@ declare module 'astro:transitions' {
 	export const ViewTransitions: ViewTransitionsModule['default'];
 }
 
+declare module 'astro:middleware' {
+	export * from 'astro/middleware/namespace';
+}
+
+declare module 'astro:components' {
+	export * from 'astro/components';
+}
+
 type MD = import('./dist/@types/astro').MarkdownInstance<Record<string, any>>;
 interface ExportedMarkdownModuleEntities {
 	frontmatter: MD['frontmatter'];
diff --git a/packages/astro/package.json b/packages/astro/package.json
index 91c59100d..76e67fb92 100644
--- a/packages/astro/package.json
+++ b/packages/astro/package.json
@@ -23,6 +23,9 @@
       ],
       "middleware": [
         "./dist/core/middleware/index.d.ts"
+      ],
+      "middleware/namespace": [
+        "./dist/core/middleware/namespace.d.ts"
       ]
     }
   },
@@ -70,6 +73,10 @@
       "types": "./dist/core/middleware/index.d.ts",
       "default": "./dist/core/middleware/index.js"
     },
+    "./middleware/namespace": {
+      "types": "./dist/core/middleware/namespace.d.ts",
+      "default": "./dist/core/middleware/namespace.js"
+    },
     "./transitions": "./dist/transitions/index.js"
   },
   "imports": {
diff --git a/packages/astro/src/@types/astro.ts b/packages/astro/src/@types/astro.ts
index f9568d417..0449b89d4 100644
--- a/packages/astro/src/@types/astro.ts
+++ b/packages/astro/src/@types/astro.ts
@@ -1920,7 +1920,7 @@ export interface APIContext<Props extends Record<string, any> = Record<string, a
 	 *
 	 * ```ts
 	 * // src/middleware.ts
-	 * import {defineMiddleware} from "astro/middleware";
+	 * import {defineMiddleware} from "astro:middleware";
 	 *
 	 * export const onRequest = defineMiddleware((context, next) => {
 	 *   context.locals.greeting = "Hello!";
diff --git a/packages/astro/src/core/create-vite.ts b/packages/astro/src/core/create-vite.ts
index 5b2ebfa21..f4938d2eb 100644
--- a/packages/astro/src/core/create-vite.ts
+++ b/packages/astro/src/core/create-vite.ts
@@ -170,6 +170,14 @@ export async function createVite(
 					find: /^astro$/,
 					replacement: fileURLToPath(new URL('../@types/astro', import.meta.url)),
 				},
+				{
+					find: 'astro:middleware',
+					replacement: 'astro/middleware/namespace',
+				},
+				{
+					find: 'astro:components',
+					replacement: 'astro/components',
+				},
 			],
 			conditions: ['astro'],
 			// Astro imports in third-party packages should use the same version as root
diff --git a/packages/astro/src/core/errors/errors-data.ts b/packages/astro/src/core/errors/errors-data.ts
index c717a2b03..9bac01519 100644
--- a/packages/astro/src/core/errors/errors-data.ts
+++ b/packages/astro/src/core/errors/errors-data.ts
@@ -658,7 +658,7 @@ export const ResponseSentError = {
  *
  * For example:
  * ```ts
- * import {defineMiddleware} from "astro/middleware";
+ * import {defineMiddleware} from "astro:middleware";
  * export const onRequest = defineMiddleware((context, _) => {
  * 	// doesn't return anything or call `next`
  * 	context.locals.someData = false;
@@ -678,7 +678,7 @@ export const MiddlewareNoDataOrNextCalled = {
  *
  * For example:
  * ```ts
- * import {defineMiddleware} from "astro/middleware";
+ * import {defineMiddleware} from "astro:middleware";
  * export const onRequest = defineMiddleware(() => {
  *   return "string"
  * });
@@ -698,7 +698,7 @@ export const MiddlewareNotAResponse = {
  *
  * For example:
  * ```ts
- * import {defineMiddleware} from "astro/middleware";
+ * import {defineMiddleware} from "astro:middleware";
  * export const onRequest = defineMiddleware((context, next) => {
  *   context.locals = 1541;
  *   return next();
diff --git a/packages/astro/src/core/middleware/namespace.ts b/packages/astro/src/core/middleware/namespace.ts
new file mode 100644
index 000000000..e504f866c
--- /dev/null
+++ b/packages/astro/src/core/middleware/namespace.ts
@@ -0,0 +1,4 @@
+export {
+	defineMiddleware,
+	sequence,
+} from './index.js';
diff --git a/packages/astro/test/fixtures/astro-component-code/src/pages/basic.astro b/packages/astro/test/fixtures/astro-component-code/src/pages/basic.astro
index 9fba8620a..ddbd92fed 100644
--- a/packages/astro/test/fixtures/astro-component-code/src/pages/basic.astro
+++ b/packages/astro/test/fixtures/astro-component-code/src/pages/basic.astro
@@ -1,5 +1,5 @@
 ---
-import {Code} from 'astro/components';
+import {Code} from 'astro:components';
 ---
 <html>
 <head><title>Code component</title></head>
diff --git a/packages/astro/test/fixtures/astro-component-code/src/pages/css-theme.astro b/packages/astro/test/fixtures/astro-component-code/src/pages/css-theme.astro
index 8a4a8debf..743423849 100644
--- a/packages/astro/test/fixtures/astro-component-code/src/pages/css-theme.astro
+++ b/packages/astro/test/fixtures/astro-component-code/src/pages/css-theme.astro
@@ -1,5 +1,5 @@
 ---
-import {Code} from 'astro/components';
+import {Code} from 'astro:components';
 ---
 <html>
 <head><title>Code component</title></head>
diff --git a/packages/astro/test/fixtures/astro-component-code/src/pages/custom-theme.astro b/packages/astro/test/fixtures/astro-component-code/src/pages/custom-theme.astro
index 80cafe5cc..45e92dccf 100644
--- a/packages/astro/test/fixtures/astro-component-code/src/pages/custom-theme.astro
+++ b/packages/astro/test/fixtures/astro-component-code/src/pages/custom-theme.astro
@@ -1,5 +1,5 @@
 ---
-import {Code} from 'astro/components';
+import {Code} from 'astro:components';
 ---
 <html>
 <head><title>Code component</title></head>
diff --git a/packages/astro/test/fixtures/astro-component-code/src/pages/imported.astro b/packages/astro/test/fixtures/astro-component-code/src/pages/imported.astro
index 02e6b4b03..6ea6782d6 100644
--- a/packages/astro/test/fixtures/astro-component-code/src/pages/imported.astro
+++ b/packages/astro/test/fixtures/astro-component-code/src/pages/imported.astro
@@ -1,5 +1,5 @@
 ---
-import {Code} from 'astro/components';
+import {Code} from 'astro:components';
 import riGrammar from '../assets/ri.tmLanguage.json'
 import serendipity from '../assets/serendipity-morning.json'
 
diff --git a/packages/astro/test/fixtures/astro-component-code/src/pages/inline.astro b/packages/astro/test/fixtures/astro-component-code/src/pages/inline.astro
index 05422c8bf..10c17f4e2 100644
--- a/packages/astro/test/fixtures/astro-component-code/src/pages/inline.astro
+++ b/packages/astro/test/fixtures/astro-component-code/src/pages/inline.astro
@@ -1,5 +1,5 @@
 ---
-import {Code} from 'astro/components';
+import {Code} from 'astro:components';
 ---
 <html>
 <head><title>Code component</title></head>
diff --git a/packages/astro/test/fixtures/astro-component-code/src/pages/no-lang.astro b/packages/astro/test/fixtures/astro-component-code/src/pages/no-lang.astro
index ebc1b0810..d0ae5f95f 100644
--- a/packages/astro/test/fixtures/astro-component-code/src/pages/no-lang.astro
+++ b/packages/astro/test/fixtures/astro-component-code/src/pages/no-lang.astro
@@ -1,5 +1,5 @@
 ---
-import {Code} from 'astro/components';
+import {Code} from 'astro:components';
 ---
 <html>
 <head><title>Code component</title></head>
diff --git a/packages/astro/test/fixtures/astro-component-code/src/pages/wrap-false.astro b/packages/astro/test/fixtures/astro-component-code/src/pages/wrap-false.astro
index ca1e238c7..aa4a58707 100644
--- a/packages/astro/test/fixtures/astro-component-code/src/pages/wrap-false.astro
+++ b/packages/astro/test/fixtures/astro-component-code/src/pages/wrap-false.astro
@@ -1,5 +1,5 @@
 ---
-import {Code} from 'astro/components';
+import {Code} from 'astro:components';
 ---
 <html>
 <head><title>Code component</title></head>
diff --git a/packages/astro/test/fixtures/astro-component-code/src/pages/wrap-null.astro b/packages/astro/test/fixtures/astro-component-code/src/pages/wrap-null.astro
index cff0190e8..f72e093dd 100644
--- a/packages/astro/test/fixtures/astro-component-code/src/pages/wrap-null.astro
+++ b/packages/astro/test/fixtures/astro-component-code/src/pages/wrap-null.astro
@@ -1,5 +1,5 @@
 ---
-import {Code} from 'astro/components';
+import {Code} from 'astro:components';
 ---
 <html>
 <head><title>Code component</title></head>
diff --git a/packages/astro/test/fixtures/astro-component-code/src/pages/wrap-true.astro b/packages/astro/test/fixtures/astro-component-code/src/pages/wrap-true.astro
index 82e8f65c2..43ccb5452 100644
--- a/packages/astro/test/fixtures/astro-component-code/src/pages/wrap-true.astro
+++ b/packages/astro/test/fixtures/astro-component-code/src/pages/wrap-true.astro
@@ -1,5 +1,5 @@
 ---
-import {Code} from 'astro/components';
+import {Code} from 'astro:components';
 ---
 <html>
 <head><title>Code component</title></head>
diff --git a/packages/astro/test/fixtures/code-component/src/pages/index.astro b/packages/astro/test/fixtures/code-component/src/pages/index.astro
index 763f32cae..d165a4308 100644
--- a/packages/astro/test/fixtures/code-component/src/pages/index.astro
+++ b/packages/astro/test/fixtures/code-component/src/pages/index.astro
@@ -1,5 +1,5 @@
 ---
-import { Code } from 'astro/components';
+import { Code } from 'astro:components';
 ---
 <html>
 	<head>
diff --git a/packages/astro/test/fixtures/middleware-dev/src/middleware.js b/packages/astro/test/fixtures/middleware-dev/src/middleware.js
index 2f9fc08b9..854c997c1 100644
--- a/packages/astro/test/fixtures/middleware-dev/src/middleware.js
+++ b/packages/astro/test/fixtures/middleware-dev/src/middleware.js
@@ -1,4 +1,4 @@
-import { sequence, defineMiddleware } from 'astro/middleware';
+import { sequence, defineMiddleware } from 'astro:middleware';
 
 const first = defineMiddleware(async (context, next) => {
 	if (context.request.url.includes('/lorem')) {
diff --git a/packages/astro/test/fixtures/middleware-ssg/src/middleware.js b/packages/astro/test/fixtures/middleware-ssg/src/middleware.js
index f28d89f67..04c0bfb3a 100644
--- a/packages/astro/test/fixtures/middleware-ssg/src/middleware.js
+++ b/packages/astro/test/fixtures/middleware-ssg/src/middleware.js
@@ -1,4 +1,4 @@
-import { sequence, defineMiddleware } from 'astro/middleware';
+import { sequence, defineMiddleware } from 'astro:middleware';
 
 const first = defineMiddleware(async (context, next) => {
 	if (context.request.url.includes('/second')) {
diff --git a/packages/astro/test/fixtures/ssr-redirect/src/middleware.ts b/packages/astro/test/fixtures/ssr-redirect/src/middleware.ts
index a8de8d130..57ce55678 100644
--- a/packages/astro/test/fixtures/ssr-redirect/src/middleware.ts
+++ b/packages/astro/test/fixtures/ssr-redirect/src/middleware.ts
@@ -1,4 +1,4 @@
-import { defineMiddleware } from 'astro/middleware';
+import { defineMiddleware } from 'astro:middleware';
 
 export const onRequest = defineMiddleware(({ request }, next) => {
 	if(new URL(request.url).pathname === '/middleware-redirect/') {
diff --git a/packages/astro/test/fixtures/static-build-code-component/src/pages/index.astro b/packages/astro/test/fixtures/static-build-code-component/src/pages/index.astro
index e2f564a3b..c87ed5b08 100644
--- a/packages/astro/test/fixtures/static-build-code-component/src/pages/index.astro
+++ b/packages/astro/test/fixtures/static-build-code-component/src/pages/index.astro
@@ -1,5 +1,5 @@
 ---
-import {Code} from 'astro/components';
+import {Code} from 'astro:components';
 ---
 <html>
 <head><title>Testing</title></head>
diff --git a/packages/astro/test/fixtures/static-build-dir/src/pages/index.astro b/packages/astro/test/fixtures/static-build-dir/src/pages/index.astro
index e2f564a3b..c87ed5b08 100644
--- a/packages/astro/test/fixtures/static-build-dir/src/pages/index.astro
+++ b/packages/astro/test/fixtures/static-build-dir/src/pages/index.astro
@@ -1,5 +1,5 @@
 ---
-import {Code} from 'astro/components';
+import {Code} from 'astro:components';
 ---
 <html>
 <head><title>Testing</title></head>