diff --git a/src/content/docs/en/guides/images.mdx b/src/content/docs/en/guides/images.mdx index 4f00cdf0c2d9b..1d1eed2af3057 100644 --- a/src/content/docs/en/guides/images.mdx +++ b/src/content/docs/en/guides/images.mdx @@ -271,7 +271,7 @@ Alternatively, the CDN may provide its own SDKs to more easily integrate in an A ## Images in Markdown files -Use standard Markdown `![alt](src)` syntax in your `.md` files. This syntax works with Astro's [Image Service API](/en/reference/image-service-reference/) to optimize your local images stored in `src/`. Remote images and images stored in the `public/` folder are not optimized. +Use standard Markdown `![alt](src)` syntax in your `.md` files. This syntax works with Astro's [Image Service API](/en/reference/image-service-reference/) to optimize your local images stored in `src/` and remote images. Images stored in the `public/` folder are never optimized. ```md @@ -291,9 +291,9 @@ Use standard Markdown `![alt](src)` syntax in your `.md` files. This syntax work ![Astro](https://example.com/images/remote-image.png) ``` -The `` tag is not supported for local images, and the `` and `` components are unavailable in `.md` files. +The HTML `` tag can also be used to display images stored in `public/` or remote images without any image optimization or processing. However, `` is not supported for your local images in `src`. -If you require more control over your image attributes, we recommend using [Astro's MDX integration](/en/guides/integrations-guide/mdx/) to add support for`.mdx` file format. MDX allows adding components to Markdown and there are additional [image options available in MDX](#images-in-mdx-files). +The `` and `` components are unavailable in `.md` files. If you require more control over your image attributes, we recommend using [Astro's MDX integration](/en/guides/integrations-guide/mdx/) to add support for `.mdx` file format. MDX allows additional [image options available in MDX](#images-in-mdx-files), including combining components with Markdown syntax. ## Images in MDX files diff --git a/src/content/docs/en/guides/integrations-guide/vercel.mdx b/src/content/docs/en/guides/integrations-guide/vercel.mdx index ee09d53fb033f..9c44a27d88a3f 100644 --- a/src/content/docs/en/guides/integrations-guide/vercel.mdx +++ b/src/content/docs/en/guides/integrations-guide/vercel.mdx @@ -266,7 +266,7 @@ export default defineConfig({ To implement Vercel's [Draft mode](https://vercel.com/docs/build-output-api/v3/features#draft-mode), or [On-Demand Incremental Static Regeneration (ISR)](https://vercel.com/docs/build-output-api/v3/features#on-demand-incremental-static-regeneration-isr), you can create a bypass token and provide it to the `isr` config along with any routes to exclude from caching: -```js title="astro.config.mjs" {7-12} +```js title="astro.config.mjs" {7-16} import { defineConfig } from 'astro/config'; import vercel from '@astrojs/vercel'; @@ -277,7 +277,11 @@ export default defineConfig({ // A secret random string that you create. bypassToken: "005556d774a8", // Paths that will always be served fresh. - exclude: [ "/api/invalidate", "/posts/[...slug]" ] + exclude: [ + '/preview', + '/auth/[page]', + /^\/api\/.+/ // Regular expressions supported since @astrojs/vercel@v8.1.0 + ] } }) }) diff --git a/src/content/docs/en/reference/cli-reference.mdx b/src/content/docs/en/reference/cli-reference.mdx index f11b76b2db4ce..3f78bb7acfe06 100644 --- a/src/content/docs/en/reference/cli-reference.mdx +++ b/src/content/docs/en/reference/cli-reference.mdx @@ -432,6 +432,14 @@ Sets which network IP addresses the dev server and preview server should listen Do not use the `--host` flag to expose the dev server and preview server in a production environment. The servers are designed for local use while developing your site only. ::: +### `--allowed-hosts` + +

+ +Specifies the hostnames that Astro is allowed to respond to in `dev` or `preview` modes. Can be passed a comma-separated list of hostnames or `true` to allow any hostname. + +Refer to [Vite's `allowedHosts` feature](https://vite.dev/config/server-options.html#server-allowedhosts) for more information, including security implications of allowing hostnames. + ### `--verbose` Enables verbose logging, which is helpful when debugging an issue. diff --git a/src/content/docs/en/reference/experimental-flags/responsive-images.mdx b/src/content/docs/en/reference/experimental-flags/responsive-images.mdx index 92685f6db38cb..25388db538954 100644 --- a/src/content/docs/en/reference/experimental-flags/responsive-images.mdx +++ b/src/content/docs/en/reference/experimental-flags/responsive-images.mdx @@ -24,9 +24,67 @@ Enables support for automatic responsive images in your project. } ``` -When this flag is enabled, you can pass a `layout` prop to any `` or `` component to create a responsive image. - -When a layout is set, images have automatically generated `srcset` and `sizes` attributes based on the image's dimensions and the layout type. Images with `responsive` and `full-width` layouts will have styles applied to ensure they resize according to their container. +With this flag enabled, you have access to additional [`image` configuration settings](#responsive-image-configuration-settings) for controlling the default behavior of all images processed and optimized by Astro: + +- Local and remote images using [the Markdown `![]()` syntax](/en/guides/images/#images-in-markdown-files). +- The [``](/en/guides/images/#display-optimized-images-with-the-image--component) and [``](/en/guides/images/#create-responsive-images-with-the-picture--component) components. + +Additionally, Astro's image components can receive [responsive image props](#responsive-image-properties) to override these defaults on a per-image basis. + +Images in your `public/` folder are never optimized, and responsive images are not supported. + +## Responsive image configuration settings + +Set [`image.experimentalLayout`](/en/reference/configuration-reference/#imageexperimentallayout) with a default value (`responsive`, `fixed`, or `full-width`) to enable responsive images throughout your project. + +If this value is not configured, you can still pass a `layout` prop to any `` or `` component to create a responsive image. However, Markdown images will not be responsive. + +Optionally, you can configure [`image.experimentalObjectFit`](/en/reference/configuration-reference/#imageexperimentalobjectfit) and [`image.experimentalObjectPosition`](/en/reference/configuration-reference/#imageexperimentalobjectposition) which will apply to all processed images by default. + +Each of these settings can be overridden on any individual `` or `` component with a prop, but all Markdown images will always use the default settings. + +```js title="astro.config.mjs" +{ + image: { + // Used for all Markdown images; not configurable per-image + // Used for all `` and `` components unless overridden with a prop + experimentalLayout: 'responsive', + }, + experimental: { + responsiveImages: true, + }, +} +``` + +## Responsive image properties + +These are additional properties available to the `` and `` components when responsive images are enabled: + +- `layout`: The layout type for the image. Can be `responsive`, `fixed`, `full-width`, or `none`. Defaults to the value of [`image.experimentalLayout`](/en/reference/configuration-reference/#imageexperimentallayout). +- `fit`: Defines how the image should be cropped if the aspect ratio is changed. Values match those of CSS `object-fit`. Defaults to `cover`, or the value of [`image.experimentalObjectFit`](/en/reference/configuration-reference/#imageexperimentalobjectfit) if set. +- `position`: Defines the position of the image crop if the aspect ratio is changed. Values match those of CSS `object-position`. Defaults to `center`, or the value of [`image.experimentalObjectPosition`](/en/reference/configuration-reference/#imageexperimentalobjectposition) if set. +- `priority`: If set, eagerly loads the image. Otherwise, images will be lazy-loaded. Use this for your largest above-the-fold image. Defaults to `false`. + +The `widths` and `sizes` attributes are automatically generated based on the image's dimensions and the layout type, and in most cases should not be set manually. The generated `sizes` attribute for `responsive` and `full-width` images +is based on the assumption that the image is displayed at close to the full width of the screen when the viewport is smaller than the image's width. If it is significantly different (e.g. if it's in a multi-column layout on small screens) you may need to adjust the `sizes` attribute manually for best results. + +The `densities` attribute is not compatible with responsive images and will be ignored if set. + +For example, with `responsive` set as the default layout, you can override any individual image's `layout` property: + +```astro +--- +import { Image } from 'astro:assets'; +import myImage from '../assets/my_image.png'; +--- +This will use responsive layout +This will use full-width layout +This will disable responsive images +``` + +## Generated HTML output for responsive images + +When a layout is set, either by default or on an individual component, images have automatically generated `srcset` and `sizes` attributes based on the image's dimensions and the layout type. Images with `responsive` and `full-width` layouts will have styles applied to ensure they resize according to their container. ```astro title=MyComponent.astro --- @@ -83,46 +141,4 @@ The following styles are applied to ensure the images resize correctly: } ``` -## Responsive image properties - -These are additional properties available to the `` and `` components when responsive images are enabled: - -- `layout`: The layout type for the image. Can be `responsive`, `fixed`, `full-width` or `none`. Defaults to value of [`image.experimentalLayout`](/en/reference/configuration-reference/#imageexperimentallayout). -- `fit`: Defines how the image should be cropped if the aspect ratio is changed. Values match those of CSS `object-fit`. Defaults to `cover`, or the value of [`image.experimentalObjectFit`](/en/reference/configuration-reference/#imageexperimentalobjectfit) if set. -- `position`: Defines the position of the image crop if the aspect ratio is changed. Values match those of CSS `object-position`. Defaults to `center`, or the value of [`image.experimentalObjectPosition`](/en/reference/configuration-reference/#imageexperimentalobjectposition) if set. -- `priority`: If set, eagerly loads the image. Otherwise images will be lazy-loaded. Use this for your largest above-the-fold image. Defaults to `false`. - -The `widths` and `sizes` attributes are automatically generated based on the image's dimensions and the layout type, and in most cases should not be set manually. The generated `sizes` attribute for `responsive` and `full-width` images -is based on the assumption that the image is displayed at close to the full width of the screen when the viewport is smaller than the image's width. If it is significantly different (e.g. if it's in a multi-column layout on small screens) you may need to adjust the `sizes` attribute manually for best results. - -The `densities` attribute is not compatible with responsive images and will be ignored if set. - -## Responsive image configuration settings - -You can enable responsive images for all `` and `` components by setting [`image.experimentalLayout`](/en/reference/configuration-reference/#imageexperimentallayout) with a default value. This settings can be overridden by the `layout` prop on each component. - -```js title="astro.config.mjs" -{ - image: { - // Used for all `` and `` components unless overridden - experimentalLayout: 'responsive', - }, - experimental: { - responsiveImages: true, - }, -} -``` - -With `responsive` set as the default layout, you can override any individual image's `layout` property: - -```astro ---- -import { Image } from 'astro:assets'; -import myImage from '../assets/my_image.png'; ---- -This will use responsive layout -This will use full-width layout -This will disable responsive images -``` - For a complete overview, and to give feedback on this experimental API, see the [Responsive Images RFC](https://github.com/withastro/roadmap/blob/responsive-images/proposals/0053-responsive-images.md). \ No newline at end of file diff --git a/src/content/docs/en/reference/programmatic-reference.mdx b/src/content/docs/en/reference/programmatic-reference.mdx index def9e842ca386..203177efa6f99 100644 --- a/src/content/docs/en/reference/programmatic-reference.mdx +++ b/src/content/docs/en/reference/programmatic-reference.mdx @@ -144,7 +144,7 @@ Returns a `Promise` that resolves once all pending requests have been fulfilled

-**Type:** `(inlineConfig: AstroInlineConfig) => Promise` +**Type:** `(inlineConfig: AstroInlineConfig, options?: BuildOptions) => Promise`

Similar to [`astro build`](/en/reference/cli-reference/#astro-build), it builds your site for deployment. @@ -157,6 +157,39 @@ await build({ }); ``` +### `BuildOptions` + +```ts +export interface BuildOptions { + devOutput?: boolean; + teardownCompiler?: boolean; +} +``` + +#### `devOutput` + +

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

+ +Output a development-based build similar to code transformed in `astro dev`. This can be useful to test build-only issues with additional debugging information included. + +#### `teardownCompiler` + +

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

+ +Teardown the compiler WASM instance after build. This can improve performance when building once but may cause a performance hit if building multiple times in a row. + +When building multiple projects in the same execution (e.g. during tests), disabling this option can greatly increase performance and reduce peak memory usage at the cost of higher sustained memory usage. + ## `preview()`

@@ -246,4 +279,96 @@ import { sync } from "astro"; await sync({ root: "./my-project", }); -``` \ No newline at end of file +``` + +## `mergeConfig()` + +

+ +**Type:** `(config: T, overrides: DeepPartial) => T` + +

+ +Imported from `astro/config`, merges a partial Astro configuration on top of an existing, valid, Astro configuration. + +`mergeConfig()` accepts an Astro config object and a partial config (any set of valid Astro config options), and returns a valid Astro config combining both values such that: + +- Arrays are concatenated (including integrations and remark plugins). +- Objects are merged recursively. +- Vite options are merged using [Vite's own `mergeConfig` function](https://vite.dev/guide/api-javascript#mergeconfig) with the default `isRoot` flag. +- Options that can be provided as functions are wrapped into new functions that recursively merge the return values from both configurations with these same rules. +- All other options override the existing config. + +```ts +import { mergeConfig } from "astro/config"; + +mergeConfig( + { + output: 'static', + site: 'https://example.com', + integrations: [tailwind()], + server: ({command}) => ({ + port: command === 'dev' ? 4321 : 1234, + }), + build: { + client: './custom-client', + }, + }, + { + output: 'server', + base: '/astro', + integrations: [mdx()], + server: ({command}) => ({ + host: command === 'dev' ? 'localhost' : 'site.localhost', + }), + build: { + server: './custom-server', + }, + } +); + +// Result is equivalent to: +{ + output: 'server', + site: 'https://example.com', + base: '/astro', + integrations: [tailwind(), mdx()], + server: ({command}) => ({ + port: command === 'dev' ? 4321 : 1234, + host: command === 'dev' ? 'localhost' : 'site.localhost', + }), + build: { + client: './custom-client', + server: './custom-server', + }, +} +``` + +## `validateConfig()` + +

+ +**Type:** `(userConfig: any, root: string, cmd: string): Promise` + +

+ +Imported from `astro/config`, validates an object as if it was exported from `astro.config.mjs` and imported by Astro. + + +It takes the following arguments: +- The configuration to be validated. +- The root directory of the project. +- The Astro command that is being executed (`build`, `dev`, `sync`, etc.) + +The returned promise resolves to the validated configuration, filled with all default values appropriate for the given Astro command. + +```ts +import { validateConfig } from "astro/config"; + +const config = await validateConfig({ + integrations: [tailwind()], +}, "./my-project", "build"); + +// defaults are applied +await rm(config.outDir, { recursive: true, force: true }); +```