astro

Minor Changes

• #11360 a79a8b0 Thanks @ascorbic! - Changes how type generation works

  The generated .d.ts file is now at a new location:

  - .astro/db-types.d.ts
  + .astro/integrations/astro_db/db.d.ts
  

  The following line can now be removed from src/env.d.ts:

  - /// <reference path="../.astro/db-types.d.ts" />
  

Patch Changes

• #11645 849e4c6 Thanks @bluwy! - Refactors internally to use node:util parseArgs instead of yargs-parser

• Updated dependencies []:

  • @astrojs/[email protected]

Patch Changes

• Updated dependencies [849e4c6, a79a8b0]:
  • @astrojs/[email protected]

Patch Changes

• #11645 849e4c6 Thanks @bluwy! - Refactors internally to use node:util parseArgs instead of arg

Patch Changes

• #11678 34da907 Thanks @ematipico! - Fixes a case where omitting a semicolon and line ending with carriage return - CRLF - in the prerender option could throw an error.

• #11535 932bd2e Thanks @matthewp! - Encrypt server island props

  Server island props are now encrypted with a key generated at build-time. This is intended to prevent accidentally leaking secrets caused by exposing secrets through prop-passing. This is not intended to allow a server island to be trusted to skip authentication, or to protect against any other vulnerabilities other than secret leakage.

  See the RFC for an explanation: https://github.com/withastro/roadmap/blob/server-islands/proposals/server-islands.md#props-serialization

• #11655 dc0a297 Thanks @billy-le! - Fixes Astro Actions input validation when using default values with a form input.

• #11689 c7bda4c Thanks @ematipico! - Fixes an issue in the Astro actions, where the size of the generated cookie was exceeding the size permitted by the Set-Cookie header.

Patch Changes

• #11535 932bd2e Thanks @matthewp! - Move polyfills up before awaiting the env module in the Node.js adapter.

  Previously the env setting was happening before the polyfills were applied. This means that if the Astro env code (or any dependencies) depended on crypto, it would not be polyfilled in time.

  Polyfills should be applied ASAP to prevent races. This moves it to the top of the Node adapter.

Patch Changes

• #11653 32be549 Thanks @florian-lefebvre! - Updates astro:env docs to reflect current developments and usage guidance

• #11658 13b912a Thanks @bholmesdev! - Fixes orThrow() type when calling an Action without an input validator.

• #11603 f31d466 Thanks @bholmesdev! - Improves user experience when render an Action result from a form POST request:

  • Removes "Confirm post resubmission?" dialog when refreshing a result.
  • Removes the ?_astroAction=NAME flag when a result is rendered.

  Also improves the DX of directing to a new route on success. Actions will now redirect to the route specified in your action string on success, and redirect back to the previous page on error. This follows the routing convention of established backend frameworks like Laravel.

  For example, say you want to redirect to a /success route when actions.signup succeeds. You can add /success to your action string like so:

  <form method="POST" action={'/success' + actions.signup}></form>
  

  • On success, Astro will redirect to /success.
  • On error, Astro will redirect back to the current page.

  You can retrieve the action result from either page using the Astro.getActionResult() function.

  Note on security

  This uses a temporary cookie to forward the action result to the next page. The cookie will be deleted when that page is rendered.

  ⚠ The action result is not encrypted. In general, we recommend returning minimal data from an action handler to a) avoid leaking sensitive information, and b) avoid unexpected render issues once the temporary cookie is deleted. For example, a login function may return a user's session id to retrieve from your Astro frontmatter, rather than the entire user object.

Patch Changes

• #11624 7adb350 Thanks @bluwy! - Prevents throwing errors when checking if a component is a React component in runtime

Patch Changes

• #11624 7adb350 Thanks @bluwy! - Prevents throwing errors when checking if a component is a Solid component in runtime

Patch Changes

• #11648 589d351 Thanks @bholmesdev! - Fixes unexpected error when refreshing a POST request from a form using Actions.

• #11600 09ec2ca Thanks @ArmandPhilippot! - Deprecates getEntryBySlug and getDataEntryById functions exported by astro:content in favor of getEntry.

• #11593 81d7150 Thanks @bholmesdev! - Adds support for Date(), Map(), and Set() from action results. See devalue for a complete list of supported values.

  Also fixes serialization exceptions when deploying Actions with edge middleware on Netlify and Vercel.

• #11617 196092a Thanks @abubakriz! - Fix toolbar audit incorrectly flagging images as above the fold.

• #11634 2716f52 Thanks @bholmesdev! - Fixes internal server error when calling an Astro Action without arguments on Vercel.

• #11628 9aaf58c Thanks @madbook! - Ensures consistent CSS chunk hashes across different environments

Patch Changes

• #11584 a65ffe3 Thanks @bholmesdev! - Removes async local storage dependency from Astro Actions. This allows Actions to run in Cloudflare and Stackblitz without opt-in flags or other configuration.

  This also introduces a new convention for calling actions from server code. Instead of calling actions directly, you must wrap function calls with the new Astro.callAction() utility.

  callAction() is meant to trigger an action from server code. getActionResult() usage with form submissions remains unchanged.

  ---
  import { actions } from 'astro:actions';
  
  const result = await Astro.callAction(actions.searchPosts, {
    searchTerm: Astro.url.searchParams.get('search'),
  });
  ---
  
  {
    result.data &&
      {
        /* render the results */
      }
  }
  

  Migration

  If you call actions directly from server code, update function calls to use the Astro.callAction() wrapper for pages and context.callAction() for endpoints:

  ---
  import { actions } from 'astro:actions';
  
  - const result = await actions.searchPosts({ searchTerm: 'test' });
  + const result = await Astro.callAction(actions.searchPosts, { searchTerm: 'test' });
  ---
  

  If you deploy with Cloudflare and added the nodejs_compat or nodejs_als flags for Actions, we recommend removing these:

  compatibility_flags = [
  - "nodejs_compat",
  - "nodejs_als"
  ]
  

  You can also remove node:async_hooks from the vite.ssr.external option in your astro.config file:

  // astro.config.mjs
  import { defineConfig } from 'astro/config';
  
  export default defineConfig({
  - vite: {
  -   ssr: {
  -     external: ["node:async_hooks"]
  -   }
  - }
  })
  

Minor Changes

• #11507 a62345f Thanks @ematipico! - Adds color-coding to the console output during the build to highlight slow pages.

  Pages that take more than 500 milliseconds to render will have their build time logged in red. This change can help you discover pages of your site that are not performant and may need attention.

• #11379 e5e2d3e Thanks @alexanderniebuhr! - The experimental.contentCollectionJsonSchema feature introduced behind a flag in v4.5.0 is no longer experimental and is available for general use.

  If you are working with collections of type data, Astro will now auto-generate JSON schema files for your editor to get IntelliSense and type-checking. A separate file will be created for each data collection in your project based on your collections defined in src/content/config.ts using a library called zod-to-json-schema.

  This feature requires you to manually set your schema's file path as the value for $schema in each data entry file of the collection:

  {
    "$schema": "../../../.astro/collections/authors.schema.json",
    "name": "Armand",
    "skills": ["Astro", "Starlight"]
  }
  

  Alternatively, you can set this value in your editor settings. For example, to set this value in VSCode's json.schemas setting, provide the path of files to match and the location of your JSON schema:

  {
    "json.schemas": [
      {
        "fileMatch": ["/src/content/authors/**"],
        "url": "./.astro/collections/authors.schema.json"
      }
    ]
  }
  

  If you were previously using this feature, please remove the experimental flag from your Astro config:

  import { defineConfig } from 'astro'
  
  export default defineConfig({
  -  experimental: {
  -    contentCollectionJsonSchema: true
  -  }
  })
  

  If you have been waiting for stabilization before using JSON Schema generation for content collections, you can now do so.

  Please see the content collections guide for more about this feature.

• #11542 45ad326 Thanks @ematipico! - The experimental.rewriting feature introduced behind a flag in v4.8.0 is no longer experimental and is available for general use.

  Astro.rewrite() and context.rewrite() allow you to render a different page without changing the URL in the browser. Unlike using a redirect, your visitor is kept on the original page they visited.

  Rewrites can be useful for showing the same content at multiple paths (e.g. /products/shoes/men/ and /products/men/shoes/) without needing to maintain two identical source files.

  Rewrites are supported in Astro pages, endpoints, and middleware.

  Return Astro.rewrite() in the frontmatter of a .astro page component to display a different page's content, such as fallback localized content:

  ---
  // src/pages/es-cu/articles/introduction.astro 
  return Astro.rewrite("/es/articles/introduction")
  ---
  

  Use context.rewrite() in endpoints, for example to reroute to a different page:

  // src/pages/api.js
  export function GET(context) {
    if (!context.locals.allowed) {
      return context.rewrite('/');
    }
  }
  

  The middleware next() function now accepts a parameter with the same type as the rewrite() function. For example, with next("/"), you can call the next middleware function with a new Request.

  // src/middleware.js
  export function onRequest(context, next) {
    if (!context.cookies.get('allowed')) {
      return next('/'); // new signature
    }
    return next();
  }
  

  If you were previously using this feature, please remove the experimental flag from your Astro config:

  // astro.config.mjs
  export default defineConfig({
  -  experimental: {
  -    rewriting: true
  -  }
  })
  

  If you have been waiting for stabilization before using rewrites in Astro, you can now do so.

  Please see the routing guide in docs for more about using this feature.

