From 9f697f39e6168a774771927c239d1b15a4cf5a96 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Tue, 28 Jan 2025 19:21:58 +0100 Subject: [PATCH 01/34] fix: update addDevToolbarApp type The `string` type was definitely removed in withastro/astro#11987. Other pages was up-to-date but not the integrations reference. --- .../docs/en/reference/integrations-reference.mdx | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index c12e52fce394b..8373c06318994 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -33,7 +33,7 @@ interface AstroIntegration { addWatchFile: (path: URL | string) => void; addClientDirective: (directive: ClientDirectiveConfig) => void; addMiddleware: (middleware: AstroIntegrationMiddleware) => void; - addDevToolbarApp: (pluginEntrypoint: string) => void; + addDevToolbarApp: (entrypoint: DevToolbarAppEntry) => void; injectScript: (stage: InjectedScriptStage, content: string) => void; injectRoute: (injectedRoute: { pattern: string; entrypoint: string; prerender?: boolean }) => void; createCodegenDir: () => URL; @@ -103,7 +103,7 @@ The following hooks are built in to Astro: addRenderer: (renderer: AstroRenderer) => void; addClientDirective: (directive: ClientDirectiveConfig) => void; addMiddleware: (middleware: AstroIntegrationMiddleware) => void; - addDevToolbarApp: (pluginEntrypoint: string) => void; + addDevToolbarApp: (entrypoint: DevToolbarAppEntry) => void; addWatchFile: (path: URL | string) => void; injectScript: (stage: InjectedScriptStage, content: string) => void; injectRoute: (injectedRoute: { pattern: string; entrypoint: string; prerender?: boolean }) => void; @@ -255,7 +255,7 @@ declare module 'astro' {

