From 1dd07112573dc267386b5f746a799cb4e05e2c13 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Mon, 15 Sep 2025 13:46:39 +0200 Subject: [PATCH 1/4] fix(integrations-guide): add/format the API references block --- .../en/guides/integrations-guide/alpinejs.mdx | 9 +++- .../docs/en/guides/integrations-guide/db.mdx | 32 +++++++++++--- .../en/guides/integrations-guide/markdoc.mdx | 18 +++++++- .../docs/en/guides/integrations-guide/mdx.mdx | 29 ++++++++++--- .../guides/integrations-guide/partytown.mdx | 22 ++++++++-- .../en/guides/integrations-guide/preact.mdx | 16 +++++-- .../en/guides/integrations-guide/solid-js.mdx | 9 ++-- .../en/guides/integrations-guide/vercel.mdx | 43 +++++++++++++++---- .../docs/en/guides/integrations-guide/vue.mdx | 24 +++++++++-- 9 files changed, 167 insertions(+), 35 deletions(-) diff --git a/src/content/docs/en/guides/integrations-guide/alpinejs.mdx b/src/content/docs/en/guides/integrations-guide/alpinejs.mdx index 6c4bf5527d157..247db15888b40 100644 --- a/src/content/docs/en/guides/integrations-guide/alpinejs.mdx +++ b/src/content/docs/en/guides/integrations-guide/alpinejs.mdx @@ -8,7 +8,8 @@ githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/int category: renderer i18nReady: true --- -import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' +import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; +import Since from '~/components/Since.astro'; This **[Astro integration][astro-integration]** adds [Alpine.js](https://alpinejs.dev/) to your project so that you can use Alpine.js anywhere on your page. @@ -96,6 +97,12 @@ export default defineConfig({ ### `entrypoint` +

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