Patch Changes

• #11509 dfbca06 Thanks @bluwy! - Excludes hoisted scripts and styles from Astro components imported with ?url or ?raw

• #11561 904f1e5 Thanks @ArmandPhilippot! - Uses the correct pageSize default in page.size JSDoc comment

• #11571 1c3265a Thanks @bholmesdev! - BREAKING CHANGE to the experimental Actions API only. Install the latest @astrojs/react integration as well if you're using React 19 features.

  Make .safe() the default return value for actions. This means { data, error } will be returned when calling an action directly. If you prefer to get the data while allowing errors to throw, chain the .orThrow() modifier.

  import { actions } from 'astro:actions';
  
  // Before
  const { data, error } = await actions.like.safe();
  // After
  const { data, error } = await actions.like();
  
  // Before
  const newLikes = await actions.like();
  // After
  const newLikes = await actions.like.orThrow();
  

  Migration

  To migrate your existing action calls:

  • Remove .safe from existing safe action calls
  • Add .orThrow to existing unsafe action calls

• #11546 7f26de9 Thanks @ArmandPhilippot! - Remove "SSR Only" mention in Astro.redirect inline documentation and update reference link.

• #11525 8068131 Thanks @ematipico! - Fixes a case where the build was failing when experimental.actions was enabled, an adapter was in use, and there were not actions inside the user code base.

• #11574 e3f29d4 Thanks @Princesseuh! - Fixes line with the error not being properly highlighted in the error overlay

• #11570 84189b6 Thanks @bholmesdev! - BREAKING CHANGE to the experimental Actions API only. Install the latest @astrojs/react integration as well if you're using React 19 features.

  Updates the Astro Actions fallback to support action={actions.name} instead of using getActionProps(). This will submit a form to the server in zero-JS scenarios using a search parameter:

  ---
  import { actions } from 'astro:actions';
  ---
  
  <form action={actions.logOut}>
    <!--output: action="?_astroAction=logOut"-->
    <button>Log Out</button>
  </form>
  

  You may also construct form action URLs using string concatenation, or by using the URL() constructor, with the an action's .queryString property:

  ---
  import { actions } from 'astro:actions';
  
  const confirmationUrl = new URL('/confirmation', Astro.url);
  confirmationUrl.search = actions.queryString;
  ---
  
  <form method="POST" action={confirmationUrl.pathname}>
    <button>Submit</button>
  </form>
  

  Migration

  getActionProps() is now deprecated. To use the new fallback pattern, remove the getActionProps() input from your form and pass your action function to the form action attribute:

  ---
  import {
    actions,
  - getActionProps,
  } from 'astro:actions';
  ---
  
  + <form method="POST" action={actions.logOut}>
  - <form method="POST">
  - <input {...getActionProps(actions.logOut)} />
    <button>Log Out</button>
  </form>
  

• #11559 1953dbb Thanks @bryanwood! - Allows actions to return falsy values without an error

• #11553 02c85b5 Thanks @ematipico! - Fixes an issue in content collection caching, where two documents with the same contents were generating an error during the build.

• #11548 602c5bf Thanks @TheOtterlord! - Fixes astro add for packages with only prerelease versions

• #11566 0dcef3a Thanks @Princesseuh! - Fixes DomException errors not being handled properly

• #11529 504c383 Thanks @matthewp! - Fix server islands with trailingSlash: always

Patch Changes

• #11567 d27cf6d Thanks @ascorbic! - Logs underlying error when a template cannot be downloaded

Patch Changes

• #11571 1c3265a Thanks @bholmesdev! - BREAKING CHANGE to the experimental Actions API only. Install the latest @astrojs/react integration as well if you're using React 19 features.

  Make .safe() the default return value for actions. This means { data, error } will be returned when calling an action directly. If you prefer to get the data while allowing errors to throw, chain the .orThrow() modifier.

  import { actions } from 'astro:actions';
  
  // Before
  const { data, error } = await actions.like.safe();
  // After
  const { data, error } = await actions.like();
  
  // Before
  const newLikes = await actions.like();
  // After
  const newLikes = await actions.like.orThrow();
  

  Migration

  To migrate your existing action calls:

  • Remove .safe from existing safe action calls
  • Add .orThrow to existing unsafe action calls

