feat: add injectDevRoute utility

.changeset/large-cycles-boil.md

@@ -0,0 +1,5 @@
+---
+"astro-integration-kit": minor
+---
+
+Adds a new utility, `injectDevRoute`

docs/astro.config.ts

@@ -119,6 +119,10 @@ export default defineConfig({
 							label: "hasIntegration",
 							link: "/utilities/has-integration/",
 						},
+						{
+							label: "injectDevRoute",
+							link: "/utilities/inject-dev-route/",
+						},
 						{
 							label: "watchIntegration (HMR)",
 							link: "/utilities/watch-integration/",

docs/src/content/docs/utilities/add-dts.mdx

@@ -32,7 +32,7 @@ create a file inside `.astro` and reference it from `src/env.d.ts`. For example:
     <TabItem label="Standalone utilities">
     ```ts title="integration/index.ts" "addDts"
     import type { AstroIntegration } from "astro";
-    import { addDts } from "astro-integration-kit";
+    import { addDts } from "astro-integration-kit/utilities";
 
     export default function myIntegration(): AstroIntegration {
         return {

docs/src/content/docs/utilities/add-virtual-import.mdx

@@ -31,7 +31,7 @@ import { Tabs, TabItem } from '@astrojs/starlight/components';
     <TabItem label="Standalone utilities">
     ```ts title="integration/index.ts" "addVirtualImport"
     import type { AstroIntegration } from "astro";
-    import { addVirtualImport } from "astro-integration-kit";
+    import { addVirtualImport } from "astro-integration-kit/utilities";
 
     export default function myIntegration(): AstroIntegration {
         return {

docs/src/content/docs/utilities/add-vite-plugin.mdx

@@ -30,7 +30,7 @@ to the Astro config. For example:
     <TabItem label="Standalone utilities">
     ```ts title="integration/index.ts" "addVitePlugin"
     import type { AstroIntegration } from "astro";
-    import { addVitePlugin } from "astro-integration-kit";
+    import { addVitePlugin } from "astro-integration-kit/utilities";
     import { VitePWA } from 'vite-plugin-pwa'
 
     export default function myIntegration(): AstroIntegration {

docs/src/content/docs/utilities/has-integration.mdx

@@ -30,7 +30,7 @@ import { Tabs, TabItem } from '@astrojs/starlight/components';
 	<TabItem label="Standalone utilities">
 	```ts title="my-integration/index.ts" "hasIntegration"
 	import type { AstroIntegration } from "astro";
-	import { hasIntegration } from "astro-integration-kit";
+	import { hasIntegration } from "astro-integration-kit/utilities";
 
 	export default function myIntegration(): AstroIntegration {
 		return {

docs/src/content/docs/utilities/inject-dev-route.mdx

@@ -0,0 +1,60 @@
+---
+title: injectDevRoute
+description: Allows to inject a route in development only.
+---
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+`injectDevRoute` allows to inject a route in development only. For example:
+
+<Tabs>
+    <TabItem label="Extended hooks">
+	```ts title="my-integration/index.ts" /injectDevRoute\\b/ {2,6}
+	import { createResolver, defineIntegration } from "astro-integration-kit";
+	import { injectDevRoutePlugin } from "astro-integration-kit/plugins";
+
+	export default defineIntegration({
+		name: "my-integration",
+		plugins: [injectDevRoutePlugin],
+		setup() {
+			const { resolve } = createResolver(import.meta.url);
+
+			return {
+				"astro:config:setup": ({ injectDevRoute }) => {
+					injectDevRoute({
+						pattern: "/foo",
+						entrypoint: resolve("./pages/foo.astro")
+					})
+				}
+			}
+		}
+	})
+	```
+	</TabItem>
+	<TabItem label="Standalone utilities">
+	```ts title="integration/index.ts" "watchIntegration"
+	import type { AstroIntegration } from "astro";
+	import { createResolver } from "astro-integration-kit";
+	import { injectDevRoute } from "astro-integration-kit/utilities";
+
+	export default function myIntegration(): AstroIntegration {
+		const { resolve } = createResolver(import.meta.url);
+
+		return {
+			name: "my-integration",
+			hooks: {
+				"astro:config:setup": ({ command, injectRoute }) => {
+					injectDevRoute({
+						command,
+						injectRoute,
+						injectedRoute: {
+							pattern: "/foo",
+							entrypoint: resolve("./pages/foo.astro")
+						},
+					})
+				},
+			}
+		}
+	}
+	``` 
+	</TabItem>
+</Tabs>

docs/src/content/docs/utilities/watch-integration.mdx

@@ -31,7 +31,8 @@ the integration directory has changed. For example:
 	<TabItem label="Standalone utilities">
 	```ts title="integration/index.ts" "watchIntegration"
 	import type { AstroIntegration } from "astro";
-	import { createResolver, watchIntegration } from "astro-integration-kit";
+	import { createResolver } from "astro-integration-kit";
+	import { watchIntegration } from "astro-integration-kit/utilities";
 
 	export default function myIntegration(): AstroIntegration {
 		const { resolve } = createResolver(import.meta.url);

package/src/core/define-integration.ts

@@ -45,7 +45,10 @@ export const defineIntegration = <
 	}) => ExtendedHooks<TPlugins>;
 }): ((options?: z.input<TOptionsSchema>) => AstroIntegration) => {
 	return (_options: z.input<TOptionsSchema> = {}) => {
-		const parsedOptions = (optionsSchema || z.record(z.any())).safeParse(_options, { errorMap });
+		const parsedOptions = (optionsSchema || z.record(z.any())).safeParse(
+			_options,
+			{ errorMap },
+		);
 
 		if (!parsedOptions.success) {
 			throw new AstroError(

package/src/plugins/index.ts

@@ -2,13 +2,15 @@ import { addDtsPlugin } from "./add-dts.js";
 import { addVirtualImportPlugin } from "./add-virtual-import.js";
 import { addVitePluginPlugin } from "./add-vite-plugin.js";
 import { hasIntegrationPlugin } from "./has-integration.js";
+import { injectDevRoutePlugin } from "./inject-dev-route.js";
 import { watchIntegrationPlugin } from "./watch-integration.js";
 
 export const corePlugins = [
 	addDtsPlugin,
 	addVirtualImportPlugin,
 	addVitePluginPlugin,
 	hasIntegrationPlugin,
+	injectDevRoutePlugin,
 	watchIntegrationPlugin,
 ] as const;
 
@@ -17,5 +19,6 @@ export {
 	addVirtualImportPlugin,
 	addVitePluginPlugin,
 	hasIntegrationPlugin,
+	injectDevRoutePlugin,
 	watchIntegrationPlugin,
 };

package/src/plugins/inject-dev-route.ts

@@ -0,0 +1,11 @@
+import { definePlugin } from "../core/define-plugin.js";
+import { injectDevRoute } from "../utilities/inject-dev-route.js";
+
+export const injectDevRoutePlugin = definePlugin({
+	name: "injectDevRoute",
+	hook: "astro:config:setup",
+	implementation:
+		({ command, injectRoute }) =>
+		(injectedRoute: Parameters<typeof injectDevRoute>[0]["injectedRoute"]) =>
+			injectDevRoute({ command, injectRoute, injectedRoute }),
+});

package/src/utilities/index.ts

@@ -2,4 +2,5 @@ export { addDts } from "./add-dts.js";
 export { addVirtualImport } from "./add-virtual-import.js";
 export { addVitePlugin } from "./add-vite-plugin.js";
 export { hasIntegration } from "./has-integration.js";
+export { injectDevRoute } from "./inject-dev-route.js";
 export { watchIntegration } from "./watch-integration.js";

package/src/utilities/inject-dev-route.ts

@@ -0,0 +1,35 @@
+import type { HookParameters, InjectedRoute } from "astro";
+
+/**
+ * Allows to inject a route in development only
+ *
+ * @param {object} params
+ * @param {import("astro").HookParameters<"astro:config:setup">["command"]} params.command
+ * @param {import("astro").HookParameters<"astro:config:setup">["injectRoute"]} params.injectRoute
+ * @param {import("astro").InjectedRoute} params.injectedRoute
+ *
+ * @example
+ * ```ts
+ * injectDevRoute({
+ *      command,
+ *      injectRoute,
+ *      injectedRoute: {
+ *          pattern: "/foo",
+ *          entrypoint: resolve("./pages/foo.astro")
+ *      },
+ * })
+ * ```
+ *
+ * @see https://astro-integration-kit.netlify.app/utilities/inject-dev-route/
+ */
+export const injectDevRoute = ({
+	command,
+	injectRoute,
+	injectedRoute,
+}: Pick<HookParameters<"astro:config:setup">, "command" | "injectRoute"> & {
+	injectedRoute: InjectedRoute;
+}) => {
+	if (command === "dev") {
+		injectRoute(injectedRoute);
+	}
+};