-**Type:** `(pluginEntrypoint: string) => void;` +**Type:** `(entrypoint: DevToolbarAppEntry) => void;` Adds a [custom dev toolbar app](/en/reference/dev-toolbar-app-reference/). @@ -281,7 +281,11 @@ export default () => ({ name: "dev-toolbar-app", hooks: { "astro:config:setup": ({ addDevToolbarApp }) => { - addDevToolbarApp("./astro-dev-toolbar-app/plugin.js"); + addDevToolbarApp({ + entrypoint: "./astro-dev-toolbar-app/plugin.js", + id: "my-plugin", + name: "My Plugin" + }); }, }, }); From 94490baf76f5a4fa8446d50f1ead1a8d0b90049e Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Tue, 28 Jan 2025 19:24:55 +0100 Subject: [PATCH 02/34] fix: mismatch between paths in addDevToolbarApp code snippets --- src/content/docs/en/guides/upgrade-to/v5.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/upgrade-to/v5.mdx b/src/content/docs/en/guides/upgrade-to/v5.mdx index b73305552be6c..8ce843e6df9d7 100644 --- a/src/content/docs/en/guides/upgrade-to/v5.mdx +++ b/src/content/docs/en/guides/upgrade-to/v5.mdx @@ -1140,14 +1140,14 @@ If you were using the deprecated shape, update your dev toolbar app to use the n ```js title="my-integration.mjs" del={1-2} ins={4-10} // Old shape -addDevToolbarApp("./my-app.js"); +addDevToolbarApp("./my-dev-toolbar-app.mjs"); // New shape addDevToolbarApp({ id: "my-app", name: "My App", icon: "...", - entrypoint: "./my-app.js", + entrypoint: "./my-dev-toolbar-app.mjs", }); ``` From 0b02aed3df1d3b442adbbe1c2a293eb01c2d15f5 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Tue, 28 Jan 2025 19:28:43 +0100 Subject: [PATCH 03/34] consistency: injectRoute and injectTypes was the only objects expanded In overview of the functions available, `injectRoute` and `InjectedType` was the only ones expanded. It might be better to be consistent with the others and since `InjectedRoute` and `InjectedType` can be imported, it could be nice to show the types there. --- src/content/docs/en/reference/integrations-reference.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 8373c06318994..8bd2f4bcf31d6 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -35,7 +35,7 @@ interface AstroIntegration { addMiddleware: (middleware: AstroIntegrationMiddleware) => void; addDevToolbarApp: (entrypoint: DevToolbarAppEntry) => void; injectScript: (stage: InjectedScriptStage, content: string) => void; - injectRoute: (injectedRoute: { pattern: string; entrypoint: string; prerender?: boolean }) => void; + injectRoute: (injectedRoute: InjectedRoute) => void; createCodegenDir: () => URL; logger: AstroIntegrationLogger; }) => void | Promise; @@ -46,7 +46,7 @@ interface AstroIntegration { 'astro:config:done'?: (options: { config: AstroConfig; setAdapter: (adapter: AstroAdapter) => void; - injectTypes: (injectedType: { filename: string; content: string }) => URL; + injectTypes: (injectedType: InjectedType) => URL; logger: AstroIntegrationLogger; }) => void | Promise; 'astro:route:setup'?: (options: { route: RouteOptions; logger: AstroIntegrationLogger; }) => void | Promise; @@ -106,7 +106,7 @@ The following hooks are built in to Astro: addDevToolbarApp: (entrypoint: DevToolbarAppEntry) => void; addWatchFile: (path: URL | string) => void; injectScript: (stage: InjectedScriptStage, content: string) => void; - injectRoute: (injectedRoute: { pattern: string; entrypoint: string; prerender?: boolean }) => void; + injectRoute: (injectedRoute: InjectedRoute) => void; createCodegenDir: () => URL; logger: AstroIntegrationLogger; }) => void | Promise; @@ -626,7 +626,7 @@ interface IntegrationResolvedRoute { 'astro:config:done'?: (options: { config: AstroConfig; setAdapter: (adapter: AstroAdapter) => void; - injectTypes: (injectedType: { filename: string; content: string }) => URL; + injectTypes: (injectedType: InjectedType) => URL; logger: AstroIntegrationLogger; }) => void | Promise; ``` From edfcc7ef247630b4a1bd6f3ed43fa6e330a7ea0a Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Tue, 28 Jan 2025 19:33:07 +0100 Subject: [PATCH 04/34] move `astro:routes:resolved` to keep related hooks together --- src/content/docs/en/reference/integrations-reference.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 8bd2f4bcf31d6..fcd2197e0f8c5 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -39,10 +39,6 @@ interface AstroIntegration { createCodegenDir: () => URL; logger: AstroIntegrationLogger; }) => void | Promise; - 'astro:routes:resolved'?: (options: { - routes: IntegrationResolvedRoute[]; - logger: AstroIntegrationLogger; - }) => void | Promise; 'astro:config:done'?: (options: { config: AstroConfig; setAdapter: (adapter: AstroAdapter) => void; @@ -50,6 +46,10 @@ interface AstroIntegration { logger: AstroIntegrationLogger; }) => void | Promise; 'astro:route:setup'?: (options: { route: RouteOptions; logger: AstroIntegrationLogger; }) => void | Promise; + 'astro:routes:resolved'?: (options: { + routes: IntegrationResolvedRoute[]; + logger: AstroIntegrationLogger; + }) => void | Promise; 'astro:server:setup'?: (options: { server: vite.ViteDevServer; logger: AstroIntegrationLogger; }) => void | Promise; 'astro:server:start'?: (options: { address: AddressInfo; logger: AstroIntegrationLogger; }) => void | Promise; 'astro:server:done'?: (options: { logger: AstroIntegrationLogger; }) => void | Promise; From 04771cc9f0aa7114a349d9486efa2ff187257651 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Tue, 28 Jan 2025 21:31:51 +0100 Subject: [PATCH 05/34] add missing `buildOutput` option in `astro:config:done` It was added in withastro/astro#11824 so it seems to be since v5. --- .../docs/en/reference/integrations-reference.mdx | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index fcd2197e0f8c5..a27441661fdef 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -44,6 +44,7 @@ interface AstroIntegration { setAdapter: (adapter: AstroAdapter) => void; injectTypes: (injectedType: InjectedType) => URL; logger: AstroIntegrationLogger; + buildOutput: 'static' | 'server'; }) => void | Promise; 'astro:route:setup'?: (options: { route: RouteOptions; logger: AstroIntegrationLogger; }) => void | Promise; 'astro:routes:resolved'?: (options: { @@ -628,6 +629,7 @@ interface IntegrationResolvedRoute { setAdapter: (adapter: AstroAdapter) => void; injectTypes: (injectedType: InjectedType) => URL; logger: AstroIntegrationLogger; + buildOutput: 'static' | 'server'; }) => void | Promise; ``` @@ -643,7 +645,7 @@ A read-only copy of the user-supplied [Astro config](/en/reference/configuration Makes the integration an adapter. Read more in the [adapter API](/en/reference/adapter-reference/). -#### `injectTypes` options +#### `injectTypes` option

@@ -665,6 +667,16 @@ const path = injectTypes({ console.log(path) // URL ``` +#### `buildOutput` option + +

+ +**Type:** `'static' | 'server'`
+ +

+ +Allows you to adapt the logic of your integration depending on the user's project output. + ### `astro:server:setup` **Previous hook:** [`astro:config:done`](#astroconfigdone) From f8eaa5ac1509416bef3d21761f49c5d78cace64a Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Tue, 28 Jan 2025 22:06:34 +0100 Subject: [PATCH 06/34] add missing `toolbar` option in `astro:server:setup` It seems it was added in withastro/astro#7821 so in v4.7.0. --- .../en/reference/integrations-reference.mdx | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index a27441661fdef..eef963dd9c1e3 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -51,7 +51,11 @@ interface AstroIntegration { routes: IntegrationResolvedRoute[]; logger: AstroIntegrationLogger; }) => void | Promise; - 'astro:server:setup'?: (options: { server: vite.ViteDevServer; logger: AstroIntegrationLogger; }) => void | Promise; + 'astro:server:setup'?: (options: { + server: vite.ViteDevServer; + logger: AstroIntegrationLogger; + toolbar: ReturnType; + }) => void | Promise; 'astro:server:start'?: (options: { address: AddressInfo; logger: AstroIntegrationLogger; }) => void | Promise; 'astro:server:done'?: (options: { logger: AstroIntegrationLogger; }) => void | Promise; 'astro:build:start'?: (options: { logger: AstroIntegrationLogger; }) => void | Promise; @@ -690,6 +694,7 @@ Allows you to adapt the logic of your integration depending on the user's projec ```js 'astro:server:setup'?: (options: { server: vite.ViteDevServer; + toolbar: ReturnType; refreshContent: (options: { loaders?: Array; context?: Record; @@ -717,6 +722,16 @@ export default { } ``` +#### `toolbar` option + +

+ +**Type:** `ReturnType`
+ +

+ +Allows you to interact with the toolbar when the Astro's server is set up. + #### `refreshContent` option

@@ -769,7 +784,6 @@ You can also pass a `context` object to the loaders. This can be used to pass ar The loader can then access the `refreshContextData` property to get the webhook body. See the [`refreshContextData`](/en/reference/content-loader-reference/#refreshcontextdata) property for more information. - ### `astro:server:start` **Previous hook:** [`astro:server:setup`](#astroserversetup) From d236dfb7f9f45bb1cfb8709fc2029e703fb83c6e Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Tue, 28 Jan 2025 22:10:52 +0100 Subject: [PATCH 07/34] add missing `refreshContent` option in Quick API Reference --- src/content/docs/en/reference/integrations-reference.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index eef963dd9c1e3..b451427748a33 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -55,6 +55,7 @@ interface AstroIntegration { server: vite.ViteDevServer; logger: AstroIntegrationLogger; toolbar: ReturnType; + refreshContent?: (options: RefreshContentOptions) => Promise; }) => void | Promise; 'astro:server:start'?: (options: { address: AddressInfo; logger: AstroIntegrationLogger; }) => void | Promise; 'astro:server:done'?: (options: { logger: AstroIntegrationLogger; }) => void | Promise; From d24cbd553f1f047dae2d35c4a9c1e5be9b4d5442 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Tue, 28 Jan 2025 22:12:21 +0100 Subject: [PATCH 08/34] add missing logger in `astro:server:setup` type overview --- src/content/docs/en/reference/integrations-reference.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index b451427748a33..cd83b7cf905c0 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -695,6 +695,7 @@ Allows you to adapt the logic of your integration depending on the user's projec ```js 'astro:server:setup'?: (options: { server: vite.ViteDevServer; + logger: AstroIntegrationLogger; toolbar: ReturnType; refreshContent: (options: { loaders?: Array; From 22f515a5b7a689dabb6258f842fc46e29fff2c40 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Tue, 28 Jan 2025 22:17:43 +0100 Subject: [PATCH 09/34] add missing `middlewareEntryPoint` in `astro:build:ssr` The other options of this hooks are not documented so I just added the option in the Quick API Reference and fixed the type in the `astro:build:ssr` type overview. --- src/content/docs/en/reference/integrations-reference.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index cd83b7cf905c0..5084e12270962 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -71,6 +71,7 @@ interface AstroIntegration { 'astro:build:ssr'?: (options: { manifest: SerializedSSRManifest; entryPoints: Map; + middlewareEntryPoint: URL | undefined; logger: AstroIntegrationLogger; }) => void | Promise; 'astro:build:done'?: (options: { @@ -879,7 +880,7 @@ The address, family and port number supplied by the [Node.js Net module](https:/ 'astro:build:ssr'?: (options: { manifest: SerializedSSRManifest, entryPoints: Map, - middlewareEntryPoint: URL + middlewareEntryPoint: URL | undefined; }) => void | Promise; ``` From 60fb911a71be7f2e1a7e08090fa30f05c783d70b Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Tue, 28 Jan 2025 22:29:14 +0100 Subject: [PATCH 10/34] add missing `pages` option in `astro:build:done` --- .../docs/en/reference/integrations-reference.mdx | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 5084e12270962..7c7f8d97aa515 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -75,6 +75,7 @@ interface AstroIntegration { logger: AstroIntegrationLogger; }) => void | Promise; 'astro:build:done'?: (options: { + pages: { pathname: string }[]; dir: URL; /** @deprecated Use the `assets` map and the new `astro:routes:resolved` hook */ routes: IntegrationRouteData[]; @@ -894,6 +895,7 @@ The address, family and port number supplied by the [Node.js Net module](https:/ ```js 'astro:build:done'?: (options: { + pages: { pathname: string }[]; dir: URL; /** @deprecated Use the `assets` map and the new `astro:routes:resolved` hook */ routes: IntegrationRouteData[]; @@ -902,6 +904,15 @@ The address, family and port number supplied by the [Node.js Net module](https:/ }) => void | Promise; ``` +#### `pages` options + +

+ +**Type:** `{pathname: string}[]` +

+ +{/* Not sure about this one yet... There was a plan to remove it because undocumented but the PR was closed. Implemented in withastro/astro#2820 */} + #### `dir` option **Type:** [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) From 62e6de2bd4bd31ade4dc744835fb70d2864dd643 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Wed, 29 Jan 2025 12:21:17 +0100 Subject: [PATCH 11/34] consistent types preview (indent, options list, options on new line) --- .../en/reference/integrations-reference.mdx | 69 +++++++++++++------ 1 file changed, 48 insertions(+), 21 deletions(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 7c7f8d97aa515..7b6a860ff6846 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -39,17 +39,16 @@ interface AstroIntegration { createCodegenDir: () => URL; logger: AstroIntegrationLogger; }) => void | Promise; + 'astro:routes:resolved'?: (options: { + routes: IntegrationResolvedRoute[]; + logger: AstroIntegrationLogger; + }) => void | Promise; 'astro:config:done'?: (options: { config: AstroConfig; setAdapter: (adapter: AstroAdapter) => void; injectTypes: (injectedType: InjectedType) => URL; logger: AstroIntegrationLogger; buildOutput: 'static' | 'server'; - }) => void | Promise; - 'astro:route:setup'?: (options: { route: RouteOptions; logger: AstroIntegrationLogger; }) => void | Promise; - 'astro:routes:resolved'?: (options: { - routes: IntegrationResolvedRoute[]; - logger: AstroIntegrationLogger; }) => void | Promise; 'astro:server:setup'?: (options: { server: vite.ViteDevServer; @@ -57,9 +56,16 @@ interface AstroIntegration { toolbar: ReturnType; refreshContent?: (options: RefreshContentOptions) => Promise; }) => void | Promise; - 'astro:server:start'?: (options: { address: AddressInfo; logger: AstroIntegrationLogger; }) => void | Promise; - 'astro:server:done'?: (options: { logger: AstroIntegrationLogger; }) => void | Promise; - 'astro:build:start'?: (options: { logger: AstroIntegrationLogger; }) => void | Promise; + 'astro:server:start'?: (options: { + address: AddressInfo; + logger: AstroIntegrationLogger; + }) => void | Promise; + 'astro:server:done'?: (options: { + logger: AstroIntegrationLogger; + }) => void | Promise; + 'astro:build:start'?: (options: { + logger: AstroIntegrationLogger; + }) => void | Promise; 'astro:build:setup'?: (options: { vite: vite.InlineConfig; pages: Map; @@ -67,12 +73,15 @@ interface AstroIntegration { updateConfig: (newConfig: vite.InlineConfig) => void; logger: AstroIntegrationLogger; }) => void | Promise; - 'astro:build:generated'?: (options: { dir: URL; logger: AstroIntegrationLogger; }) => void | Promise; + 'astro:build:generated'?: (options: { + dir: URL; + logger: AstroIntegrationLogger; + }) => void | Promise; 'astro:build:ssr'?: (options: { - manifest: SerializedSSRManifest; - entryPoints: Map; - middlewareEntryPoint: URL | undefined; - logger: AstroIntegrationLogger; + manifest: SerializedSSRManifest; + entryPoints: Map; + middlewareEntryPoint: URL | undefined; + logger: AstroIntegrationLogger; }) => void | Promise; 'astro:build:done'?: (options: { pages: { pathname: string }[]; @@ -82,6 +91,10 @@ interface AstroIntegration { assets: Map; logger: AstroIntegrationLogger; }) => void | Promise; + 'astro:route:setup'?: (options: { + route: RouteOptions; + logger: AstroIntegrationLogger; + }) => void | Promise; // ... any custom hooks from integrations }; @@ -799,7 +812,10 @@ The loader can then access the `refreshContextData` property to get the webhook **Why:** To intercept network requests at the specified address. If you intend to use this address for middleware, consider using `astro:server:setup` instead. ```js -'astro:server:start'?: (options: { address: AddressInfo }) => void | Promise; +'astro:server:start'?: (options: { + address: AddressInfo; + logger: AstroIntegrationLogger; +}) => void | Promise; ``` #### `address` option @@ -817,7 +833,9 @@ The address, family and port number supplied by the [Node.js Net module](https:/ **Why:** To run any cleanup events you may trigger during the `astro:server:setup` or `astro:server:start` hooks. ```js -'astro:server:done'?: () => void | Promise; +'astro:server:done'?: (options: { + logger: AstroIntegrationLogger; +}) => void | Promise; ``` ### `astro:build:start` @@ -831,7 +849,9 @@ The address, family and port number supplied by the [Node.js Net module](https:/ **Why:** To set up any global objects or clients needed during a production build. This can also extend the build configuration options in the [adapter API](/en/reference/adapter-reference/). ```js -'astro:build:start'?: () => void | Promise; +'astro:build:start'?: (options: { + logger: AstroIntegrationLogger; +}) => void | Promise; ``` ### `astro:build:setup` @@ -864,7 +884,10 @@ The address, family and port number supplied by the [Node.js Net module](https:/ **Why:** To access generated routes and assets **before** build artifacts are cleaned up. This is a very uncommon use case. We recommend using [`astro:build:done`](#astrobuilddone) unless you really need to access the generated files before cleanup. ```js -'astro:build:generated'?: (options: { dir: URL }) => void | Promise; +'astro:build:generated'?: (options: { + dir: URL; + logger: AstroIntegrationLogger; +}) => void | Promise; ``` ### `astro:build:ssr` @@ -879,9 +902,10 @@ The address, family and port number supplied by the [Node.js Net module](https:/ ```js 'astro:build:ssr'?: (options: { - manifest: SerializedSSRManifest, - entryPoints: Map, - middlewareEntryPoint: URL | undefined; + manifest: SerializedSSRManifest; + entryPoints: Map; + middlewareEntryPoint: URL | undefined; + logger: AstroIntegrationLogger; }) => void | Promise; ``` @@ -1046,7 +1070,10 @@ A list of all generated pages. It is an object with one property. **Why:** To set options for a route at build or request time, such as enabling [on-demand server rendering](/en/guides/on-demand-rendering/#enabling-on-demand-rendering). ```js -'astro:route:setup'?: (options: { route: RouteOptions }) => void | Promise; +'astro:route:setup'?: (options: { + route: RouteOptions; + logger: AstroIntegrationLogger; +}) => void | Promise; ``` #### `route` option From 95d82074b05aaf33fb1b91189b139dfd2f8aeaa8 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Wed, 29 Jan 2025 16:20:41 +0100 Subject: [PATCH 12/34] api references formatting --- .../en/reference/integrations-reference.mdx | 101 ++++++++++++++---- 1 file changed, 79 insertions(+), 22 deletions(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 7b6a860ff6846..7d1960d4602db 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -135,13 +135,19 @@ The following hooks are built in to Astro: #### `config` option +

+ **Type:** `AstroConfig` +

A read-only copy of the user-supplied [Astro config](/en/reference/configuration-reference/). This is resolved _before_ any other integrations have run. If you need a copy of the config after all integrations have completed their config updates, [see the `astro:config:done` hook](#astroconfigdone). #### `command` option +

+ **Type:** `'dev' | 'build' | 'preview' | 'sync'` +

- `dev` - Project is executed with `astro dev` - `build` - Project is executed with `astro build` @@ -150,13 +156,20 @@ A read-only copy of the user-supplied [Astro config](/en/reference/configuration #### `isRestart` option -**Type:** `boolean` +

+ +**Type:** `boolean`
+ +

`false` when the dev server starts, `true` when a reload is triggered. Useful to detect when this function is called more than once. #### `updateConfig` option +

+ **Type:** `(newConfig: DeepPartial) => AstroConfig;` +

A callback function to update the user-supplied [Astro config](/en/reference/configuration-reference/). Any config you provide **will be merged with the user config + other integration config updates,** so you are free to omit keys! @@ -181,8 +194,11 @@ export default { #### `addRenderer` option -**Type:** `(renderer:` [`AstroRenderer`](https://github.com/withastro/astro/blob/fdd607c5755034edf262e7b275732519328a33b2/packages/astro/src/%40types/astro.ts#L872-L883) `) => void;` +

+ +**Type:** `(renderer:` [`AstroRenderer`](https://github.com/withastro/astro/blob/fdd607c5755034edf262e7b275732519328a33b2/packages/astro/src/%40types/astro.ts#L872-L883) `) => void;`
**Examples:** [`svelte`](https://github.com/withastro/astro/blob/main/packages/integrations/svelte/src/index.ts), [`react`](https://github.com/withastro/astro/blob/main/packages/integrations/react/src/index.ts), [`preact`](https://github.com/withastro/astro/blob/main/packages/integrations/preact/src/index.ts), [`vue`](https://github.com/withastro/astro/blob/main/packages/integrations/vue/src/index.ts), [`solid`](https://github.com/withastro/astro/blob/main/packages/integrations/solid/src/index.ts) +

A callback function to add a component framework renderer (i.e. React, Vue, Svelte, etc). You can browse the examples and type definition above for more advanced options, but here are the 2 main options to be aware of: @@ -195,7 +211,11 @@ The functions `clientEntrypoint` and `serverEntrypoint` accept a `URL`. #### `addWatchFile` option -**Type:** `URL | string` +

+ +**Type:** `URL | string`
+ +

If your integration depends on some configuration file that Vite doesn't watch and/or needs a full dev server restart to take effect, add it with `addWatchFile`. Whenever that file changes, the Astro dev server will be reloaded (you can check when a reload happens with `isRestart`). @@ -209,9 +229,11 @@ addWatchFile(new URL('./tailwind.config.js', config.root)); #### `addClientDirective` option -

+

-**Type:** `(directive:` [`ClientDirectiveConfig`](https://github.com/withastro/astro/blob/00327c213f74627ac9ca1dec774efa5bf71e9375/packages/astro/src/%40types/astro.ts#L1872-L1875) `) => void;` +**Type:** `(directive:` [`ClientDirectiveConfig`](https://github.com/withastro/astro/blob/00327c213f74627ac9ca1dec774efa5bf71e9375/packages/astro/src/%40types/astro.ts#L1872-L1875) `) => void;`
+ +

Adds a [custom client directive](/en/reference/directives-reference/#custom-client-directives) to be used in `.astro` files. @@ -274,9 +296,11 @@ declare module 'astro' { #### `addDevToolbarApp` option -

+

-**Type:** `(entrypoint: DevToolbarAppEntry) => void;` +**Type:** `(entrypoint: DevToolbarAppEntry) => void;`
+ +

Adds a [custom dev toolbar app](/en/reference/dev-toolbar-app-reference/). @@ -328,9 +352,11 @@ export default { ``` #### `addMiddleware` option -

+

-**Type:** `(middleware:` [`AstroIntegrationMiddleware`](https://github.com/withastro/astro/blob/852ac0f75dfca1b2602e9cdbfa0447d9998e2449/packages/astro/src/%40types/astro.ts#L2124-L2127) `) => void;` +**Type:** `(middleware:` [`AstroIntegrationMiddleware`](https://github.com/withastro/astro/blob/852ac0f75dfca1b2602e9cdbfa0447d9998e2449/packages/astro/src/%40types/astro.ts#L2124-L2127) `) => void;`
+ +

Adds [middleware](/en/guides/middleware/) to run on each request. Takes the `entrypoint` module that contains the middleware, and an `order` to specify whether it should run before (`pre`) other middleware or after (`post`). @@ -390,7 +416,10 @@ export default () => ({ #### `injectRoute` option -**Type:** `({ pattern: string; entrypoint: string; pattern?: boolean }) => void;` +

+ +**Type:** `({ pattern: string; entrypoint: string | URL; prerender?: boolean }) => void;` +

A callback function to inject routes into an Astro project. Injected routes can be [`.astro` pages](/en/basics/astro-pages/) or [`.js` and `.ts` route handlers](/en/guides/endpoints/#static-file-endpoints). @@ -446,7 +475,10 @@ injectRoute({ #### `injectScript` option +

+ **Type:** `(stage: InjectedScriptStage, content: string) => void;` +

A callback function to inject a string of JavaScript content onto every page. @@ -490,7 +522,10 @@ const integration = { ### `astro:routes:resolved` +

+ +

**Previous hook:** [`astro:config:setup`](#astroconfigsetup) @@ -509,7 +544,10 @@ const integration = { #### `routes` option +

+ **Type:** [`IntegrationResolvedRoute[]`](#integrationresolvedroute-type-reference) +

A list of all routes with their associated metadata. @@ -655,21 +693,29 @@ interface IntegrationResolvedRoute { #### `config` option +

+ **Type:** `AstroConfig` +

A read-only copy of the user-supplied [Astro config](/en/reference/configuration-reference/). This is resolved _after_ other integrations have run. #### `setAdapter` option +

+ **Type:** `(adapter: AstroAdapter) => void;` +

Makes the integration an adapter. Read more in the [adapter API](/en/reference/adapter-reference/). #### `injectTypes` option -

+

-**Type:** `(injectedType: { filename: string; content: string }) => URL` +**Type:** `(injectedType: { filename: string; content: string }) => URL`
+ +

Allows you to inject types into your user's project by adding a new `*.d.ts` file. @@ -720,7 +766,10 @@ Allows you to adapt the logic of your integration depending on the user's projec ``` #### `server` option +

+ **Type:** [`ViteDevServer`](https://vite.dev/guide/api-javascript.html#vitedevserver) +

A mutable instance of the Vite server used in "dev" mode. For instance, this is [used by our Partytown integration](/en/guides/integrations-guide/partytown/) to inject the Partytown server as middleware: @@ -820,7 +869,10 @@ The loader can then access the `refreshContextData` property to get the webhook #### `address` option +

+ **Type:** [`AddressInfo`](https://microsoft.github.io/PowerBI-JavaScript/interfaces/_node_modules__types_node_net_d_._net_.addressinfo.html) +

The address, family and port number supplied by the [Node.js Net module](https://nodejs.org/api/net.html). @@ -928,18 +980,12 @@ The address, family and port number supplied by the [Node.js Net module](https:/ }) => void | Promise; ``` -#### `pages` options +#### `dir` option

-**Type:** `{pathname: string}[]` -

- -{/* Not sure about this one yet... There was a plan to remove it because undocumented but the PR was closed. Implemented in withastro/astro#2820 */} - -#### `dir` option - **Type:** [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) +

A URL path to the build output directory. Note that if you need a valid absolute path string, you should use Node's built-in [`fileURLToPath`](https://nodejs.org/api/url.html#urlfileurltopathurl) utility. @@ -967,7 +1013,10 @@ export default function myIntegration() { This property is deprecated since v5.0. Check the [migration guide](/en/guides/upgrade-to/v5/#deprecated-routes-on-astrobuilddone-hook-integration-api). ::: +

+ **Type:** [`IntegrationRouteData[]`](#integrationroutedata-type-reference) +

A list of all generated routes alongside their associated metadata. @@ -1047,15 +1096,20 @@ interface IntegrationRouteData { #### `assets` option - +

-**Type:** `Map` +**Type:** `Map`
+ +

Contains URLs to output files paths, grouped by [`IntegrationResolvedRoute`](#integrationresolvedroute-type-reference) `pattern` property. #### `pages` option +

+ **Type:** `{ pathname: string }[]` +

A list of all generated pages. It is an object with one property. @@ -1078,7 +1132,10 @@ A list of all generated pages. It is an object with one property. #### `route` option +

+ **Type:** `RouteOptions` +

An object with a `component` property to identify the route and the following additional values to allow you to configure the generated route: `prerender`. From 277d5d2450cc0041dcce060a232bd808257bcbd4 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Wed, 29 Jan 2025 17:30:55 +0100 Subject: [PATCH 13/34] consistent indentation between code snippets (most use 2 spaces) --- .../en/reference/integrations-reference.mdx | 148 +++++++++--------- 1 file changed, 74 insertions(+), 74 deletions(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 7d1960d4602db..8674b46503d99 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -368,10 +368,10 @@ export default () => ({ name: "my-middleware-package", hooks: { "astro:config:setup": ({ addMiddleware }) => { - addMiddleware({ - entrypoint: '@my-package/middleware', - order: 'pre' - }); + addMiddleware({ + entrypoint: '@my-package/middleware', + order: 'pre' + }); }, }, }); @@ -405,10 +405,10 @@ export default () => ({ name: "my-middleware-package", hooks: { "astro:config:setup": ({ addMiddleware }) => { - addMiddleware({ - entrypoint: new URL('./middleware.js', import.meta.url), - order: 'pre' - }); + addMiddleware({ + entrypoint: new URL('./middleware.js', import.meta.url), + order: 'pre' + }); }, }, }); @@ -510,13 +510,13 @@ It allows you to have a dedicated folder, avoiding conflicts with another integr import { writeFileSync } from 'node:fs' const integration = { - name: 'my-integration', - hooks: { - 'astro:config:setup': ({ createCodegenDir }) => { - const codegenDir = createCodegenDir() - writeFileSync(new URL('cache.json', codegenDir), '{}', 'utf-8') - } + name: 'my-integration', + hooks: { + 'astro:config:setup': ({ createCodegenDir }) => { + const codegenDir = createCodegenDir() + writeFileSync(new URL('cache.json', codegenDir), '{}', 'utf-8') } + } } ``` @@ -555,16 +555,16 @@ Example use: ```js title="my-integration.mjs" const integration = () => { - return { - name: 'my-integration', - hooks: { - 'astro:routes:resolved': ({ routes }) => { - const projectRoutes = routes.filter(r => r.origin === 'project').map(r => r.pattern) - - console.log(projectRoutes) - }, - } + return { + name: 'my-integration', + hooks: { + 'astro:routes:resolved': ({ routes }) => { + const projectRoutes = routes.filter(r => r.origin === 'project').map(r => r.pattern) + + console.log(projectRoutes) + }, } + } } ``` @@ -813,38 +813,38 @@ By default, `refreshContent` will refresh all collections. You can optionally pa You can also pass a `context` object to the loaders. This can be used to pass arbitrary data such as the webhook body, or an event from the websocket. ```ts title=my-integration.ts {19-22} - { - name: 'my-integration', - hooks: { - 'astro:server:setup': async ({ server, refreshContent }) => { - // Register a dev server webhook endpoint - server.middlewares.use('/_refresh', async (req, res) => { - if(req.method !== 'POST') { - res.statusCode = 405 - res.end('Method Not Allowed'); - return - } - let body = ''; - req.on('data', chunk => { - body += chunk.toString(); - }); - req.on('end', async () => { - try { - const webhookBody = JSON.parse(body); - await refreshContent({ - context: { webhookBody }, - loaders: ['my-loader'] - }); - res.writeHead(200, { 'Content-Type': 'application/json' }); - res.end(JSON.stringify({ message: 'Content refreshed successfully' })); - } catch (error) { - res.writeHead(500, { 'Content-Type': 'application/json' }); - res.end(JSON.stringify({ error: 'Failed to refresh content: ' + error.message })); - } - }); - }); +{ + name: 'my-integration', + hooks: { + 'astro:server:setup': async ({ server, refreshContent }) => { + // Register a dev server webhook endpoint + server.middlewares.use('/_refresh', async (req, res) => { + if(req.method !== 'POST') { + res.statusCode = 405 + res.end('Method Not Allowed'); + return } + let body = ''; + req.on('data', chunk => { + body += chunk.toString(); + }); + req.on('end', async () => { + try { + const webhookBody = JSON.parse(body); + await refreshContent({ + context: { webhookBody }, + loaders: ['my-loader'] + }); + res.writeHead(200, { 'Content-Type': 'application/json' }); + res.end(JSON.stringify({ message: 'Content refreshed successfully' })); + } catch (error) { + res.writeHead(500, { 'Content-Type': 'application/json' }); + res.end(JSON.stringify({ error: 'Failed to refresh content: ' + error.message })); + } + }); + }); } + } } ``` @@ -1245,15 +1245,15 @@ All the messages are prepended with a label that has the same value of the integ ```ts title="integration.ts" {8} import type { AstroIntegration } from "astro"; export function formatIntegration(): AstroIntegration { - return { - name: "astro-format", - hooks: { - "astro:build:done": ({ logger }) => { - // do something - logger.info("Integration ready."); - } - } + return { + name: "astro-format", + hooks: { + "astro:build:done": ({ logger }) => { + // do something + logger.info("Integration ready."); + } } + } } ``` @@ -1268,20 +1268,20 @@ To log some messages with a different label, use the `.fork` method to specify a ```ts title="integration.ts" ".fork" import type { AstroIntegration } from "astro"; export function formatIntegration(): AstroIntegration { - return { - name: "astro-format", - hooks: { - "astro:config:done": ({ logger }) => { - // do something - logger.info("Integration ready."); - }, - "astro:build:done": ({ logger }) => { - const buildLogger = logger.fork("astro-format/build"); - // do something - buildLogger.info("Build finished.") - } - } + return { + name: "astro-format", + hooks: { + "astro:config:done": ({ logger }) => { + // do something + logger.info("Integration ready."); + }, + "astro:build:done": ({ logger }) => { + const buildLogger = logger.fork("astro-format/build"); + // do something + buildLogger.info("Build finished.") + } } + } } ``` From dea2347b416d2abef638f5a94ccd862b628b3d2b Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Wed, 29 Jan 2025 19:15:15 +0100 Subject: [PATCH 14/34] add docs for `astro:build:setup` options --- .../en/reference/integrations-reference.mdx | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 8674b46503d99..ecf86f5a83830 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -927,6 +927,104 @@ The address, family and port number supplied by the [Node.js Net module](https:/ ``` +#### `vite` option + +

+ +**Type:** [`InlineConfig`](https://vite.dev/guide/api-javascript.html#inlineconfig) +

+ +An object that allows you to access the Vite configuration used in the build. + +This can be useful if you need to access configuration options in your integration: + +```js +export default { + name: 'my-integration', + hooks: { + 'astro:build:setup': ({ vite }) => { + const { publicDir, root } = vite; + }, + } +} +``` + +#### `pages` option + +

+ +**Type:** `Map` +

+ +A `Map` with a list of pages as key and their build data as value. + +This can be used to perform an action if a route matches a criteria: + +```js +export default { + name: 'my-integration', + hooks: { + 'astro:build:setup': ({ pages }) => { + pages.forEach((data) => { + if (data.route.pattern.test("/blog")) { + console.log(data.route.type); + } + }); + }, + } +} +``` + +#### `target` option + +

+ +**Type:** `'client' | 'server'` +

+ +Builds are separated in two distinct phases: `client` and `server`. This option allow you to determine the current build phase. + +This can be used to perform an action only in a specific phase: + +```js +export default { + name: 'my-integration', + hooks: { + 'astro:build:setup': ({ target }) => { + if (target === "server") { + // do something in server build phase + } + }, + } +} +``` + +#### `updateConfig()` option + +

+ +**Type:** (newConfig: InlineConfig) => void +

+ +A callback function to update the [Vite](https://vite.dev/) options used in the build. Any config you provide **will be merged with the user config + other integration config updates**, so you are free to omit keys! + +For example, this can be used to supply a plugin to the user's project: + +```js +import awesomeCssPlugin from 'awesome-css-vite-plugin'; + +export default { + name: 'my-integration', + hooks: { + 'astro:build:setup': ({ updateConfig }) => { + updateConfig({ + plugins: [awesomeCssPlugin()], + }) + } + } +} +``` + ### `astro:build:generated` **Previous hook:** [`astro:build:setup`](#astrobuildsetup) From d407744f995af407cff59e6d07571902f85b397c Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Wed, 29 Jan 2025 23:36:16 +0100 Subject: [PATCH 15/34] add docs for `astro:build:generated` options Added in withastro/astro#4775 so v1.3.0 --- .../en/reference/integrations-reference.mdx | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index ecf86f5a83830..ffa8d6b33522c 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -1027,6 +1027,11 @@ export default { ### `astro:build:generated` +

+ + +

+ **Previous hook:** [`astro:build:setup`](#astrobuildsetup) **When:** After a static production build has finished generating routes and assets. @@ -1040,6 +1045,28 @@ export default { }) => void | Promise; ``` +#### `dir` option + +

+ +**Type:** [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) +

+ +A URL path to the build output directory. Note that if you need a valid absolute path string, you should use Node's built-in [`fileURLToPath`](https://nodejs.org/api/url.html#urlfileurltopathurl) utility. + +```js +import { fileURLToPath } from 'node:url'; + +export default { + name: 'my-integration', + hooks: { + 'astro:build:generated': ({ dir }) => { + const outFile = fileURLToPath(new URL('./my-integration.json', dir)); + } + } +} +``` + ### `astro:build:ssr` **Previous hook:** [`astro:build:setup`](#astrobuildsetup) From 985ed4341e9d32f0170b113d9dd99e291915054b Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Wed, 29 Jan 2025 23:58:13 +0100 Subject: [PATCH 16/34] add partial docs for `astro:build:ssr` options `entryPoints` added in withastro/astro#7220 so v2.7.0 `middlewareEntryPoint` added in withastro/astro#7532 so 2.8.0 --- .../en/reference/integrations-reference.mdx | 66 +++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index ffa8d6b33522c..9d9eacce1d0e3 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -1086,6 +1086,72 @@ export default { }) => void | Promise; ``` +#### `manifest` option + +

+ +**Type:** `SerializedSSRManifest` +

+ +{/* I still need to figure this one out. */} + +```js +export default { + name: 'my-integration', + hooks: { + 'astro:build:ssr': ({ manifest }) => { + // still not sure about the use case... + }, + }, +} +``` + +#### `entryPoints` option + +

+ +**Type:** `Map`
+ +

+ +A `Map` with a list of `IntegrationRouteData` as key and the physical file URL as value. + +```js +export default { + name: 'my-integration', + hooks: { + 'astro:build:ssr': ({ entryPoints }) => { + entryPoints.forEach((url) => { + console.log(url.href); + }); + }, + }, +} +``` + +#### `middlewareEntryPoint` option + +

+ +**Type:** `URL | undefined`
+ +

+ +Exposes the middleware file path. + +```js +export default { + name: 'my-integration', + hooks: { + 'astro:build:ssr': ({ middlewareEntryPoint }) => { + if (middlewareEntryPoint) { + // do some operations + } + }, + }, +} +``` + ### `astro:build:done` **Previous hook:** [`astro:build:ssr`](#astrobuildssr) From c07ab67b0b22f971f8c2c918c62a9d5797f277d6 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Thu, 30 Jan 2025 13:37:44 +0100 Subject: [PATCH 17/34] provide a more detailed description for the `toolbar` option --- .../en/reference/integrations-reference.mdx | 38 ++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 9d9eacce1d0e3..330d90658becb 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -796,7 +796,43 @@ export default {

-Allows you to interact with the toolbar when the Astro's server is set up. +An object providing callback functions to interact with the [dev toolbar](/en/reference/dev-toolbar-app-reference/): + +##### `on()` + +

+ +**Type:** `(event: string, callback: (data: T) => void) => void`
+

+ +A function that takes an event name as first argument and a callback function as second argument. This allows you to receive a message from a dev toolbar app with data associated to that event. + +##### `onAppInitialized()` + +

+ +**Type:** `(appId: string, callback: (data: Record) => void) => void`
+

+ +A function fired when a dev toolbar app is initialized. The first argument is the id of the app that was initialized. The second argument is callback function to run when the app is initialized. + +##### `onAppToggled()` + +

+ +**Type:** `(appId: string, callback: (data: { state: boolean; }) => void) => void`
+

+ +A function fired when a dev toolbar app is toggled on or off. The first argument is the id of the app that was toggled. The second argument is a callback function providing the state to execute when the application is toggled. + +##### `send()` + +

+ +**Type:** `(event: string, payload: T) => void`
+

+ +A function that takes an event name as first argument and a payload as second argument. The payload can be any serializable data. This allows you to send a message to the dev toolbar that an app can listen for. #### `refreshContent` option From cc35d1311b97db5a133b981819b26a5ca5565639 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Thu, 30 Jan 2025 16:32:27 +0100 Subject: [PATCH 18/34] fix the hooks order I moved some hooks in the page to match the hooks order. I also fixed some `Next hook`/`Previous hook` which seemed wrong or at least outdated. Tested with a custom integration and logs. --- .../en/reference/integrations-reference.mdx | 234 +++++++++--------- 1 file changed, 121 insertions(+), 113 deletions(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 330d90658becb..50c90a1b2d985 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -39,6 +39,10 @@ interface AstroIntegration { createCodegenDir: () => URL; logger: AstroIntegrationLogger; }) => void | Promise; + 'astro:route:setup'?: (options: { + route: RouteOptions; + logger: AstroIntegrationLogger; + }) => void | Promise; 'astro:routes:resolved'?: (options: { routes: IntegrationResolvedRoute[]; logger: AstroIntegrationLogger; @@ -73,16 +77,16 @@ interface AstroIntegration { updateConfig: (newConfig: vite.InlineConfig) => void; logger: AstroIntegrationLogger; }) => void | Promise; - 'astro:build:generated'?: (options: { - dir: URL; - logger: AstroIntegrationLogger; - }) => void | Promise; 'astro:build:ssr'?: (options: { manifest: SerializedSSRManifest; entryPoints: Map; middlewareEntryPoint: URL | undefined; logger: AstroIntegrationLogger; }) => void | Promise; + 'astro:build:generated'?: (options: { + dir: URL; + logger: AstroIntegrationLogger; + }) => void | Promise; 'astro:build:done'?: (options: { pages: { pathname: string }[]; dir: URL; @@ -91,10 +95,6 @@ interface AstroIntegration { assets: Map; logger: AstroIntegrationLogger; }) => void | Promise; - 'astro:route:setup'?: (options: { - route: RouteOptions; - logger: AstroIntegrationLogger; - }) => void | Promise; // ... any custom hooks from integrations }; @@ -109,7 +109,7 @@ The following hooks are built in to Astro: ### `astro:config:setup` -**Next hook:** [`astro:config:done`](#astroconfigdone) +**Next hook:** [`astro:route:setup`](#astroroutesetup) **When:** On initialization, before either the [Vite](https://vite.dev/config/) or [Astro config](/en/reference/configuration-reference/) have resolved. @@ -520,6 +520,69 @@ const integration = { } ``` +### `astro:route:setup` + +

+ +**Previous hook:** [`astro:config:setup`](#astroconfigsetup) + +**Next hook:** [`astro:routes:resolved`](#astroroutesresolved) + +**When:** In `astro dev`, whenever a route is requested. In `astro build`, while bundling and transforming a route file. + +**Why:** To set options for a route at build or request time, such as enabling [on-demand server rendering](/en/guides/on-demand-rendering/#enabling-on-demand-rendering). + +```js +'astro:route:setup'?: (options: { + route: RouteOptions; + logger: AstroIntegrationLogger; +}) => void | Promise; +``` + +#### `route` option + +

+ +**Type:** `RouteOptions` +

+ +An object with a `component` property to identify the route and the following additional values to allow you to configure the generated route: `prerender`. + +The `component` property is a readonly string path relative to the project root, e.g `"src/pages/blog/[slug].astro"`. + +##### `route.prerender` + +

+**Type:** `boolean`
+**Default:** `undefined`
+ +

+ +The `prerender` property is used to configure [on-demand server rendering](/en/guides/on-demand-rendering/#enabling-on-demand-rendering) for a route. If the route file contains an explicit `export const prerender` value, the value will be used as the default instead of `undefined`. + +```js title="astro.config.mjs" +import { defineConfig } from 'astro/config'; + +export default defineConfig({ + integrations: [setPrerender()], +}); + +function setPrerender() { + return { + name: 'set-prerender', + hooks: { + 'astro:route:setup': ({ route }) => { + if (route.component.endsWith('/blog/[slug].astro')) { + route.prerender = true; + } + }, + }, + }; +} +``` + +If the final value after running all the hooks is `undefined`, the route will fall back to a prerender default based on the [`output` option](/en/reference/configuration-reference/#output): prerendered for `static` mode, and on-demand rendered for `server` mode. + ### `astro:routes:resolved`

@@ -527,7 +590,7 @@ const integration = {

-**Previous hook:** [`astro:config:setup`](#astroconfigsetup) +**Previous hook:** [`astro:route:setup`](#astroroutesetup) **Next hook:** [`astro:config:done`](#astroconfigdone) @@ -673,7 +736,7 @@ interface IntegrationResolvedRoute { ### `astro:config:done` -**Previous hook:** [`astro:config:setup`](#astroroutesresolved) +**Previous hook:** [`astro:routes:resolved`](#astroroutesresolved) **Next hook:** [`astro:server:setup`](#astroserversetup) when running in "dev" mode, or [`astro:build:start`](#astrobuildstart) during production builds @@ -1061,52 +1124,12 @@ export default { } ``` -### `astro:build:generated` - -

- - -

- -**Previous hook:** [`astro:build:setup`](#astrobuildsetup) - -**When:** After a static production build has finished generating routes and assets. - -**Why:** To access generated routes and assets **before** build artifacts are cleaned up. This is a very uncommon use case. We recommend using [`astro:build:done`](#astrobuilddone) unless you really need to access the generated files before cleanup. - -```js -'astro:build:generated'?: (options: { - dir: URL; - logger: AstroIntegrationLogger; -}) => void | Promise; -``` - -#### `dir` option - -

- -**Type:** [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) -

- -A URL path to the build output directory. Note that if you need a valid absolute path string, you should use Node's built-in [`fileURLToPath`](https://nodejs.org/api/url.html#urlfileurltopathurl) utility. - -```js -import { fileURLToPath } from 'node:url'; - -export default { - name: 'my-integration', - hooks: { - 'astro:build:generated': ({ dir }) => { - const outFile = fileURLToPath(new URL('./my-integration.json', dir)); - } - } -} -``` - ### `astro:build:ssr` **Previous hook:** [`astro:build:setup`](#astrobuildsetup) +**Next hook:** [`astro:build:generated`](#astrobuildgenerated) + **When:** After a production SSR build has completed. **Why:** To access the SSR manifest and map of the emitted entry points. This is useful when creating custom SSR builds in plugins or integrations. @@ -1188,10 +1211,54 @@ export default { } ``` -### `astro:build:done` +### `astro:build:generated` + +

+ + +

**Previous hook:** [`astro:build:ssr`](#astrobuildssr) +**Next hook:** [`astro:build:done`](#astrobuilddone) + +**When:** After a static production build has finished generating routes and assets. + +**Why:** To access generated routes and assets **before** build artifacts are cleaned up. This is a very uncommon use case. We recommend using [`astro:build:done`](#astrobuilddone) unless you really need to access the generated files before cleanup. + +```js +'astro:build:generated'?: (options: { + dir: URL; + logger: AstroIntegrationLogger; +}) => void | Promise; +``` + +#### `dir` option + +

+ +**Type:** [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) +

+ +A URL path to the build output directory. Note that if you need a valid absolute path string, you should use Node's built-in [`fileURLToPath`](https://nodejs.org/api/url.html#urlfileurltopathurl) utility. + +```js +import { fileURLToPath } from 'node:url'; + +export default { + name: 'my-integration', + hooks: { + 'astro:build:generated': ({ dir }) => { + const outFile = fileURLToPath(new URL('./my-integration.json', dir)); + } + } +} +``` + +### `astro:build:done` + +**Previous hook:** [`astro:build:generated`](#astrobuildgenerated) + **When:** After a production build (SSG or SSR) has completed. **Why:** To access generated routes and assets for extension (ex. copy content into the generated `/assets` directory). If you plan to transform generated assets, we recommend exploring the [Vite Plugin API](https://vite.dev/guide/api-plugin.html) and [configuring via `astro:config:setup`](#updateconfig-option) instead. @@ -1342,65 +1409,6 @@ A list of all generated pages. It is an object with one property. - `pathname` - the finalized path of the page. -### `astro:route:setup` - -

- -**When:** In `astro dev`, whenever a route is requested. In `astro build`, while bundling and transforming a route file. - -**Why:** To set options for a route at build or request time, such as enabling [on-demand server rendering](/en/guides/on-demand-rendering/#enabling-on-demand-rendering). - -```js -'astro:route:setup'?: (options: { - route: RouteOptions; - logger: AstroIntegrationLogger; -}) => void | Promise; -``` - -#### `route` option - -

- -**Type:** `RouteOptions` -

- -An object with a `component` property to identify the route and the following additional values to allow you to configure the generated route: `prerender`. - -The `component` property is a readonly string path relative to the project root, e.g `"src/pages/blog/[slug].astro"`. - -##### `route.prerender` - -

-**Type:** `boolean`
-**Default:** `undefined`
- -

- -The `prerender` property is used to configure [on-demand server rendering](/en/guides/on-demand-rendering/#enabling-on-demand-rendering) for a route. If the route file contains an explicit `export const prerender` value, the value will be used as the default instead of `undefined`. - -```js title="astro.config.mjs" -import { defineConfig } from 'astro/config'; - -export default defineConfig({ - integrations: [setPrerender()], -}); - -function setPrerender() { - return { - name: 'set-prerender', - hooks: { - 'astro:route:setup': ({ route }) => { - if (route.component.endsWith('/blog/[slug].astro')) { - route.prerender = true; - } - }, - }, - }; -} -``` - -If the final value after running all the hooks is `undefined`, the route will fall back to a prerender default based on the [`output` option](/en/reference/configuration-reference/#output): prerendered for `static` mode, and on-demand rendered for `server` mode. - ### Custom hooks Custom hooks can be added to integrations by extending the `IntegrationHooks` interface through [global augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#global-augmentation). From ee538ab6776e1848e0e09c885bd67ff5667ff223 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Thu, 30 Jan 2025 18:24:48 +0100 Subject: [PATCH 19/34] try to improve `astro:build:ssr` options description --- .../en/reference/integrations-reference.mdx | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 50c90a1b2d985..18faaa0480f95 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -1149,17 +1149,20 @@ export default {

-**Type:** `SerializedSSRManifest` +**Type:** [`SerializedSSRManifest`](https://github.com/withastro/astro/blob/3b10b97a4fecd1dfd959b160a07b5b8427fe40a7/packages/astro/src/core/app/types.ts#L91-L109)

-{/* I still need to figure this one out. */} +Allows you to create a custom build by accessing the SSR manifest. ```js export default { name: 'my-integration', hooks: { 'astro:build:ssr': ({ manifest }) => { - // still not sure about the use case... + const { i18n } = manifest; + if (i18n?.strategy === "domains-prefix-always") { + // do something + } }, }, } @@ -1169,11 +1172,11 @@ export default {

-**Type:** `Map`
+**Type:** Map\<IntegrationRouteData, URL\>

-A `Map` with a list of `IntegrationRouteData` as key and the physical file URL as value. +A `Map` of the emitted entry points with the `IntegrationRouteData` as key and the physical file URL as value. ```js export default { @@ -1196,7 +1199,7 @@ export default {

-Exposes the middleware file path. +Exposes the [middleware](https://docs.astro.build/en/guides/middleware/) file path. ```js export default { @@ -1204,7 +1207,7 @@ export default { hooks: { 'astro:build:ssr': ({ middlewareEntryPoint }) => { if (middlewareEntryPoint) { - // do some operations + // do some operations if a middleware exist } }, }, From 0cb3c8b2f2d151f49a0022f0762d9fc95fd5023b Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Thu, 30 Jan 2025 18:38:25 +0100 Subject: [PATCH 20/34] add a link to some types --- src/content/docs/en/reference/integrations-reference.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 18faaa0480f95..2414dd14589ab 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -543,7 +543,7 @@ const integration = {

-**Type:** `RouteOptions` +**Type:** [`RouteOptions`](https://github.com/withastro/astro/blob/3b10b97a4fecd1dfd959b160a07b5b8427fe40a7/packages/astro/src/types/public/integrations.ts#L14-L27)

An object with a `component` property to identify the route and the following additional values to allow you to configure the generated route: `prerender`. @@ -1052,7 +1052,7 @@ export default {

-**Type:** `Map` +**Type:** Map\PageBuildData\>

A `Map` with a list of pages as key and their build data as value. From d113f0202342f523c9efa2d08620829d8f836551 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Thu, 30 Jan 2025 18:42:32 +0100 Subject: [PATCH 21/34] consistency: explicit function notation in headings We usually use `addMiddleware()` instead of `addMiddleware` in headings when the type is a function. --- .../en/reference/integrations-reference.mdx | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 2414dd14589ab..0e5ec13540c22 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -164,7 +164,7 @@ A read-only copy of the user-supplied [Astro config](/en/reference/configuration `false` when the dev server starts, `true` when a reload is triggered. Useful to detect when this function is called more than once. -#### `updateConfig` option +#### `updateConfig()` option

@@ -192,7 +192,7 @@ export default { } ``` -#### `addRenderer` option +#### `addRenderer()` option

@@ -227,7 +227,7 @@ addWatchFile('/home/user/.../my-config.json'); addWatchFile(new URL('./tailwind.config.js', config.root)); ``` -#### `addClientDirective` option +#### `addClientDirective()` option

@@ -294,7 +294,7 @@ declare module 'astro' { } ``` -#### `addDevToolbarApp` option +#### `addDevToolbarApp()` option

@@ -350,7 +350,7 @@ export default { }, }; ``` -#### `addMiddleware` option +#### `addMiddleware()` option

@@ -414,7 +414,7 @@ export default () => ({ }); ``` -#### `injectRoute` option +#### `injectRoute()` option

@@ -473,7 +473,7 @@ injectRoute({ }); ``` -#### `injectScript` option +#### `injectScript()` option

@@ -763,7 +763,7 @@ interface IntegrationResolvedRoute { A read-only copy of the user-supplied [Astro config](/en/reference/configuration-reference/). This is resolved _after_ other integrations have run. -#### `setAdapter` option +#### `setAdapter()` option

@@ -772,7 +772,7 @@ A read-only copy of the user-supplied [Astro config](/en/reference/configuration Makes the integration an adapter. Read more in the [adapter API](/en/reference/adapter-reference/). -#### `injectTypes` option +#### `injectTypes()` option

@@ -897,7 +897,7 @@ A function fired when a dev toolbar app is toggled on or off. The first argument A function that takes an event name as first argument and a payload as second argument. The payload can be any serializable data. This allows you to send a message to the dev toolbar that an app can listen for. -#### `refreshContent` option +#### `refreshContent()` option

From bdfa2adec8cac47a1b1b50728cadcf58c01ac315 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Thu, 30 Jan 2025 18:45:23 +0100 Subject: [PATCH 22/34] fix addWatchFile type --- src/content/docs/en/reference/integrations-reference.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 0e5ec13540c22..482886b7f3881 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -209,11 +209,11 @@ A callback function to add a component framework renderer (i.e. React, Vue, Svel The functions `clientEntrypoint` and `serverEntrypoint` accept a `URL`. -#### `addWatchFile` option +#### `addWatchFile()` option

-**Type:** `URL | string`
+**Type:** `(path: URL | string) => void`

From 31e32ce18505da13de049b90bcd43d9bb0e1a4ea Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Thu, 30 Jan 2025 19:09:34 +0100 Subject: [PATCH 23/34] fix `ins` highlighting, thanks HiDeoo --- src/content/docs/en/reference/integrations-reference.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 482886b7f3881..77490f39f3939 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -1451,15 +1451,15 @@ function mySetup(options: HookParameters<'astro:config:setup'>) { } ``` -Once you [publish your integration to npm](https://docs.npmjs.com/cli/v8/commands/npm-publish), running `astro add example` will install your package with any peer dependencies specified in your `package.json`. This will also apply your integration to the user's `astro.config` like so: +Once you [publish your integration to npm](https://docs.npmjs.com/cli/v8/commands/npm-publish), running `astro add example` will install your package with any peer dependencies specified in your `package.json`. This will also apply your integration to the user's `astro.config.*` like so: -```diff +```diff ins={3,6} // astro.config.mjs import { defineConfig } from 'astro/config'; -+ import example from 'example'; +import example from 'example'; export default defineConfig({ -+ integrations: [example()], + integrations: [example()], }) ``` From d33deff369cab934464f8a6c92cb471e9aefa8f7 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Thu, 30 Jan 2025 19:25:21 +0100 Subject: [PATCH 24/34] fix link and code snippet language --- src/content/docs/en/reference/integrations-reference.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 77490f39f3939..e345de7222ba4 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -1199,7 +1199,7 @@ export default {

-Exposes the [middleware](https://docs.astro.build/en/guides/middleware/) file path. +Exposes the [middleware](/en/guides/middleware/) file path. ```js export default { @@ -1453,7 +1453,7 @@ function mySetup(options: HookParameters<'astro:config:setup'>) { Once you [publish your integration to npm](https://docs.npmjs.com/cli/v8/commands/npm-publish), running `astro add example` will install your package with any peer dependencies specified in your `package.json`. This will also apply your integration to the user's `astro.config.*` like so: -```diff ins={3,6} +```mjs ins={3,6} // astro.config.mjs import { defineConfig } from 'astro/config'; import example from 'example'; From b17e3d86dadc5efb9172b7b03c89d402dbdb6423 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Fri, 31 Jan 2025 15:01:45 +0100 Subject: [PATCH 25/34] move types and break up `IntegrationResolvedRoute` and `IntegrationRouteData` --- .../en/reference/integrations-reference.mdx | 560 +++++++++++------- 1 file changed, 345 insertions(+), 215 deletions(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index e345de7222ba4..f8dcc4abfaf69 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -609,7 +609,7 @@ If the final value after running all the hooks is `undefined`, the route will fa

-**Type:** [`IntegrationResolvedRoute[]`](#integrationresolvedroute-type-reference) +**Type:** [`IntegrationResolvedRoute[]`](#integrationresolvedroute)

A list of all routes with their associated metadata. @@ -631,109 +631,6 @@ const integration = () => { } ``` -##### `IntegrationResolvedRoute` type reference - -```ts -interface IntegrationResolvedRoute { - /** - * The current **pattern** of the route. For example: - * - `src/pages/index.astro` has a pattern of `/` - * - `src/pages/blog/[...slug].astro` has a pattern of `/blog/[...slug]` - * - `src/pages/site/[blog]/[...slug].astro` has a pattern of `/site/[blog]/[...slug]` - */ - pattern: RouteData['route']; - - /** - * - * regex used for matching an input URL against a requested route - * ex. "[fruit]/about.astro" will generate the pattern: /^\/([^/]+?)\/about\/?$/ - * where pattern.test("banana/about") is "true" - * - * ## Example - * - * ```js - * if (route.pattern.test('/blog')) { - * // do something - * } - * ``` - */ - patternRegex: RouteData['pattern']; - - /** - * Source component URL - */ - entrypoint: RouteData['component']; - - /** - * Whether the route is prerendered or not - */ - isPrerendered: RouteData['prerender']; - - /** - * The {@link IntegrationResolvedRoute} to redirect to. It's present when `IntegrationResolvedRoute.type` is `redirect`. - */ - redirectRoute?: IntegrationResolvedRoute; - - /** - * @param {any} data The optional parameters of the route - * - * @description - * A function that accepts a list of params, interpolates them with the route pattern, and returns the path name of the route. - * - * ## Example - * - * For a route such as `/blog/[...id].astro`, the `generate` function would return something like this: - * - * ```js - * console.log(generate({ id: 'presentation' })) // will log `/blog/presentation` - * ``` - */ - generate: (data?: any) => string; - - /** - * Dynamic and spread route params - * ex. "/pages/[lang]/[...slug].astro" will output the params ['lang', '...slug'] - */ - params: string[]; - - /** - * Output URL pathname where this route will be served - * note: will be undefined for [dynamic] and [...spread] routes - */ - pathname?: string; - - /** - * Similar to the "params" field, but with more associated metadata. For example, for `/site/[blog]/[...slug].astro`, the segments are: - * - * 1. `{ content: 'site', dynamic: false, spread: false }` - * 2. `{ content: 'blog', dynamic: true, spread: false }` - * 3. `{ content: '...slug', dynamic: true, spread: true }` - */ - segments: RoutePart[][]; - - /** - * - * The type of the route. It can be: - * - `page`: a route that lives in the file system, usually an Astro component - * - `endpoint`: a route that lives in the file system, usually a JS file that exposes endpoints methods - * - `redirect`: a route points to another route that lives in the file system - * - `fallback`: a route that doesn't exist in the file system that needs to be handled with other means, usually the middleware - */ - type: RouteType; - - /** - * The route to redirect to. It holds information regarding the status code and its destination. - */ - redirect?: RedirectConfig; - - /** - * Whether the route comes from Astro core, an integration or the user's project - */ - origin: 'internal' | 'external' | 'project'; -} -``` - - ### `astro:config:done` **Previous hook:** [`astro:routes:resolved`](#astroroutesresolved) @@ -827,6 +724,7 @@ Allows you to adapt the logic of your integration depending on the user's projec }) => Promise; }) => void | Promise; ``` + #### `server` option

@@ -1172,7 +1070,7 @@ export default {

-**Type:** Map\<IntegrationRouteData, URL\>
+**Type:** Map\<IntegrationRouteData, URL\>

@@ -1312,7 +1210,7 @@ This property is deprecated since v5.0. Check the [migration guide](/en/guides/u

-**Type:** [`IntegrationRouteData[]`](#integrationroutedata-type-reference) +**Type:** [`IntegrationRouteData[]`](#integrationroutedata)

A list of all generated routes alongside their associated metadata. @@ -1322,75 +1220,6 @@ You can reference the full `IntegrationRouteData` type below, but the most commo - `component` - the input file path relative to the project root - `pathname` - the output file URL (undefined for routes using `[dynamic]` and `[...spread]` params) -##### `IntegrationRouteData` type reference - -```ts -interface IntegrationRouteData { - /** - * The type of the route. It can be: - * - * - `page`: a route that lives in the file system, usually an Astro component - * - `endpoint`: a route that lives in the file system, usually a JS file that exposes endpoints methods - * - `redirect`: a route that points to another route that lives in the file system - * - `fallback`: a route that doesn't exist in the file system and needs to be handled with other means, usually middleware - */ - type: 'page' | 'endpoint' | 'redirect' | 'fallback'; - /** Source component URL */ - component: string; - /** - * Output URL pathname where this route will be served - * note: will be undefined for [dynamic] and [...spread] routes - */ - pathname?: string; - /** - * regex used for matching an input URL against a requested route - * ex. "[fruit]/about.astro" will generate the pattern: /^\/([^/]+?)\/about\/?$/ - * where pattern.test("banana/about") is "true" - */ - pattern: RegExp; - /** - * Dynamic and spread route params - * ex. "/pages/[lang]/[..slug].astro" will output the params ['lang', '...slug'] - */ - params: string[]; - /** - * Similar to the "params" field, but with more associated metadata - * ex. "/pages/[lang]/index.astro" will output the segments - * [[ { content: 'lang', dynamic: true, spread: false } ]] - */ - segments: { content: string; dynamic: boolean; spread: boolean; }[][]; - /** - * A function that accepts a list of params, interpolates them with the route pattern, and returns the path name of the route. - * - * ## Example - * - * For a route such as `/blog/[...id].astro`, the `generate` function would return something like this: - * - * ```js - * console.log(generate({ id: 'presentation' })) // will log `/blog/presentation` - * ``` - * This is typically for internal use, so call with caution! - */ - generate: (data?: any) => string; - /** - * Whether the route is prerendered or not. - */ - prerender: boolean; - /** - * The paths of the physical files emitted by this route. When a route **isn't** prerendered, the value is either `undefined` or an empty array. - */ - distURL?: URL[]; - /** - * The route to redirect to. It holds information regarding the status code and its destination. - */ - redirect?: RedirectConfig; - /** - * The `IntegrationRouteData` to redirect to. It's present when `RouteData.type` is `redirect`. - */ - redirectRoute?: IntegrationRouteData; -} -``` - #### `assets` option

@@ -1399,7 +1228,7 @@ interface IntegrationRouteData {

-Contains URLs to output files paths, grouped by [`IntegrationResolvedRoute`](#integrationresolvedroute-type-reference) `pattern` property. +Contains URLs to output files paths, grouped by [`IntegrationResolvedRoute`](#integrationresolvedroute) `pattern` property. #### `pages` option @@ -1428,46 +1257,9 @@ declare global { Astro reserves the `astro:` prefix for future built-in hooks. Please choose a different prefix when naming your custom hook. -### `HookParameters` - -You can get the type of a hook’s arguments by passing the hook’s name to the `HookParameters` utility type. In the following example, a function’s `options` argument is typed to match the parameters of the `astro:config:setup` hook: - -```ts /HookParameters(?:<.+>)?/ -import type { HookParameters } from 'astro'; - -function mySetup(options: HookParameters<'astro:config:setup'>) { - options.updateConfig({ /* ... */ }); -} -``` - -## Allow installation with `astro add` +## Integration types reference -[The `astro add` command](/en/reference/cli-reference/#astro-add) allows users to easily add integrations and adapters to their project. If you want _your_ integration to be installable with this tool, **add `astro-integration` to the `keywords` field in your `package.json`**: - -```json -{ - "name": "example", - "keywords": ["astro-integration"], -} -``` - -Once you [publish your integration to npm](https://docs.npmjs.com/cli/v8/commands/npm-publish), running `astro add example` will install your package with any peer dependencies specified in your `package.json`. This will also apply your integration to the user's `astro.config.*` like so: - -```mjs ins={3,6} -// astro.config.mjs -import { defineConfig } from 'astro/config'; -import example from 'example'; - -export default defineConfig({ - integrations: [example()], -}) -``` - -:::caution -This assumes your integration definition is 1) a `default` export and 2) a function. Ensure this is true before adding the `astro-integration` keyword! -::: - -## `AstroIntegrationLogger` +### `AstroIntegrationLogger` An instance of the Astro logger, useful to write logs. This logger uses the same [log level](/en/reference/cli-reference/#--verbose) configured via CLI. @@ -1530,6 +1322,344 @@ The example above will produce logs with `[astro-format]` by default, and `[astr [astro-format/build] Build finished. ``` +### `HookParameters` + +You can get the type of a hook’s arguments by passing the hook’s name to the `HookParameters` utility type. In the following example, a function’s `options` argument is typed to match the parameters of the `astro:config:setup` hook: + +```ts /HookParameters(?:<.+>)?/ +import type { HookParameters } from 'astro'; + +function mySetup(options: HookParameters<'astro:config:setup'>) { + options.updateConfig({ /* ... */ }); +} +``` + +### `IntegrationResolvedRoute` + +```ts +interface IntegrationResolvedRoute { + pattern: RouteData['route']; + patternRegex: RouteData['pattern']; + entrypoint: RouteData['component']; + isPrerendered: RouteData['prerender']; + redirectRoute?: IntegrationResolvedRoute; + generate: (data?: any) => string; + params: string[]; + pathname?: string; + segments: RoutePart[][]; + type: RouteType; + redirect?: RedirectConfig; + origin: 'internal' | 'external' | 'project'; +} +``` + +#### `pattern` + +

+ +**Type:** `string` +

+ +Allows you to identify the type of route based on its path. Here are some examples of paths associated with their pattern: +* `src/pages/index.astro` will be `/` +* `src/pages/blog/[...slug].astro` will be `/blog/[...slug]` +* `src/pages/site/[blog]/[...slug].astro` will be `/site/[blog]/[...slug]` + +#### `patternRegex` + +

+ +**Type:** `RegExp` +

+ +Allows you to access a regex used for matching an input URL against a requested route. + +For example, given a `[fruit]/about.astro` path, the regex will be `/^\/([^/]+?)\/about\/?$/`. Using `pattern.test("banana/about")` will return `true`. + +#### `entrypoint` + +

+ +**Type:** `string` +

+ +The URL pathname of the source component. + +#### `isPrerendered` + +

+ +**Type:** `boolean` +

+ +Determines whether the route use [on demand rendering](/en/guides/on-demand-rendering/). The value will be `true` for projects configured with: +* `output: 'static'` when the route does not export `const prerender = true` +* `output: 'server'` when the route exports `const prerender = false` + +#### `redirectRoute` + +

+ +**Type:** `IntegrationResolvedRoute | undefined` +

+ +When the value of `IntegrationResolvedRoute.type` is `redirect`, the value will be the `IntegrationResolvedRoute` to redirect to. Otherwise, the value will be undefined. + +#### `generate()` + +

+ +**Type:** `(data?: any) => string` +

+ +A function that provides the optional parameters of the route, interpolates them with the route pattern, and returns the path name of the route. + +For example, with a route such as `/blog/[...id].astro`, the `generate` function could return: + +```js +console.log(generate({ id: 'presentation' })) // will log `/blog/presentation` +``` + +#### `params` + +

+ +**Type:** `string[]` +

+ +Allows you to access the route `params`. For example, when a project uses the following [dynamic routes](/en/guides/routing/#dynamic-routes) `/pages/[lang]/[...slug].astro`, the value will be `['lang', '...slug']`. + +#### `pathname` + +

+ +**Type:** `string | undefined` +

+ +For regular routes, the value will be the URL pathname where this route will be served. When the project uses [dynamic routes](/en/guides/routing/#dynamic-routes) (ie. `[dynamic]` or `[...spread]`), the pathname will be undefined. + +#### `segments` + +

+ +**Type:** RoutePart[][] +

+ +Allows you to access the route [`params`](#params) with additional metadata. Each object contains the following properties: +* `content`: the `param` name, +* `dynamic`: wether the route is dynamic or not, +* `spread`: whether the dynamic route uses the spread syntax or not. + +For example, the following route `/pages/[blog]/[...slug].astro` will output the segments: + +```js +[ + [ + { content: 'pages', dynamic: false, spread: false }, + { content: 'blog', dynamic: true, spread: false }, + { content: '...slug', dynamic: true, spread: true } + ] +] +``` + +#### `type` + +

+ +**Type:** `RouteType` +

+ +Allows you to identify the type of route. Possible values are: +* `page`: a route that lives in the file system, usually an Astro component +* `endpoint`: a route that lives in the file system, usually a JS file that exposes endpoints methods +* `redirect`: a route points to another route that lives in the file system +* `fallback`: a route that doesn't exist in the file system that needs to be handled with other means, usually the middleware + +#### `redirect` + +

+ +**Type:** RedirectConfig | undefined +

+ +Allows you to access the route to redirect to. This can be a string or an object containing information about the status code and its destination. + +#### `origin` + +

+ +**Type:** `'internal' | 'external' | 'project'` +

+ +Determines if a route comes from Astro core (`internal`), an integration (`external`) or the user's project (`project`). + +### `IntegrationRouteData` + +:::caution +This type is deprecated since v5.0. Use [`IntegrationResolvedRoute`](#integrationresolvedroute) instead. +::: + +A smaller version of the `RouteData` that is used in the integrations. + +```ts +interface IntegrationRouteData { + type: RouteType; + component: string; + pathname?: string; + pattern: RegExp; + params: string[]; + segments: { content: string; dynamic: boolean; spread: boolean; }[][]; + generate: (data?: any) => string; + prerender: boolean; + distURL?: URL[]; + redirect?: RedirectConfig; + redirectRoute?: IntegrationRouteData; +} +``` + +#### `type` + +

+ +**Type:** `RouteType` +

+ +Allows you to identify the type of the route. The value can be: +- `page`: a route that lives in the file system, usually an Astro component +- `endpoint`: a route that lives in the file system, usually a JS file that exposes endpoints methods +- `redirect`: a route that points to another route that lives in the file system +- `fallback`: a route that doesn't exist in the file system and needs to be handled with other means, usually middleware + +#### `component` + +

+ +**Type:** `string` +

+ +Allows you to access the source component URL pathname. + +#### `pathname` + +

+ +**Type:** `string | undefined` +

+ +For regular routes, the value will be the URL pathname where this route will be served. When the project uses [dynamic routes](/en/guides/routing/#dynamic-routes) (ie. `[dynamic]` or `[...spread]`), the pathname will be undefined. + +#### `pattern` + +

+ +**Type:** `RegExp` +

+ +Allows you to access a regex used for matching an input URL against a requested route. + +For example, given a `[fruit]/about.astro` path, the regex will be `/^\/([^/]+?)\/about\/?$/`. Using `pattern.test("banana/about")` will return `true`. + +#### `params` + +

+ +**Type:** `string[]` +

+ +Allows you to access the route `params`. For example, when a project uses the following [dynamic routes](/en/guides/routing/#dynamic-routes) `/pages/[lang]/[...slug].astro`, the value will be `['lang', '...slug']`. + +#### `segments` + +

+ +**Type:** `{ content: string; dynamic: boolean; spread: boolean; }[][]` +

+ +Allows you to access the route [`params`](#params-1) with additional metadata. Each object contains the following properties: +* `content`: the `param`, +* `dynamic`: wether the route is dynamic or not, +* `spread`: whether the dynamic route uses the spread syntax or not. + +For example, the following route `/pages/[lang]/index.astro` will output the segments `[[ { content: 'lang', dynamic: true, spread: false } ]]`. + +#### `generate()` + +

+ +**Type:** `(data?: any) => string` +

+ +A function that provides the optional parameters of the route, interpolates them with the route pattern, and returns the path name of the route. + +For example, with a route such as `/blog/[...id].astro`, the `generate` function could return: + +```js +console.log(generate({ id: 'presentation' })) // will log `/blog/presentation` +``` + +#### `prerender` + +

+ +**Type:** `boolean` +

+ +Determines whether the route is prerendered or not. + +#### `distURL` + +

+ +**Type:** `URL[] | undefined` +

+ +The paths of the physical files emitted by this route. When a route **isn't** prerendered, the value is either `undefined` or an empty array. + +#### `redirect` + +

+ +**Type:** RedirectConfig | undefined +

+ +Allows you to access the route to redirect to. This can be a string or an object containing information about the status code and its destination. + +#### `redirectRoute` + +

+ +**Type:** `IntegrationRouteData | undefined` +

+ +When the value of `RouteData.type` is `redirect`, the value will contains the `IntegrationRouteData` of the route to redirect to. Otherwise, the value will be undefined. + +## Allow installation with `astro add` + +[The `astro add` command](/en/reference/cli-reference/#astro-add) allows users to easily add integrations and adapters to their project. If you want _your_ integration to be installable with this tool, **add `astro-integration` to the `keywords` field in your `package.json`**: + +```json +{ + "name": "example", + "keywords": ["astro-integration"], +} +``` + +Once you [publish your integration to npm](https://docs.npmjs.com/cli/v8/commands/npm-publish), running `astro add example` will install your package with any peer dependencies specified in your `package.json`. This will also apply your integration to the user's `astro.config.*` like so: + +```js ins={3,6} +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import example from 'example'; + +export default defineConfig({ + integrations: [example()], +}) +``` + +:::caution +This assumes your integration definition is 1) a `default` export and 2) a function. Ensure this is true before adding the `astro-integration` keyword! +::: + ## Integration Ordering All integrations are run in the order that they are configured. For instance, for the array `[react(), svelte()]` in a user's `astro.config.*`, `react` will run before `svelte`. From eba6fd51af5c9dce1622ea18e66779e18a52c5c7 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Fri, 31 Jan 2025 15:06:20 +0100 Subject: [PATCH 26/34] add a link from Hooks to AstroIntegrationLogger --- src/content/docs/en/reference/integrations-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index f8dcc4abfaf69..cb4e8513f4534 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -103,7 +103,7 @@ interface AstroIntegration { ## Hooks -Astro provides hooks that integrations can implement to execute during certain parts of Astro's lifecycle. Astro hooks are defined in the `IntegrationHooks` interface, which is part of the global `Astro` namespace. +Astro provides hooks that integrations can implement to execute during certain parts of Astro's lifecycle. Astro hooks are defined in the `IntegrationHooks` interface, which is part of the global `Astro` namespace. Each hook has a [`logger` option](astrointegrationlogger) that allows you to use the Astro logger to write logs. The following hooks are built in to Astro: From e02829a4ef53c7599526ec349741eb7254a49c0e Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Fri, 31 Jan 2025 15:26:02 +0100 Subject: [PATCH 27/34] bring back redundancy in headings to avoid links errors --- .../docs/en/reference/integrations-reference.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index d58670f6374a4..3f0eca13cac75 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -609,7 +609,7 @@ If the final value after running all the hooks is `undefined`, the route will fa

-**Type:** [`IntegrationResolvedRoute[]`](#integrationresolvedroute) +**Type:** [`IntegrationResolvedRoute[]`](#integrationresolvedroute-type-reference)

A list of all routes with their associated metadata. @@ -1070,7 +1070,7 @@ export default {

-**Type:** Map\<IntegrationRouteData, URL\>
+**Type:** Map\<IntegrationRouteData, URL\>

@@ -1210,7 +1210,7 @@ This property is deprecated since v5.0. Check the [migration guide](/en/guides/u

-**Type:** [`IntegrationRouteData[]`](#integrationroutedata) +**Type:** [`IntegrationRouteData[]`](#integrationroutedata-type-reference)

A list of all generated routes alongside their associated metadata. @@ -1228,7 +1228,7 @@ You can reference the full `IntegrationRouteData` type below, but the most commo

-Contains URLs to output files paths, grouped by [`IntegrationResolvedRoute`](#integrationresolvedroute) `pattern` property. +Contains URLs to output files paths, grouped by [`IntegrationResolvedRoute`](#integrationresolvedroute-type-reference) `pattern` property. #### `pages` option @@ -1334,7 +1334,7 @@ function mySetup(options: HookParameters<'astro:config:setup'>) { } ``` -### `IntegrationResolvedRoute` +### `IntegrationResolvedRoute` type reference ```ts interface IntegrationResolvedRoute { @@ -1493,10 +1493,10 @@ Allows you to access the route to redirect to. This can be a string or an object Determines if a route comes from Astro core (`internal`), an integration (`external`) or the user's project (`project`). -### `IntegrationRouteData` +### `IntegrationRouteData` type reference :::caution -This type is deprecated since v5.0. Use [`IntegrationResolvedRoute`](#integrationresolvedroute) instead. +This type is deprecated since v5.0. Use [`IntegrationResolvedRoute`](#integrationresolvedroute-type-reference) instead. ::: A smaller version of the `RouteData` that is used in the integrations. From 168cb66539a7206d9f914fe9d7bd2c8a4c382b2f Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Fri, 31 Jan 2025 15:34:47 +0100 Subject: [PATCH 28/34] fix last link... --- src/content/docs/en/reference/integrations-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 3f0eca13cac75..1123b6b27a614 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -103,7 +103,7 @@ interface AstroIntegration { ## Hooks -Astro provides hooks that integrations can implement to execute during certain parts of Astro's lifecycle. Astro hooks are defined in the `IntegrationHooks` interface, which is part of the global `Astro` namespace. Each hook has a [`logger` option](astrointegrationlogger) that allows you to use the Astro logger to write logs. +Astro provides hooks that integrations can implement to execute during certain parts of Astro's lifecycle. Astro hooks are defined in the `IntegrationHooks` interface, which is part of the global `Astro` namespace. Each hook has a [`logger` option](#astrointegrationlogger) that allows you to use the Astro logger to write logs. The following hooks are built in to Astro: From 8dd180fe458bfa7f90c543c1098cad2bd124df09 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Fri, 31 Jan 2025 15:43:45 +0100 Subject: [PATCH 29/34] fix `segments` output example, wrong guess --- src/content/docs/en/reference/integrations-reference.mdx | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 1123b6b27a614..e3ecd2762219d 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -1454,11 +1454,9 @@ For example, the following route `/pages/[blog]/[...slug].astro` will output the ```js [ - [ - { content: 'pages', dynamic: false, spread: false }, - { content: 'blog', dynamic: true, spread: false }, - { content: '...slug', dynamic: true, spread: true } - ] + [ { content: 'pages', dynamic: false, spread: false } ], + [ { content: 'blog', dynamic: true, spread: false } ], + [ { content: '...slug', dynamic: true, spread: true } ] ] ``` From a20a6c8fee602ba386521bfed38a7316e382bc08 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Mon, 3 Feb 2025 16:40:04 +0100 Subject: [PATCH 30/34] use consistent formatting for `route` option properties (component, prerender) --- src/content/docs/en/reference/integrations-reference.mdx | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index e3ecd2762219d..029bf23f6c5ef 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -548,7 +548,14 @@ const integration = { An object with a `component` property to identify the route and the following additional values to allow you to configure the generated route: `prerender`. -The `component` property is a readonly string path relative to the project root, e.g `"src/pages/blog/[slug].astro"`. +##### `route.component` + +

+**Type:** `string`
+ +

+ +The `component` property is a readonly string path relative to the project root, e.g `"src/pages/blog/[slug].astro"`. Its value helps you identify the route being set up. ##### `route.prerender` From e761fbee24c02026b18d7c9efbe8774edb871de2 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Tue, 4 Feb 2025 21:30:04 +0100 Subject: [PATCH 31/34] Apply Fryuni's suggestions from code review Co-authored-by: Luiz Ferraz --- src/content/docs/en/reference/integrations-reference.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 029bf23f6c5ef..5a7acf2fb9217 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -599,9 +599,9 @@ If the final value after running all the hooks is `undefined`, the route will fa **Previous hook:** [`astro:route:setup`](#astroroutesetup) -**Next hook:** [`astro:config:done`](#astroconfigdone) +**Next hook:** [`astro:config:done`](#astroconfigdone) (only during setup) -**When:** In `astro dev`, it also runs if a file based route changes (added/removed/updated). +**When:** In `astro dev`, it also runs on every change to a file based route (added/removed/updated). **Why:** To access routes and their metadata From 142515278c5b31f267b4433215dae464982755fc Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Wed, 5 Feb 2025 12:29:35 +0100 Subject: [PATCH 32/34] remove the deprecated option from the Quick API reference --- src/content/docs/en/reference/integrations-reference.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 5a7acf2fb9217..42c5a70a91d23 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -90,8 +90,6 @@ interface AstroIntegration { 'astro:build:done'?: (options: { pages: { pathname: string }[]; dir: URL; - /** @deprecated Use the `assets` map and the new `astro:routes:resolved` hook */ - routes: IntegrationRouteData[]; assets: Map; logger: AstroIntegrationLogger; }) => void | Promise; From 414a5c910a3d26be16773cea5c5117e2ba8c51b0 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Wed, 5 Feb 2025 14:48:37 +0100 Subject: [PATCH 33/34] more accurate `When` description for `astro:route:setup` Co-authored-by: Luiz Ferraz --- src/content/docs/en/reference/integrations-reference.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 42c5a70a91d23..77484bb0e757b 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -526,7 +526,7 @@ const integration = { **Next hook:** [`astro:routes:resolved`](#astroroutesresolved) -**When:** In `astro dev`, whenever a route is requested. In `astro build`, while bundling and transforming a route file. +**When:** In `astro build`, before bundling starts. In `astro dev`, while building the module graph and on every change to a file based route (added/removed/updated). **Why:** To set options for a route at build or request time, such as enabling [on-demand server rendering](/en/guides/on-demand-rendering/#enabling-on-demand-rendering). From bd09702af3c7770a892b7c3c52dd03379bf7e204 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Thu, 6 Feb 2025 16:25:04 +0100 Subject: [PATCH 34/34] Apply edits from T&D Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Co-authored-by: HiDeoo <494699+HiDeoo@users.noreply.github.com> --- src/content/docs/en/reference/integrations-reference.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index 77484bb0e757b..8013912697ff2 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -553,7 +553,7 @@ An object with a `component` property to identify the route and the following ad

-The `component` property is a readonly string path relative to the project root, e.g `"src/pages/blog/[slug].astro"`. Its value helps you identify the route being set up. +The `component` property indicates the entrypoint that will be rendered on the route. You can access this value before the routes are built to configure on-demand server rendering for that page. ##### `route.prerender` @@ -780,7 +780,7 @@ A function that takes an event name as first argument and a callback function as **Type:** `(appId: string, callback: (data: Record) => void) => void`

-A function fired when a dev toolbar app is initialized. The first argument is the id of the app that was initialized. The second argument is callback function to run when the app is initialized. +A function fired when a dev toolbar app is initialized. The first argument is the id of the app that was initialized. The second argument is a callback function to run when the app is initialized. ##### `onAppToggled()` @@ -798,7 +798,7 @@ A function fired when a dev toolbar app is toggled on or off. The first argument **Type:** `(event: string, payload: T) => void`

-A function that takes an event name as first argument and a payload as second argument. The payload can be any serializable data. This allows you to send a message to the dev toolbar that an app can listen for. +A function that sends a message to the dev toolbar that an app can listen for. This takes an event name as the first argument and a payload as the second argument which can be any serializable data. #### `refreshContent()` option @@ -1275,7 +1275,7 @@ configured via CLI. - `logger.error("Message")`; - `logger.debug("Message")`; -All the messages are prepended with a label that has the same value of the integration. +All the messages are prepended with a label that has the same value as the name of the integration. ```ts title="integration.ts" {8} import type { AstroIntegration } from "astro";