• #11570 84189b6 Thanks @bholmesdev! - BREAKING CHANGE to the experimental Actions API only. Install the latest @astrojs/react integration as well if you're using React 19 features.

  Updates the Astro Actions fallback to support action={actions.name} instead of using getActionProps(). This will submit a form to the server in zero-JS scenarios using a search parameter:

  ---
  import { actions } from 'astro:actions';
  ---
  
  <form action={actions.logOut}>
    <!--output: action="?_astroAction=logOut"-->
    <button>Log Out</button>
  </form>
  

  You may also construct form action URLs using string concatenation, or by using the URL() constructor, with the an action's .queryString property:

  ---
  import { actions } from 'astro:actions';
  
  const confirmationUrl = new URL('/confirmation', Astro.url);
  confirmationUrl.search = actions.queryString;
  ---
  
  <form method="POST" action={confirmationUrl.pathname}>
    <button>Submit</button>
  </form>
  

  Migration

  getActionProps() is now deprecated. To use the new fallback pattern, remove the getActionProps() input from your form and pass your action function to the form action attribute:

  ---
  import {
    actions,
  - getActionProps,
  } from 'astro:actions';
  ---
  
  + <form method="POST" action={actions.logOut}>
  - <form method="POST">
  - <input {...getActionProps(actions.logOut)} />
    <button>Log Out</button>
  </form>
  

Patch Changes

• #11505 8ff7658 Thanks @ematipico! - Enhances the dev server logging when rewrites occur during the lifecycle or rendering.

  The dev server will log the status code before and after a rewrite:

  08:16:48 [404] (rewrite) /foo/about 200ms
  08:22:13 [200] (rewrite) /about 23ms
  

• #11506 026e8ba Thanks @sarah11918! - Fixes typo in documenting the slot="fallback" attribute for Server Islands experimental feature.

• #11508 ca335e1 Thanks @cramforce! - Escapes HTML in serialized props

• #11501 4db78ae Thanks @martrapp! - Adds the missing export for accessing the getFallback() function of the client site router.

Patch Changes

• #11486 9c0c849 Thanks @ematipico! - Adds a new function called addClientRenderer to the Container API.

  This function should be used when rendering components using the client:* directives. The addClientRenderer API must be used
  after the use of the addServerRenderer:

  const container = await experimental_AstroContainer.create();
  container.addServerRenderer({ renderer });
  container.addClientRenderer({ name: '@astrojs/react', entrypoint: '@astrojs/react/client.js' });
  const response = await container.renderToResponse(Component);
  

• #11500 4e142d3 Thanks @Princesseuh! - Fixes inferRemoteSize type not working

• #11496 53ccd20 Thanks @alfawal! - Hide the dev toolbar on window.print() (CTRL + P)

Minor Changes

• #11341 49b5145 Thanks @madcampos! - Adds support for Shiki's defaultColor option.

  This option allows you to override the values of a theme's inline style, adding only CSS variables to give you more flexibility in applying multiple color themes.

  Configure defaultColor: false in your Shiki config to apply throughout your site, or pass to Astro's built-in <Code> component to style an individual code block.

  import { defineConfig } from 'astro/config';
  export default defineConfig({
    markdown: {
      shikiConfig: {
        themes: {
          light: 'github-light',
          dark: 'github-dark',
        },
        defaultColor: false,
      },
    },
  });
  

  ---
  import { Code } from 'astro:components';
  ---
  
  <Code code={`const useMyColors = true`} lang="js" defaultColor={false} />
  

• #11304 2e70741 Thanks @Fryuni! - Refactors the type for integration hooks so that integration authors writing custom integration hooks can now allow runtime interactions between their integration and other integrations.

  This internal change should not break existing code for integration authors.

  To declare your own hooks for your integration, extend the Astro.IntegrationHooks interface:

  // your-integration/types.ts
  declare global {
    namespace Astro {
      interface IntegrationHooks {
        'myLib:eventHappened': (your: string, parameters: number) => Promise<void>;
      }
    }
  }
  

  Call your hooks on all other integrations installed in a project at the appropriate time. For example, you can call your hook on initialization before either the Vite or Astro config have resolved:

  // your-integration/index.ts
  import './types.ts';
  
  export default (): AstroIntegration => {
    return {
      name: 'your-integration',
      hooks: {
        'astro:config:setup': async ({ config }) => {
          for (const integration of config.integrations) {
            await integration.hooks['myLib:eventHappened'].?('your values', 123);
          }
        },
      }
    }
  }
  

  Other integrations can also now declare your hooks:

  // other-integration/index.ts
  import 'your-integration/types.ts';
  
  export default (): AstroIntegration => {
    return {
      name: 'other-integration',
      hooks: {
        'myLib:eventHappened': async (your, values) => {
          // ...
        },
      },
    };
  };
  

