;
```
+
#### `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:
@@ -701,7 +754,53 @@ export default {
}
```
-#### `refreshContent` option
+#### `toolbar` option
+
+
+
+**Type:** `ReturnType`
+
+
+
+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 a 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 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
@@ -716,44 +815,43 @@ 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 }));
+ }
+ });
+ });
}
+ }
}
```
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)
@@ -765,12 +863,18 @@ 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
+
+
**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).
@@ -783,7 +887,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`
@@ -797,7 +903,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`
@@ -821,46 +929,249 @@ The address, family and port number supplied by the [Node.js Net module](https:/
```
-### `astro:build:generated`
+#### `vite` option
-**Previous hook:** [`astro:build:setup`](#astrobuildsetup)
+
-**When:** After a static production build has finished generating routes and assets.
+**Type:** [`InlineConfig`](https://vite.dev/guide/api-javascript.html#inlineconfig)
+
-**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.
+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
-'astro:build:generated'?: (options: { dir: URL }) => void | Promise;
+export default {
+ name: 'my-integration',
+ hooks: {
+ 'astro:build:setup': ({ vite }) => {
+ const { publicDir, root } = vite;
+ },
+ }
+}
```
-### `astro:build:ssr`
+#### `pages` option
-**Previous hook:** [`astro:build:setup`](#astrobuildsetup)
+
-**When:** After a production SSR build has completed.
+**Type:** Map\PageBuildData\>
+
-**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.
-- `entryPoints` maps a page route to the physical file emitted after the build;
-- `middlewareEntryPoint` is the file system path of the middleware file;
+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
-'astro:build:ssr'?: (options: {
- manifest: SerializedSSRManifest,
- entryPoints: Map,
- middlewareEntryPoint: URL
-}) => void | Promise;
+export default {
+ name: 'my-integration',
+ hooks: {
+ 'astro:build:setup': ({ pages }) => {
+ pages.forEach((data) => {
+ if (data.route.pattern.test("/blog")) {
+ console.log(data.route.type);
+ }
+ });
+ },
+ }
+}
```
-### `astro:build:done`
+#### `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: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.
+- `entryPoints` maps a page route to the physical file emitted after the build;
+- `middlewareEntryPoint` is the file system path of the middleware file;
+
+```js
+'astro:build:ssr'?: (options: {
+ manifest: SerializedSSRManifest;
+ entryPoints: Map;
+ middlewareEntryPoint: URL | undefined;
+ logger: AstroIntegrationLogger;
+}) => void | Promise;
+```
+
+#### `manifest` option
+
+
+
+**Type:** [`SerializedSSRManifest`](https://github.com/withastro/astro/blob/3b10b97a4fecd1dfd959b160a07b5b8427fe40a7/packages/astro/src/core/app/types.ts#L91-L109)
+
+
+Allows you to create a custom build by accessing the SSR manifest.
+
+```js
+export default {
+ name: 'my-integration',
+ hooks: {
+ 'astro:build:ssr': ({ manifest }) => {
+ const { i18n } = manifest;
+ if (i18n?.strategy === "domains-prefix-always") {
+ // do something
+ }
+ },
+ },
+}
+```
+
+#### `entryPoints` option
+
+
+
+**Type:** Map\<IntegrationRouteData, URL\>
+
+
+
+A `Map` of the emitted entry points with the `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](/en/guides/middleware/) file path.
+
+```js
+export default {
+ name: 'my-integration',
+ hooks: {
+ 'astro:build:ssr': ({ middlewareEntryPoint }) => {
+ if (middlewareEntryPoint) {
+ // do some operations if a middleware exist
+ }
+ },
+ },
+}
+```
+
+### `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.
```js
'astro:build:done'?: (options: {
+ pages: { pathname: string }[];
dir: URL;
/** @deprecated Use the `assets` map and the new `astro:routes:resolved` hook */
routes: IntegrationRouteData[];
@@ -871,7 +1182,10 @@ The address, family and port number supplied by the [Node.js Net module](https:/
#### `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.
@@ -899,7 +1213,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.
@@ -908,159 +1225,107 @@ 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
-
+
-**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.
- `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.
+### Custom hooks
-**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).
+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).
-```js
-'astro:route:setup'?: (options: { route: RouteOptions }) => void | Promise;
+```ts
+declare global {
+ namespace Astro {
+ export interface IntegrationHook {
+ 'your:hook': (params: YourHookParameters) => 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`.
+Astro reserves the `astro:` prefix for future built-in hooks. Please choose a different prefix when naming your custom hook.
-The `component` property is a readonly string path relative to the project root, e.g `"src/pages/blog/[slug].astro"`.
+## Integration types reference
-##### `route.prerender`
+### `AstroIntegrationLogger`
-
-**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`.
+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.
-```js title="astro.config.mjs"
-import { defineConfig } from 'astro/config';
+**Methods available** to write to terminal:
+- `logger.info("Message")`;
+- `logger.warn("Message")`;
+- `logger.error("Message")`;
+- `logger.debug("Message")`;
-export default defineConfig({
- integrations: [setPrerender()],
-});
+All the messages are prepended with a label that has the same value as the name of the integration.
-function setPrerender() {
+```ts title="integration.ts" {8}
+import type { AstroIntegration } from "astro";
+export function formatIntegration(): AstroIntegration {
return {
- name: 'set-prerender',
+ name: "astro-format",
hooks: {
- 'astro:route:setup': ({ route }) => {
- if (route.component.endsWith('/blog/[slug].astro')) {
- route.prerender = true;
- }
- },
- },
- };
+ "astro:build:done": ({ logger }) => {
+ // do something
+ logger.info("Integration ready.");
+ }
+ }
+ }
}
```
-
-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
+The example above will log a message that includes the provided `info` message:
-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).
+```shell
+[astro-format] Integration ready.
+```
-```ts
-declare global {
- namespace Astro {
- export interface IntegrationHook {
- 'your:hook': (params: YourHookParameters) => Promise
+To log some messages with a different label, use the `.fork` method to specify an alternative to the default `name`:
+
+```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.")
+ }
}
}
}
```
-Astro reserves the `astro:` prefix for future built-in hooks. Please choose a different prefix when naming your custom hook.
+The example above will produce logs with `[astro-format]` by default, and `[astro-format/build]` when specified:
+
+```shell
+[astro-format] Integration ready.
+[astro-format/build] Build finished.
+```
### `HookParameters`
@@ -1074,96 +1339,330 @@ function mySetup(options: HookParameters<'astro:config:setup'>) {
}
```
-## 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`**:
+### `IntegrationResolvedRoute` type reference
-```json
-{
- "name": "example",
- "keywords": ["astro-integration"],
+```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';
}
```
-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:
+#### `pattern`
-```diff
-// astro.config.mjs
-import { defineConfig } from 'astro/config';
-+ import example from 'example';
+
-export default defineConfig({
-+ integrations: [example()],
-})
+**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`
```
-:::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!
-:::
+#### `params`
-## `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.
+**Type:** `string[]`
+
-**Methods available** to write to terminal:
-- `logger.info("Message")`;
-- `logger.warn("Message")`;
-- `logger.error("Message")`;
-- `logger.debug("Message")`;
+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']`.
-All the messages are prepended with a label that has the same value of the integration.
+#### `pathname`
-```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.");
- }
- }
- }
+
+
+**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` type reference
+
+:::caution
+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.
+
+```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;
}
```
-The example above will log a message that includes the provided `info` message:
+#### `type`
-```shell
-[astro-format] Integration ready.
+
+
+**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`
```
-To log some messages with a different label, use the `.fork` method to specify an alternative to the default `name`:
+#### `prerender`
-```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.")
- }
- }
- }
+
+
+**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"],
}
```
-The example above will produce logs with `[astro-format]` by default, and `[astro-format/build]` when specified:
+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:
-```shell
-[astro-format] Integration ready.
-[astro-format/build] Build finished.
+```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`.