diff options
| -rw-r--r-- | packages/astro/src/@types/astro.ts | 539 |
1 files changed, 271 insertions, 268 deletions
diff --git a/packages/astro/src/@types/astro.ts b/packages/astro/src/@types/astro.ts index 8a26ebaba..0382e8479 100644 --- a/packages/astro/src/@types/astro.ts +++ b/packages/astro/src/@types/astro.ts @@ -409,6 +409,7 @@ export interface ImageServiceConfig<T extends Record<string, any> = Record<strin * Docs: https://docs.astro.build/reference/configuration-reference/ */ export interface AstroUserConfig { + /** * @docs * @kind heading @@ -417,97 +418,86 @@ export interface AstroUserConfig { /** * @docs - * @name root - * @cli --root + * @name site * @type {string} - * @default `"."` (current working directory) - * @summary Set the project root. The project root is the directory where your Astro project (and all `src`, `public` and `package.json` files) live. - * @description You should only provide this option if you run the `astro` CLI commands in a directory other than the project root directory. Usually, this option is provided via the CLI instead of the [Astro config file](https://docs.astro.build/en/guides/configuring-astro/#supported-config-file-types), since Astro needs to know your project root before it can locate your config file. - * - * If you provide a relative path (ex: `--root: './my-project'`) Astro will resolve it against your current working directory. - * - * #### Examples + * @description + * Your final, deployed URL. Astro uses this full URL to generate your sitemap and canonical URLs in your final build. It is strongly recommended that you set this configuration to get the most out of Astro. * * ```js * { - * root: './my-project-directory' + * site: 'https://www.my-site.dev' * } * ``` - * ```bash - * $ astro build --root ./my-project-directory - * ``` */ - root?: string; + site?: string; /** * @docs - * @name srcDir + * @name base * @type {string} - * @default `"./src"` - * @description Set the directory that Astro will read your site from. + * @description + * The base path to deploy to. Astro will use this path as the root for your pages and assets both in development and in production build. * - * The value can be either an absolute file system path or a path relative to the project root. + * In the example below, `astro dev` will start your server at `/docs`. * * ```js * { - * srcDir: './www' + * base: '/docs' * } * ``` - */ - srcDir?: string; - - /** - * @docs - * @name publicDir - * @type {string} - * @default `"./public"` - * @description - * Set the directory for your static assets. Files in this directory are served at `/` during dev and copied to your build directory during build. These files are always served or copied as-is, without transform or bundling. * - * The value can be either an absolute file system path or a path relative to the project root. + * When using this option, all of your static asset imports and URLs should add the base as a prefix. You can access this value via `import.meta.env.BASE_URL`. * + * The value of `import.meta.env.BASE_URL` will be determined by your `trailingSlash` config, no matter what value you have set for `base`. + * + * A trailing slash is always included if `trailingSlash: "always"` is set. If `trailingSlash: "never"` is set, `BASE_URL` will not include a trailing slash, even if `base` includes one. + * + * Additionally, Astro will internally manipulate the configured value of `config.base` before making it available to integrations. The value of `config.base` as read by integrations will also be determined by your `trailingSlash` configuration in the same way. + * + * In the example below, the values of `import.meta.env.BASE_URL` and `config.base` when processed will both be `/docs`: * ```js * { - * publicDir: './my-custom-publicDir-directory' + * base: '/docs/', + * trailingSlash: "never" * } * ``` - */ - publicDir?: string; - - /** - * @docs - * @name outDir - * @type {string} - * @default `"./dist"` - * @see build.server - * @description Set the directory that `astro build` writes your final build to. * - * The value can be either an absolute file system path or a path relative to the project root. + * In the example below, the values of `import.meta.env.BASE_URL` and `config.base` when processed will both be `/docs/`: * * ```js * { - * outDir: './my-custom-build-directory' + * base: '/docs', + * trailingSlash: "always" * } * ``` */ - outDir?: string; + base?: string; /** * @docs - * @name cacheDir - * @type {string} - * @default `"./node_modules/.astro"` - * @description Set the directory for caching build artifacts. Files in this directory will be used in subsequent builds to speed up the build time. + * @name trailingSlash + * @type {('always' | 'never' | 'ignore')} + * @default `'ignore'` + * @see build.format + * @description * - * The value can be either an absolute file system path or a path relative to the project root. + * Set the route matching behavior of the dev server. Choose from the following options: + * - `'always'` - Only match URLs that include a trailing slash (ex: "/foo/") + * - `'never'` - Never match URLs that include a trailing slash (ex: "/foo") + * - `'ignore'` - Match URLs regardless of whether a trailing "/" exists + * + * Use this configuration option if your production host has strict handling of how trailing slashes work or do not work. + * + * You can also set this if you prefer to be more strict yourself, so that URLs with or without trailing slashes won't work during development. * * ```js * { - * cacheDir: './my-custom-cache-directory' + * // Example: Require a trailing slash during development + * trailingSlash: 'always' * } * ``` */ - cacheDir?: string; + trailingSlash?: 'always' | 'never' | 'ignore'; /** * @docs @@ -556,106 +546,187 @@ export interface AstroUserConfig { /** * @docs - * @name site - * @type {string} + * @name output + * @type {('static' | 'server' | 'hybrid')} + * @default `'static'` + * @see adapter * @description - * Your final, deployed URL. Astro uses this full URL to generate your sitemap and canonical URLs in your final build. It is strongly recommended that you set this configuration to get the most out of Astro. + * + * Specifies the output target for builds. + * + * - `'static'` - Building a static site to be deploy to any static host. + * - `'server'` - Building an app to be deployed to a host supporting SSR (server-side rendering). + * - `'hybrid'` - Building a static site with a few server-side rendered pages. * * ```js - * { - * site: 'https://www.my-site.dev' - * } + * import { defineConfig } from 'astro/config'; + * + * export default defineConfig({ + * output: 'static' + * }) * ``` */ - site?: string; + output?: 'static' | 'server' | 'hybrid'; + /** * @docs - * @name compressHTML - * @type {boolean} - * @default `true` + * @name adapter + * @typeraw {AstroIntegration} + * @see output * @description - * This is an option to minify your HTML output and reduce the size of your HTML files. By default, Astro removes all whitespace from your HTML, including line breaks, from `.astro` components. This occurs both in development mode and in the final build. - * To disable HTML compression, set the `compressHTML` flag to `false`. + * + * Deploy to your favorite server, serverless, or edge host with build adapters. Import one of our first-party adapters for [Netlify](https://docs.astro.build/en/guides/deploy/netlify/#adapter-for-ssr), [Vercel](https://docs.astro.build/en/guides/deploy/vercel/#adapter-for-ssr), and more to engage Astro SSR. + * + * [See our Server-side Rendering guide](https://docs.astro.build/en/guides/server-side-rendering/) for more on SSR, and [our deployment guides](https://docs.astro.build/en/guides/deploy/) for a complete list of hosts. * * ```js + * import netlify from '@astrojs/netlify'; * { - * compressHTML: false + * // Example: Build for Netlify serverless deployment + * adapter: netlify(), * } * ``` */ - compressHTML?: boolean; + adapter?: AstroIntegration; /** * @docs - * @name base - * @type {string} + * @name integrations + * @typeraw {AstroIntegration[]} * @description - * The base path to deploy to. Astro will use this path as the root for your pages and assets both in development and in production build. * - * In the example below, `astro dev` will start your server at `/docs`. + * Extend Astro with custom integrations. Integrations are your one-stop-shop for adding framework support (like Solid.js), new features (like sitemaps), and new libraries (like Partytown). + * + * Read our [Integrations Guide](https://docs.astro.build/en/guides/integrations-guide/) for help getting started with Astro Integrations. * * ```js + * import react from '@astrojs/react'; + * import tailwind from '@astrojs/tailwind'; * { - * base: '/docs' + * // Example: Add React + Tailwind support to Astro + * integrations: [react(), tailwind()] * } * ``` + */ + integrations?: Array< + AstroIntegration | (AstroIntegration | false | undefined | null)[] | false | undefined | null + >; + + /** + * @docs + * @name root + * @cli --root + * @type {string} + * @default `"."` (current working directory) + * @summary Set the project root. The project root is the directory where your Astro project (and all `src`, `public` and `package.json` files) live. + * @description You should only provide this option if you run the `astro` CLI commands in a directory other than the project root directory. Usually, this option is provided via the CLI instead of the [Astro config file](https://docs.astro.build/en/guides/configuring-astro/#supported-config-file-types), since Astro needs to know your project root before it can locate your config file. * - * When using this option, all of your static asset imports and URLs should add the base as a prefix. You can access this value via `import.meta.env.BASE_URL`. + * If you provide a relative path (ex: `--root: './my-project'`) Astro will resolve it against your current working directory. * - * The value of `import.meta.env.BASE_URL` will be determined by your `trailingSlash` config, no matter what value you have set for `base`. + * #### Examples * - * A trailing slash is always included if `trailingSlash: "always"` is set. If `trailingSlash: "never"` is set, `BASE_URL` will not include a trailing slash, even if `base` includes one. + * ```js + * { + * root: './my-project-directory' + * } + * ``` + * ```bash + * $ astro build --root ./my-project-directory + * ``` + */ + root?: string; + + /** + * @docs + * @name srcDir + * @type {string} + * @default `"./src"` + * @description Set the directory that Astro will read your site from. * - * Additionally, Astro will internally manipulate the configured value of `config.base` before making it available to integrations. The value of `config.base` as read by integrations will also be determined by your `trailingSlash` configuration in the same way. + * The value can be either an absolute file system path or a path relative to the project root. * - * In the example below, the values of `import.meta.env.BASE_URL` and `config.base` when processed will both be `/docs`: * ```js * { - * base: '/docs/', - * trailingSlash: "never" + * srcDir: './www' * } * ``` + */ + srcDir?: string; + + /** + * @docs + * @name publicDir + * @type {string} + * @default `"./public"` + * @description + * Set the directory for your static assets. Files in this directory are served at `/` during dev and copied to your build directory during build. These files are always served or copied as-is, without transform or bundling. * - * In the example below, the values of `import.meta.env.BASE_URL` and `config.base` when processed will both be `/docs/`: + * The value can be either an absolute file system path or a path relative to the project root. * * ```js * { - * base: '/docs', - * trailingSlash: "always" + * publicDir: './my-custom-publicDir-directory' * } * ``` */ - base?: string; + publicDir?: string; /** * @docs - * @name trailingSlash - * @type {('always' | 'never' | 'ignore')} - * @default `'ignore'` - * @see build.format - * @description + * @name outDir + * @type {string} + * @default `"./dist"` + * @see build.server + * @description Set the directory that `astro build` writes your final build to. * - * Set the route matching behavior of the dev server. Choose from the following options: - * - `'always'` - Only match URLs that include a trailing slash (ex: "/foo/") - * - `'never'` - Never match URLs that include a trailing slash (ex: "/foo") - * - `'ignore'` - Match URLs regardless of whether a trailing "/" exists + * The value can be either an absolute file system path or a path relative to the project root. * - * Use this configuration option if your production host has strict handling of how trailing slashes work or do not work. + * ```js + * { + * outDir: './my-custom-build-directory' + * } + * ``` + */ + outDir?: string; + + /** + * @docs + * @name cacheDir + * @type {string} + * @default `"./node_modules/.astro"` + * @description Set the directory for caching build artifacts. Files in this directory will be used in subsequent builds to speed up the build time. * - * You can also set this if you prefer to be more strict yourself, so that URLs with or without trailing slashes won't work during development. + * The value can be either an absolute file system path or a path relative to the project root. * * ```js * { - * // Example: Require a trailing slash during development - * trailingSlash: 'always' + * cacheDir: './my-custom-cache-directory' * } * ``` */ - trailingSlash?: 'always' | 'never' | 'ignore'; + cacheDir?: string; /** * @docs + * @name compressHTML + * @type {boolean} + * @default `true` + * @description + * This is an option to minify your HTML output and reduce the size of your HTML files. By default, Astro removes all whitespace from your HTML, including line breaks, from `.astro` components. This occurs both in development mode and in the final build. + * To disable HTML compression, set the `compressHTML` flag to `false`. + * + * ```js + * { + * compressHTML: false + * } + * ``` + */ + compressHTML?: boolean; + + + /** + * @docs * @name scopedStyleStrategy * @type {('where' | 'class' | 'attribute')} * @default `'attribute'` @@ -675,48 +746,37 @@ export interface AstroUserConfig { /** * @docs - * @name adapter - * @typeraw {AstroIntegration} - * @see output + * @name vite + * @typeraw {ViteUserConfig} * @description * - * Deploy to your favorite server, serverless, or edge host with build adapters. Import one of our first-party adapters for [Netlify](https://docs.astro.build/en/guides/deploy/netlify/#adapter-for-ssr), [Vercel](https://docs.astro.build/en/guides/deploy/vercel/#adapter-for-ssr), and more to engage Astro SSR. + * Pass additional configuration options to Vite. Useful when Astro doesn't support some advanced configuration that you may need. * - * [See our Server-side Rendering guide](https://docs.astro.build/en/guides/server-side-rendering/) for more on SSR, and [our deployment guides](https://docs.astro.build/en/guides/deploy/) for a complete list of hosts. + * View the full `vite` configuration object documentation on [vitejs.dev](https://vitejs.dev/config/). + * + * #### Examples * * ```js - * import netlify from '@astrojs/netlify'; * { - * // Example: Build for Netlify serverless deployment - * adapter: netlify(), + * vite: { + * ssr: { + * // Example: Force a broken package to skip SSR processing, if needed + * external: ['broken-npm-package'], + * } + * } * } * ``` - */ - adapter?: AstroIntegration; - - /** - * @docs - * @name output - * @type {('static' | 'server' | 'hybrid')} - * @default `'static'` - * @see adapter - * @description - * - * Specifies the output target for builds. - * - * - `'static'` - Building a static site to be deploy to any static host. - * - `'server'` - Building an app to be deployed to a host supporting SSR (server-side rendering). - * - `'hybrid'` - Building a static site with a few server-side rendered pages. * * ```js - * import { defineConfig } from 'astro/config'; - * - * export default defineConfig({ - * output: 'static' - * }) + * { + * vite: { + * // Example: Add custom vite plugins directly to your Astro project + * plugins: [myPlugin()], + * } + * } * ``` */ - output?: 'static' | 'server' | 'hybrid'; + vite?: ViteUserConfig; /** * @docs @@ -910,73 +970,6 @@ export interface AstroUserConfig { /** * @docs * @kind heading - * @name Prefetch Options - * @type {boolean | object} - * @description - * Enable prefetching for links on your site to provide faster page transitions. - * (Enabled by default on pages using the `<ViewTransitions />` router. Set `prefetch: false` to opt out of this behaviour.) - * - * This configuration automatically adds a prefetch script to every page in the project - * giving you access to the `data-astro-prefetch` attribute. - * Add this attribute to any `<a />` link on your page to enable prefetching for that page. - * - * ```html - * <a href="/about" data-astro-prefetch>About</a> - * ``` - * Further customize the default prefetching behavior using the [`prefetch.defaultStrategy`](#prefetchdefaultstrategy) and [`prefetch.prefetchAll`](#prefetchprefetchall) options. - * - * See the [Prefetch guide](https://docs.astro.build/en/guides/prefetch/) for more information. - */ - prefetch?: - | boolean - | { - /** - * @docs - * @name prefetch.prefetchAll - * @type {boolean} - * @description - * Enable prefetching for all links, including those without the `data-astro-prefetch` attribute. - * This value defaults to `true` when using the `<ViewTransitions />` router. Otherwise, the default value is `false`. - * - * ```js - * prefetch: { - * prefetchAll: true - * } - * ``` - * - * When set to `true`, you can disable prefetching individually by setting `data-astro-prefetch="false"` on any individual links. - * - * ```html - * <a href="/about" data-astro-prefetch="false">About</a> - *``` - */ - prefetchAll?: boolean; - - /** - * @docs - * @name prefetch.defaultStrategy - * @type {'tap' | 'hover' | 'viewport' | 'load'} - * @default `'hover'` - * @description - * The default prefetch strategy to use when the `data-astro-prefetch` attribute is set on a link with no value. - * - * - `'tap'`: Prefetch just before you click on the link. - * - `'hover'`: Prefetch when you hover over or focus on the link. (default) - * - `'viewport'`: Prefetch as the links enter the viewport. - * - `'load'`: Prefetch all links on the page after the page is loaded. - * - * You can override this default value and select a different strategy for any individual link by setting a value on the attribute. - * - * ```html - * <a href="/about" data-astro-prefetch="viewport">About</a> - * ``` - */ - defaultStrategy?: 'tap' | 'hover' | 'viewport' | 'load'; - }; - - /** - * @docs - * @kind heading * @name Server Options * @description * @@ -1061,6 +1054,92 @@ export interface AstroUserConfig { /** * @docs * @kind heading + * @name Dev Toolbar Options + */ + devToolbar?: { + /** + * @docs + * @name devToolbar.enabled + * @type {boolean} + * @default `true` + * @description + * Whether to enable the Astro Dev Toolbar. This toolbar allows you to inspect your page islands, see helpful audits on performance and accessibility, and more. + * + * This option is scoped to the entire project, to only disable the toolbar for yourself, run `npm run astro preferences disable devToolbar`. To disable the toolbar for all your Astro projects, run `npm run astro preferences disable devToolbar --global`. + */ + enabled: boolean; + }; + + /** + * @docs + * @kind heading + * @name Prefetch Options + * @type {boolean | object} + * @description + * Enable prefetching for links on your site to provide faster page transitions. + * (Enabled by default on pages using the `<ViewTransitions />` router. Set `prefetch: false` to opt out of this behaviour.) + * + * This configuration automatically adds a prefetch script to every page in the project + * giving you access to the `data-astro-prefetch` attribute. + * Add this attribute to any `<a />` link on your page to enable prefetching for that page. + * + * ```html + * <a href="/about" data-astro-prefetch>About</a> + * ``` + * Further customize the default prefetching behavior using the [`prefetch.defaultStrategy`](#prefetchdefaultstrategy) and [`prefetch.prefetchAll`](#prefetchprefetchall) options. + * + * See the [Prefetch guide](https://docs.astro.build/en/guides/prefetch/) for more information. + */ + prefetch?: + | boolean + | { + /** + * @docs + * @name prefetch.prefetchAll + * @type {boolean} + * @description + * Enable prefetching for all links, including those without the `data-astro-prefetch` attribute. + * This value defaults to `true` when using the `<ViewTransitions />` router. Otherwise, the default value is `false`. + * + * ```js + * prefetch: { + * prefetchAll: true + * } + * ``` + * + * When set to `true`, you can disable prefetching individually by setting `data-astro-prefetch="false"` on any individual links. + * + * ```html + * <a href="/about" data-astro-prefetch="false">About</a> + *``` + */ + prefetchAll?: boolean; + + /** + * @docs + * @name prefetch.defaultStrategy + * @type {'tap' | 'hover' | 'viewport' | 'load'} + * @default `'hover'` + * @description + * The default prefetch strategy to use when the `data-astro-prefetch` attribute is set on a link with no value. + * + * - `'tap'`: Prefetch just before you click on the link. + * - `'hover'`: Prefetch when you hover over or focus on the link. (default) + * - `'viewport'`: Prefetch as the links enter the viewport. + * - `'load'`: Prefetch all links on the page after the page is loaded. + * + * You can override this default value and select a different strategy for any individual link by setting a value on the attribute. + * + * ```html + * <a href="/about" data-astro-prefetch="viewport">About</a> + * ``` + */ + defaultStrategy?: 'tap' | 'hover' | 'viewport' | 'load'; + }; + + /** + * @docs + * @kind heading * @name Image Options */ image?: { @@ -1194,25 +1273,6 @@ export interface AstroUserConfig { /** * @docs * @kind heading - * @name Dev Toolbar Options - */ - devToolbar?: { - /** - * @docs - * @name devToolbar.enabled - * @type {boolean} - * @default `true` - * @description - * Whether to enable the Astro Dev Toolbar. This toolbar allows you to inspect your page islands, see helpful audits on performance and accessibility, and more. - * - * This option is scoped to the entire project, to only disable the toolbar for yourself, run `npm run astro preferences disable devToolbar`. To disable the toolbar for all your Astro projects, run `npm run astro preferences disable devToolbar --global`. - */ - enabled: boolean; - }; - - /** - * @docs - * @kind heading * @name Markdown Options */ markdown?: { @@ -1339,63 +1399,6 @@ export interface AstroUserConfig { /** * @docs * @kind heading - * @name Integrations - * @description - * - * Extend Astro with custom integrations. Integrations are your one-stop-shop for adding framework support (like Solid.js), new features (like sitemaps), and new libraries (like Partytown). - * - * Read our [Integrations Guide](https://docs.astro.build/en/guides/integrations-guide/) for help getting started with Astro Integrations. - * - * ```js - * import react from '@astrojs/react'; - * import tailwind from '@astrojs/tailwind'; - * { - * // Example: Add React + Tailwind support to Astro - * integrations: [react(), tailwind()] - * } - * ``` - */ - integrations?: Array< - AstroIntegration | (AstroIntegration | false | undefined | null)[] | false | undefined | null - >; - - /** - * @docs - * @kind heading - * @name Vite - * @description - * - * Pass additional configuration options to Vite. Useful when Astro doesn't support some advanced configuration that you may need. - * - * View the full `vite` configuration object documentation on [vitejs.dev](https://vitejs.dev/config/). - * - * #### Examples - * - * ```js - * { - * vite: { - * ssr: { - * // Example: Force a broken package to skip SSR processing, if needed - * external: ['broken-npm-package'], - * } - * } - * } - * ``` - * - * ```js - * { - * vite: { - * // Example: Add custom vite plugins directly to your Astro project - * plugins: [myPlugin()], - * } - * } - * ``` - */ - vite?: ViteUserConfig; - - /** - * @docs - * @kind heading * @name i18n * @type {object} * @version 3.5.0 |