+ You can extend Alpine by setting the `entrypoint` option to a root-relative import specifier (e.g. `entrypoint: "/src/entrypoint"`). The default export of this file should be a function that accepts an Alpine instance prior to starting. This allows the use of custom directives, plugins and other customizations for advanced use cases. diff --git a/src/content/docs/en/guides/integrations-guide/db.mdx b/src/content/docs/en/guides/integrations-guide/db.mdx index b9fa37733f49b..e6f98d12e64b1 100644 --- a/src/content/docs/en/guides/integrations-guide/db.mdx +++ b/src/content/docs/en/guides/integrations-guide/db.mdx @@ -11,6 +11,7 @@ i18nReady: true import { FileTree } from '@astrojs/starlight/components'; import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; import ReadMore from '~/components/ReadMore.astro'; +import Since from '~/components/Since.astro'; Astro DB is a fully-managed SQL database designed for the Astro ecosystem: develop locally in Astro and deploy to any [libSQL-compatible database](/en/guides/astro-db/). @@ -96,6 +97,11 @@ export default defineDb({ ### `columns` +

+ +**Type:** `ColumnsConfig` +

+ Table columns are configured using the `columns` object: ```ts @@ -151,6 +157,11 @@ type UserTableInferInsert = { ### `indexes` +

+ +**Type:** `{ on: string | string[]; unique?: boolean | undefined; name?: string | undefined; }[]` +

+ Table indexes are used to improve lookup speeds on a given column or combination of columns. The `indexes` property accepts an array of configuration objects specifying the columns to index: ```ts title="db/config.ts" {9-11} @@ -172,12 +183,17 @@ This will generate a unique index on the `authorId` and `published` columns with The following configuration options are available for each index: -- `on`: `string | string[]` - A single column or array of column names to index. -- `unique`: `boolean` - Set to `true` to enforce unique values across the indexed columns. -- `name`: `string` (optional) - A custom name for the unique index. This will override Astro's generated name based on the table and column names being indexed (e.g. `Comment_authorId_published_idx`). Custom names are global, so ensure index names do not conflict between tables. +- `on` - A single column or array of column names to index. +- `unique` - Set to `true` to enforce unique values across the indexed columns. +- `name` (optional) - A custom name for the unique index. This will override Astro's generated name based on the table and column names being indexed (e.g. `Comment_authorId_published_idx`). Custom names are global, so ensure index names do not conflict between tables. ### `foreignKeys` +

+ +**Type:** `{ columns: string | string[]; references: () => Column | Column[]; }[]` +

+ :::tip `foreignKeys` is an advanced API for relating multiple table columns. If you only need to reference a single column, try using [the column `references` property.](#columns) @@ -213,8 +229,8 @@ const Comment = defineTable({ Each foreign key configuration object accepts the following properties: -- `columns`: `string[]` - An array of column names to relate to the referenced table. -- `references`: `() => Column[]` - A function that returns an array of columns from the referenced table. +- `columns` - A single column or array of column names to relate to the referenced table. +- `references` - A function that returns a single column or an array of columns from the referenced table. ## Astro DB CLI reference @@ -255,6 +271,12 @@ Execute a raw SQL query against your database. Use the `--remote` flag to run ag ### `isDbError()` +

+ +**Type:** `(err: unknown) => boolean`
+ +

+ The `isDbError()` function checks if an error is a libSQL database exception. This may include a foreign key constraint error when using references, or missing fields when inserting data. You can combine `isDbError()` with a try / catch block to handle database errors in your application: ```ts title="src/pages/api/comment/[id].ts" "idDbError" diff --git a/src/content/docs/en/guides/integrations-guide/markdoc.mdx b/src/content/docs/en/guides/integrations-guide/markdoc.mdx index edd27c10e453f..9e6a0539580e1 100644 --- a/src/content/docs/en/guides/integrations-guide/markdoc.mdx +++ b/src/content/docs/en/guides/integrations-guide/markdoc.mdx @@ -8,10 +8,10 @@ githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/int category: other i18nReady: true --- -import { FileTree } from '@astrojs/starlight/components'; +import { FileTree, Steps } from '@astrojs/starlight/components'; import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'; -import { Steps } from '@astrojs/starlight/components'; import ReadMore from '~/components/ReadMore.astro'; +import Since from '~/components/Since.astro'; This **[Astro integration][astro-integration]** enables the usage of [Markdoc](https://markdoc.dev/) to create components, pages, and content collection entries. @@ -593,6 +593,13 @@ The Astro Markdoc integration handles configuring Markdoc options and capabiliti ### `allowHTML` +

+ +**Type:** `boolean`
+**Default:** `false`
+ +

+ Enables writing HTML markup alongside Markdoc tags and nodes. By default, Markdoc will not recognize HTML markup as semantic content. @@ -615,6 +622,13 @@ When `allowHTML` is enabled, HTML markup inside Markdoc documents will be render ### `ignoreIndentation` +

+ +**Type:** `boolean`
+**Default:** `false`
+ +

+ By default, any content that is indented by four spaces is treated as a code block. Unfortunately, this behavior makes it difficult to use arbitrary levels of indentation to improve the readability of documents with complex structure. When using nested tags in Markdoc, it can be helpful to indent the content inside of tags so that the level of depth is clear. To support arbitrary indentation, we have to disable the indent-based code blocks and modify several other markdown-it parsing rules that account for indent-based code blocks. These changes can be applied by enabling the ignoreIndentation option. diff --git a/src/content/docs/en/guides/integrations-guide/mdx.mdx b/src/content/docs/en/guides/integrations-guide/mdx.mdx index cf984dc08dc86..87c0be17a2c37 100644 --- a/src/content/docs/en/guides/integrations-guide/mdx.mdx +++ b/src/content/docs/en/guides/integrations-guide/mdx.mdx @@ -271,8 +271,12 @@ MDX does not support passing remark and rehype plugins as a string. You should i ### `extendMarkdownConfig` -* **Type:** `boolean` -* **Default:** `true` +

+ +**Type:** `boolean`
+**Default:** `true`
+ +

MDX will extend [your project's existing Markdown configuration](/en/reference/configuration-reference/#markdown-options) by default. To override individual options, you can specify their equivalent in your MDX configuration. @@ -326,13 +330,25 @@ export default defineConfig({ ### `recmaPlugins` +

+ +**Type:** `PluggableList`
+**Default:** `[]`
+ +

+ These are plugins that modify the output [estree](https://github.com/estree/estree) directly. This is useful for modifying or injecting JavaScript variables in your MDX files. We suggest [using AST Explorer](https://astexplorer.net/) to play with estree outputs, and trying [`estree-util-visit`](https://unifiedjs.com/explore/package/estree-util-visit/) for searching across JavaScript nodes. ### `optimize` -* **Type:** `boolean | { ignoreElementNames?: string[] }` +

+ +**Type:** `boolean | { ignoreElementNames?: string[] }`
+**Default:** `false`
+ +

This is an optional configuration setting to optimize the MDX output for faster builds and rendering via an internal rehype plugin. This may be useful if you have many MDX files and notice slow builds. However, this option may generate some unescaped HTML, so make sure your site's interactive parts still work correctly after enabling it. @@ -354,9 +370,12 @@ export default defineConfig({ #### `ignoreElementNames` -* **Type:** `string[]` +

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

-

Previously known as `customComponentNames`. An optional property of `optimize` to prevent the MDX optimizer from handling certain element names, like [custom components passed to imported MDX content via the components prop](/en/guides/integrations-guide/mdx/#custom-components-with-imported-mdx). diff --git a/src/content/docs/en/guides/integrations-guide/partytown.mdx b/src/content/docs/en/guides/integrations-guide/partytown.mdx index 3d20790b7bb40..c4e800dcde66d 100644 --- a/src/content/docs/en/guides/integrations-guide/partytown.mdx +++ b/src/content/docs/en/guides/integrations-guide/partytown.mdx @@ -110,7 +110,12 @@ export default defineConfig({ This mirrors the [Partytown config object](https://partytown.qwik.dev/configuration/). -### config.debug +### `config.debug` + +

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

Partytown ships with a `debug` mode; enable or disable it by passing `true` or `false` to `config.debug`. If [`debug` mode](https://partytown.qwik.dev/debugging) is enabled, it will output detailed logs to the browser console. @@ -128,7 +133,12 @@ export default defineConfig({ }); ``` -### config.forward +### `config.forward` + +

+ +**Type:** `PartytownForwardProperty[]` +

Third-party scripts typically add variables to the `window` object so that you can communicate with them throughout your site. But when a script is loaded in a web-worker, it doesn't have access to that global `window` object. @@ -150,7 +160,12 @@ export default defineConfig({ }); ``` -### config.resolveUrl +### `config.resolveUrl` + +

+ +**Type:** `(url: URL, location: Location, type: ResolveUrlType) => URL | undefined | null` +

Some third-party scripts may require [proxying](https://partytown.qwik.dev/proxying-requests/) through `config.resolveUrl()`, which runs inside the service worker. You can set this configuration option to check for a specific URL, and optionally return a proxied URL instead: @@ -211,4 +226,3 @@ Note that the integration config will override `window.partytown` if you set a p * [Optimise Google Analytics using Partytown in Astro](https://ricostacruz.com/posts/google-analytics-in-astro) [astro-integration]: /en/guides/integrations-guide/ - diff --git a/src/content/docs/en/guides/integrations-guide/preact.mdx b/src/content/docs/en/guides/integrations-guide/preact.mdx index e5eaef3432121..227cf8ba8fc61 100644 --- a/src/content/docs/en/guides/integrations-guide/preact.mdx +++ b/src/content/docs/en/guides/integrations-guide/preact.mdx @@ -133,7 +133,13 @@ The Astro Preact integration handles how Preact components are rendered and it h For basic usage, you do not need to configure the Preact integration. -### compat +### `compat` + +

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

You can enable `preact/compat`, Preact’s compatibility layer for rendering React components without needing to install or ship React’s larger libraries to your users’ web browsers. @@ -167,9 +173,13 @@ Check out the [`pnpm` overrides](https://pnpm.io/package_json#pnpmoverrides) and Currently, the `compat` option only works for React libraries that export code as ESM. If an error happens during build-time, try adding the library to `vite.ssr.noExternal: ['the-react-library']` in your `astro.config.mjs` file. ::: -### devtools +### `devtools` + +

-

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

You can enable [Preact devtools](https://preactjs.github.io/preact-devtools/) in development by passing an object with `devtools: true` to your `preact()` integration config: diff --git a/src/content/docs/en/guides/integrations-guide/solid-js.mdx b/src/content/docs/en/guides/integrations-guide/solid-js.mdx index af72e6497a11b..cc102b30d4c45 100644 --- a/src/content/docs/en/guides/integrations-guide/solid-js.mdx +++ b/src/content/docs/en/guides/integrations-guide/solid-js.mdx @@ -117,9 +117,13 @@ To use your first SolidJS component in Astro, head to our [UI framework document ## Configuration -### devtools +### `devtools` -

+

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

You can enable [Solid DevTools](https://github.com/thetarnav/solid-devtools) in development by passing an object with `devtools: true` to your `solid()` integration config and adding `solid-devtools` to your project dependencies: @@ -232,4 +236,3 @@ Feel free to add additional Suspense boundaries according to your preference. [solid-create-resource]: https://www.solidjs.com/docs/latest/api#createresource [solid-lazy-components]: https://www.solidjs.com/docs/latest/api#lazy - diff --git a/src/content/docs/en/guides/integrations-guide/vercel.mdx b/src/content/docs/en/guides/integrations-guide/vercel.mdx index 742d16d94ba76..c6cdbb4c8576f 100644 --- a/src/content/docs/en/guides/integrations-guide/vercel.mdx +++ b/src/content/docs/en/guides/integrations-guide/vercel.mdx @@ -101,9 +101,12 @@ To configure this adapter, pass an object to the `vercel()` function call in `as ### `webAnalytics` +

+ **Type:** `VercelWebAnalyticsConfig`
**Available for:** Serverless, Static
+

With `@vercel/analytics@1.3.x` or earlier, you can set `webAnalytics: { enabled: true }` in your Astro config to inject Vercel’s tracking scripts into all of your pages. @@ -125,9 +128,12 @@ export default defineConfig({ ### `imagesConfig` +

+ **Type:** `VercelImageConfig`
-**Available for:** Serverless, Static +**Available for:** Serverless, Static
+

Configuration options for [Vercel's Image Optimization API](https://vercel.com/docs/concepts/image-optimization). See [Vercel's image configuration documentation](https://vercel.com/docs/build-output-api/v3/configuration#images) for a complete list of supported parameters. @@ -150,9 +156,12 @@ export default defineConfig({ ### `imageService` +

+ **Type:** `boolean`
-**Available for:** Serverless, Static +**Available for:** Serverless, Static
+

When enabled, an [Image Service](/en/reference/image-service-reference/) powered by the Vercel Image Optimization API will be automatically configured and used in production. In development, the image service specified by [`devImageService`](#devimageservice) will be used instead. @@ -191,10 +200,13 @@ import astroLogo from '../assets/logo.png'; ### `devImageService` +

+ **Type:** `'sharp' | string`
-**Available for:** Serverless, Static +**Default:** `sharp`
+**Available for:** Serverless, Static
-**Default**: `sharp` +

Allows you to configure which image service to use in development when [imageService](#imageservice) is enabled. This can be useful if you cannot install Sharp's dependencies on your development machine, but using another image service like Squoosh would allow you to preview images in your dev environment. Build is unaffected and will always use Vercel's Image Optimization. @@ -215,10 +227,13 @@ export default defineConfig({ ### `isr` -**Type:** boolean | VercelISRConfig
-**Available for:** Serverless +

+ +**Type:** `boolean | VercelISRConfig`
+**Default:** `false`
+**Available for:** Serverless
-**Default**: `false` +

Allows your project to be deployed as an [ISR (Incremental Static Regeneration)](https://vercel.com/docs/incremental-static-regeneration) function, which caches your on-demand rendered pages in the same way as prerendered pages after first request. @@ -287,8 +302,11 @@ export default defineConfig({ ### `includeFiles` +

+ **Type:** `string[]`
**Available for:** Serverless +

Use this property to force files to be bundled with your function. This is helpful when you notice missing files. @@ -306,8 +324,11 @@ export default defineConfig({ ### `excludeFiles` +

+ **Type:** `string[]`
**Available for:** Serverless +

Use this property to exclude any files from the bundling process that would otherwise be included. @@ -325,8 +346,11 @@ export default defineConfig({ ### `maxDuration` +

+ **Type:** `number`
**Available for:** Serverless +

Use this property to extend or limit the maximum duration (in seconds) that Serverless Functions can run before timing out. See the [Vercel documentation](https://vercel.com/docs/functions/serverless-functions/runtimes#maxduration) for the default and maximum limit for your account plan. @@ -344,9 +368,12 @@ export default defineConfig({ ### `skewProtection` +

+ **Type:** `boolean`
-**Available for:** Serverless +**Available for:** Serverless
+

Use this property to enable [Vercel Skew protection](https://vercel.com/docs/deployments/skew-protection) (available with Vercel Pro and Enterprise accounts). diff --git a/src/content/docs/en/guides/integrations-guide/vue.mdx b/src/content/docs/en/guides/integrations-guide/vue.mdx index 004d64c8b230e..71f055723d4de 100644 --- a/src/content/docs/en/guides/integrations-guide/vue.mdx +++ b/src/content/docs/en/guides/integrations-guide/vue.mdx @@ -140,7 +140,13 @@ export default defineConfig({ }); ``` -### appEntrypoint +### `appEntrypoint` + +

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

You can extend the Vue `app` instance setting the `appEntrypoint` option to a root-relative import specifier (for example, `appEntrypoint: "/src/pages/_app"`). @@ -165,7 +171,13 @@ export default (app: App) => { }; ``` -### jsx +### `jsx` + +

+ +**Type:** `boolean | object`
+ +

You can use Vue JSX by setting `jsx: true`. @@ -198,9 +210,13 @@ export default defineConfig({ }); ``` -### devtools +### `devtools` + +

-

+**Type:** `boolean | object`
+ +

You can enable [Vue DevTools](https://devtools-next.vuejs.org/) in development by passing an object with `devtools: true` to your `vue()` integration config: From 5596a4037c81146fafe2d83ac6e47336d4cd0a32 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Mon, 15 Sep 2025 21:43:31 +0200 Subject: [PATCH 2/4] add optional, consistency Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> --- src/content/docs/en/guides/integrations-guide/db.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/integrations-guide/db.mdx b/src/content/docs/en/guides/integrations-guide/db.mdx index e6f98d12e64b1..d1ffbc348c28e 100644 --- a/src/content/docs/en/guides/integrations-guide/db.mdx +++ b/src/content/docs/en/guides/integrations-guide/db.mdx @@ -184,7 +184,7 @@ This will generate a unique index on the `authorId` and `published` columns with The following configuration options are available for each index: - `on` - A single column or array of column names to index. -- `unique` - Set to `true` to enforce unique values across the indexed columns. +- `unique` (optional) - Set to `true` to enforce unique values across the indexed columns. - `name` (optional) - A custom name for the unique index. This will override Astro's generated name based on the table and column names being indexed (e.g. `Comment_authorId_published_idx`). Custom names are global, so ensure index names do not conflict between tables. ### `foreignKeys` From 775967a89dd33b4cfad6fe77f30c22a084df431f Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Tue, 16 Sep 2025 16:17:37 +0200 Subject: [PATCH 3/4] clearer partytown config description Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> --- src/content/docs/en/guides/integrations-guide/partytown.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/integrations-guide/partytown.mdx b/src/content/docs/en/guides/integrations-guide/partytown.mdx index c4e800dcde66d..479709094aac3 100644 --- a/src/content/docs/en/guides/integrations-guide/partytown.mdx +++ b/src/content/docs/en/guides/integrations-guide/partytown.mdx @@ -107,7 +107,7 @@ export default defineConfig({ }); ``` -This mirrors the [Partytown config object](https://partytown.qwik.dev/configuration/). +This mirrors the [Partytown config object](https://partytown.qwik.dev/configuration/) and all options can be set in `partytown.config`. Some common configuration options for Astro projects are described on this page. ### `config.debug` From c8856e7f495c614977d8bcd6ab60fa55636dc29d Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Tue, 16 Sep 2025 16:18:51 +0200 Subject: [PATCH 4/4] remove partytown types and reword headings Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> --- .../guides/integrations-guide/partytown.mdx | 21 +++---------------- 1 file changed, 3 insertions(+), 18 deletions(-) diff --git a/src/content/docs/en/guides/integrations-guide/partytown.mdx b/src/content/docs/en/guides/integrations-guide/partytown.mdx index 479709094aac3..956f22a6bf621 100644 --- a/src/content/docs/en/guides/integrations-guide/partytown.mdx +++ b/src/content/docs/en/guides/integrations-guide/partytown.mdx @@ -110,12 +110,7 @@ export default defineConfig({ This mirrors the [Partytown config object](https://partytown.qwik.dev/configuration/) and all options can be set in `partytown.config`. Some common configuration options for Astro projects are described on this page. -### `config.debug` - -

- -**Type:** `boolean` -

+### Enabling debug mode Partytown ships with a `debug` mode; enable or disable it by passing `true` or `false` to `config.debug`. If [`debug` mode](https://partytown.qwik.dev/debugging) is enabled, it will output detailed logs to the browser console. @@ -133,12 +128,7 @@ export default defineConfig({ }); ``` -### `config.forward` - -

- -**Type:** `PartytownForwardProperty[]` -

+### Forwarding variables Third-party scripts typically add variables to the `window` object so that you can communicate with them throughout your site. But when a script is loaded in a web-worker, it doesn't have access to that global `window` object. @@ -160,12 +150,7 @@ export default defineConfig({ }); ``` -### `config.resolveUrl` - -

- -**Type:** `(url: URL, location: Location, type: ResolveUrlType) => URL | undefined | null` -

+### Proxying requests Some third-party scripts may require [proxying](https://partytown.qwik.dev/proxying-requests/) through `config.resolveUrl()`, which runs inside the service worker. You can set this configuration option to check for a specific URL, and optionally return a proxied URL instead: