From a7b158f38aa0867cfd7ddb3da7e519df2b6897b8 Mon Sep 17 00:00:00 2001 From: Emanuele Stoppa Date: Wed, 26 Feb 2025 11:47:34 +0000 Subject: [PATCH 1/7] feat: document new CLI flag (#11019) Co-authored-by: Armand Philippot Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Co-authored-by: yanthomasdev <61414485+yanthomasdev@users.noreply.github.com> --- src/content/docs/en/reference/cli-reference.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/content/docs/en/reference/cli-reference.mdx b/src/content/docs/en/reference/cli-reference.mdx index f11b76b2db4ce..2ab19521208d1 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 `allowHosts` 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. From 2c63b7cf8c353781d34f8ec3330af7bc6d5f5792 Mon Sep 17 00:00:00 2001 From: Emanuele Stoppa Date: Wed, 26 Feb 2025 11:52:10 +0000 Subject: [PATCH 2/7] feat(vercel): update `exclude` API for upcoming new feature (#11065) Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> --- src/content/docs/en/guides/integrations-guide/vercel.mdx | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) 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 + ] } }) }) From ebb44303c091b272d903e5dbd95a8941a6a20a65 Mon Sep 17 00:00:00 2001 From: PolyWolf <31190026+p0lyw0lf@users.noreply.github.com> Date: Wed, 26 Feb 2025 06:55:17 -0500 Subject: [PATCH 3/7] 5.4.0: Markdown Remote Images (#11021) Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com> --- src/content/docs/en/guides/images.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) 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 From 1537514a38b8499ca3fd2296dedc0541083c2707 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Wed, 26 Feb 2025 07:56:41 -0400 Subject: [PATCH 4/7] Experimental responsive images for Markdown (#11060) Co-authored-by: p0lyw0lf <31190026+p0lyw0lf@users.noreply.github.com> --- .../experimental-flags/responsive-images.mdx | 107 ++++++++++-------- 1 file changed, 62 insertions(+), 45 deletions(-) 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..d289be6b4f7fd 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,68 @@ 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 behaviour 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 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 +142,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 From af9c8bf3361171fa7bbe3894d82e174d3a0477ac Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Wed, 26 Feb 2025 09:58:47 -0400 Subject: [PATCH 5/7] Apply suggestions from Armand code review Co-authored-by: Armand Philippot --- src/content/docs/en/reference/cli-reference.mdx | 2 +- .../docs/en/reference/experimental-flags/responsive-images.mdx | 3 +-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/src/content/docs/en/reference/cli-reference.mdx b/src/content/docs/en/reference/cli-reference.mdx index 2ab19521208d1..3f78bb7acfe06 100644 --- a/src/content/docs/en/reference/cli-reference.mdx +++ b/src/content/docs/en/reference/cli-reference.mdx @@ -438,7 +438,7 @@ Do not use the `--host` flag to expose the dev server and preview server in a pr 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 `allowHosts` feature](https://vite.dev/config/server-options.html#server-allowedhosts) for more information, including security implications of allowing hostnames. +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` 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 d289be6b4f7fd..c8f04a6ce71ef 100644 --- a/src/content/docs/en/reference/experimental-flags/responsive-images.mdx +++ b/src/content/docs/en/reference/experimental-flags/responsive-images.mdx @@ -49,8 +49,7 @@ Each of these settings can be overridden on any individual `` or `` and `` components unless overridden with a prop experimentalLayout: 'responsive', - }, - + }, experimental: { responsiveImages: true, }, From 0d6da95f5200a28d93911081273e9534130a19f8 Mon Sep 17 00:00:00 2001 From: Luiz Ferraz Date: Wed, 26 Feb 2025 12:22:46 -0300 Subject: [PATCH 6/7] Document new programmatic APIs and options (#11051) Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> --- .../en/reference/programmatic-reference.mdx | 129 +++++++++++++++++- 1 file changed, 127 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/reference/programmatic-reference.mdx b/src/content/docs/en/reference/programmatic-reference.mdx index def9e842ca386..107c92b49b642 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 }); +``` From 552b08533a57d70baad765c37ad436e400fa81c6 Mon Sep 17 00:00:00 2001 From: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Date: Wed, 26 Feb 2025 19:49:35 -0400 Subject: [PATCH 7/7] Apply suggestions from Yan code review Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com> --- .../en/reference/experimental-flags/responsive-images.mdx | 6 +++--- src/content/docs/en/reference/programmatic-reference.mdx | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) 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 c8f04a6ce71ef..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,7 +24,7 @@ Enables support for automatic responsive images in your project. } ``` -With this flag enabled, you have access to additional [`image` configuration settings](#responsive-image-configuration-settings) for controlling the default behaviour of all images processed and optimized by Astro: +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. @@ -60,10 +60,10 @@ Each of these settings can be overridden on any individual `` or `` 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). +- `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`. +- `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. diff --git a/src/content/docs/en/reference/programmatic-reference.mdx b/src/content/docs/en/reference/programmatic-reference.mdx index 107c92b49b642..203177efa6f99 100644 --- a/src/content/docs/en/reference/programmatic-reference.mdx +++ b/src/content/docs/en/reference/programmatic-reference.mdx @@ -186,9 +186,9 @@ Output a development-based build similar to code transformed in `astro dev`. Thi

-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. +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. +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()`