diff --git a/src/content/docs/en/guides/upgrade-to/v5.mdx b/src/content/docs/en/guides/upgrade-to/v5.mdx index ae8b246b011d7..8b2c6157f1c16 100644 --- a/src/content/docs/en/guides/upgrade-to/v5.mdx +++ b/src/content/docs/en/guides/upgrade-to/v5.mdx @@ -1111,7 +1111,7 @@ function useRoute(route: IntegrationRouteData) { } ``` -See the [API reference for `IntegrationRouteData`](/en/reference/integrations-reference/#integrationroutedata-type-reference). +See the [API reference for `IntegrationRouteData`](/en/reference/integrations-reference/#integrationroutedata). ### Changed: `distURL` is now an array (Integrations API) @@ -1138,7 +1138,7 @@ if (route.distURL) { } ``` -See the [API reference for `IntegrationRouteData`](/en/reference/integrations-reference/#integrationroutedata-type-reference). +See the [API reference for `IntegrationRouteData`](/en/reference/integrations-reference/#integrationroutedata). ### Changed: Arguments passed to `app.render()` (Adapter API) diff --git a/src/content/docs/en/reference/adapter-reference.mdx b/src/content/docs/en/reference/adapter-reference.mdx index a08e35d1b6b25..7313348ed0cb4 100644 --- a/src/content/docs/en/reference/adapter-reference.mdx +++ b/src/content/docs/en/reference/adapter-reference.mdx @@ -476,11 +476,11 @@ If not provided, Astro will fallback to its default behavior for fetching error

-**Type:** `RouteData`
+**Type:** [`RouteData`](/en/reference/integrations-reference/#routedata)
**Default:** `app.match(request)`

-Provides a value for [`integrationRouteData`](/en/reference/integrations-reference/#integrationroutedata-type-reference) if you already know the route to render. Doing so will bypass the internal call to [`app.match()`](#appmatch) to determine the route to render. +Defines the information about a route. This is useful when you already know the route to render. Doing so will bypass the internal call to [`app.match()`](#appmatch) to determine the route to render. ```js "routeData" const routeData = app.match(request); diff --git a/src/content/docs/en/reference/integrations-reference.mdx b/src/content/docs/en/reference/integrations-reference.mdx index b24c204fa85ea..d7b824679d128 100644 --- a/src/content/docs/en/reference/integrations-reference.mdx +++ b/src/content/docs/en/reference/integrations-reference.mdx @@ -614,7 +614,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. @@ -1075,7 +1075,7 @@ export default {

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

@@ -1215,7 +1215,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. @@ -1233,7 +1233,7 @@ You can reference the full `IntegrationRouteData` type below, but the most commo

-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 @@ -1264,6 +1264,23 @@ Astro reserves the `astro:` prefix for future built-in hooks. Please choose a di ## Integration types reference +The following types can be imported from the `astro` module: + +```ts +import type { + AstroIntegrationLogger, + HookParameters, + IntegrationResolvedRoute, + RedirectConfig, + RouteData, + RoutePart, + RouteType, + ValidRedirectStatus, + // The following are deprecated: + IntegrationRouteData, +} from "astro"; +``` + ### `AstroIntegrationLogger` An instance of the Astro logger, useful to write logs. This logger uses the same [log level](/en/reference/cli-reference/#--verbose) @@ -1339,22 +1356,20 @@ function mySetup(options: HookParameters<'astro:config:setup'>) { } ``` -### `IntegrationResolvedRoute` type reference +### `IntegrationResolvedRoute` + +A subset of [`RouteData`](#routedata) with remapped properties. ```ts -interface IntegrationResolvedRoute { +interface IntegrationResolvedRoute extends Pick< + RouteData, + 'generate' | 'params' | 'pathname' | 'segments' | 'type' | 'redirect' | 'origin' + > & { 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'; } ``` @@ -1362,7 +1377,7 @@ interface IntegrationResolvedRoute {

-**Type:** `string` +**Type:** [`RouteData['route']`](#route)

Allows you to identify the type of route based on its path. Here are some examples of paths associated with their pattern: @@ -1374,7 +1389,7 @@ Allows you to identify the type of route based on its path. Here are some exampl

-**Type:** `RegExp` +**Type:** [`RouteData['pattern']`](#pattern-1)

Allows you to access a regex used for matching an input URL against a requested route. @@ -1385,7 +1400,7 @@ For example, given a `[fruit]/about.astro` path, the regex will be `/^\/([^/]+?)

-**Type:** `string` +**Type:** [`RouteData['component']`](#component)

The URL pathname of the source component. @@ -1394,7 +1409,7 @@ The URL pathname of the source component.

-**Type:** `boolean` +**Type:** [`RouteData['prerender']`](#prerender)

Determines whether the route use [on demand rendering](/en/guides/on-demand-rendering/). The value will be `true` for projects configured with: @@ -1410,6 +1425,40 @@ Determines whether the route use [on demand rendering](/en/guides/on-demand-rend When the value of `IntegrationResolvedRoute.type` is `redirect`, the value will be the `IntegrationResolvedRoute` to redirect to. Otherwise, the value will be undefined. +### `RedirectConfig` + +

+ +**Type:** string | \{ status: ValidRedirectStatus; destination: string; \} +

+ +Describes the destination of a redirect. This can be a string or an object containing information about the status code and its destination. + +### `RouteData` + +Describes the information about a route. This contains the following properties: + +#### `route` + +

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

+ +Defines the current route pattern. 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]` + +#### `component` + +

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

+ +Specifies the source component URL. + #### `generate()`

@@ -1419,10 +1468,10 @@ When the value of `IntegrationResolvedRoute.type` is `redirect`, the value will 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: +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` +generate({ id: 'presentation' }) // will output `/blog/presentation` ``` #### `params` @@ -1443,11 +1492,32 @@ Allows you to access the route `params`. For example, when a project uses the fo 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. +#### `distURL` + +

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

+ +Defines 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. + +#### `pattern` + +

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

+ +Specifies a regex to use 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`. + #### `segments`

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

Allows you to access the route [`params`](#params) with additional metadata. Each object contains the following properties: @@ -1469,172 +1539,160 @@ For example, the following route `/pages/[blog]/[...slug].astro` will output the

-**Type:** `RouteType` +**Type:** [`RouteType`](#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 +Allows you to identify the [type of route](#routetype). -#### `redirect` +#### `prerender`

-**Type:** RedirectConfig | undefined +**Type:** `boolean`

-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. +Determines whether a route uses [on demand rendering](/en/guides/on-demand-rendering/) or is statically prerendered at build time. -#### `origin` +See also [`prerendered`](/en/reference/routing-reference/#prerender) in the routing reference. + +#### `redirect`

-**Type:** `'internal' | 'external' | 'project'` +**Type:** RedirectConfig | undefined

-Determines if a route comes from Astro core (`internal`), an integration (`external`) or the user's project (`project`). +Allows you to access the route to redirect to. -### `IntegrationRouteData` type reference +#### `redirectRoute` -:::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. +**Type:** `RouteData | undefined` +

-```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; -} -``` +Specifies the `RouteData` to redirect to when [`RouteData.type`](#type) is `redirect`. -#### `type` +#### `fallbackRoutes`

-**Type:** `RouteType` +**Type:** `RouteData[]`
+

-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 +Defines a list of `RouteData` to fallback to when [`i18n.fallback`](/en/reference/configuration-reference/#i18nfallback) has a list of locales. -#### `component` +#### `isIndex`

-**Type:** `string` +**Type:** `boolean`

-Allows you to access the source component URL pathname. +Specifies if the route is a directory index (e.g. `src/pages/index.astro`, `src/pages/blog/index.astro`). -#### `pathname` +#### `origin`

-**Type:** `string | undefined` +**Type:** `'internal' | 'external' | 'project'`
+

-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. +Determines if a route comes from Astro core (`internal`), an integration (`external`) or the user's project (`project`). -#### `pattern` +### `RoutePart`

-**Type:** `RegExp` +**Type:** `{ content: string; dynamic: boolean; spread: boolean; }`

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

-**Type:** `string[]` +**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']`. +Specifies the parameter name for the route. For example: +* `about.astro` has the name `about` +* `[slug].astro` has the name `slug` +* `[...id].astro` has the name `id` -#### `segments` +#### `dynamic`

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

-Allows you to access the route [`params`](#params-1) with additional metadata. Each object contains the following properties: -* `content`: the `param`, -* `dynamic`: whether 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 } ]]`. +Whether the route is dynamic or not. -#### `generate()` +#### `spread`

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

-A function that provides the optional parameters of the route, interpolates them with the route pattern, and returns the path name of the route. +Whether the dynamic route uses the spread syntax or not. -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` +### `RouteType`

-**Type:** `boolean` +**Type:** `'page' | 'endpoint' | 'redirect' | 'fallback'`

-Determines whether the route is prerendered or not. +A union of supported route types: -#### `distURL` +* `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 a middleware + +### `ValidRedirectStatus`

-**Type:** `URL[] | undefined` +**Type:** `301 | 302 | 303 | 307 | 308 | 300 | 304`

-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. +A union of supported redirect status code. -#### `redirect` +### Deprecated type imports -

+The following types are deprecated and will be removed in a future major version: -**Type:** RedirectConfig | undefined -

+#### `IntegrationRouteData` -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. +:::caution +This type is deprecated since v5.0. Use [`IntegrationResolvedRoute`](#integrationresolvedroute) instead. +::: -#### `redirectRoute` +A smaller version of the [`RouteData`](#routedata) that is used in the integrations. + +```ts +type IntegrationRouteData = Omit< + RouteData, + 'isIndex' | 'fallbackRoutes' | 'redirectRoute' | 'origin' +> & { + redirectRoute?: IntegrationRouteData; +}; +``` + +##### `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. +When the value of [`RouteData.type`](#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`