From edb5437058c00a2ed6f1119ace6a50c3a42c10f4 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger Date: Wed, 24 Jan 2024 18:20:25 -0400 Subject: [PATCH] [docs] reorder items for configuration reference page (#9815) * docs-config-ref-order * Update packages/astro/src/@types/astro.ts Co-authored-by: Reuben Tier <64310361+TheOtterlord@users.noreply.github.com> * Update packages/astro/src/@types/astro.ts Co-authored-by: Reuben Tier <64310361+TheOtterlord@users.noreply.github.com> --------- Co-authored-by: Nate Moore Co-authored-by: Reuben Tier <64310361+TheOtterlord@users.noreply.github.com> --- packages/astro/src/@types/astro.ts | 547 +++++++++++++++-------------- 1 file changed, 275 insertions(+), 272 deletions(-) diff --git a/packages/astro/src/@types/astro.ts b/packages/astro/src/@types/astro.ts index 8a26ebaba6cd..0382e8479929 100644 --- a/packages/astro/src/@types/astro.ts +++ b/packages/astro/src/@types/astro.ts @@ -409,6 +409,7 @@ export interface ImageServiceConfig = Record; + + /** + * @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 @@ -675,48 +746,37 @@ export interface AstroUserConfig { /** * @docs - * @name adapter - * @typeraw {AstroIntegration} - * @see output - * @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. - * - * [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'; - * { - * // Example: Build for Netlify serverless deployment - * adapter: netlify(), - * } - * ``` - */ - adapter?: AstroIntegration; - - /** - * @docs - * @name output - * @type {('static' | 'server' | 'hybrid')} - * @default `'static'` - * @see adapter + * @name vite + * @typeraw {ViteUserConfig} * @description * - * Specifies the output target for builds. + * Pass additional configuration options to Vite. Useful when Astro doesn't support some advanced configuration that you may need. * - * - `'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. + * View the full `vite` configuration object documentation on [vitejs.dev](https://vitejs.dev/config/). + * + * #### Examples * * ```js - * import { defineConfig } from 'astro/config'; + * { + * vite: { + * ssr: { + * // Example: Force a broken package to skip SSR processing, if needed + * external: ['broken-npm-package'], + * } + * } + * } + * ``` * - * export default defineConfig({ - * output: 'static' - * }) + * ```js + * { + * vite: { + * // Example: Add custom vite plugins directly to your Astro project + * plugins: [myPlugin()], + * } + * } * ``` */ - output?: 'static' | 'server' | 'hybrid'; + vite?: ViteUserConfig; /** * @docs @@ -907,73 +967,6 @@ export interface AstroUserConfig { inlineStylesheets?: 'always' | 'auto' | 'never'; }; - /** - * @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 `` 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 `` link on your page to enable prefetching for that page. - * - * ```html - * About - * ``` - * 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 `` 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 - * About - *``` - */ - 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 - * About - * ``` - */ - defaultStrategy?: 'tap' | 'hover' | 'viewport' | 'load'; - }; - /** * @docs * @kind heading @@ -1058,6 +1051,92 @@ export interface AstroUserConfig { server?: ServerConfig | ((options: { command: 'dev' | 'preview' }) => ServerConfig); + /** + * @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 `` 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 `` link on your page to enable prefetching for that page. + * + * ```html + * About + * ``` + * 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 `` 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 + * About + *``` + */ + 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 + * About + * ``` + */ + defaultStrategy?: 'tap' | 'hover' | 'viewport' | 'load'; + }; + /** * @docs * @kind heading @@ -1191,25 +1270,6 @@ export interface AstroUserConfig { remotePatterns?: Partial[]; }; - /** - * @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 @@ -1336,63 +1396,6 @@ export interface AstroUserConfig { remarkRehype?: RemarkRehype; }; - /** - * @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