• #11305 d495df5 Thanks @matthewp! - Experimental Server Islands

  Server Islands allow you to specify components that should run on the server, allowing the rest of the page to be more aggressively cached, or even generated statically. Turn any .astro component into a server island by adding the server:defer directive and optionally, fallback placeholder content:

  ---
  import Avatar from '../components/Avatar.astro';
  import GenericUser from '../components/GenericUser.astro';
  ---
  
  <header>
    <h1>Page Title</h1>
    <div class="header-right">
      <Avatar server:defer>
        <GenericUser slot="fallback" />
      </Avatar>
    </div>
  </header>
  

  The server:defer directive can be used on any Astro component in a project using hybrid or server mode with an adapter. There are no special APIs needed inside of the island.

  Enable server islands by adding the experimental flag to your Astro config with an appropriate output mode and adatper:

  import { defineConfig } from 'astro/config';
  import netlify from '@astrojs/netlify';
  
  export default defineConfig({
    output: 'hybrid',
    adapter: netlify(),
    experimental {
      serverIslands: true,
    },
  });
  

  For more information, see the server islands documentation.

• #11482 7c9ed71 Thanks @Princesseuh! - Adds a --noSync parameter to the astro check command to skip the type-gen step. This can be useful when running astro check inside packages that have Astro components, but are not Astro projects

• #11098 36e30a3 Thanks @itsmatteomanf! - Adds a new inferRemoteSize() function that can be used to infer the dimensions of a remote image.

  Previously, the ability to infer these values was only available by adding the [inferSize] attribute to the <Image> and <Picture> components or getImage(). Now, you can also access this data outside of these components.

  This is useful for when you need to know the dimensions of an image for styling purposes or to calculate different densities for responsive images.

  ---
  import { inferRemoteSize, Image } from 'astro:assets';
  
  const imageUrl = 'https://...';
  const { width, height } = await inferRemoteSize(imageUrl);
  ---
  
  <Image src={imageUrl} width={width / 2} height={height} densities={[1.5, 2]} />
  

• #11391 6f9b527 Thanks @ARipeAppleByYoursTruly! - Adds Shiki's defaultColor option to the <Code /> component, giving you more control in applying multiple themes

• #11176 a751458 Thanks @tsawada! - Adds two new values to the pagination page prop: page.first and page.last for accessing the URLs of the first and last pages.

Patch Changes

• #11477 7e9c4a1 Thanks @ematipico! - Fixes an issue where the development server was emitting a 404 status code when the user uses a rewrite that emits a 200 status code.

• #11479 ca969d5 Thanks @florian-lefebvre! - Fixes a case where invalid astro:env variables at runtime would not throw correctly

• #11489 061f1f4 Thanks @ematipico! - Move root inside the manifest and make serialisable

• #11415 e9334d0 Thanks @florian-lefebvre! - Refactors how sync works and when it's called. Fixes an issue with astro:env types in dev not being generated

• #11478 3161b67 Thanks @bluwy! - Supports importing Astro components with Vite queries, like ?url, ?raw, and ?direct

• #11491 fe3afeb Thanks @matthewp! - Fix for Server Islands in Vercel adapter

  Vercel, and probably other adapters only allow pre-defined routes. This makes it so that the astro:build:done hook includes the _server-islands/ route as part of the route data, which is used to configure available routes.

• #11483 34f9c25 Thanks @Princesseuh! - Fixes Astro not working on low versions of Node 18 and 20

• Updated dependencies [49b5145]:

  • @astrojs/[email protected]

Minor Changes

• #11341 49b5145 Thanks @madcampos! - Adds support for Shiki's defaultColor option.

  This option allows you to override the values of a theme's inline style, adding only CSS variables to give you more flexibility in applying multiple color themes.

  Configure defaultColor: false in your Shiki config to apply throughout your site, or pass to Astro's built-in <Code> component to style an individual code block.

  import { defineConfig } from 'astro/config';
  export default defineConfig({
    markdown: {
      shikiConfig: {
        themes: {
          light: 'github-light',
          dark: 'github-dark',
        },
        defaultColor: false,
      },
    },
  });
  

  ---
  import { Code } from 'astro:components';
  ---
  
  <Code code={`const useMyColors = true`} lang="js" defaultColor={false} />
  

Minor Changes

• #11490 6ad02b5 Thanks @bluwy! - Bumps Svelte 5 peer dependency to ^5.0.0-next.190 and support the latest slots/snippets API

Patch Changes

• Updated dependencies [2e70741]:
  • @astrojs/[email protected]