# Astro

> astro documentation pack

## [Astro](https://docharvest.github.io/docs/astro/)

Contents

astro

Astro

Astro

-   [Astro Coursesastro-courses](/docs/astro/astro-courses/)
-   [Contribute to Astrocontribute](/docs/astro/contribute/)
-   [Develop and builddevelop-and-build](/docs/astro/develop-and-build/)
-   [Editor setupeditor-setup](/docs/astro/editor-setup/)
-   [Getting startedgetting-started](/docs/astro/getting-started/)
-   [Install Astroinstall-and-setup](/docs/astro/install-and-setup/)
-   [Astro recipesrecipes](/docs/astro/recipes/)
-   [Upgrade Astroupgrade-astro](/docs/astro/upgrade-astro/)
-   [Componentsbasics/astro-components](/docs/astro/basics/astro-components/)
-   [Pagesbasics/astro-pages](/docs/astro/basics/astro-pages/)
-   [Layoutsbasics/layouts](/docs/astro/basics/layouts/)
-   [Project structurebasics/project-structure](/docs/astro/basics/project-structure/)
-   [Islands architectureconcepts/islands](/docs/astro/concepts/islands/)
-   [Why Astro?concepts/why-astro](/docs/astro/concepts/why-astro/)
-   [Actionsguides/actions](/docs/astro/guides/actions/)
-   [Authenticationguides/authentication](/docs/astro/guides/authentication/)
-   [Use a backend service with Astroguides/backend](/docs/astro/guides/backend/)
-   [Building Astro sites with AI toolsguides/build-with-ai](/docs/astro/guides/build-with-ai/)
-   [Route cachingguides/caching](/docs/astro/guides/caching/)
-   [Scripts and event handlingguides/client-side-scripts](/docs/astro/guides/client-side-scripts/)
-   [Use a CMS with Astroguides/cms](/docs/astro/guides/cms/)
-   [Configuration overviewguides/configuring-astro](/docs/astro/guides/configuring-astro/)
-   [Content collectionsguides/content-collections](/docs/astro/guides/content-collections/)
-   [Data fetchingguides/data-fetching](/docs/astro/guides/data-fetching/)
-   [Deploy your Astro Siteguides/deploy](/docs/astro/guides/deploy/)
-   [Dev toolbarguides/dev-toolbar](/docs/astro/guides/dev-toolbar/)
-   [E-commerceguides/ecommerce](/docs/astro/guides/ecommerce/)
-   [Endpointsguides/endpoints](/docs/astro/guides/endpoints/)
-   [Using environment variablesguides/environment-variables](/docs/astro/guides/environment-variables/)
-   [Using custom fontsguides/fonts](/docs/astro/guides/fonts/)
-   [Front-end frameworksguides/framework-components](/docs/astro/guides/framework-components/)
-   [Imagesguides/images](/docs/astro/guides/images/)
-   [Imports referenceguides/imports](/docs/astro/guides/imports/)
-   [Working with integrationsguides/integrations](/docs/astro/guides/integrations/)
-   [Internationalization (i18n) Routingguides/internationalization](/docs/astro/guides/internationalization/)
-   [Markdown in Astroguides/markdown-content](/docs/astro/guides/markdown-content/)
-   [Image and video hosting with Astroguides/media](/docs/astro/guides/media/)
-   [Middlewareguides/middleware](/docs/astro/guides/middleware/)
-   [Migrate an existing project to Astroguides/migrate-to-astro](/docs/astro/guides/migrate-to-astro/)
-   [On-demand renderingguides/on-demand-rendering](/docs/astro/guides/on-demand-rendering/)

…and 376 more in the sidebar.

[llms.txt](/docs/astro/llms.txt) for agents

## [Astro Courses](https://docharvest.github.io/docs/astro/astro-courses/)

Contents

astro

Astro Courses

Astro

Astro Courses

Want to get started learning Astro with a course or tutorial?

You can learn the basics of Astro with our [official docs Build a Blog tutorial](/en/tutorial/0-introduction/), or explore our collection of recommended Astro educational content.

## Education Partners

:::tip\[Support Astro while you learn\] Use Astro's affiliate links for discounts with our education partners and some of your purchase goes directly back to funding development of the Astro open source project! :::

Learn Astro from trusted Astro educators, with video lessons, interactive challenges, and projects!

## Community learning resources

Learn from your fellow astronauts with curated collections of guides, articles, and blog posts.

## [Components](https://docharvest.github.io/docs/astro/basics/astro-components/)

Contents

astro

Components

Astro

Components

**Astro components** are the basic building blocks of any Astro project. They are HTML-only templating components with no client-side runtime and use the `.astro` file extension.

:::note If you know HTML, you already know enough to write your first Astro component.

Learn more in the [Astro syntax reference](/en/reference/astro-syntax/). :::

Astro components are extremely flexible. An Astro component can be as small as a snippet of HTML, like a collection of common `<meta>` tags that make SEO easy to work with. Components can be reusable UI elements, like a header or a profile card. Astro components can even contain an entire page layout or, when located in the special `src/pages/` folder, be an entire page itself.

The most important thing to know about Astro components is that they **don't render on the client**. They render to HTML either at build-time or on-demand. You can include JavaScript code inside of your component frontmatter, and all of it will be stripped from the final page sent to your users' browsers. The result is a faster site, with zero JavaScript footprint added by default.

When your Astro component does need client-side interactivity, you can add [standard HTML `<script>` tags](/en/guides/client-side-scripts/) or [UI Framework components](/en/guides/framework-components/#hydrating-interactive-components) as "client islands".

For components that need to render personalized or dynamic content, you can defer their server rendering by adding a [server directive](/en/reference/directives-reference/#server-directives). These "server islands" will render their content when it is available, without delaying the entire page load.

## Component Structure

An Astro component is made up of two main parts: the **Component Script** and the **Component Template**. Each part performs a different job, but together they provide a framework that is both easy to use and expressive enough to handle whatever you might want to build.

```
---
// Component Script (JavaScript)
---
<!-- Component Template (HTML + JS Expressions) -->
```

### The Component Script

Astro uses a code fence (`---`) to identify the component script in your Astro component. If you've ever written Markdown before, you may already be familiar with a similar concept called _frontmatter._ Astro's idea of a component script was directly inspired by this concept.

You can use the component script to write any JavaScript code that you need to render your template. This can include:

-   importing other Astro components
-   importing other framework components, like React
-   importing data, like a JSON file
-   fetching content from an API or database
-   creating variables that you will reference in your template

```
---

// Access passed-in component props, like `<X title="Hello, World" />`
const { title } = Astro.props;

// Fetch external data, even from a private API or database
const data = await fetch('SOME_SECRET_API_URL/users').then(r => r.json());
---
<!-- Your template here! -->
```

The code fence is designed to guarantee that the JavaScript that you write in it is "fenced in." It won't escape into your frontend application, or fall into your user's hands. You can safely write code here that is expensive or sensitive (like a call to your private database) without worrying about it ever ending up in your user's browser.

:::note The Astro component script is TypeScript, which allows you to add additional syntax to JavaScript for editor tooling, and error checking.

Read more about Astro's [built-in TypeScript support](/en/guides/typescript/). :::

### The Component Template

The component template is below the code fence and determines the HTML output of your component.

If you write plain HTML here, your component will render that HTML in any Astro page it is imported and used.

However, [Astro's component template syntax](/en/reference/astro-syntax/) also supports **JavaScript expressions**, Astro [`<style>`](/en/guides/styling/#styling-in-astro) and [`<script>`](/en/guides/client-side-scripts/) tags, **imported components**, and [**special Astro directives**](/en/reference/directives-reference/). Data and values defined in the component script can be used in the component template to produce dynamically-created HTML.

```
---
// Your component script here!

const myFavoritePokemon = [/* ... */];
const { title } = Astro.props;
---
<!-- HTML comments supported! -->
{/* JS comment syntax is also valid! */}

<Banner />
<h1>Hello, world!</h1>

<!-- Use props and other variables from the component script: -->
<p>{title}</p>

<!-- Delay component rendering and provide fallback loading content: -->
<Avatar server:defer>
  <svg slot="fallback" class="generic-avatar" transition:name="avatar">...</svg>
</Avatar>

<!-- Include other UI framework components with a `client:` directive to hydrate: -->
<ReactPokemonComponent client:visible />

<!-- Mix HTML with JavaScript expressions, similar to JSX: -->
<ul>
  {myFavoritePokemon.map((data) => <li>{data.name}</li>)}
</ul>

<!-- Use a template directive to build class names from multiple strings or even objects! -->
<p class:list={["add", "dynamic", { classNames: true }]} />
```

## Component-based design

Components are designed to be **reusable** and **composable**. You can use components inside of other components to build more and more advanced UI. For example, a `Button` component could be used to create a `ButtonGroup` component:

```
---

---
<div>
  <Button title="Button 1" />
  <Button title="Button 2" />
  <Button title="Button 3" />
</div>
```

## Component Props

An Astro component can define and accept props. These props then become available to the component template for rendering HTML. Props are available on the `Astro.props` global in your frontmatter script.

Here is an example of a component that receives a `greeting` prop and a `name` prop. Notice that the props to be received are destructured from the global `Astro.props` object.

```
---
// src/components/GreetingHeadline.astro
// Usage: <GreetingHeadline greeting="Howdy" name="Partner" />
const { greeting, name } = Astro.props;
---
<h2>{greeting}, {name}!</h2>
```

This component, when imported and rendered in other Astro components, layouts or pages, can pass these props as attributes:

```
---
// src/components/GreetingCard.astro

const name = 'Astro';
---
<h1>Greeting Card</h1>
<GreetingHeadline greeting="Hi" name={name} />
<p>I hope you have a wonderful day!</p>
```

You can also define your props with TypeScript with a `Props` type interface. Astro will automatically pick up the `Props` interface in your frontmatter and give type warnings/errors. These props can also be given default values when destructured from `Astro.props`.

```
---
// src/components/GreetingHeadline.astro
interface Props {
  name: string;
  greeting?: string;
}

const { greeting = "Hello", name } = Astro.props;
---
<h2>{greeting}, {name}!</h2>
```

Component props can be given default values to use when none are provided.

```
---
// src/components/GreetingHeadline.astro
const { greeting = "Hello", name = "Astronaut" } = Astro.props;
---
<h2>{greeting}, {name}!</h2>
```

## Slots

The `<slot />` element is a placeholder for external HTML content, allowing you to inject (or "slot") child elements from other files into your component template.

By default, all child elements passed to a component will be rendered in its `<slot />`.

:::note Unlike _props_, which are attributes passed to an Astro component available for use throughout your component with `Astro.props`, _slots_ render child HTML elements where they are written. :::

```
---
// src/components/Wrapper.astro

const { title } = Astro.props;
---
<div id="content-wrapper">
  <Header />
  <Logo />
  <h1>{title}</h1>
  <slot />  <!-- children will go here -->
  <Footer />
</div>
```

```
---
// src/pages/fred.astro

---
<Wrapper title="Fred's Page">
  <h2>All about Fred</h2>
  <p>Here is some stuff about Fred.</p>
</Wrapper>
```

This pattern is the basis of an [Astro layout component](/en/basics/layouts/): an entire page of HTML content can be “wrapped” with `<SomeLayoutComponent></SomeLayoutComponent>` tags and sent to the component to render inside of common page elements defined there.

See the [`Astro.slots` utility functions](/en/reference/astro-syntax/#astroslots) for more ways to access and render slot content.

### Named Slots

An Astro component can also have named slots. This allows you to pass only HTML elements with the corresponding slot name into a slot's location.

Slots are named using the `name` attribute:

```
---
// src/components/Wrapper.astro

const { title } = Astro.props;
---
<div id="content-wrapper">
  <Header />
  <!--  children with the `slot="after-header"` attribute will go here -->
  <slot name="after-header" />
  <Logo />
  <h1>{title}</h1>
  <!--  children without a `slot`, or with `slot="default"` attribute will go here -->
  <slot />
  <Footer />
  <!--  children with the `slot="after-footer"` attribute will go here -->
  <slot name="after-footer" />
</div>
```

To inject HTML content into a particular slot, use the `slot` attribute on any child element to specify the name of the slot. All other child elements of the component will be injected into the default (unnamed) `<slot />`.

```
---
// src/pages/fred.astro

---
<Wrapper title="Fred's Page">
  <img src="https://my.photo/fred.jpg" slot="after-header" />
  <h2>All about Fred</h2>
  <p>Here is some stuff about Fred.</p>
  <p slot="after-footer">Copyright 2022</p>
</Wrapper>
```

:::tip Use a `slot="my-slot"` attribute on the child element that you want to pass through to a matching `<slot name="my-slot" />` placeholder in your component. :::

To pass multiple HTML elements into a component's `<slot/>` placeholder without a wrapping `<div>`, use the `slot=""` attribute on [Astro's `<Fragment/>` component](/en/reference/astro-syntax/#fragments):

```
---
// Create a custom table with named slot placeholders for header and body content
---
<table class="bg-white">
  <thead class="sticky top-0 bg-white"><slot name="header" /></thead>
  <tbody class="[&_tr:nth-child(odd)]:bg-gray-100"><slot name="body" /></tbody>
</table>
```

Inject multiple rows and columns of HTML content using a `slot=""` attribute to specify the `"header"` and `"body"` content. Individual HTML elements can also be styled:

```
---

---
<CustomTable>
  <Fragment slot="header"> <!-- pass table header -->
    <tr><th>Product name</th><th>Stock units</th></tr>
  </Fragment>

  <Fragment slot="body"> <!-- pass table body -->
    <tr><td>Flip-flops</td><td>64</td></tr>
    <tr><td>Boots</td><td>32</td></tr>
    <tr><td>Sneakers</td><td class="text-red-500">0</td></tr>
  </Fragment>
</CustomTable>
```

Note that named slots must be an immediate child of the component. You cannot pass named slots through nested elements.

:::tip Named slots can also be passed to [UI framework components](/en/guides/framework-components/)! :::

:::note It is not possible to dynamically generate an Astro slot name, such as within a [map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map) function. If this feature is needed within UI framework components, it might be best to generate these dynamic slots within the framework itself. :::

### Fallback Content for Slots

Slots can also render **fallback content**. When there are no matching children passed to a slot, a `<slot />` element will render its own placeholder children.

```
---
// src/components/Wrapper.astro

const { title } = Astro.props;
---
<div id="content-wrapper">
  <Header />
  <Logo />
  <h1>{title}</h1>
  <slot>
    <p>This is my fallback content, if there is no child passed into slot</p>
  </slot>
  <Footer />
</div>
```

Fallback content will only be displayed when there are no matching elements with the `slot="name"` attribute being passed in to a named slot.

Astro will pass an empty slot when a slot element exists but has no content to pass. Fallback content cannot be used as a default when an empty slot is passed. Fallback content is only displayed when no slot element can be found.

### Transferring slots

Slots can be transferred to other components. For example, when creating nested layouts:

```
---
---
<html lang="en">
	<head>
		<meta charset="utf-8" />
		<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
		<meta name="viewport" content="width=device-width" />
		<meta name="generator" content={Astro.generator} />
    <slot name="head" />
	</head>
	<body>
		<slot />
	</body>
</html>
```

```
// src/layouts/HomeLayout.astro
---

---
<BaseLayout>
  <slot name="head" slot="head" />
  <slot />
</BaseLayout>
```

:::note Named slots can be transferred to another component using both the `name` and `slot` attributes on a `<slot />` tag. :::

Now, the default and `head` slots passed to `HomeLayout` will be transferred to the `BaseLayout` parent.

```
// src/pages/index.astro
---

---
<HomeLayout>
	<title slot="head">Astro</title>
	<h1>Astro</h1>
</HomeLayout>
```

## HTML Components

Astro supports importing and using `.html` files as components or placing these files within the `src/pages/` subdirectory as pages. You may want to use HTML components if you're reusing code from an existing site built without a framework, or if you want to ensure that your component has no dynamic features.

HTML components must contain only valid HTML, and therefore lack key Astro component features:

-   They don't support frontmatter, server-side imports, or dynamic expressions.
-   Any `<script>` tags are left unbundled, treated as if they had an [`is:inline` directive](/en/reference/directives-reference/#isinline).
-   They can only [reference assets that are in the `public/` folder](/en/basics/project-structure/#public).

:::note A [`<slot />` element](/en/basics/astro-components/#slots) inside an HTML component will work as it would in an Astro component. In order to use the [HTML Web Component Slot](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot) element instead, add `is:inline` to your `<slot>` element. :::

## Next Steps

Read more about using [UI framework components](/en/guides/framework-components/) in your Astro project.

## [Pages](https://docharvest.github.io/docs/astro/basics/astro-pages/)

Contents

astro

Pages

Astro

Pages

* * *

My page content, wrapped in a layout!

\`\`\`

Read more about [layout components](/en/basics/layouts/) in Astro.

## Markdown/MDX Pages

Astro also treats any Markdown (`.md`) files inside of `src/pages/` as pages in your final website. If you have the [MDX Integration installed](/en/guides/integrations-guide/mdx/#installation), it also treats MDX (`.mdx`) files the same way.

:::tip Consider creating [content collections](/en/guides/content-collections/) instead of pages for directories of related Markdown files that share a similar structure, such as blog posts or product items. :::

Markdown files can use the special `layout` frontmatter property to specify a [layout component](/en/basics/layouts/) that will wrap their Markdown content in a full `<html>...</html>` page document.

```
---
# Example: src/pages/page.md
layout: ../layouts/MySiteLayout.astro
title: My Markdown page
---
# Title

This is my page, written in **Markdown.**
```

Read more about [Markdown](/en/guides/markdown-content/) in Astro.

## HTML Pages

Files with the `.html` file extension can be placed in the `src/pages/` directory and used directly as pages on your site. Note that some key Astro features are not supported in [HTML Components](/en/basics/astro-components/#html-components).

## Custom 404 Error Page

For a custom 404 error page, you can create a `404.astro` or `404.md` file in `src/pages`.

This will build to a `404.html` page. Most [deploy services](/en/guides/deploy/) will find and use it.

## Custom 500 Error Page

For a custom 500 error page to show for pages that are [rendered on demand](/en/guides/on-demand-rendering/), create the file `src/pages/500.astro`. This custom page is not available for prerendered pages.

If an error occurs rendering this page, your host's default 500 error page will be shown to your visitor.

During development, if you have a `500.astro`, the error thrown at runtime is logged in your terminal, as opposed to being shown in the error overlay.

### `error`

`src/pages/500.astro` is a special page that is automatically passed an `error` prop for any error thrown during rendering. This allows you to use the details of an error (e.g. from a page, from middleware, etc.) to display information to your visitor.

The `error` prop's data type can be anything, which may affect how you type or use the value in your code:

```
---
interface Props {
  error: unknown;
}

const { error } = Astro.props;
---
<div>{error instanceof Error ? error.message : "Unknown error"}</div>
```

To avoid leaking sensitive information when displaying content from the `error` prop, consider evaluating the error first, and returning appropriate content based on the error thrown. For example, you should avoid displaying the error's stack as it contains information about how your code is structured on the server.

## Page Partials

:::caution Page partials are intended to be used in conjunction with a front-end library, such as [htmx](https://htmx.org/) or [Unpoly](https://unpoly.com/). You can also use them if you are comfortable writing low-level front-end JavaScript. For this reason they are an advanced feature.

Additionally, partials should not be used if the component contains scoped styles or scripts, as these elements will be stripped from the HTML output. If you need scoped styles, it is better to use regular, non-partial pages along with a frontend library that knows how to merge the contents into the head. :::

Partials are page components located within `src/pages/` that are not intended to render as full pages.

Like components located outside of this folder, these files do not automatically include the `<!DOCTYPE html>` declaration, nor any `<head>` content such as scoped styles and scripts.

However, because they are located in the special `src/pages/` directory, the generated HTML is available at a URL corresponding to its file path. This allows a rendering library (e.g. [htmx](https://htmx.org/), [Stimulus](https://stimulus.hotwired.dev/), [jQuery](https://jquery.com/)) to access it on the client and load sections of HTML dynamically on a page without a browser refresh or page navigation.

Partials, when combined with a rendering library, provide an alternative to [Astro islands](/en/concepts/islands/) and [`<script>` tags](/en/guides/client-side-scripts/) for building dynamic content in Astro.

Page files that can export a value for [`partial`](/en/reference/routing-reference/#partial) (e.g. `.astro` and `.mdx`, but not `.md`) can be marked as partials.

```
---

---
<li>I'm a partial!</li>
```

### Using with a library

Partials are used to dynamically update a section of a page using a library such as [htmx](https://htmx.org/).

The following example shows an `hx-post` attribute set to a partial's URL. The content from the partial page will be used to update the targeted HTML element on this page.

```
<html>
  <head>
    <title>My page</title>
    <script src="https://unpkg.com/htmx.org@1.9.6"
      integrity="sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni"
      crossorigin="anonymous"></script>
  </head>
  <body>
    <section>
      <div id="parent-div">Target here</div>
    
      <button hx-post="/partials/clicked/"
        hx-trigger="click"
        hx-target="#parent-div"
        hx-swap="innerHTML"
      >
        Click Me!
      </button>
    </section>
  </body>
</html>
```

The `.astro` partial must exist at the corresponding file path, and include an export defining the page as a partial:

```
---

---
<div>I was clicked!</div>
```

See the [htmx documentation](https://htmx.org/docs/) for more details on using htmx.

## [Layouts](https://docharvest.github.io/docs/astro/basics/layouts/)

Contents

astro

Layouts

Astro

Layouts

## const { title } = Astro.props;

 

# {title}

\`\`\`

```
---

---
<MySiteLayout title="Home Page">
  <p>My page content, wrapped in a layout!</p>
</MySiteLayout>
```

Learn more about [slots](/en/basics/astro-components/#slots).

## Using TypeScript with layouts

Any Astro layout can be modified to introduce type safety & autocompletion by providing the types for your props:

```
---
interface Props { 
  title: string;
  description: string;
  publishDate: string;
  viewCount: number;
}
const { title, description, publishDate, viewCount } = Astro.props;
---
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="description" content={description}>
    <title>{title}</title>
  </head>
  <body>
    <header>
      <p>Published on {publishDate}</p>
      <p>Viewed by {viewCount} folks</p>
    </header>
    <main>
      <slot />
    </main>
  </body>
</html>
```

## Markdown Layouts

Page layouts are especially useful for individual Markdown pages which otherwise would not have any page formatting.

Astro provides a special `layout` frontmatter property intended for [individual `.md` files located within `src/pages/` using file-based routing](/en/guides/markdown-content/#individual-markdown-pages) to specify which `.astro` component to use as the page layout. This component allows you to provide `<head>` content like meta tags (e.g. `<meta charset="utf-8">`) and styles for the Markdown page. By default, this specified component can automatically access data from the Markdown file.

This is not recognized as a special property when using [content collections](/en/guides/content-collections/) to query and render your content.

```
---
layout: ../layouts/BlogPostLayout.astro
title: "Hello, World!"
author: "Matthew Phillips"
date: "09 Aug 2022"
---
All frontmatter properties are available as props to an Astro layout component.

The `layout` property is the only special one provided by Astro.

You can use it in Markdown files located within `src/pages/`.
```

A typical layout for a Markdown page includes:

1.  The `frontmatter` prop to access the Markdown page's frontmatter and other data.
2.  A default [`<slot />`](/en/basics/astro-components/#slots) to indicate where the page's Markdown content should be rendered.

```
---
// 1. The frontmatter prop gives access to frontmatter and other data
const { frontmatter } = Astro.props;
---
<html>
  <head>
    <!-- Add other Head elements here, like styles and meta tags. -->
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta charset="utf-8">
    <title>{frontmatter.title}</title>
  </head>
  <body>
    <!-- Add other UI components here, like common headers and footers. -->
    <h1>{frontmatter.title} by {frontmatter.author}</h1>
    <!-- 2. Rendered HTML will be passed into the default slot. -->
    <slot />
    <p>Written on: {frontmatter.date}</p>
  </body>
</html>
```

You can set a layout’s [`Props` type](/en/guides/typescript/#component-props) with the `MarkdownLayoutProps` helper:

```
---

type Props = MarkdownLayoutProps<{
  // Define frontmatter props here
  title: string;
  author: string;
  date: string;
}>;

// Now, `frontmatter`, `url`, and other Markdown layout properties
// are accessible with type safety
const { frontmatter, url } = Astro.props;
---
<html>
  <head>
    <meta charset="utf-8">
    <link rel="canonical" href={new URL(url, Astro.site).pathname}>
    <title>{frontmatter.title}</title>
  </head>
  <body>
    <h1>{frontmatter.title} by {frontmatter.author}</h1>
    <slot />
    <p>Written on: {frontmatter.date}</p>
  </body>
</html>
```

### Markdown Layout Props

A Markdown layout will have access to the following information via `Astro.props`:

-   **`file`** - The absolute path of this file (e.g. `/home/user/projects/.../file.md`).
-   **`url`** - The URL of the page (e.g. `/en/guides/markdown-content`).
-   **`frontmatter`** - All frontmatter from the Markdown or MDX document.
    -   **`frontmatter.file`** - The same as the top-level `file` property.
    -   **`frontmatter.url`** - The same as the top-level `url` property.
-   **`headings`** - A list of headings (`h1 -> h6`) in the Markdown or MDX document with associated metadata. This list follows the type: `{ depth: number; slug: string; text: string }[]`.
-   **`rawContent()`** - A function that returns the raw Markdown document as a string.
-   **`compiledContent()`** - An async function that returns the Markdown document compiled to an HTML string.

:::note A Markdown layout will have access to all the Markdown file's [available properties](/en/guides/markdown-content/#available-properties) from `Astro.props` **with two key differences:**

-   Heading information (i.e. `h1 -> h6` elements) is available via the `headings` array, rather than a `getHeadings()` function.
    
-   `file` and `url` are _also_ available as nested `frontmatter` properties (i.e. `frontmatter.url` and `frontmatter.file`).
    

:::

### Importing Layouts Manually (MDX)

You can also use the special Markdown layout property in the frontmatter of MDX files to pass `frontmatter` and `headings` props directly to a specified layout component in the same way.

To pass information to your MDX layout that does not (or cannot) exist in your frontmatter, you can instead import and use a `<Layout />` component. This works like any other Astro component, and will not receive any props automatically. Pass it any necessary props directly:

```
---
layout: ../../layouts/BaseLayout.astro
title: 'My first MDX post'
publishDate: '21 September 2022'
---

}

<BaseLayout title={frontmatter.title} fancyJsHelper={fancyJsHelper}>
  Welcome to my new Astro blog, using MDX!
</BaseLayout>
```

Then, your values are available to you through `Astro.props` in your layout, and your MDX content will be injected into the page where your `<slot />` component is written:

```
---
const { title, fancyJsHelper } = Astro.props;
---
<html>
  <head>
    <!-- -->
    <meta charset="utf-8">
  </head>
  <body>
    <!-- -->
    <h1>{title}</h1>
    <slot /> <!-- your content is injected here -->
    <p>{fancyJsHelper()}</p>
    <!-- -->
  </body>
</html>
```

When using any layout (either through the frontmatter `layout` property or by importing a layout), you must include the `<meta charset="utf-8">` tag in your layout as Astro will no longer add it automatically to your MDX page.

Learn more about Astro’s Markdown and MDX support in our [Markdown guide](/en/guides/markdown-content/).

## Nesting Layouts

Layout components do not need to contain an entire page worth of HTML. You can break your layouts into smaller components, and combine layout components to create even more flexible, page templates. This pattern is useful when you want to share some code across multiple layouts.

For example, a `BlogPostLayout.astro` layout component could style a post's title, date and author. Then, a site-wide `BaseLayout.astro` could handle the rest of your page template, like navigation, footers, SEO meta tags, global styles, and fonts. You can also pass props received from your post to another layout, just like any other nested component.

```
---
// src/layouts/BlogPostLayout.astro

const { frontmatter } = Astro.props;
---
<BaseLayout url={frontmatter.url}>
  <h1>{frontmatter.title}</h1>
  <h2>Post author: {frontmatter.author}</h2>
  <slot />
</BaseLayout>
```

## [Project structure](https://docharvest.github.io/docs/astro/basics/project-structure/)

Contents

astro

Project structure

Astro

Project structure

Your new Astro project generated from the `create astro` CLI wizard already includes some files and folders. Others, you will create yourself and add to Astro's existing file structure.

Here's how an Astro project is organized, and some files you will find in your new project.

## Directories and Files

Astro leverages an opinionated folder layout for your project. Every Astro project root should include the following directories and files:

-   `src/*` - Your project source code (components, pages, styles, images, etc.)
-   `public/*` - Your non-code, unprocessed assets (fonts, icons, etc.)
-   `package.json` - A project manifest.
-   `astro.config.mjs` - An Astro configuration file. (recommended)
-   `tsconfig.json` - A TypeScript configuration file. (recommended)

### Example Project Tree

A common Astro project directory might look like this:

\- public/ - robots.txt - favicon.svg - my-cv.pdf - src/ - blog/ - post1.md - post2.md - post3.md - components/ - Header.astro - Button.jsx - images/ - image1.jpg - image2.jpg - image3.jpg - layouts/ - PostLayout.astro - pages/ - posts/ - \[post\].astro - about.astro - \*\*index.astro\*\* - rss.xml.js - styles/ - global.css - content.config.ts - astro.config.mjs - package.json - tsconfig.json

### `src/`

The `src/` folder is where most of your project source code lives. This includes:

-   [Pages](/en/basics/astro-pages/)
-   [Layouts](/en/basics/layouts/)
-   [Astro components](/en/basics/astro-components/)
-   [UI framework components (React, etc.)](/en/guides/framework-components/)
-   [Styles (CSS, Sass)](/en/guides/styling/)
-   [Markdown](/en/guides/markdown-content/)
-   [Images to be optimized and processed by Astro](/en/guides/images/)

Astro processes, optimizes, and bundles your `src/` files to create the final website that is shipped to the browser. Unlike the static `public/` directory, your `src/` files are built and handled for you by Astro.

Some files (like Astro components) are not even sent to the browser as written but are instead rendered to static HTML. Other files (like CSS) are sent to the browser but may be optimized or bundled with other CSS files for performance.

:::tip While this guide describes some popular conventions used in the Astro community, the only directory reserved by Astro is `src/pages/`. You are free to rename and reorganize any other directories in a way that works best for you. :::

### `src/pages`

Pages routes are created for your site by adding [supported file types](/en/basics/astro-pages/#supported-page-files) to this directory.

:::caution `src/pages` is a **required** sub-directory in your Astro project. Without it, your site will have no pages or routes! :::

### `src/components`

**Components** are reusable units of code for your HTML pages. These could be [Astro components](/en/basics/astro-components/), or [UI framework components](/en/guides/framework-components/) like React or Vue. It is common to group and organize all of your project components together in this folder.

This is a common convention in Astro projects, but it is not required. Feel free to organize your components however you like!

### `src/layouts`

[Layouts](/en/basics/layouts/) are Astro components that define the UI structure shared by one or more [pages](/en/basics/astro-pages/).

Just like `src/components`, this directory is a common convention but not required.

### `src/styles`

It is a common convention to store your CSS or Sass files in a `src/styles` directory, but this is not required. As long as your styles live somewhere in the `src/` directory and are imported correctly, Astro will handle and optimize them.

### `public/`

The `public/` directory is for files and assets in your project that do not need to be processed during Astro's build process. The files in this folder will be copied into the build folder untouched, and then your site will be built.

This behavior makes `public/` ideal for common assets that do not require any processing, like some images and fonts, or special files such as `robots.txt` and `manifest.webmanifest`.

You can place CSS and JavaScript in your `public/` directory, but be aware that those files will not be bundled or optimized in your final build.

:::tip As a general rule, any CSS or JavaScript that you write yourself should live in your `src/` directory. :::

### `package.json`

This is a file used by JavaScript package managers to manage your dependencies. It also defines the scripts that are commonly used to run Astro (ex: `npm run dev`, `npm run build`).

There are [two kinds of dependencies](https://docs.npmjs.com/specifying-dependencies-and-devdependencies-in-a-package-json-file) you can specify in a `package.json`: `dependencies` and `devDependencies`. In most cases, these work the same: Astro needs all dependencies at build time, and your package manager will install both. We recommend putting all of your dependencies in `dependencies` to start, and only use `devDependencies` if you find a specific need to do so.

For help creating a new `package.json` file for your project, check out the [manual setup](/en/install-and-setup/#manual-setup) instructions.

### `astro.config.mjs`

This file is generated in every starter template and includes configuration options for your Astro project. Here you can specify integrations to use, build options, server options, and more.

Astro supports several file formats for its JavaScript configuration file: `astro.config.js`, `astro.config.mjs` and `astro.config.ts`. We recommend using `.mjs` in most cases or `.ts` if you want to write TypeScript in your config file.

TypeScript config file loading is handled using [`tsm`](https://github.com/lukeed/tsm) and will respect your project's `tsconfig` options.

See the [configuration reference](/en/reference/configuration-reference/) for complete details.

### `tsconfig.json`

This file is generated in every starter template and includes TypeScript configuration options for your Astro project. Some features (like npm package imports) aren’t fully supported in the editor without a `tsconfig.json` file.

See the [TypeScript Guide](/en/guides/typescript/) for details on setting configurations.

## [Islands architecture](https://docharvest.github.io/docs/astro/concepts/islands/)

Contents

astro

Islands architecture

Astro

Islands architecture

Astro helped pioneer and popularize a new frontend architecture pattern called **Islands Architecture.** Islands architecture works by rendering the majority of your page to fast, static HTML with smaller "islands" of JavaScript added when interactivity or personalization is needed on the page (an image carousel, for example). This avoids the monolithic JavaScript payloads that slow down the responsiveness of many other, modern JavaScript web frameworks.

## A brief history

The term "component island" was first coined by Etsy's frontend architect [Katie Sylor-Miller](https://sylormiller.com/) in 2019. This idea was then expanded on and documented in [this post](https://jasonformat.com/islands-architecture/) by Preact creator Jason Miller on August 11, 2020.

> The general idea of an "Islands" architecture is deceptively simple: render HTML pages on the server, and inject placeholders or slots around highly dynamic regions \[...\] that can then be "hydrated" on the client into small self-contained widgets, reusing their server-rendered initial HTML.  
> — Jason Miller, Creator of Preact

The technique that this architectural pattern builds on is also known as **partial** or **selective hydration.**

In contrast, most JavaScript-based web frameworks hydrate & render an entire website as one large JavaScript application (also known as a single-page application, or SPA). SPAs provide simplicity and power but suffer from page-load performance problems due to heavy client-side JavaScript usage.

SPAs have their place, even [embedded inside an Astro page](/en/guides/migrate-to-astro/from-create-react-app/). But, SPAs lack the native ability to selectively and strategically hydrate, making them a heavy-handed choice for most projects on the web today.

Astro became popular as the first mainstream JavaScript web framework with selective hydration built-in, using that same component islands pattern first coined by Sylor-Miller. We've since expanded and evolved on Sylor-Miller's original work, which helped to inspire a similar component island approach to dynamically server-rendered content.

## What is an island?

In Astro, an island is an enhanced UI component on an otherwise static page of HTML.

A [**client island**](#client-islands) is an interactive JavaScript UI component that is hydrated separately from the rest of the page, while a [**server island**](#server-islands) is a UI component that server-renders its dynamic content separately from the rest of the page.

Both islands run expensive or slower processes independently, on a per-component basis, for optimized page loads.

## Island components

Astro components are the building blocks of your page template. They render to static HTML with no client-side runtime.

Think of a client island as an interactive widget floating in a sea of otherwise static, lightweight, server-rendered HTML. Server islands can be added for personalized or dynamic server-rendered elements, such as a logged in visitor's profile picture.

Header (interactive island) Sidebar (static HTML) Static content like text, images, etc. Image carousel (interactive island) Footer (static HTML) Source: \[Islands Architecture: Jason Miller\](https://jasonformat.com/islands-architecture/)

An island always runs in isolation from other islands on the page, and multiple islands can exist on a page. Client islands can still share state and communicate with each other, even though they run in different component contexts.

This flexibility allows Astro to support multiple UI frameworks like [React](https://react.dev/), [Preact](https://preactjs.com/), [Svelte](https://svelte.dev/), [Vue](https://vuejs.org/), and [SolidJS](https://www.solidjs.com/). Because they are independent, you can even mix several frameworks on each page.

:::tip Although most developers will stick to just one UI framework, Astro supports multiple frameworks in the same project. This allows you to:

-   Choose the framework that is best for each component.
-   Learn a new framework without needing to start a new project.
-   Collaborate with others even when working in different frameworks.
-   Incrementally convert an existing site to another framework with no downtime. :::

## Client Islands

By default, Astro will automatically render every UI component to just HTML & CSS, **stripping out all client-side JavaScript automatically.**

```
<MyReactComponent />
```

This may sound strict, but this behavior is what keeps Astro websites fast by default and protects developers from accidentally sending unnecessary or unwanted JavaScript that might slow down their website.

Turning any static UI component into an interactive island requires only a `client:*` directive. Astro then automatically builds and bundles your client-side JavaScript for optimized performance.

```
<!-- This component is now interactive on the page! 
     The rest of your website remains static. -->
<MyReactComponent client:load />
```

With islands, client-side JavaScript is only loaded for the explicit interactive components that you mark using `client:*` directives.

And because interaction is configured at the component-level, you can handle different loading priorities for each component based on its usage. For example, `client:idle` tells a component to load when the browser becomes idle, and `client:visible` tells a component to load only once it enters the viewport.

### Benefits of client islands

The most obvious benefit of building with Astro Islands is performance: the majority of your website is converted to fast, static HTML and JavaScript is only loaded for the individual components that need it. JavaScript is one of the slowest assets that you can load per-byte, so every byte counts.

Another benefit is parallel loading. In the example illustration above, the low-priority "image carousel" island doesn't need to block the high-priority "header" island. The two load in parallel and hydrate in isolation, meaning that the header becomes interactive immediately without having to wait for the heavier carousel lower down the page.

Even better, you can tell Astro exactly how and when to render each component. If that image carousel is really expensive to load, you can attach a special [client directive](/en/reference/directives-reference/#client-directives) that tells Astro to only load the carousel when it becomes visible on the page. If the user never sees it, it never loads.

In Astro, it’s up to you as the developer to explicitly tell Astro which components on the page need to also run in the browser. Astro will only hydrate exactly what’s needed on the page and leave the rest of your site as static HTML.

**Client islands are the secret to Astro’s fast-by-default performance story!**

Read more about [using JavaScript framework components](/en/guides/framework-components/) in your project.

## Server islands

Server islands are a way to move expensive or slow server-side code out of the way of the main rendering process, making it easy to combine high-performance static HTML and dynamic server-generated components.

Add the [`server:defer` directive](/en/reference/directives-reference/#server-directives) to any Astro component on your page to turn it into its own server island:

```
---

---
<Avatar server:defer />
```

This breaks up your page with smaller areas of server-rendered content that each load in parallel.

Your page's main content can be rendered immediately with placeholder content, such as a generic avatar, until your island's own content is available. With server islands, having small components of personalized content does not delay the rendering of an otherwise static page.

This rendering pattern was built to be portable. It does not depend on any server infrastructure so it will work with any host, from a Node.js server in a Docker container to the serverless provider of your choice.

### Benefits of server islands

One benefit of server islands is the ability to render the more highly dynamic parts of your page on the fly. This allows the outer shell and main content to be more aggressively cached, providing faster performance.

Another benefit is providing a great visitor experience. Server islands are optimized and load quickly, often even before the browser has even painted the page. But in the short time it takes for your islands to render, you can display custom fallback content and prevent any layout shift.

An example of a site that benefits from Astro's server islands is an e-commerce storefront. Although the main content of product pages change infrequently, these pages typically have some dynamic pieces:

-   The user's avatar in the header.
-   Special deals and sales for the product.
-   User reviews.

Using server islands for these elements, your visitor will see the most important part of the page, your product, immediately. Generic avatars, loading spinners, and store announcements can be displayed as fallback content until the personalized parts are available.

Read more about [using server islands](/en/guides/server-islands/) in your project.

## [Why Astro?](https://docharvest.github.io/docs/astro/concepts/why-astro/)

Contents

astro

Why Astro?

Astro

Why Astro?

**Astro** is the web framework for building **content-driven websites** like blogs, marketing, and e-commerce. Astro is best-known for pioneering a new [frontend architecture](/en/concepts/islands/) to reduce JavaScript overhead and complexity compared to other frameworks. If you need a website that loads fast and has great SEO, then Astro is for you.

## Features

**Astro is an all-in-one web framework.** It includes everything you need to create a website, built-in. There are also hundreds of different [integrations](https://astro.build/integrations/) and [API hooks](/en/reference/integrations-reference/) available to customize a project to your exact use case and needs.

Some highlights include:

-   **[Islands](/en/concepts/islands/):** A component-based web architecture optimized for content-driven websites.
-   **[UI-agnostic](/en/guides/framework-components/):** Supports React, Preact, Svelte, Vue, Solid, HTMX, web components, and more.
-   **[Server-first](/en/guides/on-demand-rendering/):** Moves expensive rendering off of your visitors' devices.
-   **[Zero JS, by default](/en/basics/astro-components/):** Less client-side JavaScript to slow your site down.
-   **[Content collections](/en/guides/content-collections/):** Organize, validate, and provide TypeScript type-safety for your Markdown content.
-   **[Customizable](/en/guides/integrations/):** Partytown, MDX, and hundreds of integrations to choose from.

## Design Principles

Here are five core design principles to help explain why we built Astro, the problems that it exists to solve, and why Astro may be the best choice for your project or team.

Astro is...

1.  **[Content-driven](#content-driven):** Astro was designed to showcase your content.
2.  **[Server-first](#server-first):** Websites run faster when they render HTML on the server.
3.  **[Fast by default](#fast-by-default):** It should be impossible to build a slow website in Astro.
4.  **[Easy to use](#easy-to-use):** You don't need to be an expert to build something with Astro.
5.  **[Developer-focused](#developer-focused):** You should have the resources you need to be successful.

### Content-driven

**Astro was designed for building content-rich websites.** This includes marketing sites, publishing sites, documentation sites, blogs, portfolios, landing pages, community sites, and e-commerce sites. If you have content to show, it needs to reach your reader quickly.

By contrast, most modern web frameworks were designed for building _web applications_. These frameworks excel at building more complex, application-like experiences in the browser: logged-in admin dashboards, inboxes, social networks, todo lists, and even native-like applications like [Figma](https://figma.com/) and [Ping](https://ping.gg/). However with that complexity, they can struggle to provide great performance when delivering your content.

Astro's focus on content from its beginnings as a static site builder have allowed Astro to **sensibly scale up to performant, powerful, dynamic web applications** that still respect your content and your audience. Astro's unique focus on content lets Astro make tradeoffs and deliver unmatched performance features that wouldn't make sense for more application-focused web frameworks to implement.

### Server-first

**Astro leverages server rendering over client-side rendering in the browser as much as possible.** This is the same approach that traditional server-side frameworks -- PHP, WordPress, Laravel, Ruby on Rails, etc. -- have been using for decades. But you don't need to learn a second server-side language to unlock it. With Astro, everything is still just HTML, CSS, and JavaScript (or TypeScript, if you prefer).

This approach stands in contrast to other modern JavaScript web frameworks like Next.js, SvelteKit, Nuxt, Remix, and others. These frameworks were built for client-side rendering of your entire website and include server-side rendering mainly to address performance concerns. This approach has been dubbed the **Single-Page App (SPA)**, in contrast with Astro's **Multi-Page App (MPA)** approach.

The SPA model has its benefits. However, these come at the expense of additional complexity and performance tradeoffs. These tradeoffs harm page performance -- critical metrics like [Time to Interactive (TTI)](https://web.dev/interactive/) -- which doesn't make much sense for content-focused websites where first-load performance is essential.

Astro's server-first approach allows you to opt in to client-side rendering only if, and exactly as, necessary. You can choose to add UI framework components that run on the client. You can take advantage of Astro's view transitions router for finer control over select page transitions and animations. Astro's server-first rendering, either pre-rendered or on-demand, provides performant defaults that you can enhance and extend.

### Fast by default

Good performance is always important, but it is _especially_ critical for websites whose success depends on displaying your content. It has been well-proven that poor performance loses you engagement, conversions, and money. For example:

-   Every 100ms faster → 1% more conversions ([Mobify](https://web.dev/why-speed-matters/), earning +$380,000/yr)
-   50% faster → 12% more sales ([AutoAnything](https://www.digitalcommerce360.com/2010/08/19/web-accelerator-revs-conversion-and-sales-autoanything/))
-   20% faster → 10% more conversions ([Furniture Village](https://www.thinkwithgoogle.com/intl/en-gb/marketing-strategies/app-and-mobile/furniture-village-and-greenlight-slash-page-load-times-boosting-user-experience/))
-   40% faster → 15% more sign-ups ([Pinterest](https://medium.com/pinterest-engineering/driving-user-growth-with-performance-improvements-cfc50dafadd7))
-   850ms faster → 7% more conversions ([COOK](https://web.dev/why-speed-matters/))
-   Every 1 second slower → 10% fewer users ([BBC](https://www.creativebloq.com/features/how-the-bbc-builds-websites-that-scale))

In many web frameworks, it is easy to build a website that looks great during development only to load painfully slow once deployed. JavaScript is often the culprit, since many phones and lower-powered devices rarely match the speed of a developer's laptop.

Astro's magic is in how it combines the two values explained above -- a content focus with a server-first architecture -- to make tradeoffs and deliver features that other frameworks cannot. The result is amazing web performance for every website, out of the box. Our goal: **It should be nearly impossible to build a slow website with Astro.**

An Astro website can [load 40% faster with 90% less JavaScript](https://twitter.com/t3dotgg/status/1437195415439360003) than the same site built with the most popular React web framework. But don't take our word for it: watch Astro's performance leave Ryan Carniato (creator of Solid.js and Marko) [speechless](https://youtu.be/2ZEMb_H-LYE?t=8163).

### Easy to use

**Astro's goal is to be accessible to every web developer.** Astro was designed to feel familiar and approachable regardless of skill level or past experience with web development.

The `.astro` UI language is a superset of HTML: any valid HTML is valid Astro templating syntax! So, if you can write HTML, you can write Astro components! But, it also combines some of our favorite features borrowed from other component languages like JSX expressions (React) and CSS scoping by default (Svelte and Vue). This closeness to HTML also makes it easier to use progressive enhancement and common accessibility patterns without any overhead.

We then made sure that you could also use your favorite UI component languages that you already know, and even reuse components you might already have. React, Preact, Svelte, Vue, Solid, and others, including web components, are all supported for authoring UI components in an Astro project.

Astro was designed to be less complex than other UI frameworks and languages. One big reason for this is that Astro was designed to render on the server, not in the browser. That means that you don't need to worry about hooks (React), stale closures (also React), refs (Vue), observables (Svelte), atoms, selectors, reactions, or derivations. There is no reactivity on the server, so all of that complexity melts away.

One of our favorite sayings is **opt in to complexity.** We designed Astro to remove as much "required complexity" as possible from the developer experience, especially as you onboard for the first time. You can build a "Hello World" example website in Astro with just HTML and CSS. Then, when you need to build something more powerful, you can incrementally reach for new features and APIs as you go.

### Developer-focused

We strongly believe that Astro is only a successful project if people love using it. Astro has everything you need to support you as you build with Astro.

Astro invests in developer tools like a great CLI experience from the moment you open your terminal, an official VS Code extension for syntax highlighting, TypeScript and Intellisense, and documentation actively maintained by hundreds of community contributors and available in 14 languages.

Our welcoming, respectful, inclusive community on Discord is ready to provide support, motivation, and encouragement. Open a `#support` thread to get help with your project. Visit our dedicated `#showcase` channel for sharing your Astro sites, blog posts, videos, and even work-in-progress for safe feedback and constructive criticism. Participate in regular live events such as our weekly community call, "Talking and Doc'ing," and API/bug bashes.

As an open-source project, we welcome contributions of all types and sizes from community members of all experience levels. You are invited to join in roadmap discussions to shape the future of Astro, and we hope you'll contribute fixes and features to the core codebase, compiler, docs, language tools, websites, and other projects.

## [Contribute to Astro](https://docharvest.github.io/docs/astro/contribute/)

Contents

astro

Contribute to Astro

Astro

Contribute to Astro

import ContributorList from '~/components/ContributorList.astro'

We welcome contributions of any size and contributors of any skill level. As an open-source project, we believe in giving back to our contributors. We are happy to help with guidance on PRs, technical writing, and turning any feature idea into a reality.

:::tip\[Open Issues\] Browse [all of Astro's open GitHub issues tagged `help wanted` and `good first issues`](https://github.com/search?q=org%3Awithastro+label%3A%22good+first+issue%22%2C%22help+wanted%22%2C+state%3Aopen&type=issues) for all the code repositories: Astro code, documentation, Starlight, Astro websites, language tools, GitHub Actions, bots, the compiler... there are lots of places to contribute! :::

Want to get even more involved? See our [Governance doc](https://github.com/withastro/.github/blob/main/GOVERNANCE.md) for detailed descriptions of different roles, maintainer nomination processes, code review processes, and Code of Conduct enforcement.

## Ways to Contribute

### Project repositories

There are lots of ways to contribute to the Astro Project! Every Astro repository has a README with a link to a `CONTRIBUTING.md` file in the root of the project.

Visit [Astro's GitHub profile](https://github.com/withastro) to find the repositories for:

-   The [main Astro codebase](https://github.com/withastro/astro), including official integrations and starter templates.
    
-   [Astro Docs](https://github.com/withastro/docs), an entire Astro website! Contribute not just written content, but also Astro code addressing a11y, CSS, UI, and UX concerns. We also make our documentation available in several languages, so we need help translating the entire site.
    
-   The [Astro compiler](https://github.com/withastro/compiler-rs), written in Rust, distributed as WASM.
    
-   Astro's [language tools](https://github.com/withastro/astro/tree/main/packages/language-tools), the editor tooling required for the Astro language (`.astro` files).
    
-   [Starlight](https://github.com/withastro/starlight), Astro's official documentation framework.
    
-   The [Astro Roadmap](https://github.com/withastro/roadmap) where the future of Astro is shaped! Ideas, suggestions, and formal RFC proposals for the Astro project.
    

### Types of contributions

In addition to contributing your own code or content, you can also make a huge contribution by getting involved by leaving review comments on PRs, adding ideas in existing GitHub Issues and Discussions, and participating in our "Pinned" issue maintenance tasks!

Every PR, especially translation PRs, needs reviewers! Reviewing PRs and leaving comments, suggestions, or an approving "LGTM!" ("Looks Good To Me!") is a great way to get started in any repository, and to learn more about Astro.

We also have a very active [Discord](https://astro.build/chat) community! We value the contributions of those who welcome new members, answer support questions, and share what they have built with and for Astro! Beyond traditional GitHub contributions, Astro recognizes and supports community members who engage with our community, share Astro in blog posts, videos and conference talks, and help maintain the health of our community.

## Contributing to Docs

We have several guides available to assist you with contributing to Astro Docs.

Whether it's your very first contribution to open-source, or you need to add docs for the new Astro feature you just built, or you're an experienced translator looking for the next page to translate, or you'd like to learn more about helping as a PR reviewer... we've got you covered!

Please visit our dedicated site [_Astro Docs_ Docs](https://contribute.docs.astro.build), where you'll find our documentation to help you contribute to Astro Docs as a typo-fixer, a writer, a translator, a feature-builder, and even as a PR reviewer.

## Our contributors

These docs are brought to you by all these helpful people. [Join us on GitHub!](https://github.com/withastro/docs)

## [Develop and build](https://docharvest.github.io/docs/astro/develop-and-build/)

Contents

astro

Develop and build

Astro

Develop and build

Once you have an Astro project, now you're ready to build with Astro! 🚀

## Edit your project

To make changes to your project, open your project folder in your code editor. Working in development mode with the dev server running allows you to see updates to your site as you edit the code.

You can also [customize aspects of your development environment](#configure-your-dev-environment) such as configuring TypeScript or installing the official Astro editor extensions.

### Start the Astro dev server

Astro comes with a built-in development server that has everything you need for project development. The `astro dev` CLI command will start the local development server so that you can see your new website in action for the very first time.

Every starter template comes with a pre-configured script that will run `astro dev` for you. After navigating into your project directory, use your favorite package manager to run this command and start the Astro development server.

\`\`\`shell npm run dev \`\`\` \`\`\`shell pnpm run dev \`\`\` \`\`\`shell yarn run dev \`\`\`

If all goes well, Astro will now be serving your project on [http://localhost:4321/](http://localhost:4321/). Visit that link in your browser and see your new site!

### Work in development mode

Astro will listen for live file changes in your `src/` directory and update your site preview as you build, so you will not need to restart the server as you make changes during development. You will always be able to see an up-to-date version of your site in your browser when the dev server is running.

When viewing your site in the browser, you'll have access to the [Astro dev toolbar](/en/guides/dev-toolbar/). As you build, it will help you inspect your [islands](/en/concepts/islands/), spot accessibility issues, and more.

If you aren't able to open your project in the browser after starting the dev server, go back to the terminal where you ran the `dev` command and check the message displayed. It should tell you if an error occurred, or if your project is being served at a different URL than [http://localhost:4321/](http://localhost:4321/).

## Build and preview your site

To check the version of your site that will be created at build time, quit the dev server (Ctrl + C) and run the appropriate build command for your package manager in your terminal:

\`\`\`shell npm run build \`\`\` \`\`\`shell pnpm build \`\`\` \`\`\`shell yarn run build \`\`\`

Astro will build a deploy-ready version of your site in a separate folder (`dist/` by default) and you can watch its progress in the terminal. This will alert you to any build errors in your project before you deploy to production. If TypeScript is configured to `strict` or `strictest`, the `build` script will also check your project for type errors.

When the build is finished, run the appropriate `preview` command (e.g. `npm run preview`) in your terminal and you can view the built version of your site locally in the same browser preview window.

Note that this previews your code as it existed when the build command was last run. This is meant to give you a preview of how your site will look when it is deployed to the web. Any later changes you make to your code after building will **not** be reflected while you preview your site until you run the build command again.

Use (Ctrl + C) to quit the preview and run another terminal command, such as restarting the dev server to go back to [working in development mode](#work-in-development-mode) which does update as you edit to show a live preview of your code changes.

Read more about [the Astro CLI](/en/reference/cli-reference/) and the terminal commands you will use as you build with Astro.

:::tip You may wish to [deploy your new site right away](/en/guides/deploy/), before you begin to add or change too much code. This is helpful to get a minimal, working version of your site published and can save you extra time and effort troubleshooting your deployment later. :::

## Next Steps

Success! You are now ready to start building with Astro! 🥳

Here are a few things that we recommend exploring next. You can read them in any order. You can even leave our documentation for a bit and go play in your new Astro project codebase, coming back here whenever you run into trouble or have a question.

### Configure your dev environment

Explore the guides below to customize your development experience.

### Explore Astro's Features

### Take the introductory tutorial

Build a fully functional Astro blog starting from a single blank page in our [introductory tutorial](/en/tutorial/0-introduction/).

This is a great way to see how Astro works and walks you through the basics of pages, layouts, components, routing, islands, and more. It also includes an optional, beginner-friendly unit for those newer to web development concepts in general, which will guide you through installing the necessary applications on your computer, creating a GitHub account, and deploying your site.

## [Editor setup](https://docharvest.github.io/docs/astro/editor-setup/)

Contents

astro

Editor setup

Astro

Editor setup

See how to [set up TypeScript](/en/guides/typescript/) in your Astro project.

## Zed

[Zed](https://zed.dev/) is a high-performance, multiplayer code editor that is optimized for speed and large projects. Their [Astro extension](https://zed.dev/extensions/astro) includes features like syntax highlighting for `.astro` files, code completion, formatting, diagnostics, and go-to-definition.

## JetBrains IDEs

[Webstorm](https://www.jetbrains.com/webstorm/) is a JavaScript and TypeScript IDE that added support for the Astro Language Server in version 2024.2. This update brings features like syntax highlighting, code completion, and formatting.

Install the official plugin through [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/20959-astro) or by searching for "Astro" in the IDE's Plugins tab. You can toggle the language server in `Settings | Languages & Frameworks | TypeScript | Astro`.

For more information on Astro support in Webstorm, check out [the official Webstorm Astro Documentation](https://www.jetbrains.com/help/webstorm/astro.html).

## Other Code Editors

Our amazing community maintains several extensions for other popular editors, including:

-   [VS Code Extension on Open VSX](https://open-vsx.org/extension/astro-build/astro-vscode) \- The official Astro VS Code Extension, available on the Open VSX registry for editors like [Cursor](https://cursor.com) or [VSCodium](https://vscodium.com/).
-   [Vim Plugin](https://github.com/wuelnerdotexe/vim-astro) \- Provides syntax highlighting, indentation, and code folding support for Astro inside of Vim or Neovim
-   Neovim [LSP](https://github.com/neovim/nvim-lspconfig/blob/master/doc/configs.md#astro) and [TreeSitter](https://github.com/virchau13/tree-sitter-astro) Plugins \- Provides syntax highlighting, treesitter parsing, and code completion for Astro inside of Neovim
-   Emacs - See instructions for [Configuring Emacs and Eglot](https://medium.com/@jrmjrm/configuring-emacs-and-eglot-to-work-with-astro-language-server-9408eb709ab0) to work with Astro
-   [Astro syntax highlighting for Sublime Text](https://packagecontrol.io/packages/Astro) \- The Astro package for Sublime Text, available on the Sublime Text package manager.
-   [Nova Extension](https://extensions.panic.com/extensions/sciencefidelity/sciencefidelity.astro/) \- Provides syntax highlighting and code completion for Astro inside of Nova

## In-Browser Editors

In addition to local editors, Astro also runs well on in-browser hosted editors, including:

-   [StackBlitz](https://stackblitz.com/) and [CodeSandbox](https://codesandbox.io/) - online editors that run in your browser, with built-in syntax highlighting support for `.astro` files. No installation or configuration required!
-   [GitHub.dev](https://github.dev/) - allows you to install the Astro VS Code extension as a [web extension](https://code.visualstudio.com/api/extension-guides/web-extensions), which gives you access to only some of the full extension features. Currently, only syntax highlighting is supported.

## Other tools

### ESLint

[ESLint](https://eslint.org/) is a popular linter for JavaScript and JSX. For Astro support, [a community maintained plugin](https://github.com/ota-meshi/eslint-plugin-astro) can be installed.

See [the project's User Guide](https://ota-meshi.github.io/eslint-plugin-astro/user-guide/) for more information on how to install and set up ESLint for your project.

### Stylelint

[Stylelint](https://stylelint.io/) is a popular linter for CSS. [A community maintained Stylelint configuration](https://github.com/ota-meshi/stylelint-config-html) provides Astro support.

Installation instructions, editor integration, and additional information can be found in the project's README.

### Biome

[Biome](https://biomejs.dev/) is an all-in-one linter and formatter for the web. [Biome currently has experimental support for `.astro` files](https://biomejs.dev/internals/language-support/#html-super-languages-support), and can be used to lint and format the frontmatter in `.astro` files.

### Prettier

[Prettier](https://prettier.io/) is a popular formatter for JavaScript, HTML, CSS, and more. If you're using the [Astro VS Code Extension](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode), code formatting with Prettier is included.

To add support for formatting `.astro` files outside of the editor (e.g. CLI) or inside editors that don't support our editor tooling, install [the official Astro Prettier plugin](https://github.com/withastro/prettier-plugin-astro).

1\. Install \`prettier\` and \`prettier-plugin-astro\`.

```
<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install --save-dev --save-exact prettier prettier-plugin-astro
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm add --save-dev --save-exact prettier prettier-plugin-astro
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn add --dev --exact prettier prettier-plugin-astro
  ```
  </Fragment>
</PackageManagerTabs>
```

2.  Create a `.prettierrc` configuration file (or `.prettierrc.json`, `.prettierrc.mjs`, or [other supported formats](https://prettier.io/docs/configuration)) in the root of your project and add `prettier-plugin-astro` to it.
    
    In this file, also manually specify the parser for Astro files.
    
    ```
    {
      "plugins": ["prettier-plugin-astro"],
      "overrides": [
        {
          "files": "*.astro",
          "options": {
            "parser": "astro"
          }
        }
      ]
    }
    ```
    
3.  Optionally, install other Prettier plugins for your project, and add them to the configuration file. These additional plugins may need to be listed in a specific order. For example, if you use Tailwind, `prettier-plugin-tailwindcss` must be [the last Prettier plugin in the plugins array](https://github.com/tailwindlabs/prettier-plugin-tailwindcss#compatibility-with-other-prettier-plugins).
    
    ```
    {
      "plugins": [
        "prettier-plugin-astro",
        "prettier-plugin-tailwindcss" // needs to be last
      ],
      "overrides": [
        {
          "files": "*.astro",
          "options": {
            "parser": "astro"
          }
        }
      ]
    }
    ```
    
4.  Run the following command in your terminal to format your files.
    
    \`\`\`shell npx prettier . --write \`\`\` \`\`\`shell pnpm exec prettier . --write \`\`\` \`\`\`shell yarn exec prettier . --write \`\`\`

See the [Prettier plugin's README](https://github.com/withastro/prettier-plugin-astro/blob/main/README.md) for more information about its supported options, how to set up Prettier inside VS Code, and more.

### dprint

[dprint](https://dprint.dev/) is a highly-configurable code formatter that supports many languages, including JavaScript, TypeScript, CSS, and more. Support for `.astro` files can be added using the [markup\_fmt plugin](https://github.com/g-plane/markup_fmt).

## [Getting started](https://docharvest.github.io/docs/astro/getting-started/)

Contents

astro

Getting started

Astro

Getting started

import { CardGrid } from '@astrojs/starlight/components' import Card from '/components/Landing/Card.astro' import ListCard from '/components/Landing/ListCard.astro' import SplitCard from '/components/Landing/SplitCard.astro' import Discord from '/components/Landing/Discord.astro'

Explore \[Astro starter themes\](https://astro.build/themes/) for blogs, portfolios, docs, landing pages, SaaS, marketing, ecommerce sites, and more! Complete our introductory \[Build a Blog Tutorial\](/en/tutorial/0-introduction/) to learn the basics and create your first Astro site. \`\`\`sh # create a new project with npm npm create astro@latest \`\`\`

```
Our [installation guide](/en/install-and-setup/) has step-by-step instructions for installing Astro using our CLI wizard, creating a new project from an existing Astro GitHub repository, and for installing Astro manually.
```

\- \[Astro’s main features\](/en/concepts/why-astro/) - \[Islands architecture\](/en/concepts/islands/) - \[Astro components\](/en/basics/astro-components/) - \[The Astro template syntax\](/en/reference/astro-syntax/) \- \[Add integrations like React and Partytown\](/en/guides/integrations/) - \[Create type safe content collections\](/en/guides/content-collections/) - \[Enhance navigation with view transitions\](/en/guides/view-transitions/) - \[Connect a headless CMS to your project\](/en/guides/cms/)

## [Actions](https://docharvest.github.io/docs/astro/guides/actions/)

Contents

astro

Actions

Astro

Actions

Astro Actions allow you to define and call backend functions with type-safety. Actions perform data fetching, JSON parsing, and input validation for you. This can greatly reduce the amount of boilerplate needed compared to using an [API endpoint](/en/guides/endpoints/).

Use actions instead of API endpoints for seamless communication between your client and server code and to:

-   Automatically validate JSON and form data inputs using [Zod validation](/en/reference/modules/astro-zod/).
-   Generate type-safe functions to call your backend from the client and even [from HTML form actions](#call-actions-from-an-html-form-action). No need for manual `fetch()` calls.
-   Standardize backend errors with the [`ActionError`](/en/reference/modules/astro-actions/#actionerror) object.

## Basic usage

Actions are defined in a `server` object exported from `src/actions/index.ts`:

```

}
</script>
```

### Write your first action

Follow these steps to define an action and call it in a `script` tag in your Astro page.

1.  Create a `src/actions/index.ts` file and export a `server` object.
    
    ```
    export const server = {
      // action declarations
    }
    ```
    
2.  Import the `defineAction()` utility from `astro:actions`, and the `z` object from `astro/zod`.
    
    ```
    import { defineAction } from 'astro:actions';
    import { z } from 'astro/zod';
    
    export const server = {
      // action declarations
    }
    ```
    
3.  Use the `defineAction()` utility to define a `getGreeting` action. The `input` property will be used to validate input parameters with a [Zod schema](/en/reference/modules/astro-zod/#common-data-type-validators) and the `handler()` function includes the backend logic to run on the server.
    
    ```
    import { defineAction } from 'astro:actions';
    import { z } from 'astro/zod';
    
    export const server = {
      getGreeting: defineAction({
        input: z.object({
          name: z.string(),
        }),
        handler: async (input) => {
          return `Hello, ${input.name}!`
        }
      })
    }
    ```
    
4.  Create an Astro component with a button that will fetch a greeting using your `getGreeting` action when clicked.
    
    ```
    ---
    ---
    
    <button>Get greeting</button>
    
    <script>
    const button = document.querySelector('button');
    button?.addEventListener('click', async () => {
      // Show alert pop-up with greeting from action
    });
    </script>
    ```
    
5.  To use your action, import `actions` from `astro:actions` and then call `actions.getGreeting()` in the click handler. The `name` option will be sent to your action’s `handler()` on the server and, if there are no errors, the result will be available as the `data` property.
    
    ```
    ---
    ---
    
    <button>Get greeting</button>
    
    <script>
    import { actions } from 'astro:actions';
    
    const button = document.querySelector('button');
    button?.addEventListener('click', async () => {
      // Show alert pop-up with greeting from action
      const { data, error } = await actions.getGreeting({ name: "Houston" });
      if (!error) alert(data);
    })
    </script>
    ```
    

See the full Actions API documentation for details on [`defineAction()`](/en/reference/modules/astro-actions/#defineaction) and its properties.

## Organizing actions

All actions in your project must be exported from the `server` object in the `src/actions/index.ts` file. You can define actions inline or you can move action definitions to separate files and import them. You can even group related functions in nested objects.

For example, to colocate all of your user actions, you can create a `src/actions/user.ts` file and nest the definitions of both `getUser` and `createUser` inside a single `user` object.

```

if (error) {
  // handle error cases
  return;
}
// use `data`
```

### Accessing `data` directly without an error check

To skip error handling, for example while prototyping or using a library that will catch errors for you, use the `.orThrow()` property on your action call to throw errors instead of returning an `error`. This will return the action's `data` directly.

This example calls a `likePost()` action that returns the updated number of likes as a `number` from the action `handler`:

```
const updatedLikes = await actions.likePost.orThrow({ postId: 'example' });
//    ^ type: number
```

### Handling backend errors in your action

You can use the provided `ActionError` to throw an error from your action `handler()`, such as "not found" when a database entry is missing, or "unauthorized" when a user is not logged in. This has two main benefits over returning `undefined`:

-   You can set a status code like `404 - Not found` or `401 - Unauthorized`. This improves debugging errors in both development and in production by letting you see the status code of each request.
    
-   In your application code, all errors are passed to the `error` object on an action result. This avoids the need for `undefined` checks on data, and allows you to display targeted feedback to the user depending on what went wrong.
    

#### Creating an `ActionError`

To throw an error, import the [`ActionError()` class](/en/reference/modules/astro-actions/#actionerror) from the `astro:actions` module. Pass it a human-readable status `code` (e.g. `"NOT_FOUND"` or `"BAD_REQUEST"`), and an optional `message` to provide further information about the error.

This example throws an error from a `likePost` action when a user is not logged in, after checking a hypothetical "user-session" cookie for authentication:

```

      }
      // Otherwise, like the post
    },
  }),
};
```

#### Handling an `ActionError`

To handle this error, you can call the action from your application and check whether an `error` property is present. This property will be of type `ActionError` and will contain your `code` and `message`.

In the following example, a `LikeButton.tsx` component calls the `likePost()` action when clicked. If an authentication error occurs, the `error.code` attribute is used to determine whether to display a login link:

```

  return (
    <>
      {
        showLogin && <a href="/signin">Log in to like a post.</a>
      }
      <button onClick={async () => {
        const { data, error } = await actions.likePost({ postId });
        if (error?.code === 'UNAUTHORIZED') setShowLogin(true);
        // Early return for unexpected errors
        else if (error) return;
        // update likes
      }}>
        Like
      </button>
    </>
  )
}
```

### Handling client redirects

When calling actions from the client, you can integrate with a client-side library like `react-router`, or you can use Astro's [`navigate()` function](/en/guides/view-transitions/#trigger-navigation) to redirect to a new page when an action succeeds.

This example navigates to the homepage after a `logout` action returns successfully:

```

      if (!error) navigate('/');
    }}>
      Logout
    </button>
  );
}
```

## Accepting form data from an action

Actions accept JSON data by default. To accept form data from an HTML form, set `accept: 'form'` in your `defineAction()` call:

### Validating form data

Actions will parse submitted form data to an object, using the value of each input’s `name` attribute as the object keys. For example, a form containing `<input name="search">` will be parsed to an object like `{ search: 'user input' }`. Your action's `input` schema will be used to validate this object.

To receive the raw `FormData` object in your action handler instead of a parsed object, omit the `input` property in your action definition.

The following example shows a validated newsletter registration form that accepts a user's email and requires a "terms of service" agreement checkbox.

1.  Create an HTML form component with unique `name` attributes on each input:
    
    ```
    <form>
      <label for="email">E-mail</label>
      <input id="email" required type="email" name="email" />
      <label>
        <input required type="checkbox" name="terms">
        I agree to the terms of service
      </label>
      <button>Sign up</button>
    </form>
    ```
    
2.  Define a `newsletter` action to handle the submitted form. Validate the `email` field using the `z.email()` validator, and the `terms` checkbox using `z.boolean()`:
    
    ```
    import { defineAction } from 'astro:actions';
    import { z } from 'astro/zod';
    
    export const server = {
      newsletter: defineAction({
        accept: 'form',
        input: z.object({
          email: z.email(),
          terms: z.boolean(),
        }),
        handler: async ({ email, terms }) => { /* ... */ },
      })
    }
    ```
    
    See the [`input` API reference](/en/reference/modules/astro-actions/#input-validator) for all available form validators.
    
3.  Add a `<script>` to the HTML form to submit the user input. This example overrides the form's default submit behavior to call `actions.newsletter()`, and redirects to `/confirmation` using the `navigate()` function:
    
    ```
    <form>
      <label for="email">E-mail</label>
      <input id="email" required type="email" name="email" />
      <label>
        <input required type="checkbox" name="terms">
        I agree to the terms of service
      </label>
      <button>Sign up</button>
    </form>
    
    <script>
      import { actions } from 'astro:actions';
      import { navigate } from 'astro:transitions/client';
    
      const form = document.querySelector('form');
      form?.addEventListener('submit', async (event) => {
        event.preventDefault();
        const formData = new FormData(form);
        const { error } = await actions.newsletter(formData);
        if (!error) navigate('/confirmation');
      })
    </script>
    ```
    
    See [“Call actions from an HTML form action”](#call-actions-from-an-html-form-action) for an alternative way to submit form data.
    

### Displaying form input errors

You can validate form inputs before submission using [native HTML form validation attributes](https://developer.mozilla.org/en-US/docs/Learn/Forms/Form_validation#using_built-in_form_validation) like `required`, `type="email"`, and `pattern`. For more complex `input` validation on the backend, you can use the provided [`isInputError()`](/en/reference/modules/astro-actions/#isinputerror) utility function.

To retrieve input errors, use the `isInputError()` utility to check whether an error was caused by invalid input. Input errors contain a `fields` object with messages for each input name that failed to validate. You can use these messages to prompt your user to correct their submission.

The following example checks the error with `isInputError()`, then checks whether the error is in the email field, before finally creating a message from the errors. You can use JavaScript DOM manipulation or your preferred UI framework to display this message to users.

```

const form = document.querySelector('form');
const formData = new FormData(form);
const { error } = await actions.newsletter(formData);
if (isInputError(error)) {
  // Handle input errors.
  if (error.fields.email) {
    const message = error.fields.email.join(', ');
  }
}
```

## Call actions from an HTML form action

:::note Pages must be on-demand rendered when calling actions using a form action. [Ensure prerendering is disabled on the page](/en/guides/on-demand-rendering/#enabling-on-demand-rendering) before using this API. :::

You can enable zero-JS form submissions with standard attributes on any `<form>` element. Form submissions without client-side JavaScript may be useful both as a fallback for when JavaScript fails to load, or if you prefer to handle forms entirely from the server.

Calling [Astro.getActionResult()](/en/reference/api-reference/#getactionresult) on the server returns the result of your form submission (`data` or `error`), and can be used to dynamically redirect, handle form errors, update the UI, and more.

To call an action from an HTML form, add `method="POST"` to your `<form>`, then set the form's `action` attribute using your action, for example `action={actions.logout}`. This will set the `action` attribute to use a query string that is handled by the server automatically.

For example, this Astro component calls the `logout` action when the button is clicked and reloads the current page:

```
---

---

<form method="POST" action={actions.logout}>
  <button>Log out</button>
</form>
```

Additional attributes on the `<form>` element may be necessary for proper schema validation with Zod. For example, to include file uploads, add `enctype="multipart/form-data"` to ensure that files are sent in a format correctly recognized by `z.instanceof(File)`:

```
---

---
<form method="POST" action={actions.upload} enctype="multipart/form-data" >
  <label for="file">Upload File</label>
  <input type="file" id="file" name="file" />
  <button type="submit">Submit</button>
</form>
```

### Redirect on action success

If you need to redirect to a new route on success, you can use an action’s result on the server. A common example is creating a product record and redirecting to the new product's page, e.g. `/products/[id]`.

For example, say you have a `createProduct` action that returns the generated product id:

```

      return { id: product.id };
    },
  })
}
```

You can retrieve the action result from your Astro component by calling `Astro.getActionResult()`. This returns an object containing `data` or `error` properties when an action is called, or `undefined` if the action was not called during this request.

Use the `data` property to construct a URL to use with `Astro.redirect()`:

```
---

const result = Astro.getActionResult(actions.createProduct);
if (result && !result.error) {
  return Astro.redirect(`/products/${result.data.id}`);
}
---

<form method="POST" action={actions.createProduct}>
  <!--...-->
</form>
```

### Handle form action errors

Calling `Astro.getActionResult()` in the Astro component containing your form gives you access to the `data` and `error` objects for custom error handling.

The following example displays a general failure message when a `newsletter` action fails:

```
---

const result = Astro.getActionResult(actions.newsletter);
---

{result?.error && (
  <p class="error">Unable to sign up. Please try again later.</p>
)}
<form method="POST" action={actions.newsletter}>
  <label>
    E-mail
    <input required type="email" name="email" />
  </label>
  <button>Sign up</button>
</form>
```

For more customization, you can [use the `isInputError()` utility](#displaying-form-input-errors) to check whether an error is caused by invalid input.

The following example renders an error banner under the `email` input field when an invalid email is submitted:

```
---

const result = Astro.getActionResult(actions.newsletter);
const inputErrors = isInputError(result?.error) ? result.error.fields : {};
---

<form method="POST" action={actions.newsletter}>
  <label>
    E-mail
    <input required type="email" name="email" aria-describedby="error" />
  </label>
  {inputErrors.email && <p id="error">{inputErrors.email.join(',')}</p>}
  <button>Sign up</button>
</form>
```

#### Preserve input values on error

Inputs will be cleared whenever a form is submitted. To persist input values, you can [enable view transitions](/en/guides/view-transitions/#enabling-view-transitions-spa-mode) and apply the `transition:persist` directive to each input:

```
<input transition:persist required type="email" name="email" />
```

### Update the UI with a form action result

To use an action's return value to display a notification to the user on success, pass the action to `Astro.getActionResult()`. Use the returned `data` property to render the UI you want to display.

This example uses the `productName` property returned by an `addToCart` action to show a success message.

```
---

const result = Astro.getActionResult(actions.addToCart);
---

{result && !result.error && (
  <p class="success">Added {result.data.productName} to cart</p>
)}

<!--...-->
```

### Advanced: Persist action results with a session

Action results are displayed as a POST submission. This means that the result will be reset to `undefined` when a user closes and revisits the page. The user will also see a "confirm form resubmission?" dialog if they attempt to refresh the page.

To customize this behavior, you can add middleware to handle the result of the action manually. You may choose to persist the action result using a cookie or session storage.

Start by [creating a middleware file](/en/guides/middleware/) and importing [the `getActionContext()` utility](/en/reference/modules/astro-actions/#getactioncontext) from `astro:actions`. This function returns an `action` object with information about the incoming action request, including the action handler and whether the action was called from an HTML form. `getActionContext()` also returns the `setActionResult()` and `serializeActionResult()` functions to programmatically set the value returned by `Astro.getActionResult()`:

```

  if (action?.calledFrom === 'form') {
    const result = await action.handler();
    // ... handle the action result
    setActionResult(action.name, serializeActionResult(result));
  }
  return next();
});
```

A common practice to persist HTML form results is the [POST / Redirect / GET pattern](https://en.wikipedia.org/wiki/Post/Redirect/Get). This redirect removes the "confirm form resubmission?" dialog when the page is refreshed, and allows action results to be persisted throughout the user's session.

This example applies the POST / Redirect / GET pattern to all form submissions using session storage with the [Netlify server adapter](/en/guides/integrations-guide/netlify/) installed. Action results are written to a session store using [Netlify Blob](https://docs.netlify.com/blobs/overview/), and retrieved after a redirect using a session ID:

```

  const { action, setActionResult, serializeActionResult } =
    getActionContext(context);
  // Create a Blob store to persist action results with Netlify Blob
  const actionStore = getStore("action-session");
  
  // If an action result was forwarded as a cookie, set the result
  // to be accessible from `Astro.getActionResult()`
  const sessionId = context.cookies.get("action-session-id")?.value;
  const session = sessionId
    ? await actionStore.get(sessionId, {
        type: "json",
      })
    : undefined;
  
  if (session) {
    setActionResult(session.actionName, session.actionResult);
  
    // Optional: delete the session after the page is rendered.
    // Feel free to implement your own persistence strategy
    await actionStore.delete(sessionId);
    context.cookies.delete("action-session-id");
    return next();
  }
  
  // If an action was called from an HTML form action,
  // call the action handler and redirect to the destination page
  if (action?.calledFrom === "form") {
    const actionResult = await action.handler();
  
    // Persist the action result using session storage
    const sessionId = randomUUID();
    await actionStore.setJSON(sessionId, {
      actionName: action.name,
      actionResult: serializeActionResult(actionResult),
    });
  
    // Pass the session ID as a cookie
    // to be retrieved after redirecting to the page
    context.cookies.set("action-session-id", sessionId);
  
    // Redirect back to the previous page on error
    if (actionResult.error) {
      const referer = context.request.headers.get("Referer");
      if (!referer) {
        throw new Error(
          "Internal: Referer unexpectedly missing from Action POST request.",
        );
      }
      return context.redirect(referer);
    }
    // Redirect to the destination page on success
    return context.redirect(context.originPathname);
  }
  
  return next();
});
```

## Security when using actions

Actions are accessible as public endpoints based on the name of the action. For example, the action `blog.like()` will be accessible from `/_actions/blog.like`. This is useful for unit testing action results and debugging production errors. However, this means you **must** use same authorization checks that you would consider for API endpoints and on-demand rendered pages.

### Authorize users from an action handler

To authorize action requests, add an authentication check to your action handler. You may want to use [an authentication library](/en/guides/authentication/) to handle session management and user information.

Actions expose [a subset of the `APIContext` object](/en/reference/modules/astro-actions/#actionapicontext) to access properties passed from middleware using `context.locals`. When a user is not authorized, you can raise an `ActionError` with the `UNAUTHORIZED` code:

```

      }
      return { /* data on success */ };
    }
  })
}
```

### Gate actions from middleware

Astro recommends authorizing user sessions from your action handler to respect permission levels and rate-limiting on a per-action basis. However, you can also gate requests to all actions (or a subset of actions) from middleware.

Use the [`getActionContext()` function](/en/reference/modules/astro-actions/#getactioncontext) from your middleware to retrieve information about any inbound action requests. This includes the action name and whether that action was called using a client-side remote procedure call (RPC) function (e.g. `actions.blog.like()`) or an HTML form.

The following example rejects all action requests that do not have a valid session token. If the check fails, a "Forbidden" response is returned. Note: this method ensures that actions are only accessible when a session is present, but is _not_ a substitute for secure authorization.

```

  // Check if the action was called from a client-side function
  if (action?.calledFrom === "rpc") {
    // If so, check for a user session token
    if (!context.cookies.has("user-session")) {
      return new Response("Forbidden", { status: 403 });
    }
  }

  context.cookies.set("user-session", "session-token-value");
  return next();
});
```

## Call actions from Astro components and server endpoints

You can call actions directly from Astro component scripts using the `Astro.callAction()` wrapper (or `context.callAction()` when using a [server endpoint](/en/guides/endpoints/#server-endpoints-api-routes)). This is common to reuse logic from your actions in other server code.

Pass the action as the first argument and any input parameters as the second argument. This returns the same `data` and `error` objects you receive when calling actions on the client:

```
---

const searchQuery = Astro.url.searchParams.get('search');
if (searchQuery) {
  const { data, error } = await Astro.callAction(actions.findProduct, { query: searchQuery });
  // handle result
}
---
```

## [Authentication](https://docharvest.github.io/docs/astro/guides/authentication/)



## [Use a backend service with Astro](https://docharvest.github.io/docs/astro/guides/backend/)

Contents

astro

Use a backend service with Astro

Astro

Use a backend service with Astro

**Ready to add features like authentication, monitoring, storage, or data to your Astro project?** Follow one of our guides to integrate a backend service.

:::tip Find [community-maintained integrations](https://astro.build/integrations/) for adding popular features to your project in our integrations directory. :::

## Backend service guides

Note that many of these pages are **stubs**: they're collections of resources waiting for your contribution!

## What is a backend service?

A backend service is a cloud-based system that helps you build and manage your backend infrastructure. It provides a set of tools and services for managing databases, user authentication, and other server-side functionality. This enables you to focus on building your applications without having to worry about managing the underlying infrastructure.

## Why would I use a backend service?

You might want to consider a backend service if your project has complex server-side needs, for example:

-   user sign-ups and authentication
-   persistent data storage
-   user-uploaded asset storage
-   API generation
-   realtime communication
-   application monitoring

## [Appwrite & Astro](https://docharvest.github.io/docs/astro/guides/backend/appwrite/)

Contents

astro

Appwrite & Astro

Astro

Appwrite & Astro

[Appwrite](https://appwrite.io/) is a self-hosted backend-as-a-service platform that provides authentication and account management, user preferences, database and storage persistence, cloud functions, localization, image manipulation, and other server-side utilities.

## Official Resources

-   [Appwrite Demos for Astro](https://github.com/appwrite/demos-for-astro)

## [Firebase & Astro](https://docharvest.github.io/docs/astro/guides/backend/firebase/)

Contents

astro

Firebase & Astro

Astro

Firebase & Astro

[Firebase](https://firebase.google.com/) is an app development platform that provides a NoSQL database, authentication, realtime subscriptions, functions, and storage.

See our separate guide for [deploying to Firebase hosting](/en/guides/deploy/firebase/).

## Initializing Firebase in Astro

### Prerequisites

-   A [Firebase project with a web app configured](https://firebase.google.com/docs/web/setup).
-   An Astro project with [`output: 'server'` for on-demand rendering](/en/guides/on-demand-rendering/) enabled.
-   Firebase credentials: You will need two sets of credentials to connect Astro to Firebase:
    -   Web app credentials: These credentials will be used by the client side of your app. You can find them in the Firebase console under _Project settings > General_. Scroll down to the **Your apps** section and click on the **Web app** icon.
    -   Project credentials: These credentials will be used by the server side of your app. You can generate them in the Firebase console under _Project settings > Service accounts > Firebase Admin SDK > Generate new private key_.

### Adding Firebase credentials

To add your Firebase credentials to Astro, create an `.env` file in the root of your project with the following variables:

```
FIREBASE_PRIVATE_KEY_ID=YOUR_PRIVATE_KEY_ID
FIREBASE_PRIVATE_KEY=YOUR_PRIVATE_KEY
FIREBASE_PROJECT_ID=YOUR_PROJECT_ID
FIREBASE_CLIENT_EMAIL=YOUR_CLIENT_EMAIL
FIREBASE_CLIENT_ID=YOUR_CLIENT_ID
FIREBASE_AUTH_URI=YOUR_AUTH_URI
FIREBASE_TOKEN_URI=YOUR_TOKEN_URI
FIREBASE_AUTH_CERT_URL=YOUR_AUTH_CERT_URL
FIREBASE_CLIENT_CERT_URL=YOUR_CLIENT_CERT_URL
```

Now, these environment variables are available for use in your project.

If you would like to have IntelliSense for your Firebase environment variables, edit or create the file `env.d.ts` in your `src/` directory and configure your types:

```
interface ImportMetaEnv {
  readonly FIREBASE_PRIVATE_KEY_ID: string;
  readonly FIREBASE_PRIVATE_KEY: string;
  readonly FIREBASE_PROJECT_ID: string;
  readonly FIREBASE_CLIENT_EMAIL: string;
  readonly FIREBASE_CLIENT_ID: string;
  readonly FIREBASE_AUTH_URI: string;
  readonly FIREBASE_TOKEN_URI: string;
  readonly FIREBASE_AUTH_CERT_URL: string
  readonly FIREBASE_CLIENT_CERT_URL: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}
```

:::tip Read more about [environment variables](/en/guides/environment-variables/) and `.env` files in Astro. :::

Your project should now include these new files:

\- src/ - \*\*env.d.ts\*\* - \*\*.env\*\* - astro.config.mjs - package.json

### Installing dependencies

To connect Astro with Firebase, install the following packages using the single command below for your preferred package manager:

-   `firebase` - the Firebase SDK for the client side
-   `firebase-admin` - the Firebase Admin SDK for the server side

\`\`\`shell npm install firebase firebase-admin \`\`\` \`\`\`shell pnpm add firebase firebase-admin \`\`\` \`\`\`shell yarn add firebase firebase-admin \`\`\`

Next, create a folder named `firebase` in the `src/` directory and add two new files to this folder: `client.ts` and `server.ts`.

In `client.ts`, add the following code to initialize Firebase in the client using your web app credentials and the `firebase` package:

```

const firebaseConfig = {
  apiKey: "my-public-api-key",
  authDomain: "my-auth-domain",
  projectId: "my-project-id",
  storageBucket: "my-storage-bucket",
  messagingSenderId: "my-sender-id",
  appId: "my-app-id",
};
```

:::note Remember to replace the `firebaseConfig` object with your own web app credentials. :::

In `server.ts`, add the following code to initialize Firebase in the server using your project credentials and the `firebase-admin` package:

```

const activeApps = getApps();
const serviceAccount = {
  type: "service_account",
  project_id: import.meta.env.FIREBASE_PROJECT_ID,
  private_key_id: import.meta.env.FIREBASE_PRIVATE_KEY_ID,
  private_key: import.meta.env.FIREBASE_PRIVATE_KEY,
  client_email: import.meta.env.FIREBASE_CLIENT_EMAIL,
  client_id: import.meta.env.FIREBASE_CLIENT_ID,
  auth_uri: import.meta.env.FIREBASE_AUTH_URI,
  token_uri: import.meta.env.FIREBASE_TOKEN_URI,
  auth_provider_x509_cert_url: import.meta.env.FIREBASE_AUTH_CERT_URL,
  client_x509_cert_url: import.meta.env.FIREBASE_CLIENT_CERT_URL,
};

const initApp = () => {
  if (import.meta.env.PROD) {
    console.info('PROD env detected. Using default service account.')
    // Use default config in firebase functions. Should be already injected in the server by Firebase.
    return initializeApp()
  }
  console.info('Loading service account from env.')
  return initializeApp({
    credential: cert(serviceAccount as ServiceAccount)
  })
}
```

:::note Remember to replace the `serviceAccount` object with your own project credentials. :::

Finally, your project should now include these new files:

\- src - env.d.ts - firebase - \*\*client.ts\*\* - \*\*server.ts\*\* - .env - astro.config.mjs - package.json

## Adding authentication with Firebase

### Prerequisites

-   An Astro project [initialized with Firebase](#initializing-firebase-in-astro).
-   A Firebase project with email/password authentication enabled in the Firebase console under _Authentication > Sign-in_ method.

### Creating auth server endpoints

Firebase authentication in Astro requires the following three [Astro server endpoints](/en/guides/endpoints/):

-   `GET /api/auth/signin` - to sign in a user
-   `GET /api/auth/signout` - to sign out a user
-   `POST /api/auth/register` - to register a user

Create three endpoints related to authentication in a new directory `src/pages/api/auth/`: `signin.ts`, `signout.ts` and `register.ts`.

`signin.ts` contains the code to sign in a user using Firebase:

```

  /* Get token from request headers */
  const idToken = request.headers.get("Authorization")?.split("Bearer ")[1];
  if (!idToken) {
    return new Response(
      "No token found",
      { status: 401 }
    );
  }

  /* Verify id token */
  try {
    await auth.verifyIdToken(idToken);
  } catch (error) {
    return new Response(
      "Invalid token",
      { status: 401 }
    );
  }

  /* Create and set session cookie */
  const fiveDays = 60 * 60 * 24 * 5 * 1000;
  const sessionCookie = await auth.createSessionCookie(idToken, {
    expiresIn: fiveDays,
  });

  cookies.set("__session", sessionCookie, {
    path: "/",
  });

  return redirect("/dashboard");
};
```

:::caution Firebase only allows the use of [one cookie, and it must be named `__session`](https://firebase.google.com/docs/hosting/manage-cache#using_cookies). Any other cookies the client sends will not be visible to your application. :::

:::note This is a basic implementation of the signin endpoint. You can add more logic to this endpoint to suit your needs. :::

`signout.ts` contains the code to log out a user by deleting the session cookie:

```

  return redirect("/signin");
};
```

:::note This is a basic implementation of the signout endpoint. You can add more logic to this endpoint to suit your needs. :::

`register.ts` contains the code to register a user using Firebase:

```

  /* Get form data */
  const formData = await request.formData();
  const email = formData.get("email")?.toString();
  const password = formData.get("password")?.toString();
  const name = formData.get("name")?.toString();

  if (!email || !password || !name) {
    return new Response(
      "Missing form data",
      { status: 400 }
    );
  }

  /* Create user */
  try {
    await auth.createUser({
      email,
      password,
      displayName: name,
    });
  } catch (error: any) {
    return new Response(
      "Something went wrong",
      { status: 400 }
    );
  }
  return redirect("/signin");
};
```

:::note This is a basic implementation of the register endpoint. You can add more logic to this endpoint to suit your needs. :::

After creating server endpoints for authentication, your project directory should now include these new files:

\- src - env.d.ts - firebase - client.ts - server.ts - pages - api - auth - \*\*signin.ts\*\* - \*\*signout.ts\*\* - \*\*register.ts\*\* - .env - astro.config.mjs - package.json

### Creating pages

Create the pages that will use the Firebase endpoints:

-   `src/pages/register` - will contain a form to register a user
-   `src/pages/signin` - will contain a form to sign in a user
-   `src/pages/dashboard` - will contain a dashboard that can only be accessed by authenticated users

The example `src/pages/register.astro` below includes a form that will send a `POST` request to the `/api/auth/register` endpoint. This endpoint will create a new user using the data from the form and then will redirect the user to the `/signin` page.

```
---

---

<Layout title="Register">
  <h1>Register</h1>
  <p>Already have an account? <a href="/signin">Sign in</a></p>
  <form action="/api/auth/register" method="post">
    <label for="name">Name</label>
    <input type="text" name="name" id="name" />
    <label for="email" for="email">Email</label>
    <input type="email" name="email" id="email" />
    <label for="password">Password</label>
    <input type="password" name="password" id="password" />
    <button type="submit">Login</button>
  </form>
</Layout>
```

`src/pages/signin.astro` uses the Firebase server app to verify the user's session cookie. If the user is authenticated, the page will redirect the user to the `/dashboard` page.

The example page below contains a form that will send a `POST` request to the `/api/auth/signin` endpoint with the ID token generated by the Firebase client app.

The endpoint will verify the ID token and create a new session cookie for the user. Then, the endpoint will redirect the user to the `/dashboard` page.

```
---

/* Check if the user is authenticated */
const auth = getAuth(app);
if (Astro.cookies.has("__session")) {
  const sessionCookie = Astro.cookies.get("__session")!.value;
  const decodedCookie = await auth.verifySessionCookie(sessionCookie);
  if (decodedCookie) {
    return Astro.redirect("/dashboard");
  }
}
---

<Layout title="Sign in">
  <h1>Sign in</h1>
  <p>New here? <a href="/register">Create an account</a></p>
  <form action="/api/auth/signin" method="post">
    <label for="email" for="email">Email</label>
    <input type="email" name="email" id="email" />
    <label for="password">Password</label>
    <input type="password" name="password" id="password" />
    <button type="submit">Login</button>
  </form>
</Layout>
<script>
  import {
    getAuth,
    inMemoryPersistence,
    signInWithEmailAndPassword,
  } from "firebase/auth";
  import { app } from "../firebase/client";

  const auth = getAuth(app);
  // This will prevent the browser from storing session data
  auth.setPersistence(inMemoryPersistence);

  const form = document.querySelector("form") as HTMLFormElement;
  form.addEventListener("submit", async (e) => {
    e.preventDefault();
    const formData = new FormData(form);
    const email = formData.get("email")?.toString();
    const password = formData.get("password")?.toString();

    if (!email || !password) {
      return;
    }
    const userCredential = await signInWithEmailAndPassword(
      auth,
      email,
      password
    );
    const idToken = await userCredential.user.getIdToken();
    const response = await fetch("/api/auth/signin", {
      method: "GET",
      headers: {
        Authorization: `Bearer ${idToken}`,
      },
    });

    if (response.redirected) {
      window.location.assign(response.url);
    }
  });
</script>
```

`src/pages/dashboard.astro` will verify the user's session cookie using the Firebase server app. If the user is not authenticated, the page will redirect the user to the `/signin` page.

The example page below display the user's name and a button to sign out. Clicking the button will send a `GET` request to the `/api/auth/signout` endpoint.

The endpoint will delete the user's session cookie and redirect the user to the `/signin` page.

```
---

const auth = getAuth(app);

/* Check current session */
if (!Astro.cookies.has("__session")) {
  return Astro.redirect("/signin");
}
const sessionCookie = Astro.cookies.get("__session")!.value;
const decodedCookie = await auth.verifySessionCookie(sessionCookie);
const user = await auth.getUser(decodedCookie.uid);

if (!user) {
  return Astro.redirect("/signin");
}
---

<Layout title="dashboard">
  <h1>Welcome {user.displayName}</h1>
  <p>We are happy to see you here</p>
  <form action="/api/auth/signout">
    <button type="submit">Sign out</button>
  </form>
</Layout>
```

### Adding OAuth providers

To add OAuth providers to your app, you need to enable them in the Firebase console.

In the Firebase console, go to the **Authentication** section and click on the **Sign-in method** tab. Then, click on the **Add a new provider** button and enable the providers you want to use.

The example below uses the **Google** provider.

Edit the `signin.astro` page to add:

-   a button to sign in with Google underneath the existing form
-   an event listener on the button to handle the sign in process in the existing `<script>`.

```
---

/* Check if the user is authenticated */
const auth = getAuth(app);
if (Astro.cookies.has("__session")) {
  const sessionCookie = Astro.cookies.get("__session")!.value;
  const decodedCookie = await auth.verifySessionCookie(sessionCookie);
  if (decodedCookie) {
    return Astro.redirect("/dashboard");
  }
}
---

<Layout title="Sign in">
  <h1>Sign in</h1>
  <p>New here? <a href="/register">Create an account</a></p>
  <form action="/api/auth/signin" method="post">
    <label for="email" for="email">Email</label>
    <input type="email" name="email" id="email" />
    <label for="password">Password</label>
    <input type="password" name="password" id="password" />
    <button type="submit">Login</button>
  </form>
  <button id="google">Sign in with Google</button>
</Layout>
<script>
  import {
    getAuth,
    inMemoryPersistence,
    signInWithEmailAndPassword,
    GoogleAuthProvider,
    signInWithPopup,
  } from "firebase/auth";
  import { app } from "../firebase/client";

  const auth = getAuth(app);
  auth.setPersistence(inMemoryPersistence);

  const form = document.querySelector("form") as HTMLFormElement;
  form.addEventListener("submit", async (e) => {
    e.preventDefault();
    const formData = new FormData(form);
    const email = formData.get("email")?.toString();
    const password = formData.get("password")?.toString();

    if (!email || !password) {
      return;
    }
    const userCredential = await signInWithEmailAndPassword(
      auth,
      email,
      password
    );
    const idToken = await userCredential.user.getIdToken();
    const response = await fetch("/api/auth/signin", {
      headers: {
        Authorization: `Bearer ${idToken}`,
      },
    });

    if (response.redirected) {
      window.location.assign(response.url);
    }
  });

  const googleSignin = document.querySelector("#google") as HTMLButtonElement;
  googleSignin.addEventListener("click", async () => {
    const provider = new GoogleAuthProvider();
    const userCredential = await signInWithPopup(auth, provider);
    const idToken = await userCredential.user.getIdToken();
    const res = await fetch("/api/auth/signin", {
      headers: {
        Authorization: `Bearer ${idToken}`,
      },
    });

    if (res.redirected) {
      window.location.assign(res.url);
    }
  });
</script>
```

When clicked, the Google sign in button will open a popup window to sign in with Google. Once the user signs in, it will send a `POST` request to the `/api/auth/signin` endpoint with the ID token generated by OAuth provider.

The endpoint will verify the ID token and create a new session cookie for the user. Then, the endpoint will redirect the user to the `/dashboard` page.

## Connecting to Firestore database

### Prerequisites

-   An Astro project initialized with Firebase as described in the [Initializing Firebase in Astro](#initializing-firebase-in-astro) section.
    
-   A Firebase project with a Firestore database. You can follow the [Firebase documentation to create a new project and set up a Firestore database](https://firebase.google.com/docs/firestore/quickstart).
    

In this recipe, the Firestore collection will be called **friends** and will contain documents with the following fields:

-   `id`: autogenerated by Firestore
-   `name`: a string field
-   `age`: a number field
-   `isBestFriend`: a boolean field

### Creating the server endpoints

Create two new files in a new directory `src/pages/api/friends/`: `index.ts` and `[id].ts`. These will create two server endpoints to interact with the Firestore database in the following ways:

-   `POST /api/friends`: to create a new document in the friends collection.
-   `POST /api/friends/:id`: to update a document in the friends collection.
-   `DELETE /api/friends/:id`: to delete a document in the friends collection.

`index.ts` will contain the code to create a new document in the friends collection:

```

  const name = formData.get("name")?.toString();
  const age = formData.get("age")?.toString();
  const isBestFriend = formData.get("isBestFriend") === "on";

  if (!name || !age) {
    return new Response("Missing required fields", {
      status: 400,
    });
  }
  try {
    const db = getFirestore(app);
    const friendsRef = db.collection("friends");
    await friendsRef.add({
      name,
      age: parseInt(age),
      isBestFriend,
    });
  } catch (error) {
    return new Response("Something went wrong", {
      status: 500,
    });
  }
  return redirect("/dashboard");
};
```

:::note This is a basic implementation of the `friends` endpoint. You can add more logic to this endpoint to suit your needs. :::

`[id].ts` will contain the code to update and delete a document in the friends collection:

```

const db = getFirestore(app);
const friendsRef = db.collection("friends");

  const name = formData.get("name")?.toString();
  const age = formData.get("age")?.toString();
  const isBestFriend = formData.get("isBestFriend") === "on";

  if (!name || !age) {
    return new Response("Missing required fields", {
      status: 400,
    });
  }

  if (!params.id) {
    return new Response("Cannot find friend", {
      status: 404,
    });
  }

  try {
    await friendsRef.doc(params.id).update({
      name,
      age: parseInt(age),
      isBestFriend,
    });
  } catch (error) {
    return new Response("Something went wrong", {
      status: 500,
    });
  }
  return redirect("/dashboard");
};

  }

  try {
    await friendsRef.doc(params.id).delete();
  } catch (error) {
    return new Response("Something went wrong", {
      status: 500,
    });
  }
  return redirect("/dashboard");
};
```

:::note This is a basic implementation of the `friends/:id` endpoint. You can add more logic to this endpoint to suit your needs. :::

After creating server endpoints for Firestore, your project directory should now include these new files:

\- src - env.d.ts - firebase - client.ts - server.ts - pages - api - friends - \*\*index.ts\*\* - \*\*\[id\].ts\*\* - .env - astro.config.mjs - package.json

### Creating pages

Create the pages that will use the Firestore endpoints:

-   `src/pages/add.astro` - will contain a form to add a new friend.
-   `src/pages/edit/[id].astro` - will contain a form to edit a friend and a button to delete a friend.
-   `src/pages/friend/[id].astro` - will contain the details of a friend.
-   `src/pages/dashboard.astro` - will display a list of friends.

#### Add a new record

The example `src/pages/add.astro` below includes a form that will send a `POST` request to the `/api/friends` endpoint. This endpoint will create a new friend using the data from the form and then will redirect the user to the `/dashboard` page.

```
---

---

<Layout title="Add a new friend">
  <h1>Add a new friend</h1>
  <form method="post" action="/api/friends">
    <label for="name">Name</label>
    <input type="text" id="name" name="name" />
    <label for="age">Age</label>
    <input type="number" id="age" name="age" />
    <label for="isBestFriend">Is best friend?</label>
    <input type="checkbox" id="isBestFriend" name="isBestFriend" />
    <button type="submit">Add friend</button>
  </form>
</Layout>
```

#### Edit or Delete a record

`src/pages/edit/[id].astro` will contain a form to edit a friend data and a button to delete a friend. On submit, this page will send a `POST` request to the `/api/friends/:id` endpoint to update a friend data.

If the user clicks the delete button, this page will send a `DELETE` request to the `/api/friends/:id` endpoint to delete a friend.

```
---

interface Friend {
  name: string;
  age: number;
  isBestFriend: boolean;
}

const { id } = Astro.params;

if (!id) {
  return Astro.redirect("/404");
}

const db = getFirestore(app);
const friendsRef = db.collection("friends");
const friendSnapshot = await friendsRef.doc(id).get();

if (!friendSnapshot.exists) {
  return Astro.redirect("/404");
}

const friend = friendSnapshot.data() as Friend;
---

<Layout title="Edit {friend.name}">
  <h1>Edit {friend.name}</h1>
  <p>Here you can edit or delete your friend's data.</p>
  <form method="post" action={`/api/friends/${id}`}>
    <label for="name">Name</label>
    <input type="text" id="name" name="name" value={friend.name} />
    <label for="age">Age</label>
    <input type="number" id="age" name="age" value={friend.age} />
    <label for="isBestFriend">Is best friend?</label>
    <input
      type="checkbox"
      id="isBestFriend"
      name="isBestFriend"
      checked={friend.isBestFriend}
    />
    <button type="submit">Edit friend</button>
  </form>
  <button type="button" id="delete-document">Delete</button>
</Layout>
<script>
  const deleteButton = document.getElementById(
    "delete-document"
  ) as HTMLButtonElement;
  const url = document.querySelector("form")?.getAttribute("action") as string;
  deleteButton.addEventListener("click", async () => {
    const response = await fetch(url, {
      method: "DELETE",
    });
    if (response.redirected) {
      window.location.assign(response.url);
    }
  });
</script>
```

#### Display an individual record

`src/pages/friend/[id].astro` will display the details of a friend.

```
---

interface Friend {
  name: string;
  age: number;
  isBestFriend: boolean;
}

const { id } = Astro.params;

if (!id) {
  return Astro.redirect("/404");
}

const db = getFirestore(app);
const friendsRef = db.collection("friends");
const friendSnapshot = await friendsRef.doc(id).get();

if (!friendSnapshot.exists) {
  return Astro.redirect("/404");
}

const friend = friendSnapshot.data() as Friend;
---

<Layout title={friend.name}>
  <h1>{friend.name}</h1>
  <p>Age: {friend.age}</p>
  <p>Is best friend: {friend.isBestFriend ? "Yes" : "No"}</p>
</Layout>
```

#### Display a list of records with an edit button

Finally, `src/pages/dashboard.astro` will display a list of friends. Each friend will have a link to their details page and an edit button that will redirect the user to the edit page.

```
---

interface Friend {
  id: string;
  name: string;
  age: number;
  isBestFriend: boolean;
}

const db = getFirestore(app);
const friendsRef = db.collection("friends");
const friendsSnapshot = await friendsRef.get();
const friends = friendsSnapshot.docs.map((doc) => ({
  id: doc.id,
  ...doc.data(),
})) as Friend[];
---

<Layout title="My friends">
  <h1>Friends</h1>
  <ul>
    {
      friends.map((friend) => (
        <li>
          <a href={`/friend/${friend.id}`}>{friend.name}</a>
          <span>({friend.age})</span>
          <strong>{friend.isBestFriend ? "Bestie" : "Friend"}</strong>
          <a href={`/edit/${friend.id}`}>Edit</a>
        </li>
      ))
    }
  </ul>
</Layout>
```

After creating all the pages, you should have the following file structure:

\- src - env.d.ts - firebase - client.ts - server.ts - pages - dashboard.astro - add.astro - edit - \[id\].astro - friend - \[id\].astro - api - friends - index.ts - \[id\].ts - .env - astro.config.mjs - package.json

## Community Resources

-   [Astro and Firebase SSR app example](https://github.com/kevinzunigacuellar/astro-firebase)
-   [Using Firebase Realtime Database in Astro with Vue: A Step-by-Step Guide](https://www.launchfa.st/blog/vue-astro-firebase-realtime-database)

## [Neon Postgres & Astro](https://docharvest.github.io/docs/astro/guides/backend/neon/)

Contents

astro

Neon Postgres & Astro

Astro

Neon Postgres & Astro

[Neon](https://neon.tech) is a fully managed serverless Postgres database. It separates storage and compute to offer autoscaling, branching, and bottomless storage.

## Adding Neon to your Astro project

### Prerequisites

-   A [Neon](https://console.neon.tech/signup) account with a created project
-   Neon database connection string
-   An Astro project with [on-demand rendering (SSR)](/en/guides/on-demand-rendering/) enabled

### Environment configuration

To use Neon with Astro, you will need to set a Neon environment variable. Create or edit the `.env` file in your project root, and add the following code, replacing your own project details:

```
NEON_DATABASE_URL="postgresql://<user>:<password>@<endpoint_hostname>.neon.tech:<port>/<dbname>?sslmode=require"
```

For better TypeScript support, define environment variables in a `src/env.d.ts` file:

```
interface ImportMetaEnv {
  readonly NEON_DATABASE_URL: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}
```

Learn more about [environment variables](/en/guides/environment-variables/) and `.env` files in Astro.

### Installing dependencies

Install the `@neondatabase/serverless` package to connect to Neon:

```
npm install @neondatabase/serverless
```

### Creating a Neon client

Create a new file `src/lib/neon.ts` with the following code to initialize your Neon client:

## Querying your Neon database

You can now use the Neon client to query your database from any `.astro` component. The following example fetches the current time from the Postgres database:

```
---

const response =  await  sql`SELECT NOW() as current_time`;
const currentTime = response[0].current_time;
---

<h1>Current Time</h1>
<p>The time is: {currentTime}</p>
```

## Database branching with Neon

Neon's branching feature lets you create copies of your database for development or testing. Use this in your Astro project by creating different environment variables for each branch:

```
NEON_DATABASE_URL=your_development_branch_url
```

```
NEON_DATABASE_URL=your_production_branch_url
```

## Resources

-   [Neon documentation](https://neon.tech/docs/introduction)
-   [Neon serverless driver GitHub](https://github.com/neondatabase/serverless)
-   [Connect an Astro site or application to Neon Postgres](https://neon.tech/docs/guides/astro)

## [Prisma Postgres & Astro](https://docharvest.github.io/docs/astro/guides/backend/prisma-postgres/)

Contents

astro

Prisma Postgres & Astro

Astro

Prisma Postgres & Astro

[Prisma Postgres](https://www.prisma.io/) is a fully managed, serverless Postgres database built for modern web apps.

## Connect with Prisma ORM (Recommended)

[Prisma ORM](https://www.prisma.io/orm) is the recommended way to connect to your Prisma Postgres database. It provides type-safe queries, migrations, and global performance.

### Prerequisites

-   An Astro project with an adapter installed to enable [on-demand rendering (SSR)](/en/guides/on-demand-rendering/).

### Install dependencies and initialize Prisma

Run the following commands to install the necessary Prisma dependencies:

```
npm install prisma tsx --save-dev 
npm install @prisma/adapter-pg @prisma/client
```

Once installed, initialize Prisma in your project with the following command:

```
npx prisma init --db --output ./generated
```

You'll need to answer a few questions while setting up your Prisma Postgres database. Select the region closest to your location and a memorable name for your database, like "My Astro Project."

This will create:

-   A `prisma/` directory with a `schema.prisma` file
-   A `.env` file with a `DATABASE_URL` already set

### Define a Model

Even if you don't need any specific data models yet, Prisma requires at least one model in the schema in order to generate a client and apply migrations.

The following example defines a `Post` model as a placeholder. Add the model to your schema to get started. You can safely delete or replace it later with models that reflect your actual data.

```
generator client {
  provider = "prisma-client"
  output   = "./generated"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model Post {
  id        Int     @id @default(autoincrement())
  title     String
  content   String?
  published Boolean @default(false)
}
```

Learn more about configuring your Prisma ORM setup in the [Prisma schema reference](https://www.prisma.io/docs/concepts/components/prisma-schema).

### Generate client

Run the following command to generate the Prisma Client from your schema:

```
npx prisma generate
```

### Generate migration files

Run the following command to create the database tables and generate the Prisma Client from your schema. This will also create a `prisma/migrations/` directory with migration history files.

```
npx prisma migrate dev --name init
```

### Create a Prisma Client

Inside of `/src/lib`, create a `prisma.ts` file. This file will initialize and export your Prisma Client instance so you can query your database throughout your Astro project.

```

const connectionString = import.meta.env.DATABASE_URL;
const adapter = new PrismaPg({ connectionString });
const prisma = new PrismaClient({ adapter });
```

### Querying and displaying data

The following example shows fetching only your published posts with the Prisma Client sorted by `id`, and then displaying titles and post content in your Astro template:

```
---

const posts = await prisma.post.findMany({
  where: { published: true },
  orderBy: { id: 'desc' }
});
---

<html>
  <head>
    <title>Published Posts</title>
  </head>
  <body>
    <h1>Published Posts</h1>
    <ul>
      {posts.map((post) => (
        <li>
          <h2>{post.title}</h2>
          {post.content && <p>{post.content}</p>}
        </li>
      ))}
    </ul>
  </body>
</html>
```

It is best practice to handle queries in an API route. For more information on how to use Prisma ORM in your Astro project, see the [Astro + Prisma ORM Guide](https://www.prisma.io/docs/guides/astro).

## Connect with Other ORMs and Libraries

You can connect to Prisma Postgres via direct TCP using any other ORM, database library, or tool of your choice. Create a direct connection string in your Prisma Console to get started.

### Prerequisites

-   An Astro project with an adapter installed to enable [on-demand rendering (SSR)](/en/guides/on-demand-rendering/).
-   A [Prisma Postgres](https://pris.ly/ppg) database with a TCP enabled connection string

### Install dependencies

This example uses [`pg`, a PostgreSQL client for Node.js](https://github.com/brianc/node-postgres) to make a direct TCP connection.

Run the following command to install the `pg` package:

```
npm install pg
```

### Query your database client

Provide your connection string to the `pg` client to communicate with your SQL server and fetch data from your database.

The following example of creating a table and inserting data can be used to validate your query URL and TCP connection:

```
---

const client = new Client({ 
  connectionString: import.meta.env.DATABASE_URL,
  ssl: { rejectUnauthorized: false }
});
await client.connect();

await client.query(`
  CREATE TABLE IF NOT EXISTS posts (
    id SERIAL PRIMARY KEY,
    title TEXT UNIQUE,
    content TEXT
  );
  
  INSERT INTO posts (title, content)
  VALUES ('Hello', 'World')
  ON CONFLICT (title) DO NOTHING;
`);

const { rows } = await client.query('SELECT * FROM posts');
await client.end();
---

<h1>Posts</h1>
<p>{rows[0].title}: {rows[0].content}</p>
```

## Official Resources

-   [Astro + Prisma ORM Guide](https://www.prisma.io/docs/guides/astro)

## [Scalekit & Astro](https://docharvest.github.io/docs/astro/guides/backend/scalekit/)

Contents

astro

Scalekit & Astro

Astro

Scalekit & Astro

[Scalekit](https://scalekit.com/) is an authentication platform built for B2B and AI applications. It provides social login, enterprise SSO, magic links, and more — managing the full OAuth 2.0 / OIDC flow so you get back tokens and a user profile without building any login UI. A single Scalekit environment supports multiple applications (for example, `app.yourcompany.com` and `docs.yourcompany.com`), so your users authenticate once and share the same session across all your properties.

## Initializing Scalekit in Astro

### Prerequisites

-   A Scalekit account and environment. If you don't have one, you can sign up for free at [scalekit.com](https://scalekit.com/) and create a new environment.
-   An Astro project with [`output: 'server'` for on-demand rendering](/en/guides/on-demand-rendering/) enabled.
-   Scalekit credentials for your environment. You can find these in the **Settings > API Credentials** section of your Scalekit dashboard.
    -   `SCALEKIT_ENVIRONMENT_URL`: The URL of your Scalekit environment.
    -   `SCALEKIT_CLIENT_ID`: Your Scalekit client ID.
    -   `SCALEKIT_CLIENT_SECRET`: Your Scalekit client secret.
    -   `SCALEKIT_REDIRECT_URI`: The callback URL Scalekit will redirect to after login (e.g. `http://localhost:4321/api/auth/callback`). Register this in your Scalekit dashboard under **Settings > Redirects**.

### Adding Scalekit credentials

To add your Scalekit credentials to your Astro project, add the following to your `.env` file:

```
SCALEKIT_ENVIRONMENT_URL=YOUR_SCALEKIT_ENVIRONMENT_URL
SCALEKIT_CLIENT_ID=YOUR_SCALEKIT_CLIENT_ID
SCALEKIT_CLIENT_SECRET=YOUR_SCALEKIT_CLIENT_SECRET
SCALEKIT_REDIRECT_URI=http://localhost:4321/api/auth/callback
```

Now, these environment variables are available in your project.

If you would like to have IntelliSense for your environment variables, edit or create the `env.d.ts` in your `src/` directory and add the following:

```
/// <reference types="astro/client" />

interface ImportMetaEnv {
  readonly SCALEKIT_ENVIRONMENT_URL: string;
  readonly SCALEKIT_CLIENT_ID: string;
  readonly SCALEKIT_CLIENT_SECRET: string;
  readonly SCALEKIT_REDIRECT_URI: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

declare namespace App {
  interface Locals {
    user?: {
      sub: string;
      email?: string;
      name?: string;
    };
  }
}
```

Read more about [environment variables](/en/guides/environment-variables/) and `.env` files in Astro.

Your project should now include these files:

\- src/ - \*\*env.d.ts\*\* - \*\*.env\*\* - astro.config.mjs - package.json

### Installing dependencies

To connect to Scalekit, install `@scalekit-sdk/node` in your project.

\`\`\`shell npm install @scalekit-sdk/node \`\`\` \`\`\`shell pnpm add @scalekit-sdk/node \`\`\` \`\`\`shell yarn add @scalekit-sdk/node \`\`\`

Next, create a folder named `lib` in your `src/` directory and add a Scalekit client file:

Now, your project should include these files:

\- src/ - lib/ - \*\*scalekit.ts\*\* - env.d.ts - .env - package.json

## Adding authentication with Scalekit

Scalekit handles authentication through a standard OAuth 2.0 / OIDC redirect flow. Your app sends users to Scalekit, they sign in, and Scalekit redirects them back to your callback URL with an authorization code you exchange for tokens. This guide uses the Authorization Code flow with a client secret, which is appropriate for server-side rendered applications.

:::tip If you prefer not to use a client secret, Scalekit also supports the [PKCE flow](https://docs.scalekit.com/authenticate/fsa/multiapp/single-page-app/). The [Scalekit developer docs site](https://github.com/scalekit-inc/developer-docs) is an open-source Astro project that demonstrates a full PKCE implementation without an SDK. :::

### Creating auth server endpoints

To add authentication to your project, you will need to create three server endpoints:

-   `GET /api/auth/login`: redirects users to Scalekit to sign in.
-   `GET /api/auth/callback`: exchanges the authorization code for tokens and sets session cookies.
-   `GET /api/auth/logout`: clears session cookies and ends the Scalekit session.

Create these endpoints in the `src/pages/api/auth/` directory of your project. Your project should now include these new files:

\- src/ - lib/ - scalekit.ts - pages/ - api/ - auth/ - \*\*login.ts\*\* - \*\*callback.ts\*\* - \*\*logout.ts\*\* - env.d.ts - .env - astro.config.mjs - package.json

`login.ts` generates an authorization URL and redirects the user to Scalekit to sign in.

```

  return Response.redirect(url);
};
```

`callback.ts` receives the authorization code from Scalekit, exchanges it for tokens, and stores them in HttpOnly cookies.

```

  const code = url.searchParams.get("code");

  if (!code) {
    return Response.redirect(new URL("/", request.url).origin);
  }

  const { user, idToken, accessToken, refreshToken } =
    await scalekit.authenticateWithCode(code, REDIRECT_URI);

  const secure = url.protocol === "https:";
  const cookieOptions = { httpOnly: true, path: "/", sameSite: "lax" as const, secure };

  cookies.set("sk-id-token", idToken, cookieOptions);
  cookies.set("sk-access-token", accessToken, cookieOptions);
  cookies.set("sk-refresh-token", refreshToken, cookieOptions);

  return Response.redirect(new URL("/", request.url).origin);
};
```

`logout.ts` clears the session cookies and redirects to Scalekit's logout endpoint to end the Scalekit session.

```

  cookies.delete("sk-id-token", { path: "/" });
  cookies.delete("sk-access-token", { path: "/" });
  cookies.delete("sk-refresh-token", { path: "/" });

  const logoutUrl = scalekit.getLogoutUrl({
    idTokenHint: idToken,
    postLogoutRedirectUri: new URL("/", request.url).origin,
  });

  return Response.redirect(logoutUrl);
};
```

:::note The `postLogoutRedirectUri` passed to `getLogoutUrl()` must be registered as an allowed post-logout redirect URI in your Scalekit dashboard, otherwise Scalekit will reject the logout request. :::

### Adding session middleware

Create a `src/middleware.ts` file to validate the access token on every request and populate `Astro.locals.user` with the authenticated user's profile. When the access token has expired, the middleware automatically refreshes it using the refresh token.

```

  if (accessToken) {
    try {
      const claims = await scalekit.validateToken<IdTokenClaim>(accessToken);
      context.locals.user = {
        sub: claims.sub,
        email: claims.email,
        name: claims.name,
      };
    } catch {
      // Access token invalid or expired — try to refresh
      const refreshToken = context.cookies.get("sk-refresh-token")?.value;
      if (refreshToken) {
        try {
          const { accessToken: newToken } =
            await scalekit.refreshAccessToken(refreshToken);

          const secure = new URL(context.request.url).protocol === "https:";
          context.cookies.set("sk-access-token", newToken, {
            httpOnly: true,
            path: "/",
            sameSite: "lax",
            secure,
          });

          const claims = await scalekit.validateToken<IdTokenClaim>(newToken);
          context.locals.user = {
            sub: claims.sub,
            email: claims.email,
            name: claims.name,
          };
        } catch {
          // Refresh failed — clear session cookies
          context.cookies.delete("sk-id-token", { path: "/" });
          context.cookies.delete("sk-access-token", { path: "/" });
          context.cookies.delete("sk-refresh-token", { path: "/" });
        }
      }
    }
  }

  return next();
});
```

### Creating an authenticated page

Now that your middleware populates `Astro.locals.user`, you can create pages that show different content based on authentication state.

`dashboard.astro` is a page that is only accessible to authenticated users. It reads the user from `Astro.locals`, set by the middleware, and redirects to the home page if the user is not signed in.

```
---

const user = Astro.locals.user;

if (!user) {
  return Astro.redirect("/");
}
---

<Layout title="Dashboard">
  <h1>Welcome, {user.name ?? user.email}</h1>
  <p>You are signed in.</p>
  <a href="/api/auth/logout">Sign out</a>
</Layout>
```

## Community Resources

-   [Scalekit Node.js SDK documentation](https://github.com/scalekit-inc/scalekit-sdk-node)
-   [Astro blog tutorial with Scalekit authentication (Authorization Code flow)](https://github.com/scalekit-developers/astro-scalekit-auth-example)
-   [Scalekit developer docs site source (PKCE flow, no SDK)](https://github.com/scalekit-inc/developer-docs)

## [Monitor your Astro Site with Sentry](https://docharvest.github.io/docs/astro/guides/backend/sentry/)

Contents

astro

Monitor your Astro Site with Sentry

Astro

Monitor your Astro Site with Sentry

````
Once you've configured your `sourceMapsUploadOptions` and added your `dsn`, the SDK will automatically capture and send errors and performance events to Sentry.

## Test your setup

Add the following `<button>` element to one of your `.astro` pages. This will allow you to manually trigger an error so you can test the error reporting process.

```astro title="src/pages/index.astro"
<button onclick="throw new Error('This is a test error')">Throw test error</button>
````

To view and resolve the recorded error, log into [sentry.io](https://sentry.io/) and open your project.

## [Supabase & Astro](https://docharvest.github.io/docs/astro/guides/backend/supabase/)

Contents

astro

Supabase & Astro

Astro

Supabase & Astro

[Supabase](https://supabase.com/) is an open source Firebase alternative. It provides a Postgres database, authentication, edge functions, realtime subscriptions, and storage.

## Initializing Supabase in Astro

### Prerequisites

-   A Supabase project. If you don't have one, you can sign up for free at [supabase.com](https://supabase.com/) and create a new project.
-   An Astro project with [`output: 'server'` for on-demand rendering](/en/guides/on-demand-rendering/) enabled.
-   Supabase credentials for your project. You can find these in the **Settings > API** tab of your Supabase project.
    -   `SUPABASE_URL`: The URL of your Supabase project.
    -   `SUPABASE_ANON_KEY`: The anonymous key for your Supabase project.

### Adding Supabase credentials

To add your Supabase credentials to your Astro project, add the following to your `.env` file:

```
SUPABASE_URL=YOUR_SUPABASE_URL
SUPABASE_ANON_KEY=YOUR_SUPABASE_ANON_KEY
```

Now, these environment variables are available in your project.

If you would like to have IntelliSense for your environment variables, edit or create the `env.d.ts` in your `src/` directory and add the following:

```
interface ImportMetaEnv {
  readonly SUPABASE_URL: string
  readonly SUPABASE_ANON_KEY: string
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}
```

:::tip Read more about [environment variables](/en/guides/environment-variables/) and `.env` files in Astro. :::

Your project should now include these files:

\- src/ - \*\*env.d.ts\*\* - \*\*.env\*\* - astro.config.mjs - package.json

### Installing dependencies

To connect to Supabase, you will need to install `@supabase/supabase-js` in your project.

\`\`\`shell npm install @supabase/supabase-js \`\`\` \`\`\`shell pnpm add @supabase/supabase-js \`\`\` \`\`\`shell yarn add @supabase/supabase-js \`\`\`

Next, create a folder named `lib` in your `src/` directory. This is where you will add your Supabase client.

In `supabase.ts`, add the following to initialize your Supabase client:

Now, your project should include these files:

\- src/ - lib/ - \*\*supabase.ts\*\* - env.d.ts - .env - astro.config.mjs - package.json

## Adding authentication with Supabase

Supabase provides authentication out of the box. It supports email/password authentication and OAuth authentication with many providers including GitHub, Google, and several others.

### Prerequisites

-   An Astro project [initialized with Supabase](#initializing-supabase-in-astro).
-   A Supabase project with email/password authentication enabled. You can enable this in the **Authentication > Providers** tab of your Supabase project.

### Creating auth server endpoints

To add authentication to your project, you will need to create a few server endpoints. These endpoints will be used to register, sign in, and sign out users.

-   `POST /api/auth/register`: to register a new user.
-   `POST /api/auth/signin`: to sign in a user.
-   `GET /api/auth/signout`: to sign out a user.

Create these endpoints in the `src/pages/api/auth` directory of your project. If you are using `static` rendering mode, you must specify `export const prerender = false` at the top of each file to render these endpoints on demand. Your project should now include these new files:

\- src/ - lib/ - supabase.ts - pages/ - api/ - auth/ - \*\*signin.ts\*\* - \*\*signout.ts\*\* - \*\*register.ts\*\* - env.d.ts - .env - astro.config.mjs - package.json

`register.ts` creates a new user in Supabase. It accepts a `POST` request with the an email and password. It then uses the Supabase SDK to create a new user.

```
// With `output: 'static'` configured:
// export const prerender = false;

  const email = formData.get("email")?.toString();
  const password = formData.get("password")?.toString();

  if (!email || !password) {
    return new Response("Email and password are required", { status: 400 });
  }

  const { error } = await supabase.auth.signUp({
    email,
    password,
  });

  if (error) {
    return new Response(error.message, { status: 500 });
  }

  return redirect("/signin");
};
```

`signin.ts` signs in a user. It accepts a `POST` request with the an email and password. It then uses the Supabase SDK to sign in the user.

```
// With `output: 'static'` configured:
// export const prerender = false;

  const email = formData.get("email")?.toString();
  const password = formData.get("password")?.toString();

  if (!email || !password) {
    return new Response("Email and password are required", { status: 400 });
  }

  const { data, error } = await supabase.auth.signInWithPassword({
    email,
    password,
  });

  if (error) {
    return new Response(error.message, { status: 500 });
  }

  const { access_token, refresh_token } = data.session;
  cookies.set("sb-access-token", access_token, {
    path: "/",
  });
  cookies.set("sb-refresh-token", refresh_token, {
    path: "/",
  });
  return redirect("/dashboard");
};
```

`signout.ts` signs out a user. It accepts a `GET` request and removes the user's access and refresh tokens.

```
// With `output: 'static'` configured:
// export const prerender = false;

  cookies.delete("sb-refresh-token", { path: "/" });
  return redirect("/signin");
};
```

### Creating auth pages

Now that you have created your server endpoints, create the pages that will use them.

-   `src/pages/register`: contains a form to register a new user.
-   `src/pages/signin`: contains a form to sign in a user.
-   `src/pages/dashboard`: contains a page that is only accessible to authenticated users.

Create these pages in the `src/pages` directory. Your project should now include these new files:

\- src/ - lib/ - supabase.ts - pages/ - api/ - auth/ - signin.ts - signout.ts - register.ts - \*\*register.astro\*\* - \*\*signin.astro\*\* - \*\*dashboard.astro\*\* - env.d.ts - .env - astro.config.mjs - package.json

`register.astro` contains a form to register a new user. It accepts an email and password and sends a `POST` request to `/api/auth/register`.

```
---

---

<Layout title="Register">
  <h1>Register</h1>
  <p>Already have an account? <a href="/signin">Sign in</a></p>
  <form action="/api/auth/register" method="post">
    <label for="email">Email</label>
    <input type="email" name="email" id="email" />
    <label for="password">Password</label>
    <input type="password" name="password" id="password" />
    <button type="submit">Register</button>
  </form>
</Layout>
```

`signin.astro` contains a form to sign in a user. It accepts an email and password and sends a `POST` request to `/api/auth/signin`. It also checks for the presence of the access and refresh tokens. If they are present, it redirects to the dashboard.

```
---

const { cookies, redirect } = Astro;

const accessToken = cookies.get("sb-access-token");
const refreshToken = cookies.get("sb-refresh-token");

if (accessToken && refreshToken) {
  return redirect("/dashboard");
}
---

<Layout title="Sign in">
  <h1>Sign in</h1>
  <p>New here? <a href="/register">Create an account</a></p>
  <form action="/api/auth/signin" method="post">
    <label for="email">Email</label>
    <input type="email" name="email" id="email" />
    <label for="password">Password</label>
    <input type="password" name="password" id="password" />
    <button type="submit">Login</button>
  </form>
</Layout>
```

`dashboard.astro` contains a page that is only accessible to authenticated users. It checks for the presence of the access and refresh tokens. If they are not present or are invalid, it redirects to the sign in page.

```
---

const accessToken = Astro.cookies.get("sb-access-token");
const refreshToken = Astro.cookies.get("sb-refresh-token");

if (!accessToken || !refreshToken) {
  return Astro.redirect("/signin");
}

let session;
try {
  session = await supabase.auth.setSession({
    refresh_token: refreshToken.value,
    access_token: accessToken.value,
  });
  if (session.error) {
    Astro.cookies.delete("sb-access-token", {
      path: "/",
    });
    Astro.cookies.delete("sb-refresh-token", {
      path: "/",
    });
    return Astro.redirect("/signin");
  }
} catch (error) {
  Astro.cookies.delete("sb-access-token", {
    path: "/",
  });
  Astro.cookies.delete("sb-refresh-token", {
    path: "/",
  });
  return Astro.redirect("/signin");
}

const email = session.data.user?.email;
---
<Layout title="dashboard">
  <h1>Welcome {email}</h1>
  <p>We are happy to see you here</p>
  <form action="/api/auth/signout">
    <button type="submit">Sign out</button>
  </form>
</Layout>
```

### Adding OAuth authentication

To add OAuth authentication to your project, you will need to edit your Supabase client to enable authentication flow with `"pkce"`. You can read more about authentication flows in the [Supabase documentation](https://supabase.com/docs/guides/auth/server-side-rendering#understanding-the-authentication-flow).

Next, in the Supabase dashboard, enable the OAuth provider you would like to use. You can find the list of supported providers in the **Authentication > Providers** tab of your Supabase project.

The following example uses GitHub as the OAuth provider. To connect your project to GitHub, follow the steps in the [Supabase documentation](https://supabase.com/docs/guides/auth/social-login/auth-github).

Then, create a new server endpoint to handle the OAuth callback at `src/pages/api/auth/callback.ts`. This endpoint will be used to exchange the OAuth code for an access and refresh token.

```

  if (!authCode) {
    return new Response("No code provided", { status: 400 });
  }

  const { data, error } = await supabase.auth.exchangeCodeForSession(authCode);

  if (error) {
    return new Response(error.message, { status: 500 });
  }

  const { access_token, refresh_token } = data.session;

  cookies.set("sb-access-token", access_token, {
    path: "/",
  });
  cookies.set("sb-refresh-token", refresh_token, {
    path: "/",
  });

  return redirect("/dashboard");
};
```

Next, edit the sign in page to include a new button to sign in with the OAuth provider. This button should send a `POST` request to `/api/auth/signin` with the `provider` set to the name of the OAuth provider.

```
---

const { cookies, redirect } = Astro;

const accessToken = cookies.get("sb-access-token");
const refreshToken = cookies.get("sb-refresh-token");

if (accessToken && refreshToken) {
  return redirect("/dashboard");
}
---

<Layout title="Sign in">
  <h1>Sign in</h1>
  <p>New here? <a href="/register">Create an account</a></p>
  <form action="/api/auth/signin" method="post">
    <label for="email">Email</label>
    <input type="email" name="email" id="email" />
    <label for="password">Password</label>
    <input type="password" name="password" id="password" />
    <button type="submit">Login</button>
    <button value="github" name="provider" type="submit">Sign in with GitHub</button>
  </form>
</Layout>
```

Finally, edit the sign in server endpoint to handle the OAuth provider. If the `provider` is present, it will redirect to the OAuth provider. Otherwise, it will sign in the user with the email and password.

```

  const email = formData.get("email")?.toString();
  const password = formData.get("password")?.toString();
  const provider = formData.get("provider")?.toString();

  const validProviders = ["google", "github", "discord"];

  if (provider && validProviders.includes(provider)) {
    const { data, error } = await supabase.auth.signInWithOAuth({
      provider: provider as Provider,
      options: {
        redirectTo: "http://localhost:4321/api/auth/callback"
      },
    });

    if (error) {
      return new Response(error.message, { status: 500 });
    }

    return redirect(data.url);
  }

  if (!email || !password) {
    return new Response("Email and password are required", { status: 400 });
  }

  const { data, error } = await supabase.auth.signInWithPassword({
    email,
    password,
  });

  if (error) {
    return new Response(error.message, { status: 500 });
  }

  const { access_token, refresh_token } = data.session;
  cookies.set("sb-access-token", access_token, {
    path: "/",
  });
  cookies.set("sb-refresh-token", refresh_token, {
    path: "/",
  });
  return redirect("/dashboard");
};
```

After creating the OAuth callback endpoint and editing the sign in page and server endpoint, your project should have the following file structure:

\- src/ - lib/ - supabase.ts - pages/ - api/ - auth/ - signin.ts - signout.ts - register.ts - callback.ts - register.astro - signin.astro - dashboard.astro - env.d.ts - .env - astro.config.mjs - package.json

## Community Resources

-   [Getting into the holiday spirit with Astro, React, and Supabase](https://www.aleksandra.codes/astro-supabase)
-   [Astro and Supabase auth demo](https://github.com/kevinzunigacuellar/astro-supabase)

## [Turso & Astro](https://docharvest.github.io/docs/astro/guides/backend/turso/)

Contents

astro

Turso & Astro

Astro

Turso & Astro

````

## Querying your database

To access information from your database, import `turso` and [execute a SQL query](https://docs.turso.tech/sdk/ts/reference#simple-query) inside any `.astro` component.

The following example fetches all `posts` from your table, then displays a list of titles in a `<BlogIndex />` component:

```astro title="src/components/BlogIndex.astro"
---
import { turso } from '../turso'

const { rows } = await turso.execute('SELECT * FROM posts')
---

<ul>
  {rows.map((post) => (
    <li>{post.title}</li>
  ))}
</ul>
````

### SQL Placeholders

The `execute()` method can take [an object to pass variables to the SQL statement](https://docs.turso.tech/sdk/ts/reference#placeholders), such as `slug`, or pagination.

The following example fetches a single entry from the `posts` table `WHERE` the `slug` is the retrieved value from `Astro.params`, then displays the title of the post.

```
---
import { turso } from '../turso'

const { slug } = Astro.params

const { rows } = await turso.execute({
  sql: 'SELECT * FROM posts WHERE slug = ?',
  args: [slug!]
})
---

<h1>{rows[0].title}</h1>
```

## Turso Resources

-   [Turso Docs](https://docs.turso.tech)
-   [Turso on GitHub](https://github.com/tursodatabase)
-   [Using Turso to serve a Server-side Rendered Astro blog's content](https://blog.turso.tech/using-turso-to-serve-a-server-side-rendered-astro-blogs-content-58caa6188bd5)

## [Xata & Astro](https://docharvest.github.io/docs/astro/guides/backend/xata/)

Contents

astro

Xata & Astro

Astro

Xata & Astro

[Xata](https://xata.io) is a **Serverless Data Platform** that combines the features of a relational database, a search engine, and an analytics engine by exposing a single consistent REST API.

## Adding a database with Xata

### Prerequisites

-   A [Xata](https://app.xata.io/signin) account with a created database. (You can use the sample database from the Web UI.)
-   An Access Token (`XATA_API_KEY`).
-   Your Database URL.

After you update and initialize the [Xata CLI](https://xata.io/docs/getting-started/installation), you will have your API token in your `.env` file and database URL defined.

By the end of the setup, you should have:

```
XATA_API_KEY=hash_key

# Xata branch that will be used
# if there's not a xata branch with
# the same name as your git branch
XATA_BRANCH=main
```

And the `databaseURL` defined:

```
{
  "databaseUrl": "https://your-database-url"
}
```

### Environment configuration

To have IntelliSense and type safety for your environment variables, edit or create the file `env.d.ts` in your `src/` directory:

```
interface ImportMetaEnv {
  readonly XATA_API_KEY: string;
  readonly XATA_BRANCH?: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}
```

:::tip Read more about [environment variables](/en/guides/environment-variables/) and `.env` files in Astro. :::

Using the code generation from the Xata CLI and choosing the TypeScript option, generated an instance of the SDK for you, with types tailored to your database schema. Additionally, `@xata.io/client` was added to your `package.json`.

Your Xata environment variables and database url were automatically pulled by the SDK instance, so there's no more setup work needed.

Now, your project should have the following structure:

\- src/ - \*\*xata.ts\*\* - \*\*env.d.ts\*\* - \*\*.env\*\* - astro.config.mjs - package.json - \*\*.xatarc\*\*

## Create your queries

To query your posts, import and use `XataClient` class in a `.astro` file. The example below queries the first 50 posts from Xata's Sample Blog Database.

```
---

const xata = new XataClient({
  apiKey: import.meta.env.XATA_API_KEY,
  branch: import.meta.env.XATA_BRANCH
});

const { records } = await xata.db.Posts.getPaginated({
  pagination: {
    size: 50
  }
})
---

<ul>
  {records.map((post) => (
    <li>{post.title}</li>
  ))}
</ul>
```

It's important to note the SDK needs to be regenerated every time your schema changes. So, avoid making changes to the generated files the Xata CLI creates because once schema updates, your changes will be overwritten.

## Official Resources

-   [Xata Astro Starter](https://github.com/xataio/examples/tree/main/apps/getting-started-astro)
-   [Xata Docs: Quick Start Guide](https://xata.io/docs/getting-started/quickstart-astro)

## [Building Astro sites with AI tools](https://docharvest.github.io/docs/astro/guides/build-with-ai/)

Contents

astro

Building Astro sites with AI tools

Astro

Building Astro sites with AI tools

AI-powered editors and agentic coding tools generally have good knowledge of Astro's core APIs and concepts. However, some may use older APIs and may not be aware of newer features or recent changes to the framework.

This guide covers how to enhance AI tools with up-to-date Astro knowledge and provides best practices for building Astro sites with AI assistance.

## Astro Docs MCP Server

You can ensure your AI tools have current Astro knowledge through the Astro Docs MCP (Model Context Protocol) server. This provides real-time access to the latest documentation, helping AI tools avoid outdated recommendations and ensuring they understand current best practices.

:::tip\[What is MCP?\] [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) is a standardized way for AI tools to access external tools and data sources. :::

Unlike AI models trained on static data, the MCP server provides access to the latest Astro documentation. The server is free, open-source, and runs remotely with nothing to install locally.

The Astro Docs MCP server uses the [kapa.ai](https://www.kapa.ai/) API to maintain an up-to-date index of the Astro documentation.

### Server Details

-   **Name**: Astro Docs
-   **URL**: `https://mcp.docs.astro.build/mcp`
-   **Transport**: Streamable HTTP

### Installation

The setup process varies depending on your AI development tool. You may see some tools refer to MCP servers as connectors, adapters, extensions, or plugins.

#### Manual setup

Many tools support a common JSON configuration format for MCP servers. If there are not specific instructions for your chosen tool, you may be able to add the Astro Docs MCP server by including the following configuration in your tool's MCP settings:

\`\`\`json title="MCP Configuration" {3-6} { "mcpServers": { "Astro docs": { "type": "http", "url": "https://mcp.docs.astro.build/mcp" } } } \`\`\` \`\`\`json title="MCP Configuration" {3-7} { "mcpServers": { "Astro docs": { "type": "stdio", "command": "npx", "args": \["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"\] } } } \`\`\` \#### Claude Code CLI

[Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) is an agentic coding tool that runs on the command line. Enabling the Astro Docs MCP server allows it to access the latest documentation while generating Astro code.

Install using the terminal command:

```
claude mcp add --transport http astro-docs https://mcp.docs.astro.build/mcp
```

[More info on using MCP servers with Claude Code](https://docs.anthropic.com/en/docs/claude-code/mcp)

#### Claude Code GitHub Action

Claude Code also provides a GitHub Action that can be used to run commands in response to GitHub events. Enabling the Astro Docs MCP server allows it to access the latest documentation while answering questions in comments or generating Astro code.

You can configure it to use the Astro Docs MCP server for documentation access by adding the following to the workflow file:

```
# ...rest of your workflow configuration
- uses: anthropics/claude-code-action@beta
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    mcp_config: |
      {
        "mcpServers": {
          "astro-docs": {
            "type": "http",
            "url": "https://mcp.docs.astro.build/mcp"
          }
        }
      }
    allowed_tools: "mcp__astro-docs__search_astro_docs" 
```

[More info on using MCP servers with the Claude Code GitHub Action](https://github.com/anthropics/claude-code-action?tab=readme-ov-file#using-custom-mcp-configuration)

#### Codex CLI

Codex CLI is a command-line AI coding tool that can use the Astro Docs MCP server to access documentation while generating Astro code.

You can configure MCP servers at the global level in the `~/.codex/config.toml` file, or in a `.codex/config.toml` file in a project root.

```
[mcp_servers.astro-docs]
command = "npx"
args = ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"]
```

[More info on using MCP servers with Codex CLI](https://developers.openai.com/codex/mcp)

#### Cursor

[Cursor](https://cursor.com) is an AI code editor. Adding the Astro Docs MCP server allows Cursor to access the latest Astro documentation while performing development tasks.

Install by clicking the button below:

Add to Cursor

[More info on using MCP servers with Cursor](https://docs.cursor.com/context/mcp)

#### Visual Studio Code

[Visual Studio Code](https://code.visualstudio.com) supports MCP servers when using Copilot Chat. Adding the Astro Docs MCP server allows VS Code to access the latest Astro documentation when answering questions or performing coding tasks.

Install by clicking the button below:

Add to VS Code

[More info on using MCP servers with VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server)

#### Warp

[Warp](https://warp.dev) (formerly Warp Terminal) is an agent development environment built for coding with multiple AI agents. Adding the Astro Docs MCP server allows Warp to access the latest Astro documentation when answering questions or performing coding tasks.

1.  Open your Warp settings and go to AI > MCP Servers > Manage MCP Servers.
2.  Click "Add".
3.  Enter the following configuration. You can optionally configure the Astro MCP server to activate on startup using the `start_on_launch` flag:
    
    ```
    {
      "mcpServers": {
        "Astro docs": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"],
          "env": {},
          "working_directory": null,
          "start_on_launch": true
        }
      }
    }
    ```
    
4.  Click "Save".

[More info on using MCP servers with Warp](https://docs.warp.dev/knowledge-and-collaboration/mcp)

#### Claude.ai / Claude Desktop

[Claude.ai](https://claude.ai) is a general-purpose AI assistant. Adding the Astro Docs MCP server allows it to access the latest documentation when answering Astro questions or generating Astro code.

1.  Navigate to the [Claude.ai connector settings](https://claude.ai/settings/connectors).
2.  Click "Add custom connector". You may need to scroll down to find this option.
3.  Enter the server URL: `https://mcp.docs.astro.build/mcp`.
4.  Set the name to "Astro docs".

[More info on using MCP servers with Claude.ai](https://support.anthropic.com/en/articles/10168395-setting-up-integrations-on-claude-ai#h_cda40ecb32)

#### Windsurf

[Windsurf](https://windsurf.com/) is an AI-powered agentic coding tool, available as editor plugins or a standalone editor. It can use the Astro Docs MCP server to access documentation while performing coding tasks.

Windsurf doesn't support streaming HTTP, so it requires a local proxy configuration:

1.  Open `~/.codeium/windsurf/mcp_config.json` in your editor.
    
2.  Add the following configuration to your Windsurf MCP settings:
    
    ```
    {
      "mcpServers": {
        "Astro docs": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"]
        }
      }
    }
    ```
    
3.  Save the configuration and restart Windsurf.
    

[More info on using MCP servers with Windsurf](https://docs.windsurf.com/windsurf/cascade/mcp#mcp-config-json)

#### Gemini CLI

Gemini CLI is a command-line AI coding tool that can use the Astro Docs MCP server to access documentation while generating Astro code.

You can configure MCP servers at the global level in the `~/.gemini/settings.json` file, or in a `.gemini/settings.json` file in a project root.

```
{
  "mcpServers": {
    "Astro docs": {
      "httpUrl": "https://mcp.docs.astro.build/mcp",
    }
  }
}
```

[More info on using MCP servers with Gemini CLI](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md)

#### Google Antigravity

[Google Antigravity](https://antigravity.google/) is an agentic development platform.

1.  Open `~/.gemini/antigravity/mcp_config.json` by following the [Connecting Custom MCP Servers guide](https://antigravity.google/docs/mcp#connecting-custom-mcp-servers).
2.  Add the following configuration to `mcp_config.json`:
    
    ```
    {
      "mcpServers": {
        "astro-docs": {
          "serverUrl": "https://mcp.docs.astro.build/mcp"
        }
      }
    }
    ```
    
3.  Save the file and click "Refresh" in the "Manage MCPs" tab.

#### Zed

[Zed](https://zed.dev) supports MCP servers when using its AI capabilities. It can use the Astro Docs MCP server to access documentation while performing coding tasks.

1.  Open `~/.config/zed/settings.json` in your editor.
    
2.  Add the following configuration to your Zed MCP settings:
    
    ```
    {
       "context_servers": {
         "Astro docs": {
           "settings": {},
           "enabled": true,
           "url": "https://mcp.docs.astro.build/mcp"
         }
       }
    }
    ```
    
3.  Save the configuration.
    

[More info on using MCP servers with Zed](https://zed.dev/docs/ai/mcp)

#### ChatGPT

Refer to the [OpenAI MCP documentation](https://platform.openai.com/docs/mcp#test-and-connect-your-mcp-server) for specific setup instructions.

#### Raycast

[Raycast](https://www.raycast.com/) can connect to MCP servers to enhance its AI capabilities. Adding the Astro Docs MCP server allows Raycast to access the latest Astro documentation while answering questions.

Install by clicking the button below:

Add to Raycast

[More info on using MCP servers with Raycast](https://manual.raycast.com/model-context-protocol)

#### Opencode AI

[Opencode AI](https://opencode.ai/) is an open-source, terminal-based AI coding tool that can use the Astro Docs MCP server to access documentation while generating Astro code.

You can configure MCP servers in your Opencode configuration file, typically named `opencode.json`, located in your project root or your global configuration directory (e.g. `~/.config/opencode/opencode.json`).

```
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "Astro docs": {
      "type": "remote",
      "url": "https://mcp.docs.astro.build/mcp",
      "enabled": true
    }
  }
}
```

[More info on using Opencode AI](https://opencode.ai/)

#### GitHub Copilot Coding Agent

[GitHub Copilot](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-coding-agent) can be used as a coding agent powered by GitHub Actions. Enabling the Astro Docs MCP server allows it to access the latest Astro documentation when answering questions or performing coding tasks.

You can configure it to use the Astro Docs MCP server for documentation access by adding the following to your repository's Copilot coding agent settings available at `https://github.com/<your-org>/<your-repo>/settings/copilot/coding_agent`:

```
{
  "mcpServers": {
    "astro-docs": {
      "type": "http",
      "url": "https://mcp.docs.astro.build/mcp",
      "tools": ["mcp__astro-docs__search_astro_docs"]
    }
  }
}
```

Learn more about [extending GitHub Copilot coding agent with MCP servers](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp).

### Usage

Once configured, you can ask your AI tool questions about Astro, and it will retrieve information directly from the latest docs. Coding agents will be able to consult the latest documentation when performing coding tasks, and chatbots will be able to accurately answer questions about Astro features, APIs, and best practices.

:::note\[Remember\] The Astro Docs MCP server provides access to current documentation, but your AI tools are still responsible for interpretation and code generation. AI makes mistakes, so always review generated code carefully and test thoroughly. :::

### Troubleshooting

If you encounter issues:

-   Verify that your tool supports streamable HTTP transport.
-   Check that the server URL is correct: `https://mcp.docs.astro.build/mcp`.
-   Ensure your tool has proper internet access.
-   Consult your specific tool's MCP integration documentation.

If you are still having problems, open an issue in the [Astro Docs MCP Server repository](https://github.com/withastro/docs-mcp/issues).

## Discord AI Support

The same technology that powers Astro's MCP server is also available as a chatbot in the [Astro Discord](https://astro.build/chat) for self-serve support. Visit the `#support-ai` channel to ask questions about Astro or your project code in natural language. Your conversation is automatically threaded, and you can ask an unlimited number of follow-up questions.

**Conversations with the chatbot are public, and are subject to the same server rules for language and behavior as the rest of our channels**, but they are not actively visited by our volunteer support members. For assistance from the community, please create a thread in our regular `#support` channel.

## Background mode

When an AI coding agent is detected, `astro dev` automatically starts the dev server as a detached background process. This prevents the dev server from blocking the agent's terminal and allows it to continue working while the server runs.

A lock file (`.astro/dev.json`) is written when the dev server starts, recording the server's URL, port, and PID. This prevents duplicate servers from being started for the same project.

If you are not using an AI coding agent, `astro dev` starts in the foreground process and logs to the terminal.

To opt out of automatic background mode, set the `ASTRO_DEV_BACKGROUND` environment variable before running `astro dev`:

```
ASTRO_DEV_BACKGROUND=0 astro dev
```

See the [CLI reference](/en/reference/cli-reference/#astro-dev) for the full list of `astro dev` flags and subcommands.

### Health endpoint

The dev server exposes a `/_astro/status` endpoint that returns `{"ok": true}` as JSON. This allows agents and other tools to check programmatically whether the dev server is ready to accept requests. This endpoint is only available in the dev server and does not exist in production builds.

## Tips for AI-Powered Astro Development

-   **Start with templates**: Rather than building from scratch, ask AI tools to start with an existing [Astro template](https://astro.build/themes/) or use `npm create astro@latest` with a template option.
-   **Use `astro add` for integrations**: Ask AI tools to use `astro add` for official integrations (e.g. `astro add tailwind`, `astro add react`). For other packages, install using the command for your preferred package manager rather than editing `package.json` directly.
-   **Verify current APIs**: AI tools may use outdated patterns. Ask them to check the latest documentation, especially for newer features like sessions and actions. This is also important for features that have seen significant changes since their initial launch, such as content collections, or previously experimental features that may no longer be experimental.
-   **Use project rules**: If your AI tool supports it, set up project rules to enforce best practices and coding standards, such as the ones listed above.

## [Route caching](https://docharvest.github.io/docs/astro/guides/caching/)

Contents

astro

Route caching

Astro

Route caching

````

You can then use [`Astro.cache`](/en/reference/api-reference/#cache) in your `.astro` pages (or `context.cache` for API routes and middleware) to control caching per request. Cache defaults for groups of routes can also be defined declaratively in your config using [`routeRules`](#route-rules).

If you deploy to Netlify, Vercel, or Cloudflare, you can use their respective adapters' experimental [CDN cache provider](#adapter-cache-providers) instead of the in-memory provider.

## Adapter cache providers

Astro's first-party adapters for Netlify, Vercel, and Cloudflare each provide an experimental CDN cache provider that maps cache directives to the platform's native cache headers and invalidation API. Rather than storing responses in memory, these push your caching directives to the host's edge network, and cache hits are served straight from the CDN without invoking your server function.

During the experimental phase these providers need to be manually enabled, as shown below. In a future release, the Netlify and Vercel providers will be enabled automatically by their adapters. The Cloudflare provider requires a feature that is currently in private beta.

Each provider automatically tags cached responses with the request path, so [`cache.invalidate({ path })`](/en/reference/api-reference/#cacheinvalidate) works on platforms that only support tag-based purges.

### Netlify

<p>

<Since pkg="@astrojs/netlify" v="8.0.0" />
</p>

Import `cacheNetlify()` from `@astrojs/netlify/cache` and set it as your cache provider:

```js title="astro.config.mjs" ins={3, 7-9}

````

The provider sets `Netlify-CDN-Cache-Control` and `Netlify-Cache-Tag` headers. Cached responses use Netlify's [durable cache](https://docs.netlify.com/platform/caching/#durable-directive) so they are shared across all edge nodes, reducing function invocations. Both tag-based and path-based invalidation are supported.

### Vercel

Import `cacheVercel()` from `@astrojs/vercel/cache` and set it as your cache provider:

The provider sets `Vercel-CDN-Cache-Control` and `Vercel-Cache-Tag` headers. Both tag-based and path-based invalidation are supported. Tag invalidation is a soft invalidation: cached responses are marked as stale and revalidated in the background using stale-while-revalidate.

### Cloudflare

:::caution\[Private beta\] The Cloudflare provider requires the Cloudflare Workers Cache feature, which is currently in private beta. Without beta access, the headers are ignored and calling `cache.invalidate()` will throw an error. :::

Import `cacheCloudflare()` from `@astrojs/cloudflare/cache` and set it as your cache provider:

The provider sets `Cloudflare-CDN-Cache-Control` and `Cache-Tag` headers. The adapter enables Worker caching automatically when a Cloudflare cache provider is configured. Both tag-based and path-based invalidation are supported.

## Interacting with the cache

The [`cache` object](/en/reference/api-reference/#cache) provides methods for setting cache options, invalidating entries, and checking the current cache state. This object is available in your `.astro` pages as `Astro.cache`, and in API routes and middleware as `context.cache`.

See the [Cache API reference](/en/reference/api-reference/#cache) for more details.

### Checking if caching is enabled

When caching is not configured, `cache.set()`, `cache.tags`, and `cache.options` log a warning, and `cache.invalidate()` throws an error. To avoid this, wrap your caching logic in a conditional check using [`cache.enabled`](/en/reference/api-reference/#cacheenabled). Its value is always `false` when no provider is configured or in development mode.

```
---
if (Astro.cache.enabled) {
  const tags = await getProductTags(Astro.params.id);
  Astro.cache.set({ maxAge: 3600, tags });
}
---
```

### Setting cache options

Call [`cache.set()`](/en/reference/api-reference/#cacheset) with an options object to enable caching for the current response.

The following example caches a page for 2 minutes, serves stale content for 1 minute while revalidating, and tags the response for targeted invalidation:

```
---

---

<html><body>Cached page</body></html>
```

In API routes and middleware, use `context.cache`:

```

  return Response.json({ ok: true });
}
```

### Opting out of caching

Call [`cache.set()`](/en/reference/api-reference/#cacheset) with `false` to explicitly opt a request out of caching. This is useful when a matched [route rule](#route-rules) would otherwise cache the response:

```
---
if (isPersonalized) {
  Astro.cache.set(false);
}
---
```

### Reading cache state

You can access the current accumulated cache options via [`cache.options`](/en/reference/api-reference/#cacheoptions). This is useful for debugging or when you want to conditionally modify caching based on the current state:

```
const { maxAge, swr, tags } = context.cache.options;
```

### Invalidating cache entries

You can purge cached entries by tag or path using [`cache.invalidate()`](/en/reference/api-reference/#cacheinvalidate). This is useful for programmatically clearing cached content when it becomes stale, such as after a content update or user action.

The following example creates an API route that invalidates by tag and by path:

```

  // Invalidate a specific path
  await context.cache.invalidate({ path: '/api/data' });

  return Response.json({ purged: true });
}
```

Tag-based invalidation removes all cached entries whose tags include any of the provided tags. Path-based invalidation is exact-match only (no [glob](/en/guides/imports/#glob-patterns) or wildcard patterns).

## Merge behavior

Multiple calls to [`cache.set()`](/en/reference/api-reference/#cacheset) within a single request are merged according to the following rules:

-   **Scalar values** (`maxAge`, `swr`, `etag`): last-write-wins
-   **`lastModified`**: most recent date wins
-   **`tags`**: accumulate across all calls

Middleware, layouts, content loaders, and page code can each contribute cache directives independently.

## Dev mode behavior

In dev mode, the cache API is available so that route code does not need conditional checks, but no actual caching occurs. [`cache.enabled`](/en/reference/api-reference/#cacheenabled) is `false`, and [`cache.set()`](/en/reference/api-reference/#cacheset) and [`cache.invalidate()`](/en/reference/api-reference/#cacheinvalidate) are no-ops. To test your caching locally, build then preview your site.

## Route rules

Route rules allow you to define caching behavior for groups of routes declaratively in your config. This is useful for applying caching to large groups of routes at once.

The following example caches all API routes with stale-while-revalidate, product pages with a 1-hour freshness window, and blog posts for 5 minutes:

The following route patterns are supported:

-   **Static paths**: `/about`, `/api/health`
-   **Dynamic parameters**: `/products/[id]`, `/blog/[slug]`
-   **Rest parameters**: `/docs/[...path]`

Patterns use the same syntax, matching, and priority rules as Astro's [file-based routing](/en/guides/routing/#route-priority-order), so more specific patterns take precedence. Glob wildcards such as `*` are not supported; use a `[...rest]` parameter to match a group of routes (for example, `/api/[...path]` to match everything under `/api`).

Per-route [`cache.set()`](/en/reference/api-reference/#cacheset) calls merge with config-level route rules. Route code can override or extend the defaults set in config. For example, a route rule might set a default `maxAge` for all product pages, but individual pages can call `cache.set()` to customize or disable caching as needed.

## [Scripts and event handling](https://docharvest.github.io/docs/astro/guides/client-side-scripts/)

Contents

astro

Scripts and event handling

Astro

Scripts and event handling

// Find our component DOM on the page. const buttons = document.querySelectorAll('\[data-confetti-button\]');

// Add event listeners to fire confetti when a button is clicked. buttons.forEach((button) => { button.addEventListener('click', () => confetti()); });

````

<ReadMore>See [when your scripts will not be processed](#unprocessed-scripts) to troubleshoot script behavior, or to learn how to opt-out of this processing intentionally.</ReadMore>

## Script processing

By default, Astro processes `<script>` tags that contain no attributes (other than `src`) in the following ways:

- **TypeScript support:** All scripts are TypeScript by default.
- **Import bundling:** Import local files or npm modules, which will be bundled together.
- **Type Module:** Processed scripts become [`type="module"`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) automatically.
- **Deduplication:** If a component that contains a `<script>` is used multiple times on a page, the script will only be included once.
- **Automatic inlining:** If the script is small enough, Astro will inline it directly into the HTML to reduce the number of requests.
```astro title="src/components/Example.astro"
<script>
  // Processed! Bundled! TypeScript!
  // Importing local scripts and from npm packages works.
</script>
````

### Unprocessed scripts

Astro will not process a `<script>` tag if it has any attribute other than `src`.

You can add the [`is:inline`](/en/reference/directives-reference/#isinline) directive to intentionally opt out of processing for a script.

```
<script is:inline>
  // Will be rendered into the HTML exactly as written!
  // Not transformed: no TypeScript and no import resolution by Astro.
  // If used inside a component, this code is duplicated for each instance.
</script>
```

### Include JavaScript files on your page

You may want to write your scripts as separate `.js`/`.ts` files or need to reference an external script on another server. You can do this by referencing these in a `<script>` tag’s `src` attribute.

#### Import local scripts

**When to use this:** when your script lives inside of `src/`.

Astro will process these scripts according to the [script processing rules](#script-processing).

```
<!-- relative path to script at `src/scripts/local.js` -->
<script src="../scripts/local.js"></script>

<!-- also works for local TypeScript files -->
<script src="./script-with-types.ts"></script>
```

#### Load external scripts

**When to use this:** when your JavaScript file lives inside of `public/` or on a CDN.

To load scripts outside of your project's `src/` folder, include the `is:inline` directive. This approach skips the JavaScript processing, bundling, and optimizations that are provided by Astro when you import scripts as described above.

```
<!-- absolute path to a script at `public/my-script.js` -->
<script is:inline src="/my-script.js"></script>

<!-- full URL to a script on a remote server -->
<script is:inline src="https://my-analytics.com/script.js"></script>
```

## Common script patterns

### Handle `onclick` and other events

Some UI frameworks use custom syntax for event handling like `onClick={...}` (React/Preact) or `@click="..."` (Vue). Astro follows standard HTML more closely and does not use custom syntax for events.

Instead, you can use [`addEventListener`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener) in a `<script>` tag to handle user interactions.

```
<button class="alert">Click me!</button>

<script>
  // Find all buttons with the `alert` class on the page.
  const buttons = document.querySelectorAll('button.alert');

  // Handle clicks on each button.
  buttons.forEach((button) => {
    button.addEventListener('click', () => {
      alert('Button was clicked!');
    });
  });
</script>
```

If you have multiple `<AlertButton />` components on a page, Astro will not run the script multiple times. Scripts are bundled and only included once per page. Using `querySelectorAll` ensures that this script attaches the event listener to every button with the `alert` class found on the page.

### Web components with custom elements

You can create your own HTML elements with custom behavior using the Web Components standard. Defining a [custom element](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) in a `.astro` component allows you to build interactive components without needing a UI framework library.

In this example, we define a new `<astro-heart>` HTML element that tracks how many times you click the heart button and updates the `<span>` with the latest count.

```
<!-- Wrap the component elements in our custom element “astro-heart”. -->
<astro-heart>
  <button aria-label="Heart">💜</button> × <span>0</span>
</astro-heart>

<script>
  // Define the behavior for our new type of HTML element.
  class AstroHeart extends HTMLElement {
    connectedCallback() {
      let count = 0;

      const heartButton = this.querySelector("button");
      const countSpan = this.querySelector("span");

      // Each time the button is clicked, update the count.
      if (heartButton && countSpan) {
        heartButton.addEventListener("click", () => {
          count++;
          countSpan.textContent = count.toString();
        });
      }
    }
  }

  // Tell the browser to use our AstroHeart class for <astro-heart> elements.
  customElements.define("astro-heart", AstroHeart);
</script>
```

There are two advantages to using a custom element here:

1.  Instead of searching the whole page using `document.querySelector()`, you can use `this.querySelector()`, which only searches within the current custom element instance. This makes it easier to work with only the children of one component instance at a time.
    
2.  Although a `<script>` only runs once, the browser will run our custom element’s `connectedCallback()` method each time it finds `<astro-heart>` on the page. This means you can safely write code for one component at a time, even if you intend to use this component multiple times on a page.
    

You can learn more about custom elements in [web.dev’s Reusable Web Components guide](https://web.dev/custom-elements-v1/) and [MDN’s introduction to custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements).

### Pass frontmatter variables to scripts

In Astro components, the code in [the frontmatter](/en/basics/astro-components/#the-component-script) (between the `---` fences) runs on the server and is not available in the browser.

To pass server-side variables to client-side scripts, store them in [`data-*` attributes](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes) on HTML elements. Scripts can then access these values using the `dataset` property.

In this example component, a `message` prop is stored in a `data-message` attribute, so the custom element can read `this.dataset.message` and get the value of the prop in the browser.

```
---
const { message = 'Welcome, world!' } = Astro.props;
---

<!-- Store the message prop as a data attribute. -->
<astro-greet data-message={message}>
  <button>Say hi!</button>
</astro-greet>

<script>
  class AstroGreet extends HTMLElement {
    connectedCallback() {
      // Read the message from the data attribute.
      const message = this.dataset.message;
      const button = this.querySelector('button');
      button?.addEventListener('click', () => {
        alert(message);
      });
    }
  }

  customElements.define('astro-greet', AstroGreet);
</script>
```

Now we can use our component multiple times and be greeted by a different message for each one.

```
---

---

<!-- Use the default message: “Welcome, world!” -->
<AstroGreet />

<!-- Use custom messages passed as a props. -->
<AstroGreet message="Lovely day to build components!" />
<AstroGreet message="Glad you made it! 👋" />
```

:::tip\[Did you know?\] This is actually what Astro does behind the scenes when you pass props to a component written using a UI framework like React! For components with a `client:*` directive, Astro creates an `<astro-island>` custom element with a `props` attribute that stores your server-side props in the HTML output. :::

### Combining scripts and UI Frameworks

Elements rendered by a UI framework may not be available yet when a `<script>` tag executes. If your script also needs to handle [UI framework components](/en/guides/framework-components/), using a custom element is recommended.

## [Use a CMS with Astro](https://docharvest.github.io/docs/astro/guides/cms/)

Contents

astro

Use a CMS with Astro

Astro

Use a CMS with Astro

import Badge from "~/components/Badge.astro"

**Ready to connect a Headless CMS to your Astro project?** Follow one of our guides to integrate a CMS.

:::tip Find [community-maintained integrations](https://astro.build/integrations/?search=cms) for connecting a CMS to your project in our integrations directory. :::

## Featured CMS partners

## CMS guides

Note that many of these pages are **stubs**: they're collections of resources waiting for your contribution!

## Why use a CMS?

A Content Management System lets you write content and manage assets outside of your Astro project.

This unlocks new features for working with content. Most CMSes give you a visual content editor, the ability to specify standard types of content, and a way to collaborate with others.

A CMS can be useful for content that follows a particular structure, often giving you a dashboard-like experience and WYSIWYG editing tools. You might use a CMS to write blog posts using a CMS's rich text editor instead of Markdown files. Or you might use a CMS to maintain product listings for an eCommerce shop, making certain fields required to avoid incomplete listings.

Your Astro project can then fetch your content from your CMS and display it, wherever and however you want on your site.

## Which CMSes work well with Astro?

Because Astro takes care of the _presentation_ of your content, you'll want to choose a _headless_ CMS, like those in the list above. This means that the CMS helps you write your content, but doesn't generate a site that displays it. Instead, you fetch the content data and use in your Astro project.

Some headless CMSes, like Storyblok, provide an Astro [integration](/en/guides/integrations/) that helps fetch the content specifically for an Astro site. Others provide a JavaScript SDK, a library that you install and use to fetch your remote content.

Explore a [list of over 100 headless content management systems](https://jamstack.org/headless-cms/) where you can filter by type (e.g. Git-based, API driven) and license (open-source or closed-source).

## Can I use Astro without a CMS?

Yes! Astro provides built-in support for [Markdown](/en/guides/markdown-content/).

## [ApostropheCMS & Astro](https://docharvest.github.io/docs/astro/guides/cms/apostrophecms/)

Contents

astro

ApostropheCMS & Astro

Astro

ApostropheCMS & Astro

const env = loadEnv("", process.cwd(), 'APOS');

````

For complete configuration options and explanations, see the [`apostrophe-astro` documentation](https://apostrophecms.com/extensions/astro-integration#configuration-astro).

### Connecting ApostropheCMS widgets to Astro components
ApostropheCMS widgets are blocks of structured content that can be added to the page such as layout columns, images, and text blocks. You will need to create an Astro component for each widget in your Apostrophe project, plus a file to map those components to the corresponding Apostrophe widget.

Create a new folder at `src/widgets/` for your Astro components and the mapping file, `index.js`.

Mapped components located in this folder receive a `widget` property containing your widget's schema fields, and any custom props, through `Astro.props`. These values are then available for on-page editing.

The following example shows a `RichTextWidget.astro` component accessing the content from its corresponding ApostropheCMS widget to allow for in-context editing:

```js title="src/widgets/RichTextWidget.astro"
---
const { widget } = Astro.props;
const { content } = widget;
---
<Fragment set:html={ content }></Fragment>
````

Some standard Apostrophe widgets, such as images and videos, require **placeholders** because they do not contain editable content by default. The following example creates a standard `ImageWidget.astro` component that sets the `src` value conditionally to either the value of the `aposPlaceholder` image passed by the widget, a fallback image from the Astro project, or the image selected by the content manager using the Apostrophe `attachment` helper:

```
---
const { widget } = Astro.props;
const placeholder = widget?.aposPlaceholder;
const src = placeholder ?
  '/images/image-widget-placeholder.jpg' :
  widget?._image[0]?.attachment?._urls['full'];
---
<style>
  .img-widget {
    width: 100%;
  }
</style>
<img class="img-widget" {src} />
```

For more examples, see [the `astro-frontend` starter project widget examples](https://github.com/apostrophecms/astro-frontend/tree/main/src/widgets).

Each `.astro` component must be mapped to the corresponding core Apostrophe widget in `src/widgets/index.js`.

The example below adds the previous two components to this file:

```

const widgetComponents = {
  '@apostrophecms/rich-text': RichTextWidget,
  '@apostrophecms/image': ImageWidget
};
```

See [the ApostropheCMS documentation](https://apostrophecms.com/extensions/astro-integration) for naming conventions for standard, pro, and custom-project-level widgets

The project directory should now look like this:

\- src/ - widgets/ - \*\*index.js\*\* - \*\*ImageWidget.astro\*\* - \*\*RichTextWidget.astro\*\* - .env - astro.config.mjs - package.json

### Adding page types

Much like widgets, any page type template in your ApostropheCMS project needs to have a corresponding template component in your Astro project. You will also need a file that maps the Apostrophe page types to individual components.

Create a new folder at `src/templates/` for your Astro components and the mapping file, `index.js`. Mapped components located in this folder receive a `page` property containing the schema fields of your page, and any custom props, through `Astro.props`. These components can also access an `AposArea` component to render Apostrophe areas.

The following example shows a `HomePage.astro` component rendering a page template from its corresponding `home-page` ApostropheCMS page type, including an area schema field named `main`:

```
---

const { page, user, query } = Astro.props.aposData;
const { main } = page;
---

<section class="bp-content">
  <h1>{ page.title }</h1>
  <AposArea area={main} />
</section>
```

Each `.astro` component must be mapped to the corresponding core Apostrophe page type in `src/templates/index.js`.

The example below adds the previous `HomePage.astro` component to this file:

```

const templateComponents = {
  '@apostrophecms/home-page': HomePage
};
```

See [the ApostropheCMS documentation](https://apostrophecms.com/extensions/astro-integration/#how-apostrophe-template-names-work) for template naming conventions, including special pages and piece page types.

The project directory should now look like this:

\- src/ - widgets/ - index.js - ImageWidget.astro - RichTextWidget.astro - templates/ - \*\*HomePage.astro\*\* - \*\*index.js\*\* - .env - astro.config.mjs - package.json

### Creating the \[...slug.astro\] component and fetching Apostrophe data

Since Apostrophe is responsible for connecting URLs to content, including creating new content and pages on the fly, you will only need one top-level Astro page component: the `[...slug].astro` route.

The following example shows a minimal `[...slug].astro` component:

```
---

const aposData = await aposPageFetch(Astro.request);
const bodyClass = `myclass`;

if (aposData.redirect) {
  return Astro.redirect(aposData.url, aposData.status);
}
if (aposData.notFound) {
  Astro.response.status = 404;
}
---
<AposLayout title={aposData.page?.title} {aposData} {bodyClass}>
    <Fragment slot="standardHead">
      <meta name="description" content={aposData.page?.seoDescription} />
      <meta name="viewport" content="width=device-width, initial-scale=1" />
      <meta charset="UTF-8" />
    </Fragment>
    <AposTemplate {aposData} slot="main"/>
</AposLayout>
```

See [the ApostropheCMS documentation](https://apostrophecms.com/extensions/astro-integration#creating-the-slugastro-component-and-fetching-apostrophe-data) for additional templating options, including slots available in the `AposTemplate` component.

## Making a blog with Astro and ApostropheCMS

With the integration set up, you can now create a blog with Astro and ApostropheCMS. Your blog will use an Apostrophe piece, a stand-alone content type that can be included on any page, and a piece page type, a specialized page type that is used for displaying those pieces either individually or collectively.

### Prerequisites

1.  **An ApostropheCMS project with the Apostrophe CLI tool installed** - You can create a new project or use an existing one. However, this tutorial will only show how to create a blog piece and piece page type. You will have to integrate any other existing project code independently. If you don't have the CLI tool installed, consult the [Apostrophe CLI installation instructions](https://docs.apostrophecms.org/guide/setting-up.html#the-apostrophe-cli-tool).
2.  **An Astro project integrated with ApostropheCMS** - To create a project from scratch, see [integrating with Astro](#integrating-with-astro) for instructions on how to set up the integration, or use the [astro-frontend](https://github.com/apostrophecms/astro-frontend) starter project.

### Creating a blog piece and piece page type

To create your blog piece and piece page type for their display, navigate to the root of your ApostropheCMS project in your terminal. Use the ApostropheCMS CLI tool to create the new piece and piece page type with the following command:

```
apos add piece blog --page
```

This will create two new modules in your project, one for the blog piece type and one for the corresponding piece page type. Next, open the `app.js` file at the root of your ApostropheCMS project in your code editor and add your new modules.

```
require('apostrophe')({
  // other configuration options
  modules: {
    // other project modules
    blog: {},
    'blog-page': {}
  }
});
```

The `blog-page` module also needs to be added to the `@apostrophecms/page` module `types` option array so that it can be selected in the page creation modal. In your ApostropheCMS project, open the `modules/@apostrophecms/page/index.js` file and add the `blog-page`.

```
module.exports = {
  options: {
    types: [
      {
        name: '@apostrophecms/home-page',
        label: 'Home'
      },
      // Any other project pages
      {
        name: 'blog-page',
        label: 'Blog'
      }
    ]
  }
};
```

### Creating the blog schema

In an ApostropheCMS project, editors are offered a set of input fields for adding content. Here is an example of a simple blog post that adds three input fields, an `authorName`, `publicationDate` and `content` area where content managers can add multiple widget instances. In this case, we are specifying they can add the image and rich-text widgets we created during the [integration setup](#connecting-apostrophecms-widgets-to-astro-components).

```
module.exports = {
  extend: '@apostrophecms/piece-type',
  options: {
    label: 'Blog',
    // Additionally add a `pluralLabel` option if needed.
  },
  fields: {
    add: {
      authorName: {
        type: 'string',
        label: 'Author'
      },
      publicationDate: {
        type: 'date',
        label: 'Publication date'
      },
      content: {
        type: 'area',
        label: 'Content',
        options: {
          widgets: {
            '@apostrophecms/rich-text': {},
            '@apostrophecms/image': {}
          }
        }
      }
    },
    group: {
      basics: {
        label: 'Basic',
        fields: [ 'authorName', 'publicationDate', 'content' ]
      }
    }
  }
};
```

At this point, all the components coming from the ApostropheCMS project are set up. Start the local site from the command line using `npm run dev`, making sure to pass in the `APOS_EXTERNAL_FRONT_KEY` environment variable set to your selected string:

```
APOS_EXTERNAL_FRONT_KEY='MyRandomString' npm run dev
```

### Displaying the blog posts

To display a page with all the blog posts create a `BlogIndex.astro` component file in the `src/templates` directory of your Astro project and add the following code:

After fetching both the page and pieces data from the `aposData` prop, this component creates markup using both fields from the blog piece schema we created, but also from the `piece.title` and `piece._url` that is added to each piece by Apostrophe.

```
---

const { page, pieces } = Astro.props.aposData;
---

<section class="bp-content">
  <h1>{ page.title }</h1>

  <h2>Blog Posts</h2>

  {pieces.map(piece => (
    <h4>
      Released On { dayjs(piece.publicationDate).format('MMMM D, YYYY') }
    </h4>
    <h3>
      <a href={ piece._url }>{ piece.title }</a>
    </h3>
    <h4>{ piece.authorName }</h4>
  ))}
</section>
```

To display individual blog posts, create a `BlogShow.astro` file in the Astro project `src/templates` folder with the following code:

This component uses the `<AposArea>` component to display any widgets added to the `content` area and the `authorName` and `publicationDate` content entered into the fields of the same names.

```
---

const { page, piece } = Astro.props.aposData;
const { main } = piece;
---

<section class="bp-content">
  <h1>{ piece.title }</h1>
  <h3>Created by: { piece.authorName }
  <h4>
    Released On { dayjs(piece.publicationDate).format('MMMM D, YYYY') }
  </h4>
  <AposArea area={content} />
</section>
```

Finally, these Astro components must be mapped to the corresponding ApostropheCMS page types. Open the Astro project `src/templates/index.js` file and modify it to contain the following code:

```

const templateComponents = {
  '@apostrophecms/home-page': HomePage,
  '@apostrophecms/blog-page:index': BlogIndexPage,
  '@apostrophecms/blog-page:show': BlogShowPage
};
```

### Creating blog posts

Adding blog posts to your site is accomplished by using the ApostropheCMS content and management tools to create those posts and by publishing at least one index page to display them.

With the Astro dev server running, navigate to the login page located at [http://localhost:4321/login](http://localhost:4321/login) in your browser preview. Use the credentials that were added during the [creation of the ApostropheCMS project](https://docs.apostrophecms.org/guide/development-setup.html#creating-a-project) to log in as an administrator. Your ApostropheCMS project should still be running.

Once you are logged in, your browser will be redirected to the home page of your project and will display an admin bar at the top for editing content and managing your project.

To add your first blog post, click on the `Blogs` button in the admin bar to open the blog piece creation modal. Clicking on the `New Blog` button in the upper right will open an editing modal where you can add content. The `content` area field will allow you to add as many image and rich text widgets as you desire.

You can repeat this step and add as many posts as you want. You will also follow these steps every time you want to add a new post.

To publish a page for displaying all your posts, click on the `Pages` button in the admin bar. From the page tree modal click on the `New Page` button. In the `Type` dropdown in the right column select `Blog`. Add a title for the page and then click `Publish and View`. You will only need to do this once.

Any new blog posts that are created will be automatically displayed on this page. Individual blog posts can be displayed by clicking on the link created on the index page.

The `content` area of individual posts can be edited directly on the page by navigating to the post and clicking `edit` in the admin bar. Other fields can be edited by using the editing modal opened when clicking the `Blogs` menu item in the admin bar.

### Deploying your site

To deploy your website, you need to host both your Astro and ApostropheCMS projects.

For Astro, visit our [deployment guides](/en/guides/deploy/) and follow the instructions for your preferred hosting provider.

For the ApostropheCMS project, follow the instructions for your hosting type in our [hosting guide](https://docs.apostrophecms.org/guide/hosting.html). Finally, you'll need to supply an `APOS_HOST` environment variable to the Astro project to reflect the correct URL where your ApostropheCMS site has been deployed.

## Official Resources

-   [Astro integration for ApostropheCMS](https://apostrophecms.com/extensions/astro-integration) - ApostropheCMS Astro plugin, integration guide and starter projects for both Apostrophe and Astro
-   [Sample Astro project for use with ApostropheCMS](https://github.com/apostrophecms/astro-frontend) - A simple Astro project with several pages and Apostrophe widgets already created.
-   [Sample ApostropheCMS starter-kit for use with Astro](https://apostrophecms.com/starter-kits/astro-integration-starter-kit) - An ApostropheCMS project with core page modifications for use with Astro.

## Community Resources

-   [Integrating ApostropheCMS with Astro, Pt. 1](https://apostrophecms.com/blog/how-to-integrate-astro-with-apostrophecms-pt-1) by Antonello Zaini
-   [Integrating ApostropheCMS with Astro, Pt. 2](https://apostrophecms.com/blog/how-to-integrate-astro-with-apostrophecms-pt-2) by Antonello Zaini
-   [Show & Tell Live | Astro & Apostrophe](https://youtu.be/cwJhtJhAhwA?si=6iUU9EjidfdnOdCh)

## [Builder.io & Astro](https://docharvest.github.io/docs/astro/guides/cms/builderio/)



## [ButterCMS & Astro](https://docharvest.github.io/docs/astro/guides/cms/buttercms/)

Contents

astro

ButterCMS & Astro

Astro

ButterCMS & Astro

````
export const butterClient = Butter(import.meta.env.BUTTER_TOKEN);
```
````

**This authenticates the SDK using your API Token and exports it to be used across your project.**

### Fetching Data

To fetch content, import this client and use one of its `retrieve` functions.

In this example, we [retrieve a collection](https://buttercms.com/docs/api/#retrieve-a-collection) that has three fields: a short text `name`, a number `price`, and a WYSIWYG `description`.

```
---

const response = await butterClient.content.retrieve(["shopitem"]);

interface ShopItem {
	name: string,
	price: number,
	description: string,
}

const items = response.data.data.shopitem as ShopItem[];
---
<body>
	{items.map(item => <div>
		<h2>{item.name} - ${item.price}</h2>
		<p set:html={item.description}></p>
	</div>)}
</body>
```

The interface mirrors the field types. The WYSIWYG `description` field loads as a string of HTML, and [`set:html`](/en/reference/directives-reference/#sethtml) lets you render it.

Similarly, you can [retrieve a page](https://buttercms.com/docs/api/#get-a-single-page) and display its fields:

```
---

const response = await butterClient.page.retrieve("*", "simple-page");
const pageData = response.data.data;

interface Fields {
  seo_title: string,
  headline: string,
  hero_image: string,
}

const fields = pageData.fields as Fields;
---
<html>
  <title>{fields.seo_title}</title>
  <body>
    <h1>{fields.headline}</h1>
    <img src={fields.hero_image} />
  </body>
</html>
```

## Official Resources

-   [Astro + ButterCMS Starter Project](https://buttercms.com/starters/astro-starter-project/)
-   The [full ButterCMS API documentation](https://buttercms.com/docs/api/)
-   ButterCMS's [JavaScript Guide](https://buttercms.com/docs/api-client/javascript/)

## Community Resources

-   Add yours!

## [Caisy & Astro](https://docharvest.github.io/docs/astro/guides/cms/caisy/)

Contents

astro

Caisy & Astro

Astro

Caisy & Astro

[Caisy](https://caisy.io/) is a headless CMS that exposes a GraphQL API to access content.

## Using Caisy CMS with Astro

Use `graphql-request` and Caisy's rich text renderer for Astro to fetch your CMS data and display your content on an Astro page:

```
---

const params = Astro.params;

const client = new GraphQLClient(
	`https://cloud.caisy.io/api/v3/e/${import.meta.env.CAISY_PROJECT_ID}/graphql`,
	{
		headers: {
			'x-caisy-apikey': import.meta.env.CAISY_API_KEY
		}
	}
);
const gqlResponse = await client.request(
	gql`
		query allBlogArticle($slug: String) {
			allBlogArticle(where: { slug: { eq: $slug } }) {
				edges {
					node {
						text {
							json
						}
						title
						slug
						id
					}
				}
			}
		}
	`,
	{ slug: params.slug }
);

const post = gqlResponse?.allBlogArticle?.edges?.[0]?.node;
---
<h1>{post.title}</h1>
<RichTextRenderer node={post.text.json} />
```

## Official Resources

-   Check out the Caisy + Astro example on [GitHub](https://github.com/caisy-io/caisy-example-astro) or [StackBlitz](https://stackblitz.com/github/caisy-io/caisy-example-astro?file=src%2Fpages%2Fblog%2F%5B...slug%5D.astro)
-   Query your documents in [draft mode](https://caisy.io/developer/docs/external-api/localization-and-preview#preview-mode-15) and multiple [locales](https://caisy.io/developer/docs/external-api/localization-and-preview#localization-in-a-graphql-query-8).
-   Use [pagination](https://caisy.io/developer/docs/external-api/queries-pagination) to query large numbers of documents.
-   Use [filter](https://caisy.io/developer/docs/external-api/external-filter-and-sorting) in your queries and [order](https://caisy.io/developer/docs/external-api/external-filter-and-sorting#sorting-8) the results

## [CloudCannon & Astro](https://docharvest.github.io/docs/astro/guides/cms/cloudcannon/)

Contents

astro

CloudCannon & Astro

Astro

CloudCannon & Astro

[CloudCannon](https://cloudcannon.com) is a Git-based headless content management system that provides a visual editor for your content and UI components, providing a rich, live editing experience.

:::tip If you're starting a project from scratch, you can use the [CloudCannon Astro Component Starter Template](https://astro-component-starter.cc) with 40+ prebuilt components set up for CloudCannon visual editing to cut down on setup time. :::

## Integrating with Astro

This guide will describe the process of configuring CloudCannon as a CMS for Astro using the CloudCannon Site Dashboard.

The Site Dashboard provides you with an organized view of your Astro files and the ability to edit them using:

-   A [Visual Editor](https://cloudcannon.com/documentation/articles/the-visual-editor/) for an interactive preview of your site, allowing you to edit directly on the page.
-   A [Content Editor](https://cloudcannon.com/documentation/articles/the-content-editor/) for WYSIWYG rich text editing in a minimal view.
-   A [Data Editor](https://cloudcannon.com/documentation/articles/the-data-editor/) for managing structured data files and markup.

You can also configure role-based access to a minimal [Source Editor](https://cloudcannon.com/documentation/articles/the-source-editor/), an in-browser code editor for making minor changes to the source code of your files.

## Prerequisites

1.  A CloudCannon account. If you don’t have an account, you can [sign up with CloudCannon](https://app.cloudcannon.com/register).
2.  An existing Astro project stored locally, or on one of CloudCannon's supported Git providers: GitHub, GitLab, or Bitbucket. If you do not have an existing project, you can start with CloudCannon's [Astro Component Starter](https://astro-component-starter.cc).

## Configure a new CloudCannon Site

The following steps will configure a new CloudCannon Site from your dashboard. This Site will connect to an existing Astro repository and allow you to manage and edit your content with CloudCannon's WYSIWYG text editor.

1.  In your CloudCannon Organization Home page, create a new Site.
2.  Authenticate your Git provider and select the Astro repository you want to connect to.
3.  Choose a name for your Site, then CloudCannon will create the Site and start syncing your files.
4.  Follow CloudCannon's guided tasks in your Site dashboard for completing your Site setup, including creating a CloudCannon configuration file (`cloudcannon.config.yml`).
5.  Configure how CloudCannon looks and behaves for editors by adding configuration to your CloudCannon config file. You can make edits using CloudCannon's [Configuration Mode](https://cloudcannon.com/documentation/articles/what-is-configuration-mode/), or you can add config manually yourself in a code editor.
6.  Turn off Configuration Mode to return to the editing interface for content creators. Your configuration file will be saved back to your repository with the rest of your files.

You can now explore your Site Dashboard to see your Astro site's content files and edit them with the [Content Editor](https://cloudcannon.com/documentation/articles/what-is-the-content-editor/) (e.g. `.md`, `.mdx`), [Data Editor](https://cloudcannon.com/documentation/articles/what-is-the-data-editor/) (e.g. `.yml`, `.json`), and [Visual Editor](https://cloudcannon.com/documentation/articles/what-is-the-visual-editor/) (e.g. `.astro`) as appropriate.

You may also want to take advantage of some CloudCannon features, such as [organizing your files into collections](#cloudcannon-collections-and-schemas), [creating CloudCannon schemas](#create-a-cloudcannon-schema-for-a-collection), and setting up your project for [visual editing](#configure-visual-editing).

For more detailed instructions, see [CloudCannon's Getting Started Guide](https://cloudcannon.com/documentation/guides/getting-started-with-cloudcannon/).

## CloudCannon collections and schemas

If you use [Astro's content collections](/en/guides/content-collections/), then you will be familiar with CloudCannon's concepts of collections (used for organization/navigation in your Site Dashboard) and schemas (used to define the format of new content entries).

Your CloudCannon Site Dashboard allows you to organize your Astro project's pages and content into collections: groups of related files with a similar format. This allows you to see similar types of content together for ease of editing and makes your content files easy to navigate, sort, and filter.

### Create a CloudCannon schema for a collection

To ensure that the data properties of your CloudCannon entries match the Zod validation `schema` defined in your content collection, you can create a [CloudCannon schema](https://cloudcannon.com/documentation/articles/what-is-a-schema/) (a blank template document for creating a new entry). Creating a template schema can ensure that any new documents created in CloudCannon will have the properties required by your content collection and avoid type errors in your project. Your CloudCannon schema can also include default values to start new documents, such as an author name for a single-person blog.

The following example will create a CloudCannon schema based on an Astro content collection (`blog`) for blog posts written in Markdown. This schema will be available when [creating a new entry](#creating-a-new-entry) from the CloudCannon "Posts" collection:

1.  Create a folder at `.cloudcannon/schemas/` if it does not already exist.
    
2.  Add an existing blank file in this folder to be used as a default blog post template. The name is unimportant, but the file must have the same file extension as your Astro content collection entries (e.g. `post.md`).
    
3.  Provide the necessary frontmatter fields required by your content collection's schema. You do not need to provide any values for these, but any content you do include will be automatically included when a new entry is created. These are fields that will be available in the sidebar of your Content Editor.
    
    The following example schema for a blog post has placeholders for the title, author, and date:
    
    ```
    ---
    title:
    author:
    date:
    ---
    ```
    
4.  In your CloudCannon configuration file's `collections_config` property, add the file path to your schema under the CloudCannon collection under the "Posts" collection.
    
    ```
    collections_config:
      posts:
        path: content/blog
        name: Posts
        icon: post_add
        schemas:
          default:
            path: .cloudcannon/schemas/post.md
            name: Blog Post Entry
    ```
    

## Creating a new entry

In your CloudCannon Site Dashboard, you can create new content using the "Add" button. You will be able to select an entry type from the schemas you have defined in `cloudcannon.config.yml`, depending on which collection you are currently in.

You can also upload files to CloudCannon, or create new files directly in your Astro project. When you save your Site changes, new files created in either location will be synchronized and available in both CloudCannon and your Astro project.

The following example will create a new blog post from the CloudCannon Site Dashboard "Posts" collection using the `post.md` template schema created to satisfy the `blog` Astro content collection:

1\. In the CloudCannon Site Dashboard, navigate to the collection representing the kind of content you want to add. For example, navigate to the "Posts" collection to add a new blog post.

2.  Use the "Add" button to create a new post. If you have configured CloudCannon's `post.md` schema, then you can choose the default blog post entry to create a new post.
    
3.  Fill in the necessary fields in the sidebar of your Content Editor (e.g. `title`, `author`, `date`), and post content and save your post.
    
4.  This post is saved locally in CloudCannon and should now be visible from your Site Dashboard in your "Posts" collection. You can view and edit all your individual posts from this dashboard page.
    
5.  When you are ready to commit this new post back to your Astro repository, select "Save" in the Site navigation sidebar from your Site Dashboard. This will show you all unsaved changes made to your site since your last commit back to your repository and allow you to review and select which ones to save or discard.
    
6.  Return to view your Astro project files and pull new changes from git. You will now find a new `.md` file inside the specified directory for this new post, for example:
    
    \- src/ - content/ - blog/ - \*\*my-new-post.md\*\*
7.  Navigate to that file in your code editor and verify that you can see the Markdown content you entered. For example:
    
    ```
    ---
    title: My New Post
    author: Sarah
    date: 2025-11-12
    ---
    
    This is my very first post created in CloudCannon. I am **super** excited!
    ```
    

## Rendering CloudCannon content

Use Astro's Content Collections API to [query and display your posts and collections](/en/guides/content-collections/#querying-build-time-collections), just as you would in any Astro project.

### Displaying a collection list

The following example displays a list of each post title, with a link to an individual post page.

```
---

const posts = await getCollection('blog');
---
<ul>
  {posts.map(post => (
    <li>
      <a href={`/posts/${post.id}`}>{post.data.title}</a>
    </li>
  ))}
</ul>
```

### Displaying a single entry

To display content from an individual post, you can import and use the `<Content />` component to [render your content to HTML](/en/guides/content-collections/#rendering-body-content):

```
---

const entry = await getEntry('blog', 'my-first-post');
const { Content } = await render(entry);
---

<main>
  <h1>{entry.data.title}</h1>
  <p>By: {entry.data.author}</p>
  <Content />
</main>
```

For more information on querying, filtering, displaying your collections content, and more, see the full content [collections documentation](/en/guides/content-collections/).

## Deploying CloudCannon + Astro

[CloudCannon offers free web hosting](https://cloudcannon.com/documentation/articles/what-is-web-hosting/) as part of all of its plans, which uses Cloudflare under the hood. However, you can host with almost any hosting provider that can deploy from a Git repository.

To deploy your website, visit our [deployment guides](/en/guides/deploy/) and follow the instructions for your preferred hosting provider.

## Configure Visual Editing

CloudCannon's [Visual Editor](https://cloudcannon.com/documentation/articles/the-visual-editor/) allows you to see and edit text, images, and other content in a live, interactive preview of your site. These updates can be made using editable regions, data panels, and the sidebar.

Follow [CloudCannon's guide to set up visual editing](https://cloudcannon.com/documentation/guides/set-up-visual-editing/) (also available in your Site Dashboard). This will show you how to define [editable regions](https://cloudcannon.com/documentation/guides/set-up-visual-editing/an-overview-of-editable-regions/) of your live preview by setting HTML `data-` attributes on DOM elements, or by inserting web components.

For example, the following template creates an editable `author` value that can be updated in the live preview:

```
<p>By: <editable-text data-prop="author">{author}</editable-text></p>
```

### Visual Editing with components

CloudCannon allows you to [define Component Editable Regions](https://cloudcannon.com/documentation/guides/set-up-visual-editing/visual-editing-for-components/) for live re-rendering of Astro components in the Visual Editor. This gives you the same interactive editing experience for your Astro components.

1\. Install the \[\`@cloudcannon/editable-regions\`\](https://github.com/CloudCannon/editable-regions) package.

```
<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install @cloudcannon/editable-regions
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm add @cloudcannon/editable-regions
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn add @cloudcannon/editable-regions
  ```
  </Fragment>
</PackageManagerTabs>
```

2.  Add the `editableRegions` integration to your Astro config:
    
    ```
    import { defineConfig } from 'astro/config';
    import editableRegions from "@cloudcannon/editable-regions/astro-integration";
    
    export default defineConfig({
      // ...
      integrations: [editableRegions()],
      // ...
    });
    ```
    
3.  Follow [CloudCannon's instructions to register your components](https://cloudcannon.com/documentation/guides/set-up-visual-editing/visual-editing-for-components/#register-your-components). This tells CloudCannon that those components should be bundled for client-side use in the Visual Editor.
    
4.  Add the appropriate attributes to your components for visual editing. For example, the following `CTA.astro` component properties, such as description and button color, can be updated in CloudCannon's Visual Editor:
    
    ```
    ---
    const { description, link, buttonText, buttonColor } = Astro.props;
    ---
    
    <p data-editable="text" data-prop="description">{description}</p>
    <a href={link}>
        <span data-editable="text" data-prop="buttonText" style={`background-color: ${buttonColor}`}>{buttonText}</span>
    </a>
    ```
    

## Agent Skills for CloudCannon

CloudCannon has published an [open-source set of skills for AI coding agents](https://github.com/CloudCannon/agent-skills). They handle new Astro site migrations for you: auditing your content, writing the config, adding visual editing with editable regions, and verifying the build. The skills are composable, so you can choose to run a full migration or pull in just one piece, like adding visual editing to an Astro site that's already on CloudCannon.

1.  Run `npx skills add CloudCannon/agent-skills --all` in the root of your project
    
2.  Open your project in your AI coding agent
    
3.  Ask the agent to migrate your site to CloudCannon:
    
    ```
    Migrate this site to CloudCannon using the migrating-to-cloudcannon skill. If the skill is not found, look in .agents/, otherwise do not continue.
    ```
    

## Official Resources

-   [CloudCannon: The Astro CMS](https://cloudcannon.com/astro-cms/)
-   [Astro Component Starter](https://astro-component-starter.cc/)
-   [Astro Jetstream Template](https://cloudcannon.com/templates/jetstream/?ssg=astro)
-   [Astro Sendit Template](https://cloudcannon.com/templates/sendit/?ssg=astro)
-   [Agent Skills for Astro and CloudCannon](https://github.com/CloudCannon/agent-skills)
-   Video: [Getting started with Astro and CloudCannon CMS: WYSIWYG blogging](https://www.youtube.com/watch?v=VCbZV-SCr20)
-   Video: [Using CloudCannon's configuration mode](https://www.youtube.com/watch?v=3OOyYcPD46Y)
-   Video: [Visually edit your Astro site](https://www.youtube.com/watch?v=RMbPsyJ5Gms)

## [Contentful & Astro](https://docharvest.github.io/docs/astro/guides/cms/contentful/)



## [Cosmic & Astro](https://docharvest.github.io/docs/astro/guides/cms/cosmic/)



## [Craft CMS & Astro](https://docharvest.github.io/docs/astro/guides/cms/craft-cms/)

Contents

astro

Craft CMS & Astro

Astro

Craft CMS & Astro

[Craft CMS](https://craftcms.com/) is a flexible open source CMS with an accessible authoring experience. It includes its own front end, but can also be used as a headless CMS to provide content to your Astro project.

## Official Resources

-   Check out the official Craft CMS [GraphQL API guide](https://craftcms.com/docs/5.x/development/graphql.html)
-   The official documentation for Craft's [`headlessMode` config setting](https://craftcms.com/docs/5.x/reference/config/general.html#headlessmode)

## Community Resources

-   [SSG Astro with Headless Craft CMS Content Fetched At Build Time](https://www.olets.dev/posts/ssg-astro-with-headless-craft-cms-content-fetched-at-build-time/)
-   [SSG Astro with Headless Craft CMS Content Fetched At Build Time Or Cached In Advance](https://www.olets.dev/posts/ssg-astro-with-headless-craft-cms-content-fetched-at-build-time-or-cached-in-advance/)
-   [SSR Astro With Headless Craft CMS](https://www.olets.dev/posts/ssr-astro-with-headless-craft-cms/)

## [Craft Cross CMS & Astro](https://docharvest.github.io/docs/astro/guides/cms/craft-cross-cms/)

Contents

astro

Craft Cross CMS & Astro

Astro

Craft Cross CMS & Astro

[Craft Cross CMS](https://ecosystem.plaid.co.jp/product/karte-craft/xcms) is an API-based headless CMS from the KARTE ecosystem.

## Official Resources

-   Blog: [Build an Astro Website with Craft Cross CMS](https://solution.karte.io/blog/2025/10/build-website-with-astro-using-xcms/)
-   Sample code (GitHub): [Craft Cross CMS with Astro (sample)](https://github.com/plaidev/craft-codes/tree/main/astro/cross-cms-astro-sample)

## [Crystallize & Astro](https://docharvest.github.io/docs/astro/guides/cms/crystallize/)

Contents

astro

Crystallize & Astro

Astro

Crystallize & Astro

[Crystallize](https://crystallize.com/) is a headless content management system for eCommerce that exposes a GraphQL API.

## Example

```
---
// Fetch your catalogue paths from Crystallize GraphQL API

const apiClient = createClient({
  tenantIdentifier: 'furniture'
});

const query = `
  query getCataloguePaths{
    catalogue(language: "en", path: "/shop") {
      name
      children {
        name
        path
      }
    }
  }
`
const { data: { catalogue } } = await apiClient.catalogueApi(query)
---
<BaseLayout>
  <h1>{catalogue.name}</h1>
  <nav>
    <ul>
      {catalogue.children.map(child => (
        <li><a href={child.path}>{child.name}</a></li>
      ))}
    </ul>
  </nav>
</BaseLayout>
```

## [DatoCMS & Astro](https://docharvest.github.io/docs/astro/guides/cms/datocms/)



## [Decap CMS & Astro](https://docharvest.github.io/docs/astro/guides/cms/decap-cms/)

Contents

astro

Decap CMS & Astro

Astro

Decap CMS & Astro

[Decap CMS](https://www.decapcms.org/) (formerly Netlify CMS) is an open-source, Git-based content management system.

Decap allows you to take full advantage of all of Astro's features, including image optimization and content collections.

Decap adds a route (typically `/admin`) to your project that will load a React app to allow authorized users to manage content directly from the deployed website. Decap will commit changes directly to your Astro project's source repository.

## Installing DecapCMS

There are two options for adding Decap to Astro:

1.  [Install Decap via a package manager](https://decapcms.org/docs/install-decap-cms/#installing-with-npm) with the following command:
    
    \`\`\`shell npm install decap-cms-app \`\`\` \`\`\`shell pnpm add decap-cms-app \`\`\` \`\`\`shell yarn add decap-cms-app \`\`\`
2.  Import the package into a `<script>` tag in your page `<body>`
    
    ```
    <body>
      <!-- Include the script that builds the page and powers Decap CMS -->
      <script src="https://unpkg.com/decap-cms@^3.1.2/dist/decap-cms.js"></script>
    </body>
    ```
    

## Configuration

1\. Create a static admin folder at \`public/admin/\`

2.  Add `config.yml` to `public/admin/`:
    
    \- public - admin - config.yml
3.  To add support for content collections, configure each schema in `config.yml`. The following example configures a `blog` collection, defining a `label` for each entry's frontmatter property:
    
    ```
    collections:
      - name: "blog" # Used in routes, e.g., /admin/collections/blog
        label: "Blog" # Used in the UI
        folder: "src/content/blog" # The path to the folder where the documents are stored
        create: true # Allow users to create new documents in this collection
        fields: # The fields for each document, usually in frontmatter
          - { label: "Layout", name: "layout", widget: "hidden", default: "blog" }
          - { label: "Title", name: "title", widget: "string" }
          - { label: "Publish Date", name: "date", widget: "datetime" }
          - { label: "Featured Image", name: "thumbnail", widget: "image" }
          - { label: "Rating (scale of 1-5)", name: "rating", widget: "number" }
          - { label: "Body", name: "body", widget: "markdown" }
    ```
    
4.  Add the `admin` route for your React app in `src/pages/admin.html`.
    
    \- public - admin - config.yml - src - pages - admin.html
    
    ```
    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <meta name="robots" content="noindex" />
        <link href="config.yml" type="text/yaml" rel="cms-config-url" />
        <title>Content Manager</title>
      </head>
      <body>
        <script src="https://unpkg.com/decap-cms@^3.1.2/dist/decap-cms.js"></script>
      </body>
    </html>
    ```
    
5.  To enable media uploads to a specific folder via the Decap editor, add an appropriate path:
    
    ```
    media_folder: "src/assets/images" # Location where files will be stored in the repo 
    public_folder: "src/assets/images" # The src attribute for uploaded media
    ```
    

See [the Decap CMS configuration documentation](https://decapcms.org/docs/configure-decap-cms/) for full instructions and options.

## Usage

Navigate to `yoursite.com/admin/` to use the Decap CMS editor.

## Authentication

### Decap CMS with Netlify Identity

Decap CMS was originally developed by Netlify and has first class support for [Netlify Identity](https://docs.netlify.com/security/secure-access-to-sites/identity/).

When deploying to Netlify, configure Identity for your project via the Netlify dashboard and include the [Netlify Identity Widget](https://github.com/netlify/netlify-identity-widget) on the `admin` route of your project. Optionally include the Identity Widget on the homepage of your site if you plan to invite new users via email.

### Decap CMS with External OAuth Clients

When deploying to hosting providers other than Netlify, you must create your own OAuth routes.

In Astro, this can be done with on-demand rendered routes in your project configured with [an adapter](/en/guides/on-demand-rendering/) enabled.

See [Decap's OAuth Docs](https://decapcms.org/docs/external-oauth-clients/) for a list of compatible community-maintained OAuth clients.

## Community Resources

-   Netlify Identity Template: [astro-decap-ssg-netlify](https://github.com/OliverSpeir/astro-decap-ssg-netlify-identity)
    
-   On-demand rendering OAuth Routes with Astro Template: [astro-decap-starter-ssr](https://github.com/OliverSpeir/astro-decap-starter-ssr)
    
-   Blog Post: [Author your Astro site's content with Git-based CMSs](https://aalam.vercel.app/blog/astro-and-git-cms-netlify) by Aftab Alam
    
-   Youtube Tutorial: [Create a Custom Blog with Astro & NetlifyCMS in MINUTES!](https://www.youtube.com/watch?v=3yip2wSRX_4) by Kumail Pirzada

## [Directus & Astro](https://docharvest.github.io/docs/astro/guides/cms/directus/)

Contents

astro

Directus & Astro

Astro

Directus & Astro

[Directus](https://directus.io/) is a backend-as-a-service which can be used to host data and content for your Astro project.

## Official Resources

-   [Getting Started with Directus and Astro](https://docs.directus.io/blog/getting-started-directus-astro.html).

## Community Resources

:::note\[Have a resource to share?\] If you found (or made!) a helpful video or blog post about using Directus with Astro, [add it to this list](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/cms/directus.mdx)! :::

## [Drupal & Astro](https://docharvest.github.io/docs/astro/guides/cms/drupal/)

Contents

astro

Drupal & Astro

Astro

Drupal & Astro

[Drupal](https://www.drupal.org/) is an open-source content management tool.

## Prerequisites

To get started, you will need to have the following:

1.  **An Astro project** - If you don't have an Astro project yet, our [Installation guide](/en/install-and-setup/) will get you up and running in no time.
    
2.  **A Drupal site** - If you haven't set up a Drupal site, you can follow the official guidelines [Installing Drupal](https://www.drupal.org/docs/getting-started/installing-drupal).
    

## Integrating Drupal with Astro

### Installing the JSON:API Drupal module

To be able to get content from Drupal you need to enable the [Drupal JSON:API module](https://www.drupal.org/docs/core-modules-and-themes/core-modules/jsonapi-module).

1.  Navigate to the Extend page `admin/modules` via the Manage administrative menu
2.  Locate the JSON:API module and check the box next to it
3.  Click Install to install the new module

Now you can make `GET` requests to your Drupal application through JSON:API.

### Adding the Drupal URL in `.env`

To add your Drupal URL to Astro, create a `.env` file in the root of your project (if one does not already exist) and add the following variable:

```
DRUPAL_BASE_URL="https://drupal.ddev.site/"
```

Restart the dev server to use this environment variable in your Astro project.

### Setting up Credentials

By default, the Drupal JSON:API endpoint is accessible for external data-fetching requests without requiring authentication. This allows you to fetch data for your Astro project without credentials but it does not permit users to modify your data or site settings.

However, if you wish to restrict access and require authentication, Drupal provides [several authentication methods](https://www.drupal.org/docs/contributed-modules/api-authentication) including:

-   [Basic Authentication](https://www.drupal.org/docs/contributed-modules/api-authentication/setup-basic-authentication)
-   [API Key-based authentication](https://www.drupal.org/docs/contributed-modules/api-authentication/api-key-authentication)
-   [Access Token/OAuth-based authentication](https://www.drupal.org/docs/contributed-modules/api-authentication/setup-access-token-oauth-based-authentication)
-   [JWT Token-based authentication](https://www.drupal.org/docs/contributed-modules/api-authentication/jwt-authentication)
-   [Third-Party Provider token authentication](https://www.drupal.org/docs/contributed-modules/api-authentication/rest-api-authentication-using-external-identity-provider)

You can add your credentials to your `.env` file.

```
DRUPAL_BASIC_USERNAME="editor"
DRUPAL_BASIC_PASSWORD="editor"
DRUPAL_JWT_TOKEN="abc123"
...
```

Read more about [using environment variables](/en/guides/environment-variables/) and `.env` files in Astro.

Your root directory should now include this new files:

\- \*\*.env\*\* - astro.config.mjs - package.json

### Installing dependencies

JSON:API requests and responses can often be complex and deeply nested. To simplify working with them, you can use two npm packages that streamline both the requests and the handling of responses:

-   [`JSONA`](https://www.npmjs.com/package/jsona): JSON API v1.0 specification serializer and deserializer for use on the server and in the browser.
-   [`Drupal JSON-API Params`](https://www.npmjs.com/package/drupal-jsonapi-params): This module provides a helper Class to create the required query. While doing so, it also tries to optimise the query by using the short form, whenever possible.

\`\`\`shell npm install jsona drupal-jsonapi-params \`\`\` \`\`\`shell pnpm add jsona drupal-jsonapi-params \`\`\` \`\`\`shell yarn add jsona drupal-jsonapi-params \`\`\`

## Fetching data from Drupal

Your content is fetched from a JSON:API URL.

### Drupal JSON:API URL structure

The basic URL structure is: `/jsonapi/{entity_type_id}/{bundle_id}`

The URL is always prefixed by `jsonapi`.

-   The `entity_type_id` refers to the Entity Type, such as node, block, user, etc.
-   The `bundle_id` refers to the Entity Bundles. In the case of a Node entity type, the bundle could be article.
-   In this case, to get the list of all articles, the URL will be `[DRUPAL_BASE_URL]/jsonapi/node/article`.

To retrieve an individual entity, the URL structure will be `/jsonapi/{entity_type_id}/{bundle_id}/{uuid}`, where the uuid is the UUID of the entity. For example the URL to get a specific article will be of the form `/jsonapi/node/article/2ee9f0ef-1b25-4bbe-a00f-8649c68b1f7e`.

#### Retrieving only certain fields

Retrieve only certain field by adding the Query String field to the request.

GET: `/jsonapi/{entity_type_id}/{bundle_id}?field[entity_type]=field_list`

Examples:

-   `/jsonapi/node/article?fields[node--article]=title,created`
-   `/jsonapi/node/article/2ee9f0ef-1b25-4bbe-a00f-8649c68b1f7e?fields[node--article]=title,created,body`

#### Filtering

Add a filter to your request by adding the filter Query String.

The simplest, most common filter is a key-value filter:

GET: `/jsonapi/{entity_type_id}/{bundle_id}?filter[field_name]=value&filter[field_other]=value`

Examples:

-   `/jsonapi/node/article?filter[title]=Testing JSON:API&filter[status]=1`
-   `/jsonapi/node/article/2ee9f0ef-1b25-4bbe-a00f-8649c68b1f7e?fields[node--article]=title&filter[title]=Testing JSON:API`

You can find more query options in the [JSON:API Documentation](https://www.drupal.org/docs/core-modules-and-themes/core-modules/jsonapi-module).

### Building a Drupal query

Astro components can fetch data from your Drupal site by using `drupal-jsonapi-params` package to build the query.

The following example shows a component with a query for an "article" content type that has a text field for a title and a rich text field for content:

```
---

// Get the Drupal base URL

// Generate the JSON:API Query. Get all title and body from published articles.
const params: DrupalJsonApiParams = new DrupalJsonApiParams();
params.addFields("node--article", [
        "title",
        "body",
    ])
    .addFilter("status", "1");
// Generates the query string.
const path: string = params.getQueryString();
const url: string = baseUrl + '/jsonapi/node/article?' + path;

// Get the articles
const request: Response = await fetch(url);
const json: string | TJsonApiBody = await request.json();
// Initiate Jsona.
const dataFormatter: Jsona = new Jsona();
// Deserialise the response.
const articles = dataFormatter.deserialize(json);
---
<body>
 {articles?.length ? articles.map((article: any) => (
    <section>
      <h2>{article.title}</h2>
      <article set:html={article.body.value}></article>
    </section>
 )): <div><h1>No Content found</h1></div> }
</body>
```

You can find more querying options in the [Drupal JSON:API Documentation](https://www.drupal.org/docs/core-modules-and-themes/core-modules/jsonapi-module/jsonapi)

## Making a blog with Astro and Drupal

With the setup above, you are now able to create a blog that uses Drupal as the CMS.

### Prerequisites

1.  **An Astro project** with [`JSONA`](https://www.npmjs.com/package/jsona) and [`Drupal JSON-API Params`](https://www.npmjs.com/package/drupal-jsonapi-params) installed.
    
2.  **A Drupal site with at least one entry** - For this tutorial we recommend starting with a new Drupal site with Standard installation.
    
    In the **Content** section of your Drupal site, create a new entry by clicking the **Add** button. Then, choose Article and fill in the fields:
    
    -   **Title:** `My first article for Astro!`
    -   **Alias:** `/articles/first-article-for astro`
    -   **Description:** `This is my first Astro article! Let's see what it will look like!`
    
    Click **Save** to create your first Article. Feel free to add as many articles as you want.
    

### Displaying a list of articles

1.  Create `src/types.ts` if it does not already exist and add two new interfaces called `DrupalNode` and `Path` with the following code. These interfaces will match the fields of your article content type in Drupal and the Path fields. You will use it to type your article entries response.
    
    ```
    
    export interface Path {
        alias: string
        pid: number
        langcode: string
    }
    
    export interface DrupalNode extends Record<string, any> {
        id: string
        type: string
        langcode: string
        status: boolean
        drupal_internal__nid: number
        drupal_internal__vid: number
        changed: string
        created: string
        title: string
        default_langcode: boolean
        sticky: boolean
        path: Path
    }
    ```
    
    Your src directory should now include the new file:
    
    \- .env - astro.config.mjs - package.json - src/ - \*\*types.ts\*\*
2.  Create a new file called `drupal.ts` under `src/api` and add the following code:
    
    ```
    import {Jsona} from "jsona";
    import {DrupalJsonApiParams} from "drupal-jsonapi-params";
    import type {DrupalNode} from "../types.ts";
    import type {TJsonApiBody} from "jsona/lib/JsonaTypes";
    
    // Get the Drupal Base Url.
    export const baseUrl: string = import.meta.env.DRUPAL_BASE_URL;
    ```
    
    This will import the required libraries such as `Jsona` to deserialize the response, `DrupalJsonApiParams` to format the request url and the Node and Jsona types. It will also get the `baseUrl` from the `.env` file.
    
    Your src/api directory should now include the new file:
    
    \- .env - astro.config.mjs - package.json - src/ - api/ - \*\*drupal.ts\*\* - types.ts
3.  In that same file, create the `fetchUrl` function to make the fetch request and deserialize the response.
    
    ```
    import {Jsona} from "jsona";
    import {DrupalJsonApiParams} from "drupal-jsonapi-params";
    import type {DrupalNode} from "../types.ts";
    import type {TJsonApiBody} from "jsona/lib/JsonaTypes";
    
    // Get the Drupal Base Url.
    export const baseUrl: string = import.meta.env.DRUPAL_BASE_URL;
    
    /**
     * Fetch url from Drupal.
     *
     * @param url
     *
     * @return Promise<TJsonaModel | TJsonaModel[]> as Promise<any>
     */
    export const fetchUrl = async (url: string): Promise<any> => {
        const request: Response = await fetch(url);
        const json: string | TJsonApiBody = await request.json();
        const dataFormatter: Jsona = new Jsona();
        return dataFormatter.deserialize(json);
    }
    ```
    
4.  Create the `getArticles()` function to get all published articles.
    
    ```
    import {Jsona} from "jsona";
    import {DrupalJsonApiParams} from "drupal-jsonapi-params";
    import type {DrupalNode} from "../types.ts";
    import type {TJsonApiBody} from "jsona/lib/JsonaTypes";
    
    // Get the Drupal Base Url.
    export const baseUrl: string = import.meta.env.DRUPAL_BASE_URL;
    
    /**
     * Fetch url from Drupal.
     *
     * @param url
     *
     * @return Promise<TJsonaModel | TJsonaModel[]> as Promise<any>
     */
    export const fetchUrl = async (url: string): Promise<any> => {
        const request: Response = await fetch(url);
        const json: string | TJsonApiBody = await request.json();
        const dataFormatter: Jsona = new Jsona();
        return dataFormatter.deserialize(json);
    }
    
    /**
     * Get all published articles.
     *
     * @return Promise<DrupalNode[]>
     */
    export const getArticles = async (): Promise<DrupalNode[]> => {
        const params: DrupalJsonApiParams = new DrupalJsonApiParams();
        params
            .addFields("node--article", [
                "title",
                "path",
                "body",
                "created",
            ])
            .addFilter("status", "1");
        const path: string = params.getQueryString();
        return await fetchUrl(baseUrl + '/jsonapi/node/article?' + path);
    }
    ```
    
    Now you can use the function `getArticles()` in an `.astro` component to get all published articles with data for each title, body, path and creation date.
    
5.  Go to the Astro page where you will fetch data from Drupal. The following example creates an articles landing page at `src/pages/articles/index.astro`.
    
    Import the necessary dependencies and fetch all the entries from Drupal with a content type of `article` using `getArticles()` while passing the `DrupalNode` interface to type your response.
    
    ```
    ---
    import {Jsona} from "jsona";
    import {DrupalJsonApiParams} from "drupal-jsonapi-params";
    import type {TJsonApiBody} from "jsona/lib/JsonaTypes";
    
    import type { DrupalNode } from "../../types";
    import {getArticles} from "../../api/drupal";
    
    // Get all published articles.
    const articles = await getArticles();
    ---
    ```
    
    This fetch call using getArticles() will return a typed array of entries that can be used in your page template.
    
    Your `src/pages/` directory should now include the new file, if you used the same page file:
    
    \- .env - astro.config.mjs - package.json - src/ - api/ - drupal.ts - pages/ - articles/ - \*\*index.astro\*\* - types.ts
6.  Add content to your page, such as a title. Use `articles.map()` to show your Drupal entries as line items in a list.
    
    ```
    ---
    import {Jsona} from "jsona";
    import {DrupalJsonApiParams} from "drupal-jsonapi-params";
    import type {TJsonApiBody} from "jsona/lib/JsonaTypes";
    
    import type { DrupalNode } from "../types";
    import {getArticles} from "../api/drupal";
    
    // Get all published articles.
    const articles = await getArticles();
    ---
    <html lang="en">
      <head>
        <title>My news site</title>
      </head>
      <body>
        <h1>My news site</h1>
        <ul>
          {articles.map((article: DrupalNode) => (
            <li>
              <a href={article.path.alias.replace("internal:en/", "")}>
                <h2>{article.title}</h2>
                <p>Published on {article.created}</p>
              </a>
            </li>
          ))}
        </ul>
      </body>
    </html>
    ```
    

### Generating individual blog posts

Use the same method to fetch your data from Drupal as above, but this time, on a page that will create a unique page route for each article.

This example uses Astro's default static mode, and creates [a dynamic routing page file](/en/guides/routing/#dynamic-routes) with the `getStaticPaths()` function. This function will be called at build time to generate the list of paths that become pages.

1.  Create a new file `src/pages/articles/[path].astro` and import the `DrupalNode` interface and `getArticle()` from `src/api/drupal.ts`. Fetch your data inside a `getStaticPaths()` function to create routes for your blog.
    
    ```
    ---
    import {Jsona} from "jsona";
    import {DrupalJsonApiParams} from "drupal-jsonapi-params";
    import type {TJsonApiBody} from "jsona/lib/JsonaTypes";
    
    import type { DrupalNode } from "../../types";
    import {getArticles} from "../../api/drupal";
    
    // Get all published articles.
    export async function getStaticPaths() {
      const articles = await getArticles();
    }
    ---
    ```
    
    Your src/pages/articles directory should now include the new file:
    
    \- .env - astro.config.mjs - package.json - src/ - api/ - drupal.ts - pages/ - articles/ - index.astro - \*\*\[path\].astro\*\* - types.ts
2.  In the same file, map each Drupal entry to an object with a `params` and `props` property. The `params` property will be used to generate the URL of the page and the `props` values will be passed to the page component as props.
    
    ```
    ---
    import {Jsona} from "jsona";
    import {DrupalJsonApiParams} from "drupal-jsonapi-params";
    import type {TJsonApiBody} from "jsona/lib/JsonaTypes";
    
    import type { DrupalNode } from "../../types";
    import {getArticles} from "../../api/drupal";
    
    // Get all published articles.
    export async function getStaticPaths() {
        const articles = await getArticles();
        return articles.map((article: DrupalNode) => {
            return {
                params: {
                    // Choose `path` to match the `[path]` routing value
                    path: article.path.alias.split('/')[2]
                },
                props: {
                    title: article.title,
                    body: article.body,
                    date: new Date(article.created).toLocaleDateString('en-EN', {
                        day: "numeric",
                        month: "long",
                        year: "numeric"
                    })
                }
            }
        });
    }
    ---
    ```
    
    The property inside `params` must match the name of the dynamic route. Since the filename is `[path].astro`, the property name passed to `params` must be `path`.
    
    In our example, the `props` object passes three properties to the page:
    
    -   `title`: a string, representing the title of your post.
    -   `body`: a string, representing the content of your entry.
    -   `date`: a timestamp, based on your file creation date.
3.  Use the page `props` to display your blog post.
    
    ```
    ---
    import {Jsona} from "jsona";
    import {DrupalJsonApiParams} from "drupal-jsonapi-params";
    import type {TJsonApiBody} from "jsona/lib/JsonaTypes";
    
    import type { DrupalNode } from "../../types";
    import {getArticles} from "../../api/drupal";
    
    // Get all published articles.
    export async function getStaticPaths() {
        const articles = await getArticles();
        return articles.map((article: DrupalNode) => {
            return {
                params: {
                    path: article.path.alias.split('/')[2]
                },
                props: {
                    title: article.title,
                    body: article.body,
                    date: new Date(article.created).toLocaleDateString('en-EN', {
                        day: "numeric",
                        month: "long",
                        year: "numeric"
                    })
                }
            }
        });
    }
    
    const {title, date, body} = Astro.props;
    ---
    <html lang="en">
      <head>
        <title>{title}</title>
      </head>
      <body>
        <h1>{title}</h1>
        <time>{date}</time>
        <article set:html={body.value} />
      </body>
    </html>
    ```
    
4.  Navigate to your dev server preview and click on one of your posts to make sure your dynamic route is working.
    

### Publishing your site

To deploy your website, visit our [deployment guides](/en/guides/deploy/) and follow the instructions for your preferred hosting provider.

## Community Resources

:::note\[Have a resource to share?\] If you found (or made!) a helpful video or blog post about using Drupal with Astro, [add it to this list](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/cms/drupal.mdx)! :::

## [Flotiq & Astro](https://docharvest.github.io/docs/astro/guides/cms/flotiq/)

Contents

astro

Flotiq & Astro

Astro

Flotiq & Astro

[Flotiq](https://flotiq.com?utm_campaign=flotiq_at_astro_headless_cms&utm_medium=referral&utm_source=astro) is a headless CMS designed for various frontends, such as static sites, mobile, and web applications. Developers and content creators manage and deliver content through REST and GraphQL-based APIs.

## Integrating with Astro

This guide will use the Flotiq headless CMS API with an Astro project to display content on your website.

### Prerequisites

To get started, you will need:

1.  **An Astro project** - You can create a new project using the `npm create astro@latest` command.
2.  **A Flotiq account** - If you don't have an account, [sign up for free](https://editor.flotiq.com/register?utm_campaign=flotiq_at_astro_headless_cms&utm_medium=referral&utm_source=astro).
3.  **Flotiq read-only API key** - Find out [how to obtain your key](https://flotiq.com/docs/API/?utm_campaign=flotiq_at_astro_headless_cms&utm_medium=referral&utm_source=astro).

### Setting up the Environment variables

Add the read-only API key from your Flotiq account to the `.env` file in the root of your Astro project:

```
FLOTIQ_API_KEY=__YOUR_FLOTIQ_API_KEY__
```

### Defining a Content Type in Flotiq

First, you need to define an example [Content Type Definition](https://flotiq.com/docs/panel/content-types/?utm_campaign=flotiq_at_astro_headless_cms&utm_medium=referral&utm_source=astro) in Flotiq to store data.

Log in to your Flotiq account and create a custom Content Type Definition with the following example `Blog Post` configuration:

-   **Label**: Blog Post
-   **API Name**: blogpost
-   **Fields**:
    -   **Title**: text, required
    -   **Slug**: text, required
    -   **Content**: rich text, required

Then, create one or more example [Content Objects](https://flotiq.com/docs/panel/content-objects/?utm_campaign=flotiq_at_astro_headless_cms&utm_medium=referral&utm_source=astro) using this `Blog Post` type.

### Installing the Flotiq TypeScript SDK

To connect your project with Flotiq, install the [Flotiq SDK](https://github.com/flotiq/flotiq-api-ts) using the package manager of your choice:

\`\`\`sh npm install flotiq-api-ts \`\`\` \`\`\`sh pnpm add flotiq-api-ts \`\`\` \`\`\`sh yarn add flotiq-api-ts \`\`\`

Next, configure the SDK using your credentials. Create a new file named `flotiq.ts` inside the `src/lib` directory of your project:

This configuration can now be used throughout your project.

### Fetching and Displaying Data from Flotiq

1.  Fetch the `Blog Post` data on an Astro page using your content's custom API `BlogpostAPI`:
    
    ```
    ---
    import { flotiq } from "../lib/flotiq";
    
    const posts = await flotiq.BlogpostAPI.list();
    ---
    ```
    
2.  Display the content in your Astro template. You will have access to the `title`, `slug`, and `content` of your posts as well as other `internal` post data:
    
    ```
    ---
    import { flotiq } from "../lib/flotiq";
    
    const posts = await flotiq.BlogpostAPI.list();
    ---
    <html lang="en">
        <head>
            <title>Astro</title>
        </head>
        <body>
            {posts.data?.map((post) => (
                <section>
                    <a href={`/posts/${post.slug}`}>
                      <h2>{post.title}</h2>
            </a>
                    <div>{post.internal?.createdAt}</div>
                    <div set:html={post.content}/>
                </section>
            ))}
        </body>
    </html>
    ```
    
3.  Start the dev server and visit your page preview at `http://localhost:4321` to see the list of your blog posts. Each post will link to a page that does not yet exist. These will be created in the next step.
    

### Generating Individual Pages

Astro supports both prerendering all your pages ahead of time, or creating routes on demand when they are requested. Follow the instructions for either [static site generation](#static-site-generation) or [on-demand rendering](#on-demand-rendering) to build the page routes for your blog posts.

#### Static Site Generation

In static site generation (SSG) mode, use the `getStaticPaths()` method to fetch all possible blog post paths from Flotiq.

1.  Create a new file `[slug].astro` in the `/src/pages/posts/` directory. Fetch all blog posts and return them within the `getStaticPaths()` method:
    
    ```
    ---
    import type { Blogpost } from "flotiq-api-ts";
    import { flotiq } from "../../lib/flotiq";
    
    export async function getStaticPaths() {
      const posts = await flotiq.BlogpostAPI.list();
      return posts.data?.map((post) => ({
        params: { slug: post.slug },
        props: post
      })) || []
    }
    ---
    ```
    
2.  Add the templating to display an individual post:
    
    ```
    ---
    import type { Blogpost } from "flotiq-api-ts";
    import { flotiq } from "../../lib/flotiq";
    
    export async function getStaticPaths() {
      const posts = await flotiq.BlogpostAPI.list();
      return posts.data?.map((post) => ({
        params: { slug: post.slug },
        props: post
      })) || []
    }
    const post: Blogpost = Astro.props;
    ---
    <html lang="en">
      <title>{post.title}</title>
      <body>
        <h1>{post.title}</h1>
        <div set:html={post.content}/>
      </body>
    </html>
    ```
    
3.  Visit `http://localhost:4321` and click on a linked blog post in your list. You will now be able to navigate to the individual post's page.
    

#### On-demand Rendering

If you are using [SSR](/en/guides/on-demand-rendering/) mode, you will need to fetch a single post based on its `slug`.

1.  Create a new file `[slug].astro` in the `/src/pages/posts/` directory. Fetch the post by its `slug` field, including logic to display a 404 page when the route is not found:
    
    ```
    ---
    import type { Blogpost } from "flotiq-api-ts";
    import { flotiq } from "../../lib/flotiq";
    
    const { slug } = Astro.params;
    let post: Blogpost;
    
    const blogpostList = await flotiq.BlogpostAPI.list({
      filters: JSON.stringify({
        slug: {
          type: 'equals',
          filter: slug,
        }
      }),
      limit: 1
    });
    
    if (blogpostList.data?.[0]) {
      post = blogpostList.data[0]
    } else {
      return Astro.redirect('/404');
    }
    ---
    ```
    
2.  Add the templating to display an individual post:
    
    ```
    ---
    import type { Blogpost } from "flotiq-api-ts";
    import { flotiq } from "../../lib/flotiq";
    
    const { slug } = Astro.params;
    let post: Blogpost;
    
    const blogpostList = await flotiq.BlogpostAPI.list({
      filters: JSON.stringify({
        slug: {
          type: 'equals',
          filter: slug,
        }
      }),
      limit: 1
    });
    
    if (blogpostList.data?.[0]) {
      post = blogpostList.data[0]
    } else {
      return Astro.redirect('/404');
    }
    ---
    <html lang="en">
      <title>{post.title}</title>
      <body>
        <h1>{post.title}</h1>
        <div set:html={post.content}/>
      </body>
    </html>
    ```
    
3.  Visit `http://localhost:4321` and click on a linked blog post in your list. You will now be able to navigate to the individual post's page.
    

### Refreshing the SDK After Content Type Changes

When using the Flotiq TypeScript SDK (`flotiq-api-ts`), all your data types are accurately mapped into the Astro project.

If you make changes to the structure of your content types (such as adding a new field or modifying an existing one), you’ll need to refresh the SDK to ensure that your project reflects the latest model updates.

To do this, run the rebuild command for your package manager:

\`\`\`sh npm rebuild flotiq-api-ts \`\`\` \`\`\`sh pnpm rebuild flotiq-api-ts \`\`\` \`\`\`sh yarn rebuild flotiq-api-ts // for yarn v1 (Classic): // yarn add flotiq-api-ts \`\`\`

This will update the SDK, aligning object types, fields, and API methods with your current data model.

## Publishing Your Site

To deploy your website, visit Astro's [deployment guides](/en/guides/deploy/) and follow the instructions for your preferred hosting provider.

### Redeploy on Flotiq Changes

To update your published site, configure Flotiq to send a webhook your hosting provider to trigger a rebuild whenever your content changes.

In Flotiq, you can define which Content Type and events it should trigger on, and configure it accordingly. See the [Flotiq Webhooks documentation](https://flotiq.com/docs/panel/webhooks/async-co-webhook/?utm_campaign=flotiq_at_astro_headless_cms&utm_medium=referral&utm_source=astro) for more details.

## Official Resources

-   [Flotiq documentation](https://flotiq.com/docs/?utm_campaign=flotiq_at_astro_headless_cms&utm_medium=referral&utm_source=astro)

## Community resources

-   [Flotiq x Astro](https://maciekpalmowski.dev/blog/flotiq-cms-astro/) by Maciek Palmowski

## [Front Matter CMS & Astro](https://docharvest.github.io/docs/astro/guides/cms/frontmatter-cms/)

Contents

astro

Front Matter CMS & Astro

Astro

Front Matter CMS & Astro

[Front Matter CMS](https://frontmatter.codes/) brings the CMS to your editor, allowing you to create and preview content in real-time in Visual Studio Code.

## Integration with Astro

In this section, we'll walk through how to add Front Matter CMS to your Astro project.

### Prerequisites

-   Visual Studio Code
-   Use the [Astro Blog template](https://github.com/withastro/astro/tree/main/examples/blog) to provide the base configuration and sample content to start with Front Matter CMS.

### Install the Front Matter CMS extension

You can get the extension from the [Visual Studio Code Marketplace - Front Matter](https://marketplace.visualstudio.com/items?itemName=eliostruyf.vscode-front-matter) or by clicking on the following link: [open Front Matter CMS extension in VS Code](vscode:extension/eliostruyf.vscode-front-matter)

### Project initialization

Once Front Matter CMS is installed, you will get a new icon in the Activity Bar. It will open the **Front Matter CMS** panel in the primary sidebar when you click on it. Follow the next steps to initialize your project:

-   Click on the **Initialize project** button in the Front Matter panel
    
-   The welcome screen will open, and you can start initializing the project
    
-   Click on the first step to **Initialize project**
    
-   As Astro is one of the supported frameworks, you can select it from the list
    
-   Register your content folders, in this case, the `src/content/blog` folder.
    
    :::note Folder registration is required to let Front Matter CMS know where it can find and create your content. You can have multiple types of folders like pages, blog, docs, and many more. :::
    
-   You will be asked to enter the name of the folder. By default, it takes the folder name.
    
    :::note The name gets used during the creation process of new content. For example, having multiple folder registrations allows you to choose the type of content you want to create. :::
    
-   Click on **Show the dashboard** to open the content dashboard
    
    :::tip Once Front Matter CMS is initialized, you can open the dashboard as follows:
    
    -   Using the keyboard binding: alt + d (Windows & Linux) or options + d (macOS)
    -   Open the command palette and search for `Front Matter: Open dashboard`
    -   Click on the **Front Matter** icon on the panel's title bar or files. :::

### Project configuration

Once the project is initialized, you will get a `frontmatter.json` configuration file and a `.frontmatter` folder in the root of your project.

\- .frontmatter/ - database/ - mediaDb.json - src/ - astro.config.mjs - \*\*frontmatter.json\*\* - package.json

#### Content-type configuration

Content-types are the way Front Matter CMS manages your content. Each content-type contains a set of fields, which can be defined per type of content you want to use for your website.

The fields correspond to the front matter of your page content.

You can configure the content-types in the `frontmatter.json` file.

-   Open the `frontmatter.json` file
-   Replace the `frontMatter.taxonomy.contentTypes` array with the following content-types configuration:

```
"frontMatter.taxonomy.contentTypes": [
  {
    "name": "default",
    "pageBundle": false,
    "previewPath": "'blog'",
    "filePrefix": null,
    "fields": [
      {
        "title": "Title",
        "name": "title",
        "type": "string",
        "single": true
      },
      {
        "title": "Description",
        "name": "description",
        "type": "string"
      },
      {
        "title": "Publishing date",
        "name": "pubDate",
        "type": "datetime",
        "default": "{{now}}",
        "isPublishDate": true
      },
      {
        "title": "Content preview",
        "name": "heroImage",
        "type": "image",
        "isPreviewImage": true
      }
    ]
  }
]
```

:::note This configuration ensures that the Front Matter content-type matches the content collection schema from the Astro blog template. :::

:::tip You can find more information on content-types and the supported fields in the [content creation docs section](https://frontmatter.codes/docs/content-creation) from Front Matter CMS. :::

### Preview your articles in the editor

From the **Front Matter CMS** panel, click on the **Start server** button. This action starts the Astro local dev server. Once running, you can open the content dashboard, select one of the articles and click on the **Open preview** button to open the article in the editor.

### Create new articles

Open the **Front Matter CMS Dashboard**; you can do this as follows:

-   Open the Front Matter CMS' content dashboard
-   Click on the **Create content** button
-   Front Matter will ask you for the title of the article. Fill it in and press enter
-   Your new article will be created and opened in the editor. You can start writing your article.

### Using Markdoc with Front Matter CMS

To use Markdoc with Front Matter CMS, you must configure this in the `frontMatter.content.supportedFileTypes`. This setting lets the CMS know which types of files it can progress.

You can configure the setting as follows:

```
"frontMatter.content.supportedFileTypes": [ "md", "markdown", "mdx", "mdoc" ]
```

To allow your content to be created as Markdoc, specify the `fileType` property on the content-type.

```
"frontMatter.taxonomy.contentTypes": [
  {
    "name": "default",
    "pageBundle": false,
    "previewPath": "'blog'",
    "filePrefix": null,
    "fileType": "mdoc",
    "fields": [
      {
        "title": "Title",
        "name": "title",
        "type": "string",
        "single": true
      },
      {
        "title": "Description",
        "name": "description",
        "type": "string"
      },
      {
        "title": "Publishing date",
        "name": "pubDate",
        "type": "datetime",
        "default": "{{now}}",
        "isPublishDate": true
      },
      {
        "title": "Content preview",
        "name": "heroImage",
        "type": "image",
        "isPreviewImage": true
      }
    ]
  }
]
```

## Official Resources

-   [Front Matter CMS](https://frontmatter.codes/)
-   [Front Matter CMS - Documentation](https://frontmatter.codes/docs/)
-   [Getting started with Astro and Front Matter CMS](https://youtu.be/xb6pZiier_E)

## [Ghost & Astro](https://docharvest.github.io/docs/astro/guides/cms/ghost/)

Contents

astro

Ghost & Astro

Astro

Ghost & Astro

}

```
:::tip
Read more about [using environment variables](/en/guides/environment-variables/) and `.env` files in Astro.
:::

Your root directory should now include these new files:

<FileTree title="Project Structure">
- src/
  - **env.d.ts**
- **.env**
- astro.config.mjs
- package.json
</FileTree>

### Installing dependencies

To connect with Ghost, install the official content API wrapper [`@tryghost/content-api`](https://www.npmjs.com/package/@tryghost/content-api) using the command below for your preferred package manager, and optionally, a helpful package containing type definitions if you are using TypeScript:

<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install @tryghost/content-api
  npm install --save @types/tryghost__content-api
```

\`\`\`shell pnpm add @tryghost/content-api pnpm add --save-dev @types/tryghost\_\_content-api \`\`\` \`\`\`shell yarn add @tryghost/content-api yarn add --dev @types/tryghost\_\_content-api \`\`\`

## Making a blog with Astro and Ghost

With the setup above, you are now able to create a blog that uses Ghost as the CMS.

### Prerequisites

1.  A Ghost blog
2.  An Astro project integrated with the [Ghost content API](https://www.npmjs.com/package/@tryghost/content-api) - See [integrating with Astro](/en/guides/cms/ghost/#integrating-with-astro) for more details on how to set up an Astro project with Ghost.

This example will create an index page that lists posts with links to dynamically-generated individual post pages.

### Fetching Data

You can fetch your site's data with the Ghost content API package.

First, create a `ghost.ts` file under a `lib` directory.

\- src/ - lib/ - \*\*ghost.ts\*\* - pages/ - index.astro - astro.config.mjs - package.json

Initialize an API instance with the Ghost API using the API key from the Ghost dashboard's Integrations page.

```

// Create API instance with site credentials
```

### Displaying a list of posts

The page `src/pages/index.astro` will display a list of posts, each with a description and link to its own page.

\- src/ - lib/ - ghost.ts - pages/ - \*\*index.astro\*\* - astro.config.mjs - package.json

Import `ghostClient()` in the Astro frontmatter to use the `posts.browse()` method to access blog posts from Ghost. Set `limit: all` to retrieve all posts.

```
---

const posts = await ghostClient.posts
    .browse({
        limit: 'all',
    })
    .catch((err) => {
        console.error(err);
    });
---
```

Fetching via the content API returns an array of objects containing the [properties for each post](https://ghost.org/docs/content-api/#posts) such as:

-   `title` - the title of the post
-   `html` - the HTML rendering of the content of the post
-   `feature_image` - the source URL of the featured image of the post
-   `slug` - the slug of the post

Use the `posts` array returned from the fetch to display a list of blog posts on the page.

```
---

const posts = await ghostClient.posts
    .browse({
        limit: 'all',
    })
    .catch((err) => {
        console.error(err);
    });
---

<html lang="en">
    <head>
        <title>Astro + Ghost 👻</title>
    </head>
    <body>

        {
            posts.map((post) => (
                <a href={`/post/${post.slug}`}>
                    <h1> {post.title} </h1>
                </a>
            ))
        }
    </body>
</html>
```

### Generating pages

The page `src/pages/post/[slug].astro` [dynamically generates a page](/en/guides/routing/#dynamic-routes) for each post.

\- src/ - lib/ - ghost.ts - pages/ - index.astro - post/ - \*\*\[slug\].astro\*\* - astro.config.mjs - package.json

Import `ghostClient()` to access blog posts using `posts.browse()` and return a post as props to each of your dynamic routes.

```
---

        });

    return posts.map((post) => {
        return {
            params: {
                slug: post.slug,
            },
            props: {
                post: post,
            },
        };
    });
}

const { post } = Astro.props;
---
```

Create the template for each page using the properties of each `post` object.

```
---

        });
    return posts.map((post) => {
        return {
            params: {
                slug: post.slug,
            },
            props: {
                post: post,
            },
        };
    });
}
const { post } = Astro.props;
---
<!DOCTYPE html>
<html lang="en">
    <head>
        <title>{post.title}</title>
    </head>
    <body>
        <img src={post.feature_image} alt={post.title} />

        <h1>{post.title}</h1>
        <p>{post.reading_time} min read</p>

        <Fragment set:html={post.html} />
    </body>
</html>
```

:::note `<Fragment />` is a built-in Astro component which allows you to avoid an unnecessary wrapper element. This can be especially useful when fetching HTML from a CMS (e.g. Ghost or [WordPress](/en/guides/cms/wordpress/)). :::

### Publishing your site

To deploy your site visit our [deployment guide](/en/guides/deploy/) and follow the instructions for your preferred hosting provider.

## Community Resources

:::note\[Have a resource to share?\] If you found (or made!) a helpful video or blog post about using Ghost with Astro, [add it to this list](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/cms/ghost.mdx)! :::

## [GitCMS & Astro](https://docharvest.github.io/docs/astro/guides/cms/gitcms/)

Contents

astro

GitCMS & Astro

Astro

GitCMS & Astro

[GitCMS](https://gitcms.blog) turns GitHub into a Git-based headless CMS, offering a Notion-like markdown editing experience right in your browser.

## Official Resources

-   [Introducing GitCMS](https://gitcms.blog/posts/introducing-gitcms/)
-   [How to Configure GitCMS for an Astro Site](https://gitcms.blog/posts/how-to-configure-gitcms/)
-   [Install GitCMS Chrome Extension](https://gitcms.blog/extension)

## [Hashnode & Astro](https://docharvest.github.io/docs/astro/guides/cms/hashnode/)

Contents

astro

Hashnode & Astro

Astro

Hashnode & Astro

[Hashnode](https://hashnode.com/) is a hosted CMS that allows you to create a blog or publication.

## Integrating with Astro

The [Hashnode Public API](https://apidocs.hashnode.com/) is a GraphQL API that allows you to interact with Hashnode. This guide uses [`graphql-request`](https://github.com/jasonkuhrt/graphql-request), a minimal GraphQL client that works well with Astro, to bring your Hashnode data into your Astro project.

### Prerequisites

To get started you will need to have the following:

1.  **An Astro project** - If you don't have an Astro project yet, our [Installation guide](/en/install-and-setup/) will get you up and running in no time.
    
2.  **A Hashnode site** - You can create free personal site by visiting [Hashnode](https://hashnode.com/).
    

### Installing dependencies

Install the `graphql-request` package using the package manager of your choice:

\`\`\`shell npm install graphql-request \`\`\` \`\`\`shell pnpm add graphql-request \`\`\` \`\`\`shell yarn add graphql-request \`\`\`

## Making a blog with Astro and Hashnode

This guide uses [`graphql-request`](https://github.com/jasonkuhrt/graphql-request), a minimal GraphQL client that works well with Astro, to bring your Hashnode data into your Astro project.

### Prerequisites

1.  A Hashnode Blog
2.  An Astro project integrated with the [graphql-request](https://github.com/jasonkuhrt/graphql-request) package installed.

This example will create an index page that lists posts with links to dynamically-generated individual post pages.

### Fetching Data

1\. To fetch your site's data with the \`graphql-request\` package, make a \`src/lib\` directory and create two new files \`client.ts\` & \`schema.ts\`:

```
<FileTree title="Project Structure">
- src/
  - lib/
    - **client.ts**
    - **schema.ts**
  - pages/
    - index.astro
- astro.config.mjs
- package.json
</FileTree>
```

2.  Initialize an API instance with the GraphQLClient using the URL from your Hashnode Website.
    
    ```
    
    import { gql, GraphQLClient } from "graphql-request";
    import type { AllPostsData, PostData } from "./schema";
    
    export const getClient = () => { 
      return new GraphQLClient("https://gql.hashnode.com") 
    }
    
    const myHashnodeURL = "astroplayground.hashnode.dev";
    
    export const getAllPosts = async () => {
      const client = getClient();
    
      const allPosts = await client.request<AllPostsData>(
        gql`
          query allPosts {
            publication(host: "${myHashnodeURL}") {
              id
              title
              posts(first: 20) {
                pageInfo{
                  hasNextPage
                  endCursor
                }
                edges {
                  node {
                    id
                    author{
                      name
                      profilePicture
                    }
                    title
                    subtitle
                    brief
                    slug
                    coverImage {
                      url
                    }
                    tags {
                      name
                      slug
                    }
                    publishedAt
                    readTimeInMinutes
                  }
                }
              }
            }
          }
        `
      );
    
      return allPosts;
    };
    
    
    export const getPost = async (slug: string) => {
      const client = getClient();
    
      const data = await client.request<PostData>(
        gql`
          query postDetails($slug: String!) {
            publication(host: "${myHashnodeURL}") {
              id
              post(slug: $slug) {
                id
                author{
                  name
                  profilePicture
                }
                publishedAt
                title
                subtitle
                readTimeInMinutes
                content{
                  html
                }
                tags {
                  name
                  slug
                }
                coverImage {
                  url
                }
              }
            }
          }
        `,
        { slug: slug }
      );
          
      return data.publication.post;
    };
    ```
    
3.  Configure `schema.ts` to define the shape of the data returned from the Hashnode API.
    
    ```
    
    import { z } from "astro/zod";
    
    export const PostSchema = z.object({
        id: z.string(),
        author: z.object({
            name: z.string(),
            profilePicture: z.string(),
            }),
        publishedAt: z.string(),
        title: z.string(),
        subtitle: z.string(),
        brief: z.string(),
        slug: z.string(),
        readTimeInMinutes: z.number(),
        content: z.object({
            html: z.string(),
        }),
        tags: z.array(z.object({
            name: z.string(),
            slug: z.string(),
        })),
        coverImage: z.object({
            url: z.string(),
        }),
    })
    
    export const AllPostsDataSchema = z.object({
        id: z.string(),
        publication: z.object({
            title: z.string(),
            posts: z.object({
                pageInfo: z.object({
                    hasNextPage: z.boolean(),
                    endCursor: z.string(),
                }),
                edges: z.array(z.object({
                    node: PostSchema,
                })),
            }),
        }),
    })
    
    export const PostDataSchema = z.object({
        id: z.string(),
        publication: z.object({
            title: z.string(),
            post: PostSchema,
        }),
    })
    
    export type Post = z.infer<typeof PostSchema>
    export type AllPostsData = z.infer<typeof AllPostsDataSchema>
    export type PostData = z.infer<typeof PostDataSchema>
    ```
    

### Displaying a list of posts

Fetching via `getAllPosts()` returns an array of objects containing the properties for each post such as:

-   `title` - the title of the post
-   `brief` - the HTML rendering of the content of the post
-   `coverImage.url` - the source URL of the featured image of the post
-   `slug` - the slug of the post

Use the `posts` array returned from the fetch to display a list of blog posts on the page.

```
---

const data = await getAllPosts();
const allPosts = data.publication.posts.edges;

---

<html lang="en">
    <head>
        <title>Astro + Hashnode</title>
    </head>
    <body>

        {
            allPosts.map((post) => (
                <div>
                    <h2>{post.node.title}</h2>
                    <p>{post.node.brief}</p>
                    <img src={post.node.coverImage.url} alt={post.node.title} />
                    <a href={`/post/${post.node.slug}`}>Read more</a>
                </div>
            ))
        }
    </body>
</html>
```

### Generating pages

1\. Create the page \`src/pages/post/\[slug\].astro\` to \[dynamically generate a page\](/en/guides/routing/#dynamic-routes) for each post.

```
<FileTree title="Project Structure">
- src/
  - lib/
    - client.ts
    - schema.ts
  - pages/
    - index.astro
    - post/
      - **[slug].astro**
- astro.config.mjs
- package.json
</FileTree>
```

2.  Import and use `getAllPosts()` and `getPost()` to fetch the data from Hashnode and generate individual page routes for each post.
    
    ```
    ---
    import { getAllPosts, getPost } from '../../lib/client';
    
    
    export async function getStaticPaths() {
      const data = await getAllPosts();
      const allPosts = data.publication.posts.edges;
      return allPosts.map((post) => {
        return {
          params: { slug: post.node.slug },
        }
      })
    }
    const { slug } = Astro.params;
    const post = await getPost(slug);
    
    ---
    ```
    
3.  Create the template for each page using the properties of each `post` object. The example below shows the post title and reading time, then the full post content:
    
    ```
    ---
    import { getAllPosts, getPost } from '../../lib/client';
    
    
    export async function getStaticPaths() {
      const data = await getAllPosts();
      const allPosts = data.publication.posts.edges;
      return allPosts.map((post) => {
        return {
          params: { slug: post.node.slug },
        }
      })
    }
    const { slug } = Astro.params;
    const post = await getPost(slug);
    
    ---
    <!DOCTYPE html>
    <html lang="en">
        <head>
            <title>{post.title}</title>
        </head>
        <body>
            <img src={post.coverImage.url} alt={post.title} />
    
            <h1>{post.title}</h1>
            <p>{post.readTimeInMinutes} min read</p>
    
            <Fragment set:html={post.content.html} />
        </body>
    </html>
    ```
    
    :::note `<Fragment />` is a built-in Astro component which allows you to avoid an unnecessary wrapper element. This can be especially useful when fetching HTML from a CMS (e.g. Hashnode or [WordPress](/en/guides/cms/wordpress/)). :::
    

### Publishing your site

To deploy your site visit our [deployment guide](/en/guides/deploy/) and follow the instructions for your preferred hosting provider.

## Community Resources

-   [`astro-hashnode`](https://github.com/matthiesenxyz/astro-hashnode) on GitHub

## [Hygraph & Astro](https://docharvest.github.io/docs/astro/guides/cms/hygraph/)



## [JekyllPad & Astro](https://docharvest.github.io/docs/astro/guides/cms/jekyllpad/)

Contents

astro

JekyllPad & Astro

Astro

JekyllPad & Astro

[JekyllPad](https://www.jekyllpad.com) is a lightweight, browser-based CMS that connects directly to your GitHub repository.

It provides a modern WYSIWYG + Markdown editor, commits changes straight to your repo, and runs 100% client‑side, so you can manage content for Astro without setting up servers or learning Git.

It is a client-side application that runs completely in user's browser. This means data, oauth and security tokens, all stays in user's browser. No installation required, works with any mobile or desktop browsers.

## Official Resources

-   [JekyllPad CMS for Astro](https://www.jekyllpad.com/features/astro-headless-cms)

## [Keystatic & Astro](https://docharvest.github.io/docs/astro/guides/cms/keystatic/)

Contents

astro

Keystatic & Astro

Astro

Keystatic & Astro

[Keystatic](https://keystatic.com/) is an open source, headless content-management system that allows you to structure your content and sync it with GitHub.

:::tip If you're starting a **new Astro + Keystatic project from scratch**, you can use the [Keystatic CLI](https://keystatic.com/docs/quick-start#keystatic-cli) to generate a new project in seconds:

\`\`\`shell npm create @keystatic@latest \`\`\` \`\`\`shell pnpm create @keystatic@latest \`\`\` \`\`\`shell yarn create @keystatic \`\`\`

Select the Astro template, and you'll be ready to [deploy](#deploying-keystatic--astro)! :::

## Prerequisites

-   An existing Astro project [with an adapter configured](/en/guides/on-demand-rendering/).

:::note If you intend to sync Keystatic's data with GitHub, you will also need **a GitHub account with `write` permissions** on the repository for this project. :::

## Installing dependencies

Add both the Markdoc (for content entries) and the React (for the Keystatic Admin UI Dashboard) integrations to your Astro project, using the `astro add` command for your package manager.

\`\`\`shell npx astro add react markdoc \`\`\` \`\`\`shell pnpm astro add react markdoc \`\`\` \`\`\`shell yarn astro add react markdoc \`\`\`

You will also need two Keystatic packages:

\`\`\`shell npm install @keystatic/core @keystatic/astro \`\`\` \`\`\`shell pnpm add @keystatic/core @keystatic/astro \`\`\` \`\`\`shell yarn add @keystatic/core @keystatic/astro \`\`\`

## Adding the Astro integration

Add the Astro integration from `@keystatic/astro` in your Astro config file:

```
// astro.config.mjs
```

:::note\[Already using content collections?\] If you are already using [content collections](/en/guides/content-collections/) in your Astro project, then update the schema above to exactly match the collection(s) defined in your existing schema. :::

Keystatic is now configured to manage your content based on your schema.

## Running Keystatic locally

To launch your Keystatic Admin UI dashboard, start Astro's dev server:

````
```bash
npm run dev
```
````

Visit `http://127.0.0.1:4321/keystatic` in the browser to see the Keystatic Admin UI running.

## Creating a new post

1\. In the Keystatic Admin UI dashboard, click on the “Posts” collection.

2.  Use the button to create a new post. Add the title "My First Post" and some content, then save the post.
    
3.  This post should now be visible from your "Posts" collection. You can view and edit your individual posts from this dashboard page.
    
4.  Return to view your Astro project files. You will now find a new `.mdoc` file inside the `src/content/posts` directory for this new post:
    
    \- src/ - content/ - posts/ - \*\*my-first-post.mdoc\*\*
5.  Navigate to that file in your code editor and verify that you can see the Markdown content you entered. For example:
    
    ```
    ---
    title: My First Post
    ---
    
    This is my very first post. I am **super** excited!
    ```
    

## Rendering Keystatic content

[Query and display your posts and collections](/en/guides/content-collections/#querying-build-time-collections), just as you would in any Astro project.

### Displaying a collection list

The following example displays a list of each post title, with a link to an individual post page.

```
---
import { getCollection } from 'astro:content'

const posts = await getCollection('posts')
---
<ul>
  {posts.map(post => (
    <li>
      <a href={`/posts/${post.id}`}>{post.data.title}</a>
    </li>
  ))}
</ul>
```

### Displaying a single entry

To display content from an individual post, you can import and use the `<Content />` component to [render your content to HTML](/en/guides/content-collections/#rendering-body-content):

```
---
import { getEntry } from 'astro:content'

const post = await getEntry('posts', 'my-first-post')
const { Content } = await post.render()
---

<main>
  <h1>{post.data.title}</h1>
  <Content />
</main>
```

For more information on querying, filtering, displaying your collections content and more, see the full content [collections documentation](/en/guides/content-collections/).

## Deploying Keystatic + Astro

To deploy your website, visit our [deployment guides](/en/guides/deploy/) and follow the instructions for your preferred hosting provider.

You'll also probably want to [connect Keystatic to GitHub](https://keystatic.com/docs/connect-to-github) so you can manage content on the deployed instance of the project.

## Official Resources

-   Check out [the official Keystatic guide](https://keystatic.com/docs/installation-astro)
-   [Keystatic starter template](https://github.com/Thinkmill/keystatic/tree/main/templates/astro)

## [KeystoneJS & Astro](https://docharvest.github.io/docs/astro/guides/cms/keystonejs/)

Contents

astro

KeystoneJS & Astro

Astro

KeystoneJS & Astro

[KeystoneJS](https://keystonejs.com/) is an open source, headless content-management system that allows you to describe the structure of your schema.

## [Kontent.ai & Astro](https://docharvest.github.io/docs/astro/guides/cms/kontent-ai/)



## [microCMS & Astro](https://docharvest.github.io/docs/astro/guides/cms/microcms/)

Contents

astro

microCMS & Astro

Astro

microCMS & Astro

[microCMS](https://microcms.io/en) is an API-based headless CMS that lets you define content using schemas, and manage it using the dashboard.

## Official Resources

-   Check out [the official microCMS document](https://document.microcms.io/tutorial/astro/astro-top)
-   Blog: [Build a blog with microCMS](https://blog.microcms.io/astro-microcms-introduction/)

## [Optimizely CMS & Astro](https://docharvest.github.io/docs/astro/guides/cms/optimizely/)

Contents

astro

Optimizely CMS & Astro

Astro

Optimizely CMS & Astro

[Optimizely CMS](https://www.optimizely.com/products/content-management/) is available as a headless CMS powered by GraphQL that provides a visual editor.

## Official Resources

-   The official [Optimizely SaaS CMS documentation](https://docs.developers.optimizely.com/content-management-system/v1.0.0-CMS-SaaS/docs/overview-saas)

## Community Resources

-   [Build a headless blog with Astro and Optimizely SaaS CMS](https://world.optimizely.com/blogs/jacob-pretorius/dates/2024/5/build-a-headless-blog-with-astro-and-optimizely-saas-cms/)
-   [Sample Astro + Optimizely Graph starter project templates](https://github.com/jacobpretorius/Opti.SaaS.Astro.Demo/)

## [Pages CMS & Astro](https://docharvest.github.io/docs/astro/guides/cms/pages-cms/)

Contents

astro

Pages CMS & Astro

Astro

Pages CMS & Astro

[Pages CMS](https://pagescms.org/) is an open source, Git-based content management system for GitHub repositories that can be used to manage content in Astro projects.

## Official Resources

-   [Pages CMS documentation](https://pagescms.org/docs/)
-   [Pages CMS Astro blog template](https://github.com/pages-cms/astro-blog-template)

## [Payload CMS & Astro](https://docharvest.github.io/docs/astro/guides/cms/payload/)

Contents

astro

Payload CMS & Astro

Astro

Payload CMS & Astro

[PayloadCMS](https://payloadcms.com/) is a headless open-source content management system that can be used to provide content for your Astro project.

## Integrating with Astro

### Prerequisites

1.  **An Astro project** - If you don't have an Astro project yet, our [Installation guide](/en/install-and-setup/) will get you up and running in no time.
2.  **A MongoDB database** - PayloadCMS will ask you for a MongoDB connection string when creating a new project. You can set one up locally or use [MongoDBAtlas](https://www.mongodb.com/) to host a database on the web for free.
3.  **A PayloadCMS REST API** - Create a [PayloadCMS](https://payloadcms.com/docs/getting-started/installation) project and connect it to your MongoDB database during the setup.

:::note\[Choosing a template\] During the PayloadCMS installation, you will be asked if you want to use a template.

Choosing any of the available templates at this step (such as 'blog') automatically generates additional collections for you to use. Otherwise, you will need to manually create your PayloadCMS collections. :::

### Configuring Astro for your PayloadCMS collection

Your Payload project template will contain a file called Posts.ts in `src/collections/`. If you did not choose a template during installation that created a content collection for you, you can create a new Payload CMS Collection by adding this configuration file manually. The example below shows this file for a collection called `posts` that requires `title`, `content`, and `slug` fields:

```

const Posts: CollectionConfig = {
  slug: "posts",
  admin: {
    useAsTitle: "title",
  },
  access: {
    read: () => true,
  },

  fields: [
    {
      name: "title",
      type: "text",
      required: true,
    },
    {
      name: "content",
      type: "text",
      required: true,
    },
    {
      name: "slug",
      type: "text",
      required: true,
    },
  ],
};
```

1\. Import and add both \`Users\` (available in all PayloadCMS projects) and any other collections (e.g. \`Posts\`) to the available collections in the \`payload.config.ts\` file. \`\`\`ts title="src/payload.config.ts" ins={4, 5, 12} import { buildConfig } from "payload/config"; import path from "path";

````
import Users from "./collections/Users";
import Posts from "./collections/Posts";

export default buildConfig({
  serverURL: "http://localhost:4321",
  admin: {
    user: Users.slug,
  },
  collections: [Users, Posts],
  typescript: {
    outputFile: path.resolve(__dirname, "payload-types.ts"),
  },
  graphQL: {
    schemaOutputFile: path.resolve(__dirname, "generated-schema.graphql"),
  },
});
```

This will make a new collection called "Posts" appear in your PayloadCMS Dashboard next to the "Users" collection. 
````

2.  Enter the "Posts" collection and create a new post. After saving it, you will notice the API URL appear in the bottom right corner.
    
3.  With the dev server running, open `http://localhost:4321/api/posts` in your browser. You should see a JSON file containing the post you have created as an object.
    
    ```
    {
      "docs":[
          {
            "id":"64098b16483b0f06a7e20ed4",
            "title":"Astro & PayloadCMS Title 🚀",
            "content":"Astro & PayloadCMS Content",
            "slug":"astro-payloadcms-slug",
            "createdAt":"2023-03-09T07:30:30.837Z",
            "updatedAt":"2023-03-09T07:30:30.837Z"
          }
      ],
      "totalDocs":1,
      "limit":10,
      "totalPages":1,
      "page":1,
      "pagingCounter":1,
      "hasPrevPage":false,
      "hasNextPage":false,
      "prevPage":null,
      "nextPage":null
    }
    ```
    

:::tip By default, both Astro and PayloadCMS will use port 4321. You might want to change the PayloadCMS port in the `src/server.ts` file. Don't forget to update the `serverURL` in `src/payload.config.ts` as well. :::

### Fetching Data

Fetch your PayloadCMS data through your site's unique REST API URL and the route for your content. (By default, PayloadCMS will mount all routes through `/api`.) Then, you can render your data properties using Astro's `set:html=""` directive.

Together with your post, PayloadCMS will return some top-level metadata. The actual documents are nested within the `docs` array.

For example, to display a list of post titles and their content:

```
---

const res = await fetch("http://localhost:5000/api/posts") // http://localhost:4321/api/posts by default
const posts = await res.json()
---

<HomeLayout title='Astro Blog'>
	{
    posts.docs.map((post) => (
        <h2 set:html={post.title} />
        <p set:html={post.content} />
    ))
	}
</HomeLayout>
```

## Building a blog with PayloadCMS and Astro

Create a blog index page `src/pages/index.astro` to list each of your posts with a link to its own page.

Fetching via the API returns an array of objects (posts) that include, among others, the following properties:

-   `title`
-   `content`
-   `slug`

```
---

const res = await fetch("http://localhost:5000/api/posts") // http://localhost:4321/api/posts by default
const posts = await res.json()
---

<HomeLayout title='Astro Blog'>
	<h1>Astro + PayloadCMS 🚀</h1>
	<h2>Blog posts list:</h2>
	<ul>
		{
			posts.docs.map((post) =>(
				<li>
					<a href={`posts/${post.slug}`} set:html={post.title} />
				</li>
			))
		}
	</ul>
</HomeLayout>
```

### Using the PayloadCMS API to generate pages

Create a page `src/pages/posts/[slug].astro` to [dynamically generate a page](/en/guides/routing/#dynamic-routes) for each post.

```
---

    });
} 
---
<PostLayout title={title}>
    <article>
        <h1 set:html={title} />
        <p set:html={content} />
    </article>
</PostLayout>
```

### Publishing your site

To deploy your site visit our [deployment guide](/en/guides/deploy/) and follow the instructions for your preferred hosting provider.

## Community Resources

-   Check out the [official Astro Payload CMS integration](https://github.com/payloadcms/payload/tree/main/examples/astro).
-   Try this [Payload CMS & Astro Template](https://github.com/Lambdo-Labs/payloadcms-astro-template).
-   Check out [Astroad](https://github.com/mooxl/astroad) for easy development and VPS deployment with Docker.

## [Prepr CMS & Astro](https://docharvest.github.io/docs/astro/guides/cms/preprcms/)



## [Prismic & Astro](https://docharvest.github.io/docs/astro/guides/cms/prismic/)

Contents

astro

Prismic & Astro

Astro

Prismic & Astro

[Prismic](https://prismic.io/) is a headless content management system.

## Community Resources

-   [Building with Astro & Prismic - w/ Nate Moore](https://www.youtube.com/watch?v=qFUfuDSLdxM) (livestream) and the [repo from the show](https://github.com/natemoo-re/miles-of-code).

## [Sanity & Astro](https://docharvest.github.io/docs/astro/guides/cms/sanity/)

Contents

astro

Sanity & Astro

Astro

Sanity & Astro

[Sanity](https://www.sanity.io) is a headless content management system that focuses on [structured content](https://www.sanity.io/structured-content-platform).

## Official Resources

-   [Official Sanity integration for Astro](https://www.sanity.io/plugins/sanity-astro)
    
-   [Build your blog with Astro and Sanity](https://www.sanity.io/guides/sanity-astro-blog)
    
-   [A minimal Astro site with a Sanity Studio](https://www.sanity.io/templates/astro-sanity-clean)

## [Sitecore Experience Manager & Astro](https://docharvest.github.io/docs/astro/guides/cms/sitecore/)



## [Sitepins & Astro](https://docharvest.github.io/docs/astro/guides/cms/sitepins/)

Contents

astro

Sitepins & Astro

Astro

Sitepins & Astro

[Sitepins](https://sitepins.com) is a Git-based, headless CMS for websites built with modern frameworks like Astro. It offers a clean WYSIWYG editor, a version-controlled content workflow, and seamless integration with Astro and other SSGs.

## Getting started

1.  [Create a Sitepins account](https://app.sitepins.com/register).
    
2.  Connect your GitHub repository that contains your Astro project.
    
3.  Configure your content, media and config folders and start editing in the visual editor.
    

Once connected, Sitepins will sync your content from the selected folder and provide a visual interface to manage and publish content with full Git version control.

## Official Resources

-   [Sitepins Website](https://sitepins.com)
-   [Documentation](https://docs.sitepins.com)
-   [Live Demo](https://demo.sitepins.com)

## [Spinal & Astro](https://docharvest.github.io/docs/astro/guides/cms/spinal/)



## [Headless Statamic & Astro](https://docharvest.github.io/docs/astro/guides/cms/statamic/)

Contents

astro

Headless Statamic & Astro

Astro

Headless Statamic & Astro

[Statamic](https://statamic.com/) is a modern, flat-file CMS. It allows developers to easily create dynamic websites and applications while offering content editors an intuitive and user-friendly interface for managing content.

## Integrating with Astro

Statamic comes with a built-in [REST API](https://statamic.dev/rest-api) and [GraphQL API](https://statamic.dev/graphql) to connect your data to Astro.

### Prerequisites

To get started, you will need to have the following:

1.  REST API and GraphQL API are only available in a pro version of Statamic. You can try the Pro version free on your [local machine](https://statamic.dev/tips/how-to-enable-statamic-pro#trial-mode).
2.  **An Astro project** - If you still need an Astro project, our [Installation guide](/en/install-and-setup/) will get you up and running quickly.
3.  **A Statamic site** - If you need a Statamic website, [this guide](https://statamic.dev/quick-start-guide) will help you get started. Remember to [enable REST API](https://statamic.dev/rest-api#enable-the-api) or [GraphQL API](https://statamic.dev/graphql#enable-graphql) by adding `STATAMIC_API_ENABLED=true` or `STATAMIC_GRAPHQL_ENABLED=true` in the `.env` file and enable required resources in the API configuration file.

:::caution All the examples assume that your website has a collection called `posts`, that has a blueprint called `post`, and this blueprint has a title field (fieldtype text) and content (fieldtype markdown). :::

### Fetching Data

:::caution If you are using Statamic and Astro on your local machine remember to use `127.0.0.1` instead of `localhost` when fetching the API.

When requesting from the Astro server `localhost` doesn't resolve correctly like it does in the browser, and any fetch to either API will fail. :::

#### REST API

Fetch your Statamic data from your site's REST API URL. By default, it's `https://[YOUR-SITE]/api/`. Then, you can render your data properties using Astro's `set:html={}` directive.

For example, to display a list of titles and their content from a selected [collection](https://statamic.dev/collections):

```
---
const res = await fetch("https://[YOUR-SITE]/api/collections/posts/entries?sort=-date")
const posts = await res.json()
---
<h1>Astro + Statamic 🚀</h1>
{
  posts.map((post) => (
      <h2 set:html={post.title} />
      <p set:html={post.content} />
  ))
}
```

#### GraphQL

Fetch your Statamic data with your site's GraphQL API URL. By default, it's `https://[YOUR-SITE]/graphql/`. Then, you can render your data properties using Astro's `set:html={}` directive.

For example, to display a list of titles and their content from a selected [collection](https://statamic.dev/collections):

```
---
const graphqlQuery = {
  query: `
    query Entries($page: Int, $locale: String) {
      entries(
        collection: "posts"
        sort: "date asc"
        limit: 20
        page: $page
        filter: { locale: $locale }
      ) {
        current_page
        has_more_pages
        data {
          title
          ... on Entry_Posts_Post {
              content
            }
        }
      }
    }
  `,
  variables: {
    page: page,
    locale: locale,
  },
};

const res = await fetch("https://[YOUR-SITE]/graphql", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(graphqlQuery),
})

const { data } = await res.json();
const entries = data?.entries;
---
<h1>Astro + Statamic 🚀</h1>
{
  entries.data.map((post) => (
      <h2 set:html={post.title} />
      <p set:html={post.content} />
  ))
}
```

### Publishing your site

To deploy your Astro site visit our [deployment guides](/en/guides/deploy/) and follow the instructions for your preferred hosting provider.

## Community Resources

-   [How to build a static site using Statamic as headless CMS](https://buddy.works/guides/statamic-rest-api)
-   [Implementing Astro live previews in headless Statamic](https://maciekpalmowski.dev/implementing-live-previews-in-headless-statamic-when-using-astro/)

## [Storyblok & Astro](https://docharvest.github.io/docs/astro/guides/cms/storyblok/)



## [Strapi & Astro](https://docharvest.github.io/docs/astro/guides/cms/strapi/)



## [StudioCMS & Astro](https://docharvest.github.io/docs/astro/guides/cms/studiocms/)

Contents

astro

StudioCMS & Astro

Astro

StudioCMS & Astro

[StudioCMS](https://studiocms.dev/) is a headless CMS for Astro, built with Astro, that provides a user-friendly and configurable dashboard for content management as well as a custom rendering system to display your Astro components.

## Official resources

-   [StudioCMS documentation](https://docs.studiocms.dev/)
-   [StudioCMS GitHub repository](https://github.com/withstudiocms/studiocms)
-   [StudioCMS Discord community](https://chat.studiocms.dev)

## [TinaCMS & Astro](https://docharvest.github.io/docs/astro/guides/cms/tina-cms/)



## [Umbraco & Astro](https://docharvest.github.io/docs/astro/guides/cms/umbraco/)

Contents

astro

Umbraco & Astro

Astro

Umbraco & Astro

[Umbraco CMS](https://umbraco.com/) is an open-source ASP.NET Core CMS. By default, Umbraco uses Razor pages for its front-end, but can be used as a headless CMS.

## Integrating with Astro

In this section you will use Umbraco's native [Content Delivery API](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api) to provide content to your Astro project.

### Prerequisites

To get started, you will need to have the following:

1.  **An Astro project** - If you don’t have an Astro project yet, our [Installation guide](/en/install-and-setup/) will get you up and running in no time.
2.  **An Umbraco (v12+) project** - If you don’t have an Umbraco project yet, please see this [Installation guide](https://docs.umbraco.com/umbraco-cms/fundamentals/setup/install/).

### Setting up the Content Delivery API

To enable the Content Delivery API, update your Umbraco project's `appsettings.json` file:

```
{
  "Umbraco": {
    "CMS": {
      "DeliveryApi": {
        "Enabled": true,
        "PublicAccess": true
      }
    }
  }
}
```

You can configure additional options as needed such as public access, API keys, allowed content types, membership authorisation, and more. See the [Umbraco Content Delivery API documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api) for more information.

### Fetching Data

Use a `fetch()` call to the Content Delivery API to access your content and make it available to your Astro components.

The following example displays a list of fetched articles, including properties such as the article date and content.

```
---
const res = await fetch('http://localhost/umbraco/delivery/api/v2/content?filter=contentType:article');
const articles = await res.json();
---
<h1>Astro + Umbraco 🚀</h1>
{
  articles.items.map((article) => (
      <h1>{article.name}</h1>
      <p>{article.properties.articleDate}</p>
      <div set:html={article.properties.content?.markup}></div>
  ))
}
```

Read more about [data fetching in Astro](/en/guides/data-fetching/).

## Building a blog with Umbraco and Astro

### Prerequisites

-   **An Astro project** - If you don’t have an Astro project yet, our [Installation guide](/en/install-and-setup/) will get you up and running in no time.
    
-   **An Umbraco project (v12+)** with the Content Delivery API enabled - Follow this [Installation guide](https://docs.umbraco.com/umbraco-cms/fundamentals/setup/install/) to create a new project.
    

### Creating blog posts in Umbraco

From the [Umbraco backoffice](https://docs.umbraco.com/umbraco-cms/fundamentals/backoffice), create a Document Type for a simple blog article called 'Article'.

1\. Configure your 'Article' Document Type with the following properties:

```
	- Title (DataType: Textstring)
	- Article Date (DataType: Date Picker)
	- Content (DataType: Richtext Editor)
```

2.  Toggle "Allow as root" to `true` on the 'Article' document type.
    
3.  From the "Content" section in the Umbraco backoffice, [create and publish your first blog post](https://docs.umbraco.com/umbraco-cms/fundamentals/data/defining-content). Repeat the process as many times as you like.
    

For more information, watch a [video guide on creating Document Types](https://www.youtube.com/watch?v=otRuIkN80qM).

### Displaying a list of blog posts in Astro

Create a `src/layouts/` folder, then add a new file `Layout.astro` with the following code:

```
---
---
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>My Blog with Astro and Umbraco</title>
</head>
<body>
    <main>
        <slot />
    </main>
</body>
</html>
```

Your project should now contain the following files:

\- src/ - \*\*layouts/\*\* - \*\*Layout.astro\*\* - pages/ - index.astro

To create a list of blog posts, first `fetch` to call the Content Delivery API `content` endpoint and filter by contentType of 'article'. The article objects will include the properties and content set in the CMS. You can then loop through the articles and display a each title with a link to its article.

Replace the default contents of `index.astro` with the following code:

```
---

const res = await fetch('http://localhost/umbraco/delivery/api/v2/content?filter=contentType:article');
const articles = await res.json();
---
<Layout>
	<h2>Blog Articles</h2>
	{
        articles.items.map((article: any) => (
            <div>
                <h3>{article.properties.title}</h3>
                <p>{article.properties.articleDate}</p>
                <a href={article.route.path}>Read more</a>
            </div>
        ))
    }
</Layout>
```

### Generating individual blog posts

Create the file `[...slug].astro` at the root of the `/pages/` directory. This file will be used to [generate the individual blog pages dynamically](/en/guides/routing/#dynamic-routes).

Note that the `params` property, which generates the URL path of the page, contains `article.route.path` from the API fetch. Similarly, the `props` property must include the entire `article` itself so that you can access all the information in your CMS entry.

Add the following code to `[...slug].astro` which will create your individual blog post pages:

```
---

    let articles = await data.json();
    
    return articles.items.map((article: any) => ({
        params: { slug: article.route.path },
        props: { article: article },
    }));
}

const { article } = Astro.props;
---

<Layout>
  <h1>{article.properties.title}</h1>
  <p>{article.properties.articleDate}</p>
  <div set:html={article.properties.content?.markup}></div>
</Layout>
```

Your project should now contain the following files:

\- src/ - layouts/ - Layout.astro - pages/ - index.astro - \*\*\[...slug\].astro\*\*

With the dev server running, you should now be able to view your Umbraco-created content in your browser preview of your Astro project. Congratulations! 🚀

## Publishing your site

To deploy your site visit our [deployment guides](/en/guides/deploy/) and follow the instructions for your preferred hosting provider.

## Local dev, HTTPS and self-signed SSL certificates

If you are using the Umbraco HTTPS endpoint locally, any `fetch` queries will result in `fetch failed` with code `DEPTH_ZERO_SELF_SIGNED_CERT`. This is because Node (upon which Astro is built) won't accept self-signed certificates by default. To avoid this, use the Umbraco HTTP endpoint for local dev.

Alternatively, you can set `NODE_TLS_REJECT_UNAUTHORIZED=0` in an `env.development` file and update `astro.config.js` as shown:

```
NODE_TLS_REJECT_UNAUTHORIZED=0
```

```

const { NODE_TLS_REJECT_UNAUTHORIZED } = loadEnv(process.env.NODE_ENV, process.cwd(), "");
process.env.NODE_TLS_REJECT_UNAUTHORIZED = NODE_TLS_REJECT_UNAUTHORIZED;
// https://astro.build/config
```

This method is described in more detail in this [blog post showing how to configure your project for self-signed certificates](https://kjac.dev/posts/jamstack-for-free-with-azure-and-cloudflare/), with an [accompanying repo](https://github.com/kjac/UmbracoAzureCloudflare).

## Official Documentation

-   [Content Delivery API - Umbraco Documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api)

## Community Resources

-   [Astro-nomically Performant Websites using the Content Delivery API - Louis Richardson](https://24days.in/umbraco-cms/2023/sustainable-performant/astronomically-performant/)
-   [Generating a TypeScript OpenAPI client from Umbraco's Content Delivery API - Rick Butterfield](https://rickbutterfield.dev/blog/typescript-openapi-umbraco-content-delivery/)
-   [Jamstack For Free With Azure And CloudFlare - Kenn Jacobsen](https://kjac.dev/posts/jamstack-for-free-with-azure-and-cloudflare/)
-   [Quick n' dirty blog with Astro and Umbraco - Kenn Jacobsen](https://kjac.dev/posts/quick-n-dirty-blog-with-astro-and-umbraco/)
-   [Talk: Bake, Don't Fry - Astro & The Content Delivery API - Adam Prendergast](https://www.youtube.com/watch?v=zNxqI25dtx4)

## [Vault CMS & Astro](https://docharvest.github.io/docs/astro/guides/cms/vault-cms/)

Contents

astro

Vault CMS & Astro

Astro

Vault CMS & Astro

[Vault CMS](https://vaultcms.org) is a headless CMS for Astro powered by Obsidian and Git. Write in Markdown with live preview inside a preconfigured Obsidian vault, then deploy to your Astro site.

## Official Resources

-   [Vault CMS Documentation](https://docs.vaultcms.org/)
-   [Vault CMS Source Code](https://github.com/davidvkimball/vault-cms)

## [Headless WordPress & Astro](https://docharvest.github.io/docs/astro/guides/cms/wordpress/)

Contents

astro

Headless WordPress & Astro

Astro

Headless WordPress & Astro

[WordPress](https://wordpress.org/) is a content management system that includes its own frontend, but can also be used as a headless CMS to provide content to your Astro project.

## Integrating with Astro

WordPress comes with a built-in [WordPress REST API](https://developer.wordpress.org/rest-api/) to connect your WordPress data to Astro. You can optionally install [WPGraphQL](https://wordpress.org/plugins/wp-graphql/) or [Gato GraphQL](https://wordpress.org/plugins/gatographql/) on your site to use GraphQL.

### Prerequisites

To get started, you will need to have the following:

1.  **An Astro project** - If you don't have an Astro project yet, our [Installation guide](/en/install-and-setup/) will get you up and running in no time.
2.  **A WordPress site** - Your site's REST API is `[YOUR_SITE]/wp-json/wp/v2/` and is available by default with any WordPress site. It is also possible to [set up WordPress on a local environment](https://wordpress.org/support/article/installing-wordpress-on-your-own-computer/).

### Setting up Credentials

Your WordPress REST API is available to external requests for data fetching without authentication by default. This does not allow users to modify your data or site settings and allows you to use your data in your Astro project without any credentials.

You may choose to [require authentication](https://developer.wordpress.org/rest-api/frequently-asked-questions/#require-authentication-for-all-requests) if necessary.

### Fetching Data

Fetch your WordPress data through your site's unique REST API URL and the route for your content. (For a blog, this will commonly be `posts`.) Then, you can render your data properties using Astro's `set:html={}` directive.

For example, to display a list of post titles and their content:

```
---
const res = await fetch("https://[YOUR-SITE]/wp-json/wp/v2/posts");
const posts = await res.json();
---
<h1>Astro + WordPress 🚀</h1>
{
  posts.map((post) => (
      <h2 set:html={post.title.rendered} />
      <p set:html={post.content.rendered} />
  ))
}
```

The WordPress REST API includes [global parameters](https://developer.wordpress.org/rest-api/using-the-rest-api/global-parameters/) such as `_fields` and `_embed`.

A large quantity of data is available to you via this API, so you may wish to only fetch certain fields. You can restrict your response by adding the [`_fields`](https://developer.wordpress.org/rest-api/using-the-rest-api/global-parameters/#_fields) parameter to the API URL, for example: `[YOUR-SITE]/wp/v2/posts?_fields=author,id,excerpt,title,link`

The API can also return content related to your post, such as a link to the parent post, or to comments on the post. You can add the [`_embed`](https://developer.wordpress.org/rest-api/using-the-rest-api/global-parameters/#_embed) parameter to the API URL (e.g. `[YOUR-SITE]/wp/v2/posts?_embed`) to indicate to the server that the response should include these embedded resources.

## Building a blog with WordPress and Astro

This example fetches data from the public WordPress API of [https://norian.studio/dinosaurs/](https://norian.studio/dinosaurs/). This WordPress site stores information about individual dinosaurs under the `dinos` route, just as a blog would store individual blog posts under the `posts` route.

This example shows how to reproduce this site structure in Astro: an index page that lists dinosaurs with links to dynamically-generated individual dinosaur pages.

:::note To use [Custom Post Types (CPT)](https://learn.wordpress.org/lesson-plan/custom-post-types/) in your WordPress API (not just `post` and `page`), you will have to [configure them in your WordPress dashboard](https://stackoverflow.com/questions/48536646/how-can-i-get-data-from-custom-post-type-using-wp-rest-api) or [add REST API Support For Custom Content Types](https://developer.wordpress.org/rest-api/extending-the-rest-api/adding-rest-api-support-for-custom-content-types/) in WordPress.

This example fetches data from a WordPress site whose content types have already been configured and exposed to the REST API. :::

### Displaying a list of WordPress posts

The page `src/pages/index.astro` lists each dinosaur, with a description and link to its own page.

\- src/ - pages/ - \*\*index.astro\*\* - dinos/ - \[slug\].astro - astro.config.mjs - package.json

Fetching via the API returns an object that includes the properties:

-   `title.rendered` - Contains the HTML rendering of the title of the post.
-   `content.rendered` - Contains the HTML rendering of the content of the post.
-   `slug` - Contains the slug of the post. (This provides the link to the dynamically-generated individual dinosaur pages.)

```
---

let res = await fetch("https://norian.studio/wp-json/wp/v2/dinos");
let posts = await res.json();
---
<Layout title="Dinos!">
  <section>
    <h1>List of Dinosaurs</h1>
    {
      posts.map((post) => (
        <article>
          <h2>
            <a href={`/dinos/${post.slug}/`} set:html={post.title.rendered} />
          </h2>
          <Fragment set:html={post.content.rendered} />
        </article>
      ))
    }
  </section>
</Layout>
```

### Using the WordPress API to generate pages

The page `src/pages/dinos/[slug].astro` [dynamically generates a page](/en/guides/routing/#dynamic-routes) for each dinosaur.

```
---

const { slug } = Astro.params;

let res = await fetch(`https://norian.studio/wp-json/wp/v2/dinos?slug=${slug}`);
let [post] = await res.json();

// The getStaticPaths() is required for static Astro sites.
// If using SSR, you will not need this function.

  let posts = await data.json();

  return posts.map((post) => ({
    params: { slug: post.slug },
    props: { post: post },
  }));
}
---
<Layout title={post.title.rendered}>
  <article>
    <h1 set:html={post.title.rendered} />
    <Fragment set:html={post.content.rendered} />
  </article>
</Layout>
```

### Returning embedded resources

The `_embed` query parameter instructs the server to return related (embedded) resources.

```
---
const { slug } = Astro.params;

let res = await fetch(`https://norian.studio/wp-json/wp/v2/dinos?slug=${slug}&_embed`);
let [post] = await res.json();
---
```

The `_embedded['wp:featuredmedia']['0'].media_details.sizes.medium.source_url` property is returned, and can be used to display the featured image on each dinosaur page. (Replace `medium` with your desired image size.)

```
<Layout title={post.title.rendered}>
  <article>
    <img src={post._embedded['wp:featuredmedia']['0'].media_details.sizes.medium.source_url} />
    <h1 set:html={post.title.rendered} />
    <Fragment set:html={post.content.rendered} />
  </article>
</Layout>
```

### Publishing your site

To deploy your site visit our [deployment guides](/en/guides/deploy/) and follow the instructions for your preferred hosting provider.

## Community Resources

-   [Building An Astro Website With WordPress As A Headless CMS](https://blog.openreplay.com/building-an-astro-website-with-wordpress-as-a-headless-cms/) by Chris Bongers.
-   [Building with Astro x WordPress](https://www.youtube.com/watch?v=Jstqgklvfnc) on Ben Holmes's stream.
-   [Building a Headless WordPress Site with Astro](https://developers.wpengine.com/blog/building-a-headless-wordpress-site-with-astro) by Jeff Everhart.
-   [Astro and WordPress as an API](https://darko.io/posts/wp-as-an-api/) by Darko Bozhinovski.

## Community Resources

:::note\[Have a resource to share?\] If you found (or made!) a helpful video or blog post about using headless WordPress with Astro, [add it to this list](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/cms/wordpress.mdx)! :::

## [Zero & Astro](https://docharvest.github.io/docs/astro/guides/cms/zero/)

Contents

astro

Zero & Astro

Astro

Zero & Astro

[Zero](https://www.zerocms.io) is an AI-native, Git-based CMS built specifically for Astro, requiring no integration and working directly with existing Zod schemas and Astro components.

## [Configuration overview](https://docharvest.github.io/docs/astro/guides/configuring-astro/)

Contents

astro

Configuration overview

Astro

Configuration overview

````

It is only required if you have something to configure, but most projects will use this file. The `defineConfig()` helper provides automatic IntelliSense in your IDE and is where you will add all your configuration options to tell Astro how to build and render your project to HTML.

We recommend using the default file format `.mjs` in most cases, or `.ts` if you want to write TypeScript in your config file. However, `astro.config.js` is also supported.

<ReadMore>Read Astro's [configuration reference](/en/reference/configuration-reference/) for a full overview of all supported configuration options.</ReadMore>

## The TypeScript config File

Every Astro starter project includes a `tsconfig.json` file in your project. Astro's [component script](/en/basics/astro-components/#the-component-script) is TypeScript, which provides Astro's editor tooling and allows you to optionally add syntax to your JavaScript for type checking of your own project code.

Use the `tsconfig.json` file to configure the TypeScript template that will perform type checks on your code, configure TypeScript plugins, set import aliases, and more.

<ReadMore>Read Astro's [TypeScript guide](/en/guides/typescript/) for a full overview of TypeScript options and Astro's built-in utility types.</ReadMore>

## Development Experience

While you work in development mode, you can take advantage of your code editor and other tools to improve the Astro developer experience.

Astro provides its own official VS Code extension and is compatible with several other popular editor tools. Astro also provides a customizable toolbar that displays in your browser preview while the dev server is running. You can install and even build your own toolbar apps for additional functionality.

<ReadMore>Read Astro's guides to [editor setup options](/en/editor-setup/) and [using the dev toolbar](/en/guides/dev-toolbar/) to learn how to customize your development experience.</ReadMore>

## Common new project tasks

Here are some first steps you might choose to take with a new Astro project.

### Add your deployment domain

For generating your sitemap and creating canonical URLs, configure your deployment URL in the [`site`](/en/reference/configuration-reference/#site) option. If you are deploying to a path (e.g. `www.example.com/docs`), you can also configure a [`base`](/en/reference/configuration-reference/#base) for the root of your project.

Additionally, different deployment hosts may have different behavior regarding trailing slashes at the end of your URLs. (e.g. `example.com/about` vs `example.com/about/`). Once your site is deployed, you may need to configure your [`trailingSlash`](/en/reference/configuration-reference/#trailingslash) preference.

```js title="astro.config.mjs"
````

### Add site metadata

Astro does not use its configuration file for common SEO or meta data, only for information required to build your project code and render it to HTML.

Instead, this information is added to your page `<head>` using standard HTML `<link>` and `<meta>` tags, just as if you were writing plain HTML pages.

One common pattern for Astro sites is to create a `<Head />` [`.astro` component](/en/basics/astro-components/) that can be added to a common [layout component](/en/basics/layouts/) so it can apply to all your pages.

```
---

const { ...props } = Astro.props;
---
<html>
  <head>
    <meta charset="utf-8">
    <Head />
    <!-- Additional head elements -->
  </head>
  <body>
    <!-- Page content goes here -->
  </body>
</html>
```

Because `Head.astro` is just a regular Astro component, you can import files and receive props passed from other components, such as a specific page title.

```
---

const { title = "My Astro Website", ...props } = Astro.props;
---
<link rel="sitemap" href="/sitemap-index.xml">
<title>{title}</title>
<meta name="description" content="Welcome to my new Astro site!">

<!-- Web analytics -->
<script data-goatcounter="https://my-account.goatcounter.com/count" async src="//gc.zgo.at/count.js"></script>

<!-- Open Graph tags -->
<meta property="og:title" content="My New Astro Website" />
<meta property="og:type" content="website" />
<meta property="og:url" content="http://www.example.com/" />
<meta property="og:description" content="Welcome to my new Astro site!" />
<meta property="og:image" content="https://www.example.com/_astro/seo-banner.BZD7kegZ.webp">
<meta property="og:image:alt" content="">

<SomeOtherTags />

<Favicon />
```

## [Content collections](https://docharvest.github.io/docs/astro/guides/content-collections/)

Contents

astro

Content collections

Astro

Content collections

// 2. Import loader(s)

// 3. Import Zod

// 4. Define a `loader` and `schema` for each collection const blog = defineCollection({ loader: glob({ base: './src/content/blog', pattern: '\*\*/\*.{md,mdx}' }), schema: z.object({ title: z.string(), description: z.string(), pubDate: z.coerce.date(), updatedDate: z.coerce.date().optional(), }), });

// 5. Export a single `collections` object to register your collection(s)

````

You can then use the dedicated `getCollection()` and `getEntry()` functions to [query your content collections data](#querying-build-time-collections) and render your content.

You can choose to [generate page routes](#generating-routes-from-content) from your build-time collection entries at build time for an entirely static, prerendered site. Or, you can render your build-time collections on demand, choosing to delay building your page until it is first requested. This is useful when you have a large number of pages (e.g. thousands or tens of thousands) and want to delay building a static page until it is needed.

## Build-time collection loaders

Astro provides two built-in loaders (`glob()` and `file()`) for fetching your local content at build time. Pass the location of your data in your project or on your filesystem, and these loaders will automatically handle your data and update the persistent data store content layer.

To fetch remote data at build time, you can [build a custom loader](#custom-build-time-loaders) to retrieve your data and update the data store. Or, you can use any [third-party or community-published loader integration](https://astro.build/integrations/2/?search=&categories%5B%5D=loaders). Several already exist for popular content management systems as well as common data sources such as Obsidian vaults, GitHub repositories, or Bluesky posts.

### The `glob()` loader

The [`glob()` loader](/en/reference/content-loader-reference/#glob-loader) fetches entries from directories of Markdown, MDX, Markdoc, JSON, YAML, or TOML files from anywhere on the filesystem. If you store your content entries locally as separate files, such as a directory of blog posts, then the `glob()` loader is all you need to access your content.

This loader requires a `pattern` of entry files to match using glob patterns supported by [micromatch](https://github.com/micromatch/micromatch#matching-features), and a `base` file path of where your files are located. A unique `id` for each entry will be automatically generated from its file name, but you can [define custom IDs](#defining-custom-ids) if needed.

```ts  title="src/content.config.ts" {5}

const blog = defineCollection({
  loader: glob({ pattern: "**/*.md", base: "./src/data/blog" }),
});
````

#### Defining custom IDs

When using the [`glob()` loader](#the-glob-loader) with Markdown, MDX, Markdoc, JSON, or TOML files, every content entry [`id`](/en/reference/modules/astro-content/#collectionentryid) is automatically generated in an URL-friendly format based on the content filename. This unique `id` is used to query the entry directly from your collection. It is also useful when [creating new pages and URLs from your content](#generating-routes-from-content).

You can override a single entry’s generated `id` by adding your own `slug` property to the file frontmatter or data object for JSON files. This is similar to the “permalink” feature of other web frameworks.

```
---
title: My Blog Post
slug: my-custom-id/supports/slashes
---
Your blog post content here.
```

```
{
  "title": "My Category",
  "slug": "my-custom-id/supports/slashes",
  "description": "Your category description here."
}
```

You can also pass options to the `glob()` loader's [`generateID()` helper function](/en/reference/content-loader-reference/#generateid) when you define your build-time collection to adjust how `id`s are generated. For example, you may wish to revert the default behavior of converting uppercase letters to lowercase for each collection entry:

```

const authors = defineCollection({
  /* Retrieve all JSON files in your authors directory while retaining
   * uppercase letters in the ID. */
  loader: glob({
    pattern: "**/*.json",
    base: "./src/data/authors",
    generateId: ({ entry }) => entry.replace(/\.json$/, ""),
  }),
});
```

### The `file()` loader

The [`file()` loader](/en/reference/content-loader-reference/#file-loader) fetches multiple entries from a single local file defined in your collection. The `file()` loader will automatically detect and parse (based on the file extension) a single array of objects from JSON and YAML files, and will treat each top-level table as an independent entry in TOML files.

```

const dogs = defineCollection({
  loader: file("src/data/dogs.json"),
});
```

Each entry object in the file must have a unique `id` key property so that the entry can be identified and queried. Unlike the `glob()` loader, the `file()` loader will not automatically generate IDs for each entry.

You can provide your entries as an array of objects with an `id` property, or in object form where the unique `id` is the key:

```
// Specify an `id` property in each object of an array
[
  { "id": "poodle", "coat": "curly", "shedding": "low" },
  { "id": "afghan", "coat": "short", "shedding": "low" }
]
```

```
// Each key will be used as the `id`
{
  "poodle": { "coat": "curly", "shedding": "low" },
  "afghan": { "coat": "silky", "shedding": "low" }
}
```

#### Parsing other data formats

Support for parsing single JSON, YAML, and TOML files into collection entries with the `file()` loader is built-in (unless you have a [nested JSON document](#nested-json-documents)). To load your collection from unsupported file types, such as `.csv`, you will need to create a [parser function](/en/reference/content-loader-reference/#parser). This function can be made async if required (e.g. to fetch files from the web, or if your parser is asynchronous).

The following example shows importing a third-party CSV parser then passing a custom `parser` function to the `file()` loader:

```

const cats = defineCollection({
  loader: file("src/data/cats.csv", {
    parser: (text) => parseCsv(text, { columns: true, skipEmptyLines: true }),
  }),
});
```

##### Nested `.json` documents

The `parser()` argument can be used to load a single collection from a nested JSON document. For example, this JSON file contains multiple collections:

```
{"dogs": [{}], "cats": [{}]}
```

You can separate these collections by passing a custom `parser()` function to the `file()` loader for each collection, using Astro's built-in JSON parsing:

```

const dogs = defineCollection({
  loader: file("src/data/pets.json", { parser: (text) => JSON.parse(text).dogs })
});
const cats = defineCollection({
  loader: file("src/data/pets.json", { parser: (text) => JSON.parse(text).cats })
});
```

### Custom build-time loaders

You can [build a custom loader](/en/reference/content-loader-reference/#building-a-loader) using the Content Loader API to fetch remote content from any data source, such as a CMS, a database, or an API endpoint.

Then you can import and define your custom loader in your collections config, passing any required values:

```

const blog = defineCollection({
  loader: myLoader({
    url: "https://api.example.com/posts",
    apiKey: "my-secret",
  }),
});
```

:::tip Find community-built and third-party loaders in the [Astro integrations directory](https://astro.build/integrations/?search=&categories%5B%5D=loaders). :::

Using a custom loader to fetch your data will automatically create a collection from your remote data. This gives you all the benefits of local collections, including collection-specific API helpers such as `getCollection()` and `render()` to [query and display your data](#querying-build-time-collections), as well as schema validation.

Similar to creating an Astro integration or Vite plugin, you can [distribute your loader as an npm package](/en/guides/integrations/) that others can use in their projects.

See the full [Content Loader API](/en/reference/content-loader-reference/) for examples of how to build your own loader.

## Defining the collection schema

Schemas enforce consistent frontmatter or entry data within a collection through Zod validation. A schema **guarantees** that this data exists in a predictable form when you need to reference or query it. If any file violates its collection schema, Astro will provide a helpful error to let you know.

Schemas also power Astro's automatic TypeScript typings for your content. When you define a schema for your collection, Astro will automatically generate and apply a TypeScript interface to it. The result is full TypeScript support when you query your collection, including property autocompletion and type-checking.

:::tip In order for Astro to recognize a new or updated schema, you may need to restart the dev server or [sync the content layer](/en/reference/cli-reference/#astro-dev) (`s + enter`) to define the `astro:content` module. :::

Providing a `schema` is optional, but highly recommended! If you choose to use a schema, then every frontmatter or data property of your collection entries must be defined using a [Zod data type](/en/reference/modules/astro-zod/#common-data-type-validators):

```

const blog = defineCollection({
  loader: glob({ pattern: "**/*.md", base: "./src/data/blog" }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
  }),
});
const dogs = defineCollection({
  loader: file("src/data/dogs.json"),
  schema: z.object({
    id: z.string(),
    breed: z.string(),
    temperament: z.array(z.string()),
  }),
});
```

### Defining datatypes with Zod

Astro uses [Zod](https://github.com/colinhacks/zod) to power its content schemas. With Zod, Astro is able to validate every file's data within a collection _and_ provide automatic TypeScript types when you query content from inside your project.

To use Zod in Astro, import the `z` utility from `"astro/zod"`. This is a re-export of the Zod library, and it supports all of the features of Zod 4.

See the [`z` utility reference](/en/reference/modules/astro-zod/) for a cheatsheet of common datatypes and to learn how Zod works and what features are available.

#### Zod schema methods

All [Zod schema methods](/en/reference/modules/astro-zod/#using-zod-methods) (e.g. `.parse()`, `.transform()`) are available, with some limitations. Notably, performing custom validation checks on images using `image().refine()` is unsupported.

### Defining collection references

Collection entries can also "reference" other related entries.

With the [`reference()` function](/en/reference/modules/astro-content/#reference), you can define a property in a collection schema as an entry from another collection. For example, you can require that every `space-shuttle` entry includes a `pilot` property which uses the `pilot` collection's own schema for type checking, autocomplete, and validation.

A common example is a blog post that references reusable author profiles stored as JSON, or related post URLs stored in the same collection:

```

const blog = defineCollection({
  loader: glob({ base: "./src/content/blog", pattern: "**/*.{md,mdx}" }),
  schema: z.object({
    title: z.string(),
    // Reference a single author from the `authors` collection by `id`
    author: reference("authors"),
    // Reference an array of related posts from the `blog` collection by `id`
    relatedPosts: z.array(reference("blog")),
  }),
});

const authors = defineCollection({
  loader: glob({ pattern: "**/*.json", base: "./src/data/authors" }),
  schema: z.object({
    name: z.string(),
    portfolio: z.url(),
  }),
});
```

This example blog post specifies the `id`s of related posts and the `id` of the post author:

```
---
title: "Welcome to my blog"
author: ben-holmes # references `src/data/authors/ben-holmes.json` 
relatedPosts:
- about-me # references `src/content/blog/about-me.md`
- my-year-in-review # references `src/content/blog/my-year-in-review.md`
---
```

These references will be transformed into objects containing a `collection` key and an `id` key, allowing you to easily [query them in your templates](#accessing-referenced-data).

## Querying build-time collections

Astro provides helper functions to query a build-time collection and return one or more content entries.

-   [`getCollection()`](/en/reference/modules/astro-content/#getcollection) fetches an entire collection and returns an array of entries.
-   [`getEntry()`](/en/reference/modules/astro-content/#getentry) fetches a single entry from a collection.

These return entries with a unique `id`, a `data` object with all defined properties, and will also return a `body` containing the raw, uncompiled body of a Markdown, MDX, or Markdoc document.

```
---

// Get all entries from a collection.
// Requires the name of the collection as an argument.
const allBlogPosts = await getCollection('blog');

// Get a single entry from a collection.
// Requires the name of the collection and `id`
const poodleData = await getEntry('dogs', 'poodle');
---
```

The sort order of generated collections is non-deterministic and platform-dependent. This means that if you are calling `getCollection()` and need your entries returned in a specific order (e.g. blog posts sorted by date), you must sort the collection entries yourself:

```
---

const posts = (await getCollection('blog')).sort(
  (a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf(),
);
---
```

See the full list of properties returned by the [`CollectionEntry` type](/en/reference/modules/astro-content/#collectionentry).

### Using content in Astro templates

After querying your collections, you can access each entry's content and metadata directly inside of your Astro component template.

For example, you can create a list of links to your blog posts, displaying information from your entry's frontmatter using the `data` property:

```
---

const posts = await getCollection('blog');
---
<h1>My posts</h1>
<ul>
  {posts.map(post => (
    <li><a href={`/blog/${post.id}`}>{post.data.title}</a></li>
  ))}
</ul>
```

### Rendering body content

Once queried, you can render Markdown and MDX entries to HTML using the [`render()`](/en/reference/modules/astro-content/#render) function from `astro:content`. Calling this function gives you access to rendered HTML content, including both a `<Content />` component and a list of all rendered headings.

```
---

const entry = await getEntry("blog", "post-1");

if (!entry) {
  throw new Error("Entry not found");
}

const { Content } = await render(entry);
---

<h1>{entry.data.title}</h1>
<p>Published on: {entry.data.pubDate.toDateString()}</p>
<Content />
```

When working with MDX entries, you can also [pass your own components to `<Content />`](/en/guides/integrations-guide/mdx/#passing-components-to-mdx-content) to replace HTML elements with custom alternatives.

#### Passing content as props

A component can also pass an entire collection entry as a prop.

You can use the [`CollectionEntry`](/en/reference/modules/astro-content/#collectionentry) utility to correctly type your component's props using TypeScript. This utility takes a string argument that matches the name of your collection schema and will inherit all of the properties of that collection's schema.

```
---

interface Props {
  post: CollectionEntry<'blog'>;
}

// `post` will match your 'blog' collection schema type
const { post } = Astro.props;
---
```

### Filtering collection queries

`getCollection()` takes an optional "filter" callback that allows you to filter your query based on an entry's `id` or `data` properties.

You can use this to filter by any content criteria you like. For example, you can filter by properties like `draft` to prevent any draft blog posts from publishing to your blog:

```
---
// Example: Filter out content entries with `draft: true`

const publishedBlogEntries = await getCollection('blog', ({ data }) => {
  return data.draft !== true;
});
---
```

You can also create draft pages that are available when running the dev server, but not built in production:

```
---
// Example: Filter out content entries with `draft: true` only when building for production

const blogEntries = await getCollection('blog', ({ data }) => {
  return import.meta.env.PROD ? data.draft !== true : true;
});
---
```

The filter argument also supports filtering by nested directories within a collection. Since the `id` includes the full nested path, you can filter by the start of each `id` to only return items from a specific nested directory:

```
---
// Example: Filter entries by sub-directory in the collection

const englishDocsEntries = await getCollection('docs', ({ id }) => {
  return id.startsWith('en/');
});
---
```

### Accessing referenced data

To access [references defined in your schema](#defining-collection-references), first query your collection entry. Your references will be available on the returned `data` object. (e.g. `entry.data.author` and `entry.data.relatedPosts`)

Then, you can use the `getEntry()` function again (or `getEntries()` to retrieve multiple referenced entries) by passing those returned values. The `reference()` function in your schema transforms those values into one or more `collection` and `id` objects as a convenient way to query this related data.

```
---

// First, query a blog post
const blogPost = await getEntry("blog", "Adventures in Space");

// If the blog post doesn't exist, throw an error
if (!blogPost) {
  throw new Error("Blog post not found");
}

// Retrieve a single reference item: the blog post's author
// Equivalent to querying `{collection: "authors", id: "ben-holmes"}`
const author = await getEntry(blogPost.data.author);

// Retrieve an array of referenced items: all the related posts
// Equivalent to querying `[{collection: "blog", id: "visiting-mars"}, {collection: "blog", id: "leaving-earth-for-the-first-time"}]`
const relatedPosts = await getEntries(blogPost.data.relatedPosts);
---

<h1>{blogPost.data.title}</h1>
<p>Author: {author.data.name}</p>

<!-- ... -->

<h2>You might also like:</h2>
{relatedPosts.map((post) => <a href={post.id}>{post.data.title}</a>)}
```

## Generating Routes from Content

Content collections are stored outside of the `src/pages/` directory. This means that no pages or routes are generated for your collection items by default by Astro's [file-based routing](/en/guides/routing/).

You will need to manually create a new [dynamic route](/en/guides/routing/#dynamic-routes) if you want to generate HTML pages for each of your collection entries, such as individual blog posts. Your dynamic route will map the incoming request param (e.g. `Astro.params.id` in `src/pages/blog/[...id].astro`) to fetch the correct entry for each page.

The exact method for generating routes will depend on whether your pages are prerendered (default) or rendered on demand by a server.

### Building for static output (default)

If you are building a static website (Astro's default behavior) with build-time collections, use the [`getStaticPaths()`](/en/reference/routing-reference/#getstaticpaths) function to create multiple pages from a single page component (e.g. `src/pages/[id].astro`) during your build.

Call `getCollection()` inside of `getStaticPaths()` to have your collection data available for building static routes. Then, create the individual URL paths using the `id` property of each content entry. Each page receives the entire collection entry as a prop for [use in your page template](#using-content-in-astro-templates).

```
---

// 1. Generate a new path for every collection entry

  return posts.map(post => ({
    params: { id: post.id },
    props: { post },
  }));
}
// 2. For your template, you can get the entry directly from the prop
const { post } = Astro.props;
const { Content } = await render(post);
---
<h1>{post.data.title}</h1>
<Content />
```

This will generate a page route for every entry in the `blog` collection. For example, an entry at `src/blog/hello-world.md` will have an `id` of `hello-world`, and therefore its final URL will be `/posts/hello-world/`.

:::note If your custom slugs contain the `/` character to produce URLs with multiple path segments, you must use a [rest parameter (e.g. `[...id]`)](/en/guides/routing/#rest-parameters) in the `.astro` filename for this dynamic routing page. :::

### Building routes on demand at request time

With an adapter installed for [on-demand rendering](/en/guides/on-demand-rendering/), you can generate your dynamic page routes at request time. First, examine the request (using `Astro.request` or `Astro.params`) to find the slug on demand, and then fetch it using one of Astro's content collection helper functions:

-   [`getEntry()`](/en/reference/modules/astro-content/#getentry) for build-time collection pages that are generated once, upon first request.
-   [`getLiveEntry()`](/en/reference/modules/astro-content/#getliveentry) for live collection pages where data is (re)fetched at each request time.

```
---

if (id === undefined) {
	return Astro.redirect("/404");
}

// 2. Query for the entry directly using the request slug
const post = await getEntry("blog", id);

// 3. Redirect if the entry does not exist
if (post === undefined) {
	return Astro.redirect("/404");
}

// 4. Render the entry to HTML in the template
const { Content } = await render(post);
---
<h1>{post.data.title}</h1>
<Content />
```

:::tip Explore the `src/pages/` folder of the [blog tutorial demo code on GitHub](https://github.com/withastro/blog-tutorial-demo/tree/content-collections/src/pages) to see full examples of creating dynamic pages from your collections for blog features like a list of blog posts, tags pages, and more! :::

## Live content collections

Live collections use a different API than build-time content collections, although the configuration and helper functions are designed to feel familiar.

Key differences include:

1.  **Execution time**: Run at request time instead of build time
2.  **Configuration file**: Use `src/live.config.ts` instead of `src/content.config.ts`
3.  **Collection definition**: Use `defineLiveCollection()` instead of `defineCollection()`
4.  **Loader API**: Implement `loadCollection` and `loadEntry` methods instead of the `load` method
5.  **Data return**: Return data directly instead of storing in the data store
6.  **User-facing functions**: Use `getLiveCollection()`/`getLiveEntry()` instead of `getCollection()`/`getEntry()`

Additionally, you must have an adapter configured for [on-demand rendering](/en/guides/on-demand-rendering/) of live collection data.

Define your live collections in the special file `src/live.config.ts` (separate from your `src/content.config.ts` for build-time collections, if you have one).

Each individual collection configures:

-   a [live `loader`](#creating-a-live-loader) for your data source, and optionally for type safety (required)
-   a [live collection `schema`](#using-zod-schemas-with-live-collections) for type safety (optional)

Unlike for build-time collections, there are no built-in live loaders available. You will need to [create a custom live loader](#creating-a-live-loader) for your specific data source or find a third-party loader to pass to your live collection's `loader` property.

You can optionally [include type safety in your live loaders](/en/reference/content-loader-reference/#the-liveloader-object). Therefore, [defining a Zod `schema`](#using-zod-schemas-with-live-collections) for live collections is optional. However, if you provide one, it will take precedence over the live loader's types.

```
// Define live collections for accessing real-time data

const products = defineLiveCollection({
  loader: storeLoader({
    apiKey: process.env.STORE_API_KEY,
    endpoint: 'https://api.mystore.com/v1',
  }),
});

// Export a single `collections` object to register your collection(s)
```

You can then use the dedicated `getLiveCollection()` and `getLiveEntry()` functions to [access your live data](#accessing-live-data) and render your content.

You can [generate page routes](#generating-routes-from-content) from your live collection entries on demand, fetching your data fresh at runtime upon each request without needing a rebuild of your site like [build-time collections](#defining-build-time-content-collections) do. This is useful when accessing live, up-to-the-moment data is more important than having your content available in a performant data storage layer that persists between site builds.

### Creating a live loader

You can build a custom [live loader](/en/reference/content-loader-reference/#live-loaders) using the Live Loader API to fetch remote content fresh upon request from any data source, such as a CMS, a database or an API endpoint. You will have to tell your live loader how to fetch and return content entries from your desired data source, as well as provide error handling for unsuccessful data requests.

Using a live loader to fetch your data will automatically create a collection from your remote data. This gives you all the benefits of Astro's content collections, including collection-specific API helpers such as `getLiveCollection()` and `render()` to [query and display your data](#querying-build-time-collections), as well as helpful error handling.

:::tip Find community-built and third-party live loaders in the [Astro integrations directory](https://astro.build/integrations/?search=&categories%5B%5D=loaders). :::

See the basics of [building a live loader](/en/reference/content-loader-reference/#building-a-live-loader) using the Live Loader API

### Using Zod schemas with live collections

You can use Zod schemas with live collections to validate and transform data at runtime. This Zod validation works the same way as [schemas for build-time collections](#defining-the-collection-schema).

When you define a schema for a live collection, it takes precedence over [the live loader's types](/en/reference/content-loader-reference/#the-liveloader-object) when you query the collection:

```

const products = defineLiveCollection({
  loader: apiLoader({ endpoint: process.env.API_URL }),
  schema: z
    .object({
      id: z.string(),
      name: z.string(),
      price: z.number(),
      // Transform the API's category format
      category: z.string().transform((str) => str.toLowerCase().replace(/\s+/g, '-')),
      // Coerce the date to a Date object
      createdAt: z.coerce.date(),
    })
    .transform((data) => ({
      ...data,
      // Add a formatted price field
      displayPrice: `$${data.price.toFixed(2)}`,
    })),
});
```

When using Zod schemas with live collections, validation errors are automatically caught and returned as `AstroError` objects:

```
---

// You can handle validation errors specifically
if (LiveCollectionValidationError.is(error)) {
  console.error(error.message);
  return Astro.rewrite('/500');
}

// TypeScript knows entry.data matches your Zod schema, not the loader's type
console.log(entry?.data.displayPrice); // e.g., "$29.99"
---
```

See [Zod's README](https://github.com/colinhacks/zod) for complete documentation on how Zod works and what features are available.

### Accessing live data

Astro provides live collection helper functions to access live data on each request and return one (or more) content entries. These can be used similarly to their [build-time collection counterparts](#querying-build-time-collections).

-   [`getLiveCollection()`](/en/reference/modules/astro-content/#getlivecollection) fetches an entire collection and returns an array of entries.
-   [`getLiveEntry()`](/en/reference/modules/astro-content/#getliveentry) fetches a single entry from a collection.

These return entries with a unique `id`, and `data` object with all defined properties from the live loader. When using third-party or community loaders distributed as npm packages, check their own documentation for the expected shape of data returned.

You can use these functions to access your live data, passing the name of the collection and optionally filtering conditions.

```
---

}

// Use loader-specific filters
const { entries: draftArticles } = await getLiveCollection("articles", {
  status: "draft",
  author: "john-doe",
});

// Get a specific product by ID
const { entry: product } = await getLiveEntry("products", Astro.params.slug);
---
```

#### Rendering content

If your live loader [returns a `rendered` property](/en/reference/content-loader-reference/#livedataentryrendered), you can use [the `render()` function and `<Content />` component](#rendering-body-content) to render your content directly in your pages, using the same method as build-time collections.

You also have access to any [error returned by the live loader](/en/reference/content-loader-reference/#error-handling-in-live-loaders), for example, to rewrite to a 404 page when content cannot be displayed:

```
---

}

const { entry, error } = await getLiveEntry("articles", Astro.params.id);
if (!entry || error) {
  return Astro.rewrite("/404");
}

const { Content } = await render(entry);
---

<h1>{entry.data.title}</h1>
<Content />
```

#### Error handling

Live loaders can fail due to network issues, API errors, or validation problems. The API is designed to make error handling explicit.

When you call `getLiveCollection()` or `getLiveEntry()`, the error will be one of:

-   The error type defined by the loader (if it returned an error)
-   A `LiveEntryNotFoundError` if the entry was not found
-   A `LiveCollectionValidationError` if the collection data does not match the expected schema
-   A `LiveCollectionCacheHintError` if the cache hint is invalid
-   A `LiveCollectionError` for other errors, such as uncaught errors thrown in the loader

You can use `instanceof` to check the type of an error at runtime:

```
---

}

const { entry, error } = await getLiveEntry("products", Astro.params.id);

if (error) {
  if (error instanceof LiveEntryNotFoundError) {
    console.error(`Product not found: ${error.message}`);
    Astro.response.status = 404;
  } else {
    console.error(`Error loading product: ${error.message}`);
    return Astro.redirect("/500");
  }
}
---
```

### Caching live data

When live loaders provide [cache hints](/en/reference/content-loader-reference/#live-loaders), `getLiveEntry()` and `getLiveCollection()` return a `cacheHint` object. This allows you to control the [caching behavior](/en/guides/caching/) of your routes without manually setting headers.

Cache hints include [`tags`](/en/reference/content-loader-reference/#cachehinttags) for targeted invalidation and [`lastModified`](/en/reference/content-loader-reference/#cachehintlastmodified) to keep cached data fresh. You can also combine the cache hints with your own [cache options](/en/reference/cache-provider-reference/#cacheoptions) to further customize caching behavior.

See the \[Content Loader Reference\](/en/reference/content-loader-reference/) for more about implementing cache hints in your live loaders.

#### Entry-level cache hints

Pass the `cacheHint` returned by `getLiveEntry()` to [`Astro.cache.set()`](/en/reference/api-reference/#cacheset) to apply the loader's recommended caching strategy.

The following example passes the loader's cache hint and adds a `maxAge` to control how long the response stays fresh:

```
---

const { entry, error, cacheHint } = await getLiveEntry('products', Astro.params.id);

if (error) {
  return Astro.redirect('/404');
}

if (cacheHint) {
  Astro.cache.set(cacheHint);
}

Astro.cache.set({ maxAge: 300 });
---

<h1>{entry.data.name}</h1>
```

You can also pass a [`LiveDataEntry`](/en/reference/content-loader-reference/#livedataentry) directly to let Astro extract its `cacheHint` automatically:

```
---

const { entry, error } = await getLiveEntry('products', Astro.params.id);

if (error) {
  return Astro.redirect('/404');
}

Astro.cache.set(entry);
Astro.cache.set({ maxAge: 300, swr: 60 });
---

<h1>{entry.data.name}</h1>
```

#### Collection-level cache hints

When fetching a full collection with `getLiveCollection()`, Astro merges cache hints from the collection response and all individual entries: tags are accumulated, and the most recent `lastModified` wins.

The following example passes the merged cache hint from a collection and sets a 10-minute freshness window:

```
---

const { entries, error, cacheHint } = await getLiveCollection('products');

if (error) {
  return new Response('Error loading products', { status: 500 });
}

if (cacheHint) {
  Astro.cache.set(cacheHint);
}
Astro.cache.set({ maxAge: 600 });
---

<ul>
  {entries.map((p) => <li>{p.data.name}</li>)}
</ul>
```

#### Invalidating by entry

You can invalidate cached entries by passing a `LiveDataEntry` to [`cache.invalidate()`](/en/reference/api-reference/#cacheinvalidate). This allows you to target specific cached responses for invalidation based on the entry's cache tags, without needing to clear the entire cache.

The following example invalidates the cached response for a specific product entry:

```

  if (entry) {
    await context.cache.invalidate(entry);
  }
  return Response.json({ ok: true });
}
```

## Using JSON Schema files in your editor

Astro auto-generates [JSON Schema](https://json-schema.org/) files for collections, which you can use in your editor to get IntelliSense and type-checking for data files.

A JSON Schema file is generated for each collection in your project and output to the `.astro/collections/` directory. For example, if you have two collections, one named `authors` and another named `posts`, Astro will generate `.astro/collections/authors.schema.json` and `.astro/collections/posts.schema.json`.

### Use JSON Schemas in JSON files

You can manually point to an Astro-generated schema by setting the `$schema` field in your JSON file. The value should be a relative file path from the data file to the schema. In the following example, a data file in `src/data/authors/` uses the schema generated for the `authors` collection:

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

#### Use a schema for a group of JSON files in VS Code

In VS Code, you can configure a schema to apply to all files in a collection using the [`json.schemas` setting](https://code.visualstudio.com/docs/languages/json#_json-schemas-and-settings). In the following example, all files in the `src/data/authors/` directory will use the schema generated for the `authors` collection:

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

### Use schemas in YAML files in VS Code

In VS Code, you can add support for using JSON schemas in YAML files using the [Red Hat YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) extension. With this extension installed, you can reference a schema in a YAML file using a special comment syntax:

```
# yaml-language-server: $schema=../../../.astro/collections/authors.schema.json
name: Armand
skills:
  - Astro
  - Starlight
```

#### Use schemas for a group of YAML files in VS Code

With the Red Hat YAML extension, you can configure a schema to apply to all YAML files in a collection using the `yaml.schemas` setting. In the following example, all YAML files in the `src/data/authors/` directory will use the schema generated for the `authors` collection:

```
{
  "yaml.schemas": {
    "./.astro/collections/authors.schema.json": ["/src/content/authors/*.yml"]
  }
}
```

See [“Associating schemas”](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml#associating-schemas) in the Red Hat YAML extension documentation for more details.

## [Data fetching](https://docharvest.github.io/docs/astro/guides/data-fetching/)

Contents

astro

Data fetching

Astro

Data fetching

`.astro` files can fetch remote data to help you generate your pages.

## `fetch()` in Astro

All [Astro components](/en/basics/astro-components/) have access to the [global `fetch()` function](https://developer.mozilla.org/en-US/docs/Web/API/fetch) in their component script to make HTTP requests to APIs using the full URL (e.g. `https://example.com/api`). Additionally, you can construct a URL to your project's pages and endpoints that are rendered on demand on the server using [`new URL("/api", Astro.url)`](/en/reference/api-reference/#url).

This fetch call will be executed at build time, and the data will be available to the component template for generating dynamic HTML. If [SSR](/en/guides/on-demand-rendering/) mode is enabled, any fetch calls will be executed at runtime.

💡 Take advantage of [**top-level `await`**](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await#top_level_await) inside of your Astro component script.

💡 Pass fetched data to both Astro and framework components, as props.

```
---
// src/components/User.astro

const response = await fetch("https://randomuser.me/api/");
const data = await response.json();
const randomUser = data.results[0];
---
<!-- Data fetched at build can be rendered in HTML -->
<h1>User</h1>
<h2>{randomUser.name.first} {randomUser.name.last}</h2>

<!-- Data fetched at build can be passed to components as props -->
<Contact client:load email={randomUser.email} />
<Location city={randomUser.location.city} />
```

:::note Remember, all data in Astro components is fetched when a component is rendered.

Your deployed Astro site will fetch data **once, at build time**. In dev, you will see data fetches on component refreshes. If you need to re-fetch data multiple times client-side, use a [framework component](/en/guides/framework-components/) or a [client-side script](/en/guides/client-side-scripts/) in an Astro component. :::

## `fetch()` in Framework Components

The `fetch()` function is also globally available to any [framework components](/en/guides/framework-components/):

```

const data = await fetch('https://example.com/movies.json').then((response) => response.json());

// Components that are build-time rendered also log to the CLI.
// When rendered with a `client:*` directive, they also log to the browser console.
console.log(data);

const Movies: FunctionalComponent = () => {
  // Output the result to the page
  return <div>{JSON.stringify(data)}</div>;
};
```

## GraphQL queries

Astro can also use `fetch()` to query a GraphQL server with any valid GraphQL query.

```
---
const response = await fetch(
  "https://swapi-graphql.netlify.app/.netlify/functions/index",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      query: `
        query getFilm ($id:ID!) {
          film(id: $id) {
            title
            releaseDate
          }
        }
      `,
      variables: {
        id: "ZmlsbXM6MQ==",
      },
    }),
  }
);

const json = await response.json();
const { film } = json.data;
---
<h1>Fetching information about Star Wars: A New Hope</h1>
<h2>Title: {film.title}</h2>
<p>Year: {film.releaseDate}</p>
```

## Fetch from a Headless CMS

Astro components can fetch data from your favorite CMS and then render it as your page content. Using [dynamic routes](/en/guides/routing/#dynamic-routes), components can even generate pages based on your CMS content.

See our [CMS Guides](/en/guides/cms/) for full details on integrating Astro with headless CMSes including Storyblok, Contentful, and WordPress.

## Community resources

-   [Creating a fullstack app with Astro + GraphQL](https://robkendal.co.uk/blog/how-to-build-astro-site-with-graphql/)

## [Deploy your Astro Site](https://docharvest.github.io/docs/astro/guides/deploy/)



## [Deploy your Astro Site to AWS](https://docharvest.github.io/docs/astro/guides/deploy/aws/)

Contents

astro

Deploy your Astro Site to AWS

Astro

Deploy your Astro Site to AWS

[AWS](https://aws.amazon.com/) is a full-featured web app hosting platform that can be used to deploy an Astro site.

Deploying your project to AWS requires using the [AWS console](https://aws.amazon.com/console/). (Most of these actions can also be done using the [AWS CLI](https://aws.amazon.com/cli/)). This guide will walk you through the steps to deploy your site to AWS using [AWS Amplify](https://aws.amazon.com/amplify/), [S3 static website hosting](https://aws.amazon.com/s3/), and [CloudFront](https://aws.amazon.com/cloudfront/).

## AWS Amplify

AWS Amplify is a set of purpose-built tools and features that lets frontend web and mobile developers quickly and easily build full-stack applications on AWS. You can either deploy your Astro project as a static site, or as a server-rendered site.

### Static Site

Your Astro project is a static site by default.

1\. Create a new Amplify Hosting project.

2.  Connect your repository to Amplify.
    
3.  Modify your build settings to match your project's build process.
    
    \`\`\`yaml version: 1 frontend: phases: preBuild: commands: - npm i -g pnpm - pnpm config set store-dir .pnpm-store - pnpm i build: commands: - pnpm run build artifacts: baseDirectory: /dist files: - '\*\*/\*' cache: paths: - .pnpm-store/\*\*/\* \`\`\` \`\`\`yaml version: 1 frontend: phases: preBuild: commands: - npm ci build: commands: - npm run build artifacts: baseDirectory: /dist files: - '\*\*/\*' cache: paths: - node\_modules/\*\*/\* \`\`\` \`\`\`yaml version: 1 frontend: phases: preBuild: commands: - yarn install build: commands: - yarn build artifacts: baseDirectory: /dist files: - '\*\*/\*' cache: paths: - node\_modules/\*\*/\* \`\`\`

Amplify will automatically deploy your website and update it when you push a commit to your repository.

### Adapter for on-demand rendering

In order to deploy your project as a server-rendered site, you will need to use the third-party, [community-maintained AWS Amplify adapter](https://github.com/alexnguyennz/astro-aws-amplify) and make some changes to your config.

First, install the Amplify adapter.

\`\`\`shell pnpm add astro-aws-amplify \`\`\` \`\`\`shell npm install astro-aws-amplify \`\`\` \`\`\`shell yarn add astro-aws-amplify \`\`\`

Then, in your `astro.config.*` file, add the adapter and set the output to `server`.

Once the adapter has been installed, you can set up your Amplify project.

1\. Create a new Amplify Hosting project.

2.  Connect your repository to Amplify.
    
3.  Modify your build settings to match the adapter's build process by either editing the build settings in the AWS console, or by adding an `amplify.yaml` in the root of your project.
    
    \`\`\`yaml version: 1 frontend: phases: preBuild: commands: - npm i -g pnpm - pnpm config set store-dir .pnpm-store - pnpm i build: commands: - pnpm run build - mv node\_modules ./.amplify-hosting/compute/default artifacts: baseDirectory: .amplify-hosting files: - '\*\*/\*' cache: paths: - .pnpm-store/\*\*/\* \`\`\` \`\`\`yaml version: 1 frontend: phases: preBuild: commands: - npm ci --cache .npm --prefer-offline build: commands: - npm run build - mv node\_modules ./.amplify-hosting/compute/default artifacts: baseDirectory: .amplify-hosting files: - '\*\*/\*' cache: paths: - .npm/\*\*/\* \`\`\` \`\`\`yaml version: 1 frontend: phases: preBuild: commands: - yarn install build: commands: - yarn build - mv node\_modules ./.amplify-hosting/compute/default artifacts: baseDirectory: .amplify-hosting files: - '\*\*/\*' cache: paths: - node\_modules/\*\*/\* \`\`\`

Amplify will automatically deploy your website and update it when you push a commit to your repository.

See \[AWS's Astro deployment guide\](https://docs.aws.amazon.com/amplify/latest/userguide/get-started-astro.html) for more info.

## S3 static website hosting

S3 is the starting point of any application. It is where your project files and other assets are stored. S3 charges for file storage and number of requests. You can find more information about S3 in the [AWS documentation](https://aws.amazon.com/s3/).

1\. Create an S3 bucket with your project's name.

```
:::tip
The bucket name should be globally unique. We recommend a combination of your project name and the domain name of your site.
:::
```

2.  Disable **"Block all public access"**. By default, AWS sets all buckets to be private. To make it public, you need to uncheck the "Block public access" checkbox in the bucket's properties.
    
3.  Upload your built files located in `dist` to S3. You can do this manually in the console or use the AWS CLI. If you use the AWS CLI, use the following command after [authenticating with your AWS credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html):
    
    ```
    aws s3 cp dist/ s3://<BUCKET_NAME>/ --recursive
    ```
    
4.  Update your bucket policy to allow public access. You can find this setting in the bucket's **Permissions > Bucket policy**.
    
    ```
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Sid": "PublicReadGetObject",
          "Effect": "Allow",
          "Principal": "*",
          "Action": "s3:GetObject",
          "Resource": "arn:aws:s3:::<BUCKET_NAME>/*"
        }
      ]
    }
    ```
    
    :::caution Do not forget to replace `<BUCKET_NAME>` with the name of your bucket. :::
    
5.  Enable website hosting for your bucket. You can find this setting in the bucket's **Properties > Static website hosting**. Set your index document to `index.html` and your error document to `404.html`. Finally, you can find your new website URL in the bucket's **Properties > Static website hosting**.
    
    :::note If you are deploying a single-page application (SPA), set your error document to `index.html`. :::
    

## S3 with CloudFront

CloudFront is a web service that provides content delivery network (CDN) capabilities. It is used to cache content of a web server and distribute it to end users. CloudFront charges for the amount of data transferred. Adding CloudFront to your S3 bucket is more cost-effective and provides a faster delivery.

To connect S3 with CloudFront, create a CloudFront distribution with the following values:

-   **Origin domain:** Your S3 bucket static website endpoint. You can find your endpoint in your S3 bucket's **Properties > Static website hosting**. Alternative, you can select your s3 bucket and click on the callout to replace your bucket address with your bucket static endpoint.
-   **Viewer protocol policy:** "Redirect to HTTPS"

This configuration will serve your site using the CloudFront CDN network. You can find your CloudFront distribution URL in the bucket's **Distributions > Domain name**.

:::note When connecting CloudFront to an S3 static website endpoint, you rely on S3 bucket policies for access control. See [S3 static website hosting](#s3-static-website-hosting) section for more information about bucket policies. :::

## Continuous deployment with GitHub Actions

There are many ways to set up continuous deployment for AWS. One possibility for code hosted on GitHub is to use [GitHub Actions](https://github.com/features/actions) to deploy your website every time you push a commit.

1\. Create a new policy in your AWS account using \[IAM\](https://aws.amazon.com/iam/) with the following permissions. This policy will allow you to upload built files to your S3 bucket and invalidate the CloudFront distribution files when you push a commit.

````
```json
{
  "Version": "2012-10-17",
  "Statement": [
      {
          "Sid": "VisualEditor0",
          "Effect": "Allow",
          "Action": [
              "s3:PutObject",
              "s3:ListBucket",
              "s3:DeleteObject",
              "cloudfront:CreateInvalidation"
          ],
          "Resource": [
              "<DISTRIBUTION_ARN>",
              "arn:aws:s3:::<BUCKET_NAME>/*",
              "arn:aws:s3:::<BUCKET_NAME>"
          ]
      }
  ]
}
```

:::caution
Do not forget to replace `<DISTRIBUTION_ARN>` and `<BUCKET_NAME>`. You can find the DISTRIBUTION_ARN in **CloudFront > Distributions > Details**.
:::
````

2.  Create a new IAM user and attach the policy to the user. This will provide your `AWS_SECRET_ACCESS_KEY` and `AWS_ACCESS_KEY_ID`.
    
3.  Add this sample workflow to your repository at `.github/workflows/deploy.yml` and push it to GitHub. You will need to add `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `BUCKET_ID`, and `DISTRIBUTION_ID` as “secrets” to your repository on GitHub under **Settings** > **Secrets** > **Actions**. Click New repository secret to add each one.
    
    ```
    name: Deploy Website
    
    on:
      push:
        branches:
          - main
    
    jobs:
      deploy:
        runs-on: ubuntu-latest
        steps:
          - name: Checkout
            uses: actions/checkout@v6
          - name: Configure AWS Credentials
            uses: aws-actions/configure-aws-credentials@v1
            with:
              aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
              aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
              aws-region: us-east-1
          - name: Install modules
            run: npm ci
          - name: Build application
            run: npm run build
          - name: Deploy to S3
            run: aws s3 sync --delete ./dist/ s3://${{ secrets.BUCKET_ID }}
          - name: Create CloudFront invalidation
            run: aws cloudfront create-invalidation --distribution-id ${{ secrets.DISTRIBUTION_ID }} --paths "/*"
    ```
    
    :::note Your `BUCKET_ID` is the name of your S3 bucket. Your `DISTRIBUTION_ID` is your CloudFront distribution ID. You can find your CloudFront distribution ID in **CloudFront > Distributions > ID** :::
    

## Community Resources

-   [Deploy Astro to AWS Amplify](https://www.launchfa.st/blog/deploy-astro-aws-amplify)
-   [Deploy Astro to AWS Elastic Beanstalk](https://www.launchfa.st/blog/deploy-astro-aws-elastic-beanstalk)
-   [Deploy Astro to Amazon ECS on AWS Fargate](https://www.launchfa.st/blog/deploy-astro-aws-fargate)
-   [Troubleshooting SSR Amplify Deployments](https://docs.aws.amazon.com/amplify/latest/userguide/troubleshooting-ssr-deployment.html)

## [Deploy your Astro Site to AWS with Flightcontrol](https://docharvest.github.io/docs/astro/guides/deploy/aws-via-flightcontrol/)



## [Deploy your Astro Site to AWS with SST](https://docharvest.github.io/docs/astro/guides/deploy/aws-via-sst/)



## [Deploy your Astro Site to Azion](https://docharvest.github.io/docs/astro/guides/deploy/azion/)

Contents

astro

Deploy your Astro Site to Azion

Astro

Deploy your Astro Site to Azion

You can deploy your Astro project on [Azion](https://console.azion.com/), a platform for frontend developers to collaborate and deploy static (JAMstack) and SSR websites.

## Prerequisites

To get started, you will need:

-   An [Azion account](https://www.azion.com/). If you don’t have one, you can sign up for a free account.
-   Your app code stored in a [GitHub](https://github.com/) repository.
-   [Azion CLI](https://www.azion.com/en/documentation/products/azion-cli/overview/) installed for faster project setup and deployment.

## How to Deploy through Azion Console Dashboard

To start building, follow these steps:

1\. Access \[Azion Console\](https://console.azion.com). 2. On the homepage, click the \*\*\\+ Create\*\* button. - This opens a modal with the options to create new applications and resources. 3. Select the \*\*Import from GitHub\*\* option and click the card. - This action opens the settings page. 4. Connect your Azion account with GitHub. - A pop-up window will appear asking for authorization. 5. Select the repository you want to import from GitHub. 6. Configure the build settings: - \*\*Framework preset:\*\* Select the appropriate framework (e.g., \`Astro\`). - \*\*Root Directory:\*\* This refers to the directory in which your code is located. Your code must be located at the root directory, not a subdirectory. A ./ symbol appears in this field, indicating it’s a root directory. - \*\*Install Command:\*\* the command that compiles your settings to build for production. Build commands are executed through scripts. For example: npm run build or npm install for an NPM package. 7. Click \*\*Save and Deploy\*\*. 8. Monitor the deployment using \*\*Azion Real-Time Metrics\*\* and verify your site is live on the edge.

## How to Deploy a Static Site Using the Azion CLI

1.  **Install the Azion CLI:**
    
    -   Download and install the [Azion CLI](https://www.azion.com/en/documentation/products/azion-cli/overview/) for easier management and deployment.
    
    :::caution The Azion CLI does not currently support native Windows environments. However, you can use it on Windows through the Windows Subsystem for Linux (WSL). Follow the [WSL installation guide](https://docs.microsoft.com/en-us/windows/wsl/install) to set up a Linux environment on your Windows machine. :::
    
2.  **Authenticate the CLI:**
    
    -   Run the following command to authenticate your CLI with your Azion account.
    
    ```
    azion login
    ```
    
3.  **Set Up Your Application:**
    
    -   Use the following commands to initialize and configure your project:
    
    ```
    azion init
    ```
    
4.  **Build Your Astro Project:**
    
    -   Run your build command locally:
    
    ```
    azion build
    ```
    
5.  **Deploy Your Static Files:**
    
    -   Deploy your static files using the Azion CLI:
    
    ```
    azion deploy
    ```
    

This guide provides an overview of deploying static applications.

## Enabling Local Development Using Azion CLI

For the preview to work, you must execute the following command:

```
azion dev
```

Once you've initialized the local development server, the application goes through the `build` process.

```
Building your Edge Application. This process may take a few minutes
Running build step command:
...
```

Then, when the build is complete, the access to the application is prompted:

```
[Azion Bundler] [Server] › ✔  success   Function running on port http://localhost:3000 
```

## Troubleshooting

### Node.js runtime APIs

A project using an NPM package fails to build with an error message such as `[Error] Could not resolve "XXXX. The package "XXXX" wasn't found on the file system but is built into node.`:

This means that a package or import you are using is not compatible with Azion’s runtime APIs.

If you are directly importing a Node.js runtime API, please refer to the [Azion Node.js compatibility](https://www.azion.com/en/documentation/products/azion-edge-runtime/compatibility/node/) for further steps on how to resolve this.

If you are importing a package that imports a Node.js runtime API, check with the author of the package to see if they support the `node:*` import syntax. If they do not, you may need to find an alternative package.

## [Deploy your Astro Site with Buddy](https://docharvest.github.io/docs/astro/guides/deploy/buddy/)



## [Deploy your Astro Site with Cleavr](https://docharvest.github.io/docs/astro/guides/deploy/cleavr/)



## [Deploy your Astro Site to Clever Cloud](https://docharvest.github.io/docs/astro/guides/deploy/clever-cloud/)

Contents

astro

Deploy your Astro Site to Clever Cloud

Astro

Deploy your Astro Site to Clever Cloud

[Clever Cloud](https://clevercloud.com) is a European cloud platform that provides automated, scalable services.

## Project Configuration

You can deploy both fully static and on-demand rendered Astro projects on Clever Cloud. Regardless of your `output` mode (pre-rendered or [on-demand](/en/guides/on-demand-rendering/)), you can choose to deploy as a **static application** which runs using a post-build hook, or as a **Node.js** application, which requires some manual configuration in your `package.json`.

### Scripts

If you're running an on-demand Node.js application, update your `start` script to run the Node server. Applications on Clever Cloud listen on port **8080**.

```
"scripts": {
  "start": "node ./dist/server/entry.mjs --host 0.0.0.0 --port 8080",
} 
```

## Deploy Astro from the Console

To deploy your Astro project to Clever Cloud, you will need to **create a new application**. The application wizard will walk you through the necessary configuration steps.

1.  From the lateral menubar, click **Create** > **An application**
    
2.  Choose how to deploy:
    
    -   **Create a brand new app**: to deploy from a local repository with Git
    
    or
    
    -   **Select a GitHub repository**: to deploy from GitHub
3.  Select a **Node.js** application, or a **static** one.
    
4.  Set up the minimal size for your instance and scalability options. Astro sites can typically be deployed using the **Nano** instance. Depending on your project's specifications and dependencies, you may need to adjust accordingly as you watch the metrics from the **Overview** page.
    
5.  Select a **region** to deploy your instance.
    
6.  Skip [connecting **Add-ons** to your Clever application](https://www.clevercloud.com/developers/doc/addons/) unless you're using a database or Keycloak.
    
7.  Inject **environment variables**:
    
    -   For **Node.js**, set the following environment variables based on your package manager:
    
    \`\`\`shell CC\_NODE\_BUILD\_TOOL="npm" CC\_PRE\_BUILD\_HOOK="npm install && npm run astro telemetry disable && npm run build" \`\`\` \`\`\`shell CC\_NODE\_BUILD\_TOOL="custom" CC\_PRE\_BUILD\_HOOK="npm install -g pnpm && pnpm install" CC\_CUSTOM\_BUILD\_TOOL="pnpm run astro telemetry disable && pnpm build" \`\`\` \`\`\`shell CC\_NODE\_BUILD\_TOOL="yarn" CC\_PRE\_BUILD\_HOOK="yarn && yarn run astro telemetry disable && yarn build" \`\`\`
    
    -   For a **static** application, add these variables:
    
    \`\`\`shell CC\_POST\_BUILD\_HOOK="npm run build" CC\_PRE\_BUILD\_HOOK="npm install && npm run astro telemetry disable" CC\_WEBROOT="/dist" \`\`\` \`\`\`shell CC\_POST\_BUILD\_HOOK="pnpm build" CC\_PRE\_BUILD\_HOOK="npm install -g pnpm && pnpm install && pnpm run astro telemetry disable" CC\_WEBROOT="/dist" \`\`\` \`\`\`shell CC\_POST\_BUILD\_HOOK="yarn build" CC\_PRE\_BUILD\_HOOK="yarn && yarn run astro telemetry disable" CC\_WEBROOT="/dist" \`\`\`
8.  **Deploy!** If you're deploying from **GitHub**, your deployment should start automatically. If you're using **Git**, copy the remote and push on the **master** branch.
    

:::tip\[Other Branches\] To deploy from branches other than `master`, use `git push clever <branch>:master`.

For example, if you want to deploy your local `main` branch without renaming it, use `git push clever main:master`. :::

## Official Resources

-   [Clever Cloud documentation for deploying a Node.js application](https://www.clevercloud.com/developers/doc/applications/nodejs/)
-   [Clever Cloud documentation for deploying Astro as a static application](https://www.clevercloud.com/developers/guides/astro/)

## [Deploy your Astro Site to Cloudflare](https://docharvest.github.io/docs/astro/guides/deploy/cloudflare/)



## [Deploy your Astro Site with CloudRay](https://docharvest.github.io/docs/astro/guides/deploy/cloudray/)



## [Deploy your Astro Site with Deno](https://docharvest.github.io/docs/astro/guides/deploy/deno/)

Contents

astro

Deploy your Astro Site with Deno

Astro

Deploy your Astro Site with Deno

````
import deno from '@deno/astro-adapter';

export default defineConfig({
  output: 'server',
  adapter: deno(),
});
```
````

3.  Update your `preview` script in `package.json` with the change below.
    
    ```
    // package.json
    {
      "scripts": {
        "dev": "astro dev",
        "start": "astro dev",
        "build": "astro build",
        "preview": "astro preview"
        "preview": "deno run --allow-net --allow-read --allow-env ./dist/server/entry.mjs"
      }
    }
    ```
    
    You can now use this command to preview your production Astro site locally with Deno.
    
    \`\`\`shell npm run preview \`\`\` \`\`\`shell pnpm run preview \`\`\` \`\`\`shell yarn run preview \`\`\`

## How to deploy

You can run your Astro site on your own server, or deploy to Deno Deploy through GitHub Actions or using Deno Deploy’s CLI (command line interface).

### On your own server

1\. Copy your project onto your server.

2.  Install the project dependencies using your preferred package manager:
    
    \`\`\`shell npm install \`\`\` \`\`\`shell pnpm install \`\`\` \`\`\`shell yarn install \`\`\`
3.  Build your Astro site with your preferred package manager:
    
    \`\`\`shell npm run build \`\`\` \`\`\`shell pnpm run build \`\`\` \`\`\`shell yarn run build \`\`\`
4.  Start your application with the following command:
    
    \`\`\`bash deno run -A jsr:@std/http/file-server dist \`\`\` \`\`\`bash deno run -A ./dist/server/entry.mjs \`\`\`

### GitHub Actions Deployment

If your project is stored on GitHub, the [Deno Deploy website](https://dash.deno.com/) will guide you through setting up GitHub Actions to deploy your Astro site.

1\. Push your code to a public or private GitHub repository.

2.  Sign in on [Deno Deploy](https://dash.deno.com/) with your GitHub account, and click on [New Project](https://dash.deno.com).
    
3.  Select your repository, the branch you want to deploy from, and select **GitHub Action** mode. (Your Astro site requires a build step, and cannot use Automatic mode.)
    
4.  In your Astro project, create a new file at `.github/workflows/deploy.yml` and paste in the YAML below. This is similar to the YAML given by Deno Deploy, with the additional steps needed for your Astro site.
    
    \`\`\`yaml --- // .github/workflows/deploy.yml --- name: Deploy on: \[push\]
    
    ```
     jobs:
       deploy:
         name: Deploy
         runs-on: ubuntu-latest
         permissions:
           id-token: write # Needed for auth with Deno Deploy
           contents: read # Needed to clone the repository
    
         steps:
           - name: Clone repository
             uses: actions/checkout@v6
    
           # Not using npm? Change `npm ci` to `pnpm i` or `yarn install`
           - name: Install dependencies
             run: npm ci
    
           # Not using npm? Change `npm run build` to `pnpm run build` or `yarn run build`
           - name: Build Astro
             run: npm run build
    
           - name: Upload to Deno Deploy
             uses: denoland/deployctl@v1
             with:
               project: my-deno-project # TODO: replace with Deno Deploy project name
               entrypoint: jsr:@std/http/file-server
               root: dist
     ```
    ```
    
    \`\`\`yaml --- // .github/workflows/deploy.yml --- name: Deploy on: \[push\]
    
    ```
     jobs:
       deploy:
         name: Deploy
         runs-on: ubuntu-latest
         permissions:
           id-token: write # Needed for auth with Deno Deploy
           contents: read # Needed to clone the repository
    
         steps:
           - name: Clone repository
             uses: actions/checkout@v6
    
           # Not using npm? Change `npm ci` to `pnpm i` or `yarn install`
           - name: Install dependencies
             run: npm ci
    
           # Not using npm? Change `npm run build` to `pnpm run build` or `yarn run build`
           - name: Build Astro
             run: npm run build
    
           - name: Upload to Deno Deploy
             uses: denoland/deployctl@v1
             with:
               project: my-deno-project # TODO: replace with Deno Deploy project name
               entrypoint: dist/server/entry.mjs
     ```
    ```
    
5.  After committing this YAML file, and pushing to GitHub on your configured deploy branch, the deploy should begin automatically!
    
    You can track the progress using the "Actions" tab on your GitHub repository page, or on [Deno Deploy](https://dash.deno.com).
    

### CLI Deployment

1\. Install the \[Deno Deploy CLI\](https://docs.deno.com/deploy/manual/deployctl).

````
```bash
deno install -gArf jsr:@deno/deployctl
```
````

2.  Build your Astro site with your preferred package manager:
    
    \`\`\`shell npm run build \`\`\` \`\`\`shell pnpm run build \`\`\` \`\`\`shell yarn run build \`\`\`
3.  Run `deployctl` to deploy!
    
    \`\`\`bash cd dist && deployctl deploy jsr:@std/http/file-server \`\`\` \`\`\`bash deployctl deploy ./dist/server/entry.mjs \`\`\`
    
    You can track all your deploys on [Deno Deploy](https://dash.deno.com).
    
4.  (Optional) To simplify the build and deploy into one command, add a `deploy-deno` script in `package.json`, adapting it for your preferred package manager.
    
    \`\`\`json ins={8} // package.json { "scripts": { "dev": "astro dev", "start": "astro dev", "build": "astro build", "preview": "astro preview", "deno-deploy": "npm run build && cd dist && deployctl deploy jsr:@std/http/file-server" } } \`\`\` \`\`\`json ins={8} // package.json { "scripts": { "dev": "astro dev", "start": "astro dev", "build": "astro build", "preview": "deno run --allow-net --allow-read --allow-env ./dist/server/entry.mjs", "deno-deploy": "npm run build && deployctl deploy ./dist/server/entry.mjs" } } \`\`\`
    
    Then you can use this command to build and deploy your Astro site in one step.
    
    \`\`\`shell npm run deno-deploy \`\`\` \`\`\`shell pnpm run deno-deploy \`\`\` \`\`\`shell yarn run deno-deploy \`\`\`

## [Deploy your Astro Site with DeployHQ](https://docharvest.github.io/docs/astro/guides/deploy/deployhq/)



## [Deploy your Astro Site to EdgeOne Pages](https://docharvest.github.io/docs/astro/guides/deploy/edgeone-pages/)

Contents

astro

Deploy your Astro Site to EdgeOne Pages

Astro

Deploy your Astro Site to EdgeOne Pages

You can deploy your Astro project on [EdgeOne Pages](https://pages.edgeone.ai/), a fullstack development platform with a global edge network that can build your site from a Git connection or from the EdgeOne CLI.

## Official Resources

-   [EdgeOne Astro Framework Guide](https://pages.edgeone.ai/document/framework-astro)
-   [EdgeOne Astro template](https://github.com/TencentEdgeOne/astro-template)

## [Deploy your Astro Site to Google’s Firebase Hosting](https://docharvest.github.io/docs/astro/guides/deploy/firebase/)

Contents

astro

Deploy your Astro Site to Google’s Firebase Hosting

Astro

Deploy your Astro Site to Google’s Firebase Hosting

[Firebase Hosting](https://firebase.google.com/products/hosting) is a service provided by Google’s [Firebase](https://firebase.google.com/) app development platform, which can be used to deploy an Astro site.

See our separate guide for [adding Firebase backend services](/en/guides/backend/firebase/) such as databases, authentication, and storage.

## Project Configuration

Your Astro project can be deployed to Firebase as a static site, or as a server-side rendered site (SSR).

### Static Site

Your Astro project is a static site by default. You don’t need any extra configuration to deploy a static Astro site to Firebase.

### Adapter for SSR

To enable SSR in your Astro project and deploy on Firebase add the [Node.js adapter](/en/guides/integrations-guide/node/).

:::note Deploying an SSR Astro site to Firebase requires the [Blaze plan](https://firebase.google.com/pricing) or higher. :::

## How to deploy

1\. Install the \[Firebase CLI\](https://github.com/firebase/firebase-tools). This is a command-line tool that allows you to interact with Firebase from the terminal.

```
<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install firebase-tools
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm add firebase-tools
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn add firebase-tools
  ```
  </Fragment>
</PackageManagerTabs>
```

2.  Authenticate the Firebase CLI with your Google account. This will open a browser window where you can log in to your Google account.
    
    \`\`\`shell npx firebase login \`\`\` \`\`\`shell pnpm exec firebase login \`\`\` \`\`\`shell yarn firebase login \`\`\`
3.  Enable experimental web frameworks support. This is an experimental feature that allows the Firebase CLI to detect and configure your deployment settings for Astro.
    
    \`\`\`shell npx firebase experiments:enable webframeworks \`\`\` \`\`\`shell pnpm exec firebase experiments:enable webframeworks \`\`\` \`\`\`shell yarn firebase experiments:enable webframeworks \`\`\`
4.  Initialize Firebase Hosting in your project. This will create a `firebase.json` and `.firebaserc` file in your project root.
    
    \`\`\`shell npx firebase init hosting \`\`\` \`\`\`shell pnpm exec firebase init hosting \`\`\` \`\`\`shell yarn firebase init hosting \`\`\`
5.  Deploy your site to Firebase Hosting. This will build your Astro site and deploy it to Firebase.
    
    \`\`\`shell npx firebase deploy --only hosting \`\`\` \`\`\`shell pnpm exec firebase deploy --only hosting \`\`\` \`\`\`shell yarn firebase deploy --only hosting \`\`\`

## [Deploy your Astro Site to Fleek](https://docharvest.github.io/docs/astro/guides/deploy/fleek/)



## [Deploy your Astro Site to Fly.io](https://docharvest.github.io/docs/astro/guides/deploy/flyio/)

Contents

astro

Deploy your Astro Site to Fly.io

Astro

Deploy your Astro Site to Fly.io

You can deploy your Astro project to [Fly.io](https://fly.io/), a platform for running full stack apps and databases close to your users.

## Project Configuration

Your Astro project can be deployed to Fly.io as a static site, or as a server-side rendered site (SSR).

### Static Site

Your Astro project is a static site by default. You don’t need any extra configuration to deploy a static Astro site to Fly.io.

### Adapter for SSR

To enable on-demand rendering in your Astro project and deploy on Fly.io, add [the Node.js adapter](/en/guides/integrations-guide/node/).

## How to deploy

1\. \[Sign up for Fly.io\](https://fly.io/docs/getting-started/log-in-to-fly/#first-time-or-no-fly-account-sign-up-for-fly) if you haven't already.

2.  [Install `flyctl`](https://fly.io/docs/hands-on/install-flyctl/), your Fly.io app command center.
    
3.  Run the following command in your terminal.
    
    ```
    fly launch
    ```
    
    `flyctl` will automatically detect Astro, configure the correct settings, build your image, and deploy it to the Fly.io platform.
    

## Generating your Astro Dockerfile

If you don't already have a Dockerfile, `fly launch` will generate one for you, as well as prepare a `fly.toml` file. For pages rendered on demand, this Dockerfile will include the appropriate start command and environment variables.

You can instead create your own Dockerfile using [Dockerfile generator](https://www.npmjs.com/package/@flydotio/dockerfile) and then run using the command `npx dockerfile` for Node applications or `bunx dockerfile` for Bun applications.

## Official Resources

-   Check out [the official Fly.io docs](https://fly.io/docs/js/frameworks/astro/)

## [Deploy your Astro Site to GitHub Pages](https://docharvest.github.io/docs/astro/guides/deploy/github/)

Contents

astro

Deploy your Astro Site to GitHub Pages

Astro

Deploy your Astro Site to GitHub Pages

You can use [GitHub Pages](https://pages.github.com/) to host a static, prerendered Astro website directly from a repository on [GitHub.com](https://github.com/) using [GitHub Actions](https://github.com/features/actions).

## How to deploy

Astro maintains an [official Astro GitHub Action to deploy your project to a GitHub Pages](https://github.com/withastro/action) with very little configuration and is the recommended way to deploy to GitHub Pages.

Follow the instructions below to use the GitHub Action to deploy your Astro site to GitHub Pages. This will create a website from your repository at a GitHub URL (e.g. `https://<username>.github.io/<my-repo>`). Once deployed, you can optionally [configure a custom domain](#change-your-github-url-to-a-custom-domain) to deploy your GitHub Pages site at your preferred domain (e.g. `https://example.com`).

1\. Create a new file in your project at \`.github/workflows/deploy.yml\` and paste in the YAML below.

````
```yaml title="deploy.yml"
name: Deploy to GitHub Pages

on:
  # Trigger the workflow every time you push to the `main` branch
  # Using a different branch name? Replace `main` with your branch’s name
  push:
    branches: [ main ]
  # Allows you to run this workflow manually from the Actions tab on GitHub.
  workflow_dispatch:
  
# Allow this job to clone the repo and create a page deployment
permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout your repository using git
        uses: actions/checkout@v6
      - name: Install, build, and upload your site
        uses: withastro/action@v6
        # with:
          # path: . # The root location of your Astro project inside the repository. (optional)
          # node-version: 24 # The specific version of Node that should be used to build your site. Defaults to 24. (optional)
          # package-manager: pnpm@latest # The Node package manager that should be used to install dependencies and build your site. Automatically detected based on your lockfile. (optional)
          # build-cmd: pnpm run build # The command to run to build your site. Runs the package build script/task by default. (optional)
        # env:
          # PUBLIC_POKEAPI: 'https://pokeapi.co/api/v2' # Use single quotation marks for the variable value. (optional)

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5
```

 The Astro action can be configured with optional inputs. Provide these by uncommenting the `with:` line and the input you want to use.
 
 If your site requires any public environment variables, uncomment the `env:` line and add them there. (See the [GitHub documentation on setting secrets](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#creating-configuration-variables-for-a-repository) for adding private environment variables.)

:::caution
The official Astro [action](https://github.com/withastro/action) scans for a lockfile to detect your preferred package manager (`npm`, `yarn`, `pnpm`, or `bun`). You should commit your package manager's automatically generated `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, or `bun.lockb` file to your repository.
:::
````

2.  In your Astro config file, set [`site`](/en/reference/configuration-reference/#site) to the GitHub URL of your deployed site.
    
    ```
    import { defineConfig } from 'astro/config'
    
    export default defineConfig({
      site: 'https://astronaut.github.io',
    })
    ```
    
    The value for `site` must be one of the following:
    
    -   The following URL based on your username: `https://<username>.github.io`
    -   The random URL autogenerated for a [GitHub Organization's private page](https://docs.github.com/en/enterprise-cloud@latest/pages/getting-started-with-github-pages/changing-the-visibility-of-your-github-pages-site): `https://<random-string>.pages.github.io/`
3.  In `astro.config.mjs`, configure a value for [`base`](/en/reference/configuration-reference/#base) (usually required).
    
    GitHub Pages will publish your website at an address that depends on both your username and your repository name (e.g. `https://<username>.github.io/<my-repo>/`). Set a value for `base` that specifies the repository for your website. This is so that Astro understands your website's root is `/my-repo`, rather than the default `/`. You can skip this if your repository name matches the special `<username>.github.io` pattern (e.g. `https://github.com/username/username.github.io/`)
    
    Configure `base` as the repository’s name starting with a forward slash ( e.g. `/my-repo`):
    
    ```
    import { defineConfig } from 'astro/config'
    
    export default defineConfig({
      site: 'https://astronaut.github.io',
      base: '/my-repo',
    })
    ```
    
    :::caution\[Internal links with `base` configured\] When this value is configured, all of your internal page links must be prefixed with your `base` value:
    
    ```
    <a href="/my-repo/about">About</a>
    ```
    
    See more about [configuring a `base` value](/en/reference/configuration-reference/#base). :::
    
4.  On GitHub, go to your repository’s **Settings** tab and find the **Pages** section of the settings.
    
5.  Choose **GitHub Actions** as the **Source** of your site.
    

When you push changes to your Astro project’s repository, the GitHub Action will automatically deploy them for you at your GitHub URL.

## Change your GitHub URL to a custom domain

Once your Astro project is [deployed to GitHub pages at a GitHub URL](#how-to-deploy) following the previous instructions, you can configure a custom domain. This means that users can visit your site at your custom domain `https://example.com` instead of `https://<username>.github.io`.

1.  [Configure DNS for your domain provider](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site#configuring-a-subdomain).
    
2.  Add a `./public/CNAME` record to your project.
    
    Create the following file in your `public/` folder with a single line of text that specifies your custom domain:
    
    ```
    sub.example.com
    ```
    
    This will deploy your site at your custom domain instead of `user.github.io`.
    
3.  In your Astro config, update the value for `site` with your custom domain. Do not set a value for `base`, and remove one if it exists:
    
    ```
    import { defineConfig } from 'astro/config'
    
    export default defineConfig({
      site: 'https://example.com',
      base: '/my-repo'
    })
    ```
    
4.  If necessary, update all your page internal links to remove the `base` prefix:
    
    ```
    <a href="/my-repo/about">About</a>
    ```
    

## Examples

-   [Github Pages Deployment starter template](https://github.com/hkbertoson/github-pages)
-   [Starlight Flexoki Theme (production site)](https://delucis.github.io/starlight-theme-flexoki/)
-   [Expressive Code Color Chips (production site)](https://delucis.github.io/expressive-code-color-chips/)
-   [Starlight Markdown Blocks (production site)](https://delucis.github.io/starlight-markdown-blocks/)

## [Deploy your Astro Site to GitLab Pages](https://docharvest.github.io/docs/astro/guides/deploy/gitlab/)

Contents

astro

Deploy your Astro Site to GitLab Pages

Astro

Deploy your Astro Site to GitLab Pages

You can use [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/) to host an Astro site for your [GitLab](https://about.gitlab.com/) projects, groups, or user account.

:::tip\[Looking for an example?\] Check out [the official GitLab Pages Astro example project](https://gitlab.com/pages/astro)! :::

## How to deploy

You can deploy an Astro site to GitLab Pages by using GitLab CI/CD to automatically build and deploy your site. To do this, your source code must be hosted on GitLab and you need to make the following changes to your Astro project:

1.  Set up [`site`](/en/reference/configuration-reference/#site) and [`base`](/en/reference/configuration-reference/#base) options in `astro.config.mjs`.
    
    ```
    import { defineConfig } from 'astro/config';
    
    export default defineConfig({
      site: 'https://<username>.gitlab.io',
      base: '/<my-repo>',
      outDir: 'public',
      publicDir: 'static',
    });
    ```
    
    `site`
    
    The value for `site` must be one of the following:
    
    -   The following URL based on your username: `https://<username>.gitlab.io`
    -   The following URL based on your group name: `https://<groupname>.gitlab.io`
    -   Your custom domain if you have it configured in your GitLab project’s settings: `https://example.com`
    
    For GitLab self-managed instances, replace `gitlab.io` with your instance’s Pages domain.
    
    `base`
    
    A value for `base` may be required so that Astro will treat your repository name (e.g. `/my-repo`) as the root of your website.
    
    :::note Don't set a `base` parameter if your page is served from the root folder. :::
    
    The value for `base` should be your repository’s name starting with a forward slash, for example `/my-blog`. This is so that Astro understands your website's root is `/my-repo`, rather than the default `/`.
    
    :::caution When this value is configured, all of your internal page links must be prefixed with your `base` value:
    
    ```
    <a href="/my-repo/about">About</a>
    ```
    
    See more about [configuring a `base` value](/en/reference/configuration-reference/#base) :::
    
2.  Rename the `public/` directory to `static/`.
    
3.  Set `outDir: 'public'` in `astro.config.mjs`. This setting instructs Astro to put the static build output in a folder called `public`, which is the folder required by GitLab Pages for exposed files.
    
    If you were using the [`public/` directory](/en/basics/project-structure/#public) as a source of static files in your Astro project, rename it and use that new folder name in `astro.config.mjs` for the value of `publicDir`.
    
    For example, here are the correct `astro.config.mjs` settings when the `public/` directory is renamed to `static/`:
    
    ```
    import { defineConfig } from 'astro/config';
    
    export default defineConfig({
      outDir: 'public',
      publicDir: 'static',
    });
    ```
    
4.  Change the build output in `.gitignore`. In our example we need to change `dist/` to `public/`:
    
    ```
    # build output
    -dist/
    +public/
    ```
    
5.  Create a file called `.gitlab-ci.yml` in the root of your project with the content below. This will build and deploy your site whenever you make changes to your content:
    
    ```
    pages:
      # The Docker image that will be used to build your app
      image: node:lts
    
      before_script:
        - npm ci
    
      script:
        # Specify the steps involved to build your app here
        - npm run build
    
      artifacts:
        paths:
          # The folder that contains the built files to be published.
          # This must be called "public".
          - public
    
      only:
        # Trigger a new build and deploy only when there is a push to the
        # branch(es) below
        - main
    ```
    
6.  Commit your changes and push them to GitLab.
    
7.  On GitLab, go to your repository’s **Deploy** menu and select **Pages**. Here you will see the full URL of your GitLab Pages website. To make sure you are using the URL format `https://username.gitlab.io/my-repo`, uncheck the **Use unique domain** setting on this page.
    

Your site should now be published! When you push changes to your Astro project’s repository, the GitLab CI/CD pipeline will automatically deploy them for you.

## [Deploy your Astro Site to Google Cloud](https://docharvest.github.io/docs/astro/guides/deploy/google-cloud/)



## [Deploy your Astro Site to Heroku](https://docharvest.github.io/docs/astro/guides/deploy/heroku/)

Contents

astro

Deploy your Astro Site to Heroku

Astro

Deploy your Astro Site to Heroku

[Heroku](https://www.heroku.com/) is a platform-as-a-service for building, running, and managing modern apps in the cloud. You can deploy an Astro site to Heroku using this guide.

:::caution The following instructions use [the deprecated `heroku-static-buildpack`](https://github.com/heroku/heroku-buildpack-static#warning-heroku-buildpack-static-is-deprecated). Please see [Heroku's documentation for using `heroku-buildpack-nginx`](https://github.com/dokku/heroku-buildpack-nginx) instead. :::

## How to deploy

1\. Install the \[Heroku CLI\](https://devcenter.heroku.com/articles/heroku-cli).

2.  Create a Heroku account by [signing up](https://signup.heroku.com/).
    
3.  Run `heroku login` and fill in your Heroku credentials:
    
    ```
    $ heroku login
    ```
    
4.  Create a file called `static.json` in the root of your project with the below content:
    
    ```
    {
      "root": "./dist"
    }
    ```
    
    This is the configuration of your site; read more at [heroku-buildpack-static](https://github.com/heroku/heroku-buildpack-static).
    
5.  Set up your Heroku git remote:
    
    ```
    # version change
    $ git init
    $ git add .
    $ git commit -m "My site ready for deployment."
    
    # creates a new app with a specified name
    $ heroku apps:create example
    
    # set buildpack for static sites
    $ heroku buildpacks:set https://github.com/heroku/heroku-buildpack-static.git
    ```
    
6.  Deploy your site:
    
    ```
    # publish site
    $ git push heroku master
    
    # opens a browser to view the Dashboard version of Heroku CI
    $ heroku open
    ```

## [Deploy your Astro Site to Hostinger](https://docharvest.github.io/docs/astro/guides/deploy/hostinger/)



## [Deploy your Astro Site to Microsoft Azure](https://docharvest.github.io/docs/astro/guides/deploy/microsoft-azure/)



## [Deploy your Astro Site to Netlify](https://docharvest.github.io/docs/astro/guides/deploy/netlify/)

Contents

astro

Deploy your Astro Site to Netlify

Astro

Deploy your Astro Site to Netlify

[Netlify](https://netlify.com) offers hosting and serverless backend services for web applications and static websites. Any Astro site can be hosted on Netlify!

This guide includes instructions for deploying to Netlify through the website UI or Netlify's CLI.

## Project configuration

Your Astro project can be deployed to Netlify in three different ways: as a static site, a server-rendered site, or an edge-rendered site.

### Static site

Your Astro project is a static site by default. You don’t need any extra configuration to deploy a static Astro site to Netlify.

### Adapter for on-demand rendering

Add [the Netlify adapter](/en/guides/integrations-guide/netlify/) to enable on-demand rendering in your Astro project and deploy to Netlify with the following `astro add` command. This will install the adapter and make the appropriate changes to your `astro.config.mjs` file in one step.

```
npx astro add netlify
```

See the [Netlify adapter guide](/en/guides/integrations-guide/netlify/) to install manually instead, or for more configuration options, such as deploying your project’s Astro middleware using Netlify’s Edge Functions.

## How to deploy

You can deploy to Netlify through the website UI or using Netlify’s CLI (command line interface). The process is the same for both static and on-demand rendered Astro sites.

### Website UI deployment

If your project is stored in GitHub, GitLab, BitBucket, or Azure DevOps, you can use the Netlify website UI to deploy your Astro site.

1\. Click Add a new site in your \[Netlify dashboard\](https://app.netlify.com/)

2.  Choose Import an existing project
    
    When you import your Astro repository from your Git provider, Netlify should automatically detect and pre-fill the correct configuration settings for you.
    
3.  Make sure that the following settings are entered, then press the Deploy button:
    
    -   **Build Command:** `astro build` or `npm run build`
    -   **Publish directory:** `dist`
    
    After deploying, you will be redirected to the site overview page. There, you can edit the details of your site.
    

Any future changes to your source repository will trigger preview and production deploys based on your deployment configuration.

#### `netlify.toml` file

You can optionally create a new `netlify.toml` file at the top level of your project repository to configure your build command and publish directory, as well as other project settings including environment variables and redirects. Netlify will read this file and automatically configure your deployment.

To configure the default settings, create a `netlify.toml` file with the following contents:

```
[build]
  command = "npm run build"
  publish = "dist"
```

More info at [“Deploying an existing Astro Git repository”](https://www.netlify.com/blog/how-to-deploy-astro/#deploy-an-existing-git-repository-to-netlify) on Netlify’s blog

### CLI deployment

You can also create a new site on Netlify and link up your Git repository by installing and using the [Netlify CLI](https://cli.netlify.com/).

1\. Install Netlify's CLI globally

````
```bash
npm install --global netlify-cli
```
````

2.  Run `netlify login` and follow the instructions to log in and authorize Netlify
    
3.  Run `netlify init` and follow the instructions
    
4.  Confirm your build command (`astro build`)
    
    The CLI will automatically detect the build settings (`astro build`) and deploy directory (`dist`), and will offer to automatically generate [a `netlify.toml` file](#netlifytoml-file) with those settings.
    
5.  Build and deploy by pushing to Git
    
    The CLI will add a deploy key to the repository, which means your site will be automatically rebuilt on Netlify every time you `git push`.
    

More details from Netlify on [Deploy an Astro site using the Netlify CLI](https://www.netlify.com/blog/how-to-deploy-astro/#link-your-astro-project-and-deploy-using-the-netlify-cli)

### Set a Node.js version

If you are using a legacy [build image](https://docs.netlify.com/configure-builds/get-started/#build-image-selection) (Xenial) on Netlify, make sure that your Node.js version is set. Astro requires `v22.12.0` or higher.

You can [specify your Node.js version in Netlify](https://docs.netlify.com/configure-builds/manage-dependencies/#node-js-and-javascript) using:

-   a [`.nvmrc`](https://github.com/nvm-sh/nvm#nvmrc) file in your base directory.
-   a `NODE_VERSION` environment variable in your site's settings using the Netlify project dashboard.

## Using Netlify Functions

No special configuration is required to use Netlify Functions with Astro. Add a `netlify/functions` directory to your project root and follow [the Netlify Functions documentation](https://docs.netlify.com/functions/overview/) to get started!

## Examples

-   [Deploy An Astro site with Forms, Serverless Functions, and Redirects](https://www.netlify.com/blog/deploy-an-astro-site-with-forms-serverless-functions-and-redirects/) — Netlify Blog
-   [Deployment Walkthrough Video](https://youtu.be/GrSLYq6ZTes) — Netlify YouTube channel

## [Deploy your Astro Site with Railway](https://docharvest.github.io/docs/astro/guides/deploy/railway/)



## [Deploy your Astro Site to Render](https://docharvest.github.io/docs/astro/guides/deploy/render/)



## [Deploy your Astro Site to Seenode](https://docharvest.github.io/docs/astro/guides/deploy/seenode/)



## [Deploy your Astro Site to Sevalla](https://docharvest.github.io/docs/astro/guides/deploy/sevalla/)



## [Deploy your Astro Site to Stormkit](https://docharvest.github.io/docs/astro/guides/deploy/stormkit/)



## [Deploy your Astro Site to Surge](https://docharvest.github.io/docs/astro/guides/deploy/surge/)

Contents

astro

Deploy your Astro Site to Surge

Astro

Deploy your Astro Site to Surge

You can deploy your Astro project to [Surge](https://surge.sh/), a single-command web publishing platform designed for front-end developers.

## How to deploy

1\. Install \[the Surge CLI\](https://www.npmjs.com/package/surge) globally from the terminal, if you haven't already.

````
```shell
npm install -g surge
```
````

2.  Build your Astro site from your project’s root directory.
    
    ```
    npm run build
    ```
    
3.  Deploy to Surge using the CLI.
    
    ```
    surge dist
    ```
    
    You can [use a custom domain with Surge](http://surge.sh/help/adding-a-custom-domain) when deploying by running `surge dist yourdomain.com`.

## [Deploy your Astro Site to Vercel](https://docharvest.github.io/docs/astro/guides/deploy/vercel/)



## [Deploy your Astro Site to Zeabur](https://docharvest.github.io/docs/astro/guides/deploy/zeabur/)



## [Deploy your Astro Site to Zephyr Cloud](https://docharvest.github.io/docs/astro/guides/deploy/zephyr/)



## [Deploy your Astro Site to Zerops](https://docharvest.github.io/docs/astro/guides/deploy/zerops/)

Contents

astro

Deploy your Astro Site to Zerops

Astro

Deploy your Astro Site to Zerops

[Zerops](https://zerops.io/) is a dev-first cloud platform that can be used to deploy both Static and SSR Astro site.

This guide will walk you through setting up and deploying both Static and SSR Astro sites on Zerops.

:::tip\[Astro x Zerops Quickrun\]

Want to test running Astro on Zerops without installing or setting up anything? Using repositories [Zerops x Astro - Static](https://github.com/zeropsio/recipe-astro-static) or [Zerops x Astro - SSR on Node.js](https://github.com/zeropsio/recipe-astro-nodejs) you can deploy example Astro site with a single click.

:::

Running apps on Zerops requires two steps:

1.  Creating a project
2.  Triggering build & deploy pipeline

:::note One Zerops project can contain multiple Astro sites. :::

## Astro Static site on Zerops

### Creating a project and a service for Astro Static

Projects and services can be added either through a [`Project add`](https://app.zerops.io/dashboard/project-add) wizard or imported using a yaml structure:

```
# see https://docs.zerops.io/references/import for full reference
project:
  name: recipe-astro
services:
  - hostname: app
    type: static
```

This will create a project called `recipe-astro` with a Zerops Static service called `app`.

### Deploying your Astro Static site

To tell Zerops how to build and run your site, add a `zerops.yml` to your repository:

\`\`\`yaml title="zerops.yml" # see https://docs.zerops.io/zerops-yml/specification for full reference zerops: - setup: app build: base: nodejs@20 buildCommands: - npm i - npm build deployFiles: - dist/~ run: base: static \`\`\` \`\`\`yaml title="zerops.yml" # see https://docs.zerops.io/zerops-yml/specification for full reference zerops: - setup: app build: base: nodejs@20 buildCommands: - pnpm i - pnpm build deployFiles: - dist/~ run: base: static \`\`\` \`\`\`yaml title="zerops.yml" # see https://docs.zerops.io/zerops-yml/specification for full reference zerops: - setup: app build: base: nodejs@20 buildCommands: - yarn - yarn build deployFiles: - dist/~ run: base: static \`\`\`

Now you can [trigger the build & deploy pipeline using the Zerops CLI](#trigger-the-pipeline-using-zerops-cli-zcli) or by connecting the `app` service with your [GitHub](https://docs.zerops.io/references/github-integration/) / [GitLab](https://docs.zerops.io/references/gitlab-integration) repository from inside the service detail.

## Astro SSR site on Zerops

### Update scripts

Update your `start` script to run the server output from the Node adapter.

```
"scripts": {
  "start": "node ./dist/server/entry.mjs",
} 
```

### Creating a project and a service for Astro SSR (Node.js)

Projects and services can be added either through a [`Project add`](https://app.zerops.io/dashboard/project-add) wizard or imported using a yaml structure:

```
# see https://docs.zerops.io/references/import for full reference
project:
  name: recipe-astro
services:
  - hostname: app
    type: nodejs@20
```

This will create a project called `recipe-astro` with Zerops Node.js service called `app`.

### Deploying your Astro SSR site

To tell Zerops how to build and run your site using the official [Astro Node.js adapter](/en/guides/integrations-guide/node/) in `standalone` mode, add a `zerops.yml` file to your repository:

\`\`\`yaml title="zerops.yml" # see https://docs.zerops.io/zerops-yml/specification for full reference zerops: - setup: app build: base: nodejs@20 buildCommands: - npm i - npm run build deployFiles: - dist - package.json - node\_modules run: base: nodejs@20 ports: - port: 3000 httpSupport: true envVariables: PORT: 3000 HOST: 0.0.0.0 start: npm start \`\`\` \`\`\`yaml title="zerops.yml" # see https://docs.zerops.io/zerops-yml/specification for full reference zerops: - setup: app build: base: nodejs@20 buildCommands: - pnpm i - pnpm run build deployFiles: - dist - package.json - node\_modules run: base: nodejs@20 ports: - port: 3000 httpSupport: true envVariables: PORT: 3000 HOST: 0.0.0.0 start: pnpm start \`\`\` \`\`\`yaml title="zerops.yml" # see https://docs.zerops.io/zerops-yml/specification for full reference zerops: - setup: app build: base: nodejs@20 buildCommands: - yarn - yarn build deployFiles: - dist - package.json - node\_modules run: base: nodejs@20 ports: - port: 3000 httpSupport: true envVariables: PORT: 3000 HOST: 0.0.0.0 start: yarn start \`\`\`

Now you can [trigger the build & deploy pipeline using the Zerops CLI](#trigger-the-pipeline-using-zerops-cli-zcli) or by connecting the `app` service with your [GitHub](https://docs.zerops.io/references/github-integration/) / [GitLab](https://docs.zerops.io/references/gitlab-integration) repository from inside the service detail.

## Trigger the pipeline using Zerops CLI (zcli)

1\. Install the Zerops CLI. \`\`\`shell # To download the zcli binary directly, # use https://github.com/zeropsio/zcli/releases npm i -g @zerops/zcli \`\`\`

2.  Open [`Settings > Access Token Management`](https://app.zerops.io/settings/token-management) in the Zerops app and generate a new access token.
    
3.  Log in using your access token with the following command: `shell zcli login <token>`
    
4.  Navigate to the root of your app (where `zerops.yml` is located) and run the following command to trigger the deploy: `shell zcli push`
    

## Resources

### Official

-   [Create Zerops account](https://app.zerops.io/registration)
-   [Zerops Documentation](https://docs.zerops.io)
-   [Zerops Astro recipe](https://app.zerops.io/recipe/astro)

### Community

-   [Deploying Astro to Zerops in 3 mins](https://medium.com/@arjunaditya/how-to-deploy-astro-to-zerops-4230816a62b4)
-   [Deploying Astro SSG with Node.js on Zerops with One Click Deploy](https://youtu.be/-4KTa4VWtBE)
-   [Deploying Astro SSR with Node.js on Zerops with One Click Deploy](https://youtu.be/eR6b_JnDH6g)

## [Dev toolbar](https://docharvest.github.io/docs/astro/guides/dev-toolbar/)

Contents

astro

Dev toolbar

Astro

Dev toolbar

While the dev server is running, Astro includes a dev toolbar at the bottom of every page in your local browser preview.

This toolbar includes a number of useful tools for debugging and inspecting your site during development and can be [extended with more dev toolbar apps](#extending-the-dev-toolbar) found in the integrations directory. You can even [build your own toolbar apps](/en/recipes/making-toolbar-apps/) using the [Dev Toolbar API](/en/reference/dev-toolbar-app-reference/)!

This toolbar is enabled by default and appears when you hover over the bottom of the page. It is a development tool only and will not appear on your published site.

## Built-in apps

### Astro Menu

The Astro Menu app provides easy access to various information about the current project and links to extra resources. Notably, it provides one-click access to the Astro documentation, GitHub repository, and Discord server.

This app also includes a "Copy debug info" button which will run the [`astro info`](/en/reference/cli-reference/#astro-info) command and copy the output to your clipboard. This can be useful when asking for help or reporting issues.

### Inspect

The Inspect app provides information about any [islands](/en/concepts/islands/) on the current page. This will show you the properties passed to each island, and the client directive that is being used to render them.

### Audit

The Audit app automatically runs a series of audits on the current page, checking for the most common performance and accessibility issues. When an issue is found, a red dot will appear in the toolbar. Clicking on the app will pop up a list of results from the audit and will highlight the related elements directly in the page.

:::note The basic performance and accessibility audits performed by the dev toolbar are not a replacement for dedicated tools like [Pa11y](https://pa11y.org/) or [Lighthouse](https://developers.google.com/web/tools/lighthouse), or even better, humans!

The dev toolbar aims to provide a quick and easy way to catch common issues during development, without needing to context-switch to a different tool. :::

### Settings

The Settings app allows you to configure options for the dev toolbar, such as verbose logging, disabling notifications, and adjusting its placement on your screen.

## Extending the dev toolbar

Astro integrations can add new apps to the dev toolbar, allowing you to extend it with custom tools that are specific to your project. You can find [more dev tool apps to install in the integrations directory](https://astro.build/integrations/?search=&categories%5B%5D=toolbar) or using the [Astro Menu](#astro-menu).

Install additional dev toolbar app integrations in your project just like any other [Astro integration](/en/guides/integrations/) according to its own installation instructions.

<RecipeLinks slugs={\["en/recipes/making-toolbar-apps"\]} />

## Disabling the dev toolbar

The dev toolbar is enabled by default for every site. You can choose to disable it for individual projects and/or users as needed.

### Per-project

To disable the dev toolbar for everyone working on a project, set `devToolbar: false` in the [Astro config file](/en/reference/configuration-reference/#devtoolbarenabled).

To enable the dev toolbar again, remove these lines from your configuration, or set `enabled: true`.

### Per-user

To disable the dev toolbar for yourself on a specific project, run the [`astro preferences`](/en/reference/cli-reference/#astro-preferences) command.

```
astro preferences disable devToolbar
```

To disable the dev toolbar in all Astro projects for a user on the current machine, add the `--global` flag when running `astro-preferences`:

```
astro preferences disable --global devToolbar
```

The dev toolbar can later be enabled with:

```
astro preferences enable devToolbar
```

## [E-commerce](https://docharvest.github.io/docs/astro/guides/ecommerce/)



## [Endpoints](https://docharvest.github.io/docs/astro/guides/endpoints/)

Contents

astro

Endpoints

Astro

Endpoints

Astro lets you create custom endpoints to serve any kind of data. You can use this to generate images, expose an RSS document, or use them as API Routes to build a full API for your site.

In statically-generated sites, your custom endpoints are called at build time to produce static files. If you opt in to [SSR](/en/guides/on-demand-rendering/) mode, custom endpoints turn into live server endpoints that are called on request. Static and SSR endpoints are defined similarly, but SSR endpoints support additional features.

## Static File Endpoints

To create a custom endpoint, add a `.js` or `.ts` file to the `/pages` directory. The `.js` or `.ts` extension will be removed during the build process, so the name of the file should include the extension of the data you want to create. For example, `src/pages/data.json.ts` will build a `/data.json` endpoint.

Endpoints export a `GET` function (optionally `async`) that receives a [context object](/en/reference/api-reference/) with properties similar to the `Astro` global. Here, it returns a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object with a `name` and `url`, and Astro will call this at build time and use the contents of the body to generate the file.

```
// Outputs: /builtwith.json

}
```

Since Astro v3.0, the returned `Response` object doesn't have to include the `encoding` property anymore. For example, to produce a binary `.png` image:

```

  return new Response(await response.arrayBuffer());
}
```

You can also get type safety in your endpoint functions using the `APIRoute` type with the `satisfies` operator:

Note that endpoints whose URLs include a file extension (e.g. `src/pages/sitemap.xml.ts`) can only be accessed without a trailing slash (e.g. `/sitemap.xml`), regardless of your [`build.trailingSlash`](/en/reference/configuration-reference/#trailingslash) configuration.

### `params` and Dynamic routing

Endpoints support the same [dynamic routing](/en/guides/routing/#dynamic-routes) features that pages do. Name your file with a bracketed parameter name and export a [`getStaticPaths()` function](/en/reference/routing-reference/#getstaticpaths). Then, you can access the parameter using the `params` property passed to the endpoint function:

```

const usernames = ["Sarah", "Chris", "Yan", "Elian"];

  return new Response(
    JSON.stringify({
      name: usernames[id],
    }),
  );
}) satisfies APIRoute;

}
```

This will generate four JSON endpoints at build time: `/api/0.json`, `/api/1.json`, `/api/2.json` and `/api/3.json`. Dynamic routing with endpoints works the same as it does with pages. In static mode, you can [pass props to the endpoint using `getStaticPaths()`](/en/reference/routing-reference/#data-passing-with-props). However, with on-demand rendering, since the endpoint is a function and not a component, passing props is not supported.

### `request`

All endpoints receive a `request` property, but in static mode, you only have access to `request.url`. This returns the full URL of the current endpoint and works the same as [Astro.request.url](/en/reference/api-reference/#request) does for pages.

```

}) satisfies APIRoute;
```

## Server Endpoints (API Routes)

Everything described in the static file endpoints section can also be used in SSR mode: files can export a `GET` function which receives a [context object](/en/reference/api-reference/) with properties similar to the `Astro` global.

But, unlike in `static` mode, when you enable on-demand rendering for a route, the endpoint will be built when it is requested. This unlocks new features that are unavailable at build time, and allows you to build API routes that listen for requests and securely execute code on the server at runtime.

Your routes will be rendered on demand by default in `server` mode. In `static` mode, you must opt out of prerendering for each custom endpoint with `export const prerender = false`.

<RecipeLinks slugs={\["en/recipes/call-endpoints" \]}/>

:::note Be sure to [enable an on-demand rendering mode](/en/guides/on-demand-rendering/) before trying these examples, and opt out of prerendering in `static` mode. :::

Server endpoints can access `params` without exporting `getStaticPaths`, and they can return a `Response` object, allowing you to set status codes and headers:

```

  const product = await getProduct(id);

  if (!product) {
    return new Response(null, {
      status: 404,
      statusText: "Not found",
    });
  }

  return new Response(JSON.stringify(product), {
    status: 200,
    headers: {
      "Content-Type": "application/json",
    },
  });
}) satisfies APIRoute;
```

This will respond to any request that matches the dynamic route. For example, if we navigate to `/helmet.json`, `params.id` will be set to `helmet`. If `helmet` exists in the mock product database, the endpoint will use a `Response` object to respond with JSON and return a successful [HTTP status code](https://developer.mozilla.org/en-US/docs/Web/API/Response/status). If not, it will use a `Response` object to respond with a `404`.

In SSR mode, certain providers require the `Content-Type` header to return an image. In this case, use a `Response` object to specify a `headers` property. For example, to produce a binary `.png` image:

```

  const buffer = Buffer.from(await response.arrayBuffer()); // requires `@types/node` in your dependencies for type safety

  return new Response(buffer, {
    headers: { "Content-Type": "image/png" },
  });
}) satisfies APIRoute;
```

### HTTP methods

In addition to the `GET` function, you can export a function with the name of any [HTTP method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods). When a request comes in, Astro will check the method and call the corresponding function.

You can also export an `ALL` function to match any method that doesn't have a corresponding exported function. If there is a request with no matching method, it will redirect to your site's [404 page](/en/basics/astro-pages/#custom-404-error-page).

```

}) satisfies APIRoute;

}) satisfies APIRoute;

}) satisfies APIRoute;

}) satisfies APIRoute;
```

If you define a `GET` function but no `HEAD` function, Astro will automatically handle `HEAD` requests by calling the `GET` function and stripping the body from the response.

<RecipeLinks slugs={\["en/recipes/captcha", "en/recipes/build-forms-api" \]}/>

### `request`

In SSR mode, the `request` property returns a fully usable [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) object that refers to the current request. This allows you to accept data and check headers:

```

    const name = body.name;
    
    return new Response(
      JSON.stringify({
        message: "Your name was: " + name,
      }),
      {
        status: 200,
      },
    );
  }
  
  return new Response(null, { status: 400 });
}) satisfies APIRoute;
```

### Redirects

The endpoint context exports a `redirect()` utility similar to `Astro.redirect`:

```

  const link = await getLinkUrl(id);

  if (!link) {
    return new Response(null, {
      status: 404,
      statusText: "Not found",
    });
  }

  return redirect(link, 307);
}) satisfies APIRoute;
```

## [Using environment variables](https://docharvest.github.io/docs/astro/guides/environment-variables/)

Contents

astro

Using environment variables

Astro

Using environment variables

Astro gives you access to [Vite's built-in environment variables support](#vites-built-in-support) and includes some [default environment variables for your project](#default-environment-variables) that allow you to access configuration values for your current project (e.g. `site`, `base`), whether your project is running in development or production, and more.

Astro also provides a way to [use and organize your environment variables with type safety](#type-safe-environment-variables). It is available for use inside the Astro context (e.g. Astro components, routes and endpoints, UI framework components, middleware), and managed with [a schema in your Astro configuration](/en/reference/configuration-reference/#env).

## Vite's built-in support

Astro uses Vite's built-in support for environment variables, which are statically replaced at build time, and lets you [use any of its methods](https://vite.dev/guide/env-and-mode.html) to work with them.

Note that while _all_ environment variables are available in server-side code, only environment variables prefixed with `PUBLIC_` are available in client-side code for security purposes.

```
SECRET_PASSWORD=password123
PUBLIC_ANYBODY=there
```

In this example, `PUBLIC_ANYBODY` (accessible via `import.meta.env.PUBLIC_ANYBODY`) will be available in server or client code, while `SECRET_PASSWORD` (accessible via `import.meta.env.SECRET_PASSWORD`) will be server-side only.

:::caution `.env` files are not loaded inside [configuration files](#in-the-astro-config-file). :::

### IntelliSense for TypeScript

By default, Astro provides a type definition for `import.meta.env` in `astro/client.d.ts`.

While you can define more custom env variables in `.env.[mode]` files, you may want to get TypeScript IntelliSense for user-defined env variables which are prefixed with `PUBLIC_`.

To achieve this, you can create an `env.d.ts` in `src/` to [extend the global types](/en/guides/typescript/#extending-global-types) and configure `ImportMetaEnv` like this:

```
interface ImportMetaEnv {
  readonly DB_PASSWORD: string;
  readonly PUBLIC_POKEAPI: string;
  // more env variables...
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}
```

## Default environment variables

Astro includes a few environment variables out of the box:

-   `import.meta.env.MODE`: The mode your site is running in. This is `development` when running `astro dev` and `production` when running `astro build`.
-   `import.meta.env.PROD`: `true` if your site is running in production; `false` otherwise.
-   `import.meta.env.DEV`: `true` if your site is running in development; `false` otherwise. Always the opposite of `import.meta.env.PROD`.
-   `import.meta.env.BASE_URL`: The base URL your site is being served from. This is determined by the [`base` config option](/en/reference/configuration-reference/#base).
-   `import.meta.env.SITE`: This is set to [the `site` option](/en/reference/configuration-reference/#site) specified in your project's `astro.config`.

Use them like any other environment variable.

```
const isProd = import.meta.env.PROD;
const isDev = import.meta.env.DEV;
```

## Setting environment variables

### `.env` files

Environment variables can be loaded from `.env` files in your project directory.

Just create a `.env` file in the project directory and add some variables to it.

```
# This will only be available when run on the server!
DB_PASSWORD="foobar"

# This will be available everywhere!
PUBLIC_POKEAPI="https://pokeapi.co/api/v2"
```

You can also add `.production`, `.development` or a custom mode name to the filename itself (e.g `.env.testing`, `.env.staging`). This allows you to use different sets of environment variables at different times.

The `astro dev` and `astro build` commands default to `"development"` and `"production"` modes, respectively. You can run these commands with the [`--mode` flag](/en/reference/cli-reference/#--mode-string) to pass a different value for `mode` and load the matching `.env` file.

This allows you to run the dev server or build your site connecting to different APIs:

\`\`\`shell # Run the dev server connected to a "staging" API npm run astro dev -- --mode staging

````
# Build a site that connects to a "production" API with additional debug information
npm run astro build -- --devOutput

# Build a site that connects to a "testing" API
npm run astro build -- --mode testing
```
````

\`\`\`shell # Run the dev server connected to a "staging" API pnpm astro dev --mode staging

````
# Build a site that connects to a "production" API with additional debug information
pnpm astro build --devOutput

# Build a site that connects to a "testing" API
pnpm astro build --mode testing
```
````

\`\`\`shell # Run the dev server connected to a "staging" API yarn astro dev --mode staging

````
# Build a site that connects to a "production" API with additional debug information
yarn astro build --devOutput

# Build a site that connects to a "testing" API
yarn astro build --mode testing
```
````

For more on `.env` files, [see the Vite documentation](https://vite.dev/guide/env-and-mode.html#env-files).

### In the Astro config file

Astro evaluates configuration files before it loads your other files. This means that you cannot use `import.meta.env` in `astro.config.mjs` to access environment variables that were set in `.env` files.

You can use `process.env` in a configuration file to access other environment variables, like those [set by the CLI](#using-the-cli).

You can also use [Vite's `loadEnv` helper](https://main.vite.dev/config/#using-environment-variables-in-config) to manually load `.env` files.

```

const { SECRET_PASSWORD } = loadEnv(process.env.NODE_ENV, process.cwd(), "");
```

:::note `pnpm` does not allow you to import modules that are not directly installed in your project. If you are using `pnpm`, you will need to install `vite` to use the `loadEnv` helper.

```
pnpm add -D vite
```

:::

### Using the CLI

You can also add environment variables as you run your project:

\`\`\`shell PUBLIC\_POKEAPI=https://pokeapi.co/api/v2 yarn run dev \`\`\` \`\`\`shell PUBLIC\_POKEAPI=https://pokeapi.co/api/v2 npm run dev \`\`\` \`\`\`shell PUBLIC\_POKEAPI=https://pokeapi.co/api/v2 pnpm run dev \`\`\`

## Getting environment variables

Environment variables in Astro are accessed with `import.meta.env`, using the [`import.meta` feature added in ES2020](https://tc39.es/ecma262/2020/#prod-ImportMeta), instead of `process.env`.

For example, use `import.meta.env.PUBLIC_POKEAPI` to get the `PUBLIC_POKEAPI` environment variable.

```
// When import.meta.env.SSR === true
const data = await db(import.meta.env.DB_PASSWORD);

// When import.meta.env.SSR === false
const data = fetch(`${import.meta.env.PUBLIC_POKEAPI}/pokemon/squirtle`);
```

When using SSR, environment variables can be accessed at runtime based on the SSR adapter being used. With most adapters you can access environment variables with `process.env`, but some adapters work differently. For the Deno adapter, you will use `Deno.env.get()`. See how to [access the Cloudflare runtime](/en/guides/integrations-guide/cloudflare/#cloudflare-runtime) to handle environment variables when using the Cloudflare adapter. Astro will first check the server environment for variables, and if they don't exist, Astro will look for them in `.env` files.

## Type safe environment variables

The `astro:env` API lets you configure a type-safe schema for [environment variables you have set](#setting-environment-variables). This allows you to indicate whether they should be available on the server or the client, and define their data type and additional properties.

Developing an adapter? See how to [make an adapter compatible with `astro:env`](/en/reference/adapter-reference/#envgetsecret).

### Basic Usage

#### Define your schema

To configure a schema, add the `env.schema` option to your Astro config:

```

  fetch(`${API_URL}/ping`)
</script>
```

### Variable types

There are three kinds of environment variables, determined by the combination of `context` (`"client"` or `"server"`) and `access` (`"secret"` or `"public"`) settings defined in your schema:

-   **Public client variables**: These variables end up in both your final client and server bundles, and can be accessed from both client and server through the `astro:env/client` module:
    
    ```
    import { API_URL } from "astro:env/client";
    ```
    
-   **Public server variables**: These variables end up in your final server bundle and can be accessed on the server through the `astro:env/server` module:
    
    ```
    import { PORT } from "astro:env/server";
    ```
    
-   **Secret server variables**: These variables are not part of your final bundle and can be accessed on the server through the `astro:env/server` module:
    
    ```
    import { API_SECRET } from "astro:env/server";
    ```
    
    By default, all secrets are validated whenever anything is imported from the `astro:env/server` module. This means, secrets may be validated even when they are not imported. You may need to [pass dummy environment variables](#setting-environment-variables) to satisfy this validation during the build.
    
    You can also enable validating secrets on start by [configuring `validateSecrets: true`](/en/reference/configuration-reference/#envvalidatesecrets).
    

:::note **Secret client variables** are not supported because there is no safe way to send this data to the client. Therefore, it is not possible to configure both `context: "client"` and `access: "secret"` in your schema. :::

### Data types

There are currently four data types supported: strings, numbers, enums, and booleans:

```

envField.string({
   // context & access
   optional: true,
   default: "foo",
})

envField.number({
   // context & access
   optional: true,
   default: 15,
})

envField.boolean({
   // context & access
   optional: true,
   default: true,
})

envField.enum({
   // context & access
   values: ["foo", "bar", "baz"],
   optional: true,
   default: "baz",
})
```

For a complete list of validation fields, see the [`envField` API reference](/en/reference/modules/astro-config/#envfield).

### Retrieving secrets dynamically

Despite defining your schema, you may want to retrieve the raw value of a given secret or to retrieve secrets not defined in your schema. In this case, you can use `getSecret()` exported from `astro:env/server`:

```

getSecret("FOO"); // string | undefined
```

Learn more in [the API reference](/en/reference/modules/astro-env/#getsecret).

### Limitations

`astro:env` is a virtual module which means it can only be used inside the Astro context. For example, you can use it in:

-   Middlewares
-   Astro routes and endpoints
-   Astro components
-   Framework components
-   Modules

You cannot use it in the following and will have to resort to `process.env`:

-   `astro.config.mjs`
-   Scripts

## [Using custom fonts](https://docharvest.github.io/docs/astro/guides/fonts/)

Contents

astro

Using custom fonts

Astro

Using custom fonts

This guide will show you how to add [web fonts](https://developer.mozilla.org/en-US/docs/Learn/CSS/Styling_text/Web_fonts) to your project and use them in your components.

Astro provides a way to use fonts from your filesystem and various font providers (e.g. Fontsource, Google) through a unified, [fully customizable](/en/reference/configuration-reference/#fonts), and type-safe API.

Web fonts can impact page performance at both load time and rendering time. This API helps you keep your site performant with automatic [web font optimizations](https://web.dev/learn/performance/optimize-web-fonts) including preload links, optimized fallbacks, and opinionated defaults. [See common usage examples](#examples).

The Fonts API focuses on performance and privacy by downloading and caching fonts so they're served from your site. This can avoid sending user data to third-party sites, and also ensures that a consistent set of fonts is available to all your visitors.

## Configuring custom fonts

Registering custom fonts for your Astro project is done through [the `fonts` option](/en/reference/configuration-reference/#fonts) in your Astro config.

For each font you want to use, you must specify its [name](/en/reference/configuration-reference/#fontname), a [CSS variable](/en/reference/configuration-reference/#fontcssvariable), and an Astro font provider.

Astro provides [built-in support for the most popular font providers](/en/reference/font-provider-reference/#built-in-providers): Adobe, Bunny, Fontshare, Fontsource, Google, Google Icons and NPM, as well as for using your own local font files. Additionally, you can [further customize your font configuration](#granular-font-configuration) to optimize performance and visitor experience.

### Using a local font file

This example will demonstrate adding a custom font using the font file `DistantGalaxy.woff2`.

1.  Add your font file inside the [`src/` directory](/en/basics/project-structure/#src), for example `src/assets/fonts/`.
    
2.  Create a new font family in your Astro config file using the [local font provider](/en/reference/font-provider-reference/#local) and specify the variants to be included:
    
    ```
    import { defineConfig, fontProviders } from "astro/config";
    
    export default defineConfig({
      fonts: [{
        provider: fontProviders.local(),
        name: "DistantGalaxy",
        cssVariable: "--font-distant-galaxy",
        options: {
          variants: [{
            src: ['./src/assets/fonts/DistantGalaxy.woff2'],
            weight: 'normal',
            style: 'normal'
          }]
        }
      }]
    });
    ```
    
3.  Your font is now configured and ready to be [added to your page head](#applying-custom-fonts) so that it can be used in your project.
    

### Using Fontsource

Astro supports [several font providers](/en/reference/font-provider-reference/#built-in-providers) out of the box, including support for [Fontsource](https://fontsource.org/) that simplifies using Google Fonts and other open-source fonts.

The following example will use Fontsource to add custom font support, but the process is similar for any of Astro's built-in font providers (e.g. [Adobe](https://fonts.adobe.com/), [Bunny](https://fonts.bunny.net/)).

1.  Find the font you want to use in [Fontsource's catalog](https://fontsource.org/). This example will use [Roboto](https://fontsource.org/fonts/roboto).
    
2.  Create a new font family in your Astro config file using the [Fontsource provider](/en/reference/font-provider-reference/#fontsource):
    
    ```
    import { defineConfig, fontProviders } from "astro/config";
    
    export default defineConfig({
      fonts: [{
        provider: fontProviders.fontsource(),
        name: "Roboto",
        cssVariable: "--font-roboto",
      }]
    });
    ```
    
3.  Your font is now configured and ready to be [added to your page head](#applying-custom-fonts) so that it can be used in your project.
    

## Applying custom fonts

After [a font is configured](#configuring-custom-fonts), it must be added to your page head with an identifying CSS variable. Then, you can use this variable when defining your page styles.

1.  Import and include the [`<Font />`](/en/reference/modules/astro-assets/#font-) component with the required `cssVariable` property in the head of your page, usually in a dedicated `Head.astro` component or in a [layout](/en/basics/layouts/) component directly:
    
    ```
    ---
    import { Font } from "astro:assets";
    ---
    
    <html>
      <head>
        <Font cssVariable="--font-distant-galaxy" />
      </head>
      <body>
        <slot />
      </body>
    </html>
    ```
    
2.  In any page rendered with that layout, including the layout component itself, you can now define styles with your font's `cssVariable` to apply your custom font.
    
    In the following example, the `<h1>` heading will have the custom font applied, while the paragraph `<p>` will not.
    
    ```
    ---
    import Layout from "../layouts/Layout.astro";
    ---
    <Layout>
      <h1>In a galaxy far, far away...</h1>
    
      <p>Custom fonts make my headings much cooler!</p>
    
      <style>
      h1 {
        font-family: var(--font-distant-galaxy);
      }
      </style>
    </Layout>
    ```
    

## Preloading fonts

Font preloading should be done sparingly, as it can block the loading of other important resources or download fonts that are unnecessary for the current page. Consider preloading only the most essential fonts, necessary for displaying content visible above the fold.

To preload a font, pass the [`preload` property](/en/reference/modules/astro-assets/#preload) to the corresponding `<Font />` component. If multiple files correspond to a font, you can also specify which one to preload by passing an array.

```
---

---

<html>
  <head>
    <Font cssVariable="--font-distant-galaxy" preload />
  </head>
  <body>
    <slot />
  </body>
</html>
```

## Register fonts in Tailwind

If you are using [Tailwind](/en/guides/styling/#tailwind) for styling, you will not apply your styles with the `font-face` CSS property.

Instead, after [configuring your custom font](#configuring-custom-fonts) and [adding it to your page head](#applying-custom-fonts), you will need to update your Tailwind configuration to register your font:

````
<Tabs>

<TabItem label="Tailwind CSS 4.0">

```css title="src/styles/global.css" ins={4} ins="inline"
@import "tailwindcss";

@theme inline {
  --font-sans: var(--font-roboto);
}
```

</TabItem>

<TabItem label="Tailwind CSS 3.0">

```js title="tailwind.config.mjs" ins={6-8}
/** @type {import("tailwindcss").Config} */
export default {
  content: ["./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}"],
  theme: {
    extend: {},
    fontFamily: {
      sans: ["var(--font-roboto)"]
    }
  },
  plugins: []
};
```

</TabItem>

</Tabs>
````

See [Tailwind's docs on adding custom font families](https://tailwindcss.com/docs/font-family#using-a-custom-value) for more information.

## Using variable fonts

To use [variable fonts](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_fonts/Variable_fonts_guide) in your project, specify the available weight range instead of individual weights in your provider's configuration.

When [using a local font file](#using-a-local-font-file), you can specify that the font is variable by setting the [`weight` property of the variant](/en/reference/font-provider-reference/#weight) to a string corresponding to the exact weight range available for the font.

The following example configures Inter as a local variable font with the available weight range:

When using [other providers (e.g. Fontsource)](#using-fontsource), that support variable fonts, you can request the variable version of a font by setting the [`weights` property](/en/reference/configuration-reference/#fontweights) with an array containing the exact range of weights available for the font.

The following example downloads [Fira Code from Fontsource](https://fontsource.org/fonts/fira-code) as a variable font with the available weight range:

## Customizing font fallbacks

Fallback fonts are used when the primary font has not yet loaded, contains missing characters, or cannot be loaded for any reason. When the fallback font differs significantly from the primary font, layout shifts may occur during page loading.

To avoid this, Astro automatically tries to generate optimized fallback fonts from the last [defined fallback](/en/reference/configuration-reference/#fontfallbacks) if it is a [generic font family](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/font-family#generic-name). It uses `sans-serif` by default, but it may not match the desired appearance of your primary font. You can adjust it in your font configuration:

You can also opt out of the default optimization by setting [`font.optimizedFallbacks`](/en/reference/configuration-reference/#fontoptimizedfallbacks) to `false` in your font configuration. Astro will then use the fallback fonts specified in your configuration without any additional automatic processing.

## Accessing font data programmatically

Astro exposes low-level APIs for accessing data programmatically:

-   Font family data through the [`fontData`](/en/reference/modules/astro-assets/#fontdata) object
-   Font file URLs with the [`experimental_getFontFileURL()`](/en/reference/modules/astro-assets/#experimental_getfontfileurl) function.

This can be useful for advanced use cases where you need direct access to font files, such as generating OpenGraph images with [Satori](https://github.com/vercel/satori) in an [API Route](/en/guides/endpoints/#server-endpoints-api-routes).

The `fontData` object gives you access to all font files downloaded by Astro for your project, along with their metadata. This means that you are responsible for filtering font files to find the specific file you need, and for fetching data after resolving URLs.

The following example generates an OpenGraph image in a static file endpoint, assuming that only [one font and its format have been configured](/en/reference/configuration-reference/#fontformats) with a [format supported by Satori](https://github.com/vercel/satori?tab=readme-ov-file#fonts):

```

  if (fontPath === undefined) {
    throw new Error("Cannot find the font path.");
  }

  const url = experimental_getFontFileURL(fontPath, context.url);
  const data = await fetch(url).then((res) => res.arrayBuffer());

  const svg = await satori(
    html`<div style="color: black;">hello, world</div>`,
    {
      width: 600,
      height: 400,
      fonts: [
        {
          name: "Roboto",
          data,
          weight: 400,
          style: "normal",
        },
      ],
    },
  );

  const pngBuffer = await sharp(Buffer.from(svg)) // requires `@types/node` in your dependencies for type safety
    .resize(600, 400)
    .png()
    .toBuffer();

  return new Response(new Uint8Array(pngBuffer), {
    headers: {
      "Content-Type": "image/png",
    },
  });
};
```

## Granular font configuration

A font family is defined by a combination of properties such as weights and styles (e.g. `weights: [500, 600]` and `styles: ["normal", "bold"]`), but you may want to download only certain combinations of these.

For greater control over which font files are downloaded, you can specify the same font (ie. with the same `cssVariable`, `name`, and `provider` properties) multiple times with different combinations. Astro will merge the results and download only the required files. For example, it is possible to download normal `500` and `600` while downloading only italic `500`:

## Caching

The Fonts API caching implementation was designed to be practical in development and efficient in production. During builds, font files are copied to the `_astro/fonts` output directory, so they can benefit from HTTP caching of static assets (usually a year).

To clear the cache in development, remove the `.astro/fonts` directory. To clear the build cache, remove the `node_modules/.astro/fonts` directory.

## Examples

Astro's font feature is based on flexible configuration options. Your own project's font configuration may look different from simplified examples, so the following are provided to show what various font configurations might look like when used in production.

## [Front-end frameworks](https://docharvest.github.io/docs/astro/guides/framework-components/)

Contents

astro

Front-end frameworks

Astro

Front-end frameworks

* * *

# Use React components directly in Astro!

\`\`\`

By default, your framework components will only render on the server, as static HTML. This is useful for templating components that are not interactive and avoids sending any unnecessary JavaScript to the client.

## Hydrating interactive components

A framework component can be made interactive (hydrated) using a [`client:*` directive](/en/reference/directives-reference/#client-directives). These are component attributes that determine when your component's JavaScript should be sent to the browser.

With all client directives except `client:only`, your component will first render on the server to generate static HTML. Component JavaScript will be sent to the browser according to the directive you chose. The component will then hydrate and become interactive.

```
---
// Example: hydrating framework components in the browser.

---
<!-- This component's JS will begin importing when the page loads -->
<InteractiveButton client:load />

<!-- This component's JS will not be sent to the client until
the user scrolls down and the component is visible on the page -->
<InteractiveCounter client:visible />

<!-- This component won't render on the server, but will render on the client when the page loads -->
<InteractiveModal client:only="svelte" />
```

The JavaScript framework (React, Svelte, etc.) needed to render the component will be sent to the browser along with the component's own JavaScript. If two or more components on a page use the same framework, the framework will only be sent once.

:::note\[Accessibility\] Most framework-specific accessibility patterns should work the same when these components are used in Astro. Be sure to choose a client directive that will ensure any accessibility-related JavaScript is properly loaded and executed at the appropriate time! :::

### Available hydration directives

There are several hydration directives available for UI framework components: `client:load`, `client:idle`, `client:visible`, `client:media={QUERY}` and `client:only={FRAMEWORK}`.

See our [directives reference](/en/reference/directives-reference/#client-directives) page for a full description of these hydration directives, and their usage.

## Mixing frameworks

You can import and render components from multiple frameworks in the same Astro component.

```
---
// Example: Mixing multiple framework components on the same page.

---
<div>
  <MySvelteComponent />
  <MyReactComponent />
  <MyVueComponent />
</div>
```

Astro will recognize and render your component based on its file extension. To distinguish between frameworks that use the same file extension, [additional configuration when rendering multiple JSX frameworks](/en/guides/integrations-guide/react/#combining-multiple-jsx-frameworks) (e.g. React and Preact) is required.

:::caution Only **Astro** components (`.astro`) can contain components from multiple frameworks. :::

## Passing props to framework components

You can pass props from Astro components to framework components:

```
---

---
<div>
  <TodoList initialTodos={["learn Astro", "review PRs"]} />
  <Counter startingCount={1} />
</div>
```

Props that are passed to interactive framework components [using a `client:*` directive](/en/reference/directives-reference/#client-directives) must be [serialized](https://developer.mozilla.org/en-US/docs/Glossary/Serialization): translated into a format suitable for transfer over a network, or storage. However, Astro does not serialize every type of data structure. Therefore, there are some limitations on what can be passed as props to hydrated components.

The following prop types are supported: plain object, `number`, `string`, `Array`, `Map`, `Set`, `RegExp`, `Date`, `BigInt`, `URL`, `Uint8Array`, `Uint16Array`, `Uint32Array`, and `Infinity`

Non-supported data structures passed to components, such as functions, can only be used during the component's server rendering and cannot be used to provide interactivity. For example, passing functions to hydrated components is not supported because Astro cannot pass functions from the server in a way that makes them executable on the client.

## Passing children to framework components

Inside of an Astro component, you **can** pass children to framework components. Each framework has its own patterns for how to reference these children: React, Preact, and Solid all use a special prop named `children`, while Svelte and Vue use the `<slot />` element.

```
---

---
<MyReactSidebar>
  <p>Here is a sidebar with some text and a button.</p>
</MyReactSidebar>
```

Additionally, you can use [Named Slots](/en/basics/astro-components/#named-slots) to group specific children together.

For React, Preact, and Solid, these slots will be converted to a top-level prop. Slot names using `kebab-case` will be converted to `camelCase`.

```
---

---
<MySidebar>
  <h2 slot="title">Menu</h2>
  <p>Here is a sidebar with some text and a button.</p>
  <ul slot="social-links">
    <li><a href="https://twitter.com/astrodotbuild">Twitter</a></li>
    <li><a href="https://github.com/withastro">GitHub</a></li>
  </ul>
</MySidebar>
```

```
// src/components/MySidebar.jsx
export default function MySidebar(props) {
  return (
    <aside>
      <header>{props.title}</header>
      <main>{props.children}</main>
      <footer>{props.socialLinks}</footer>
    </aside>
  )
}
```

For Svelte and Vue these slots can be referenced using a `<slot>` element with the `name` attribute. Slot names using `kebab-case` will be preserved.

```
// src/components/MySidebar.svelte
<aside>
  <header><slot name="title" /></header>
  <main><slot /></main>
  <footer><slot name="social-links" /></footer>
</aside>
```

## Nesting framework components

Inside of an Astro file, framework component children can also be hydrated components. This means that you can recursively nest components from any of these frameworks.

```
---

---
<MyReactSidebar>
  <p>Here is a sidebar with some text and a button.</p>
  <div slot="actions">
    <MyReactButton client:idle />
    <MySvelteButton client:idle />
  </div>
</MyReactSidebar>
```

:::caution Remember: framework component files themselves (e.g. `.jsx`, `.svelte`) cannot mix multiple frameworks. :::

This allows you to build entire "apps" in your preferred JavaScript framework and render them, via a parent component, to an Astro page.

:::note Astro components are always rendered to static HTML, even when they include framework components that are hydrated. This means that you can only pass props that don't do any HTML rendering. Passing React's "render props" to framework components from an Astro component will not work, because Astro components can’t provide the client runtime behavior that this pattern requires. Instead, use named slots. :::

## Can I use Astro components inside my framework components?

Any UI framework component becomes an "island" of that framework. These components must be written entirely as valid code for that framework, using only its own imports and packages. You cannot import `.astro` components in a UI framework component (e.g. `.jsx` or `.svelte`).

You can, however, use [the Astro `<slot />` pattern](/en/basics/astro-components/#slots) to pass static content generated by Astro components as children to your framework components **inside an `.astro` component**.

```
---

---
<MyReactComponent>
  <MyAstroComponent slot="name" />
</MyReactComponent>
```

## Can I hydrate Astro components?

If you try to hydrate an Astro component with a `client:` modifier, you will get an error.

[Astro components](/en/basics/astro-components/) are HTML-only templating components with no client-side runtime. But, you can use a `<script>` tag in your Astro component template to send JavaScript to the browser that executes in the global scope.

Learn more about [client-side `<script>` tags in Astro components](/en/guides/client-side-scripts/)

## [Images](https://docharvest.github.io/docs/astro/guides/images/)

Contents

astro

Images

Astro

Images

Astro provides several ways for you to use images on your site, whether they are stored locally inside your project, linked to from an external URL, or managed in a CMS or CDN.

Astro provides built-in [`<Image />`](#image-) and [`<Picture />`](#picture-) Astro components, [Markdown image syntax](#images-in-markdown-files) (`![]()`) processing, [SVG components](#svg-components), and [an image generating function](#generating-images-with-getimage) to optimize and/or transform your images. Additionally, you can configure [automatically resizing responsive images](#responsive-image-behavior) by default, or set responsive properties on individual image and picture components.

You can always choose to use images and SVG files using native HTML elements in `.astro` or Markdown files, or the standard way for your file type (e.g. `<img />` in MDX and JSX). However, Astro does not perform any processing or optimization of these images.

There is also no native video support in Astro, and we recommend choosing a [hosted video service](/en/guides/media/) to handle the demands of optimizing and streaming video content.

See the full API reference for the [`<Image />`](/en/reference/modules/astro-assets/#image-) and [`<Picture />`](/en/reference/modules/astro-assets/#picture-) components.

## Where to store images

### `src/` vs `public/`

We recommend that local images are kept in `src/` when possible so that Astro can transform, optimize, and bundle them. Files in the `public/` directory are always served or copied into the build folder as-is, with no processing.

Your local images stored in `src/` can be used by all files in your project: `.astro`, `.md`, `.mdx`, `.mdoc`, and other UI frameworks as file imports. Images can be stored in any folder, including alongside your content.

Store your images in the `public/` folder if you want to avoid any processing. These images are available to your project files as URL paths on your domain and allow you to have a direct public link to them. For example, your site favicon will commonly be placed in the root of this folder where browsers can identify it.

### Remote images

You can also choose to store your images remotely, in a [content management system (CMS)](/en/guides/cms/) or [digital asset management (DAM)](/en/guides/media/) platform. Astro can fetch your data remotely using APIs or display images from their full URL path.

For extra protection when dealing with external sources, Astro's image components and helper function will only process (e.g. optimize, transform) images from [authorized image sources specified in your configuration](#authorizing-remote-images). Remote images from other sources will be displayed with no processing.

## Images in `.astro` files

**Options:** `<Image />`, `<Picture />`, `<img>`, `<svg>`, SVG components

Astro's templating language allows you to render optimized images with the Astro [`<Image />`](/en/reference/modules/astro-assets/#image-) component and generate multiple sizes and formats with the Astro [`<Picture />`](/en/reference/modules/astro-assets/#picture-) component. Both components also accept [responsive image properties](#responsive-image-behavior) for resizing based on container size and responding to device screen size and resolution.

Additionally, you can import and use [SVG files as Astro components](#svg-components) in `.astro` components.

All native HTML tags, including `<img>` and `<svg>`, are also available in `.astro` components. [Images rendered with HTML tags](#display-unprocessed-images-with-the-html-img-tag) will not be processed (e.g. optimized, transformed) and will be copied into your build folder as-is.

For all images in `.astro` files, **the value of the image `src` attribute is determined by the location of your image file**:

-   A local image from your project `src/` folder uses an import from the file's relative path.
    
    The image and picture components use the named import directly (e.g. `src={rocket}`), while the `<img>` tag uses the `src` object property of the import (e.g. `src={rocket.src}`).
    
-   Remote and `public/` images use a URL path.
    
    Provide a full URL for remote images (e.g. `src="https://www.example.com/images/my-remote-image.jpg"`), or a relative URL path on your site that corresponds to your file's location in your `public/` folder (e.g. `src="/images/my-public-image.jpg"` for an image located in `public/images/my-public-image.jpg`).
    

```
---

---
<Image src={localBirdImage} alt="A bird sitting on a nest of eggs." />
<Image src="/images/bird-in-public-folder.jpg" alt="A bird." width="50" height="50" />
<Image src="https://example.com/remote-bird.jpg" alt="A bird." width="50" height="50" />

<img src={localBirdImage.src} alt="A bird sitting on a nest of eggs.">
<img src="/images/bird-in-public-folder.jpg" alt="A bird.">
<img src="https://example.com/remote-bird.jpg" alt="A bird.">
```

See the full API reference for the [`<Image />`](/en/reference/modules/astro-assets/#image-) and [`<Picture />`](/en/reference/modules/astro-assets/#picture-) components including required and optional properties.

<RecipeLinks slugs={\["en/recipes/dynamically-importing-images" \]}/>

## Images in Markdown files

**Options:** `![]()`, `<img>` (with public or remote images)

Use standard Markdown `![alt](src)` syntax in your `.md` files. Your local images stored in `src/` and remote images will be processed and optimized. When you [configure responsive images globally](/en/reference/configuration-reference/#imagelayout), these images will also be [responsive](#responsive-image-behavior).

Images stored in the `public/` folder are never optimized.

```
<!-- src/pages/post-1.md -->

# My Markdown Page

<!-- Local image stored in src/assets/ -->
<!-- Use a relative file path or import alias -->
![A starry night sky.](../assets/stars.png)

<!-- Image stored in public/images/ -->
<!-- Use the file path relative to public/ -->
![A starry night sky.](/images/stars.png)

<!-- Remote image on another server -->
<!-- Use the full URL of the image -->
![Astro](https://example.com/images/remote-image.png)
```

The HTML `<img>` tag can also be used to display images stored in `public/` or remote images without any image optimization or processing. However, `<img>` is not supported for your local images in `src`.

The `<Image />` and `<Picture />` 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

**Options:** `<Image />`, `<Picture />`, `<img />`, `![]()`, SVG components

You can use Astro's `<Image />` and `<Picture />` components in your `.mdx` files by importing both the component and your image. Use them just as they are [used in `.astro` files](#images-in-astro-files). The JSX `<img />` tag is also supported for unprocessed images and [uses the same image import as the HTML `<img>` tag](#display-unprocessed-images-with-the-html-img-tag).

Additionally, there is support for [standard Markdown `![alt](src)` syntax](#images-in-markdown-files) with no import required.

```
---
title: My Page title
---

# My MDX Page

// Local image stored in the same folder
![Houston in the wild](houston.png)

// Local image stored in src/assets/
<Image src={rocket} alt="A rocketship in space." />
<img src={rocket.src} alt="A rocketship in space." />
![A rocketship in space](../assets/rocket.png)

// Image stored in public/images/
<Image src="/images/stars.png" alt="A starry night sky." />
<img src="/images/stars.png" alt="A starry night sky." />
![A starry night sky.](/images/stars.png)

// Remote image on another server
<Image src="https://example.com/images/remote-image.png" />
<img src="https://example.com/images/remote-image.png" />
![Astro](https://example.com/images/remote-image.png)
```

See the full API reference for the [`<Image />`](/en/reference/modules/astro-assets/#image-) and [`<Picture />`](/en/reference/modules/astro-assets/#picture-) components.

## Images in UI framework components

**Image options:** the framework's own image syntax (e.g. `<img />` in JSX, `<img>` in Svelte)

[Local images must first be imported](#display-unprocessed-images-with-the-html-img-tag) to access their image properties such as `src`. Then, they can be rendered as you normally would in that framework's own image syntax:

```

</script>

<img src={stars.src} alt="A starry night sky." />
```

Astro components (e.g. `<Image />`, `<Picture />`, SVG components) are unavailable inside UI framework components because [a client island must contain only valid code for its own framework](/en/guides/framework-components/#can-i-use-astro-components-inside-my-framework-components).

But, you can pass the static content generated by these components to a framework component inside a `.astro` file [as children](/en/guides/framework-components/#passing-children-to-framework-components) or using a [named `<slot/>`](/en/guides/framework-components/#can-i-use-astro-components-inside-my-framework-components):

```
---

---

<ReactComponent>
  <Image src={stars} alt="A starry night sky." />
</ReactComponent>
```

## Astro components for images

Astro provides two built-in Astro components for images (`<Image />` and `<Picture />`) and also allows you to import SVG files and use them as Astro components. These components may be used in any files that can import and render `.astro` components.

### `<Image />`

Use the built-in `<Image />` Astro component to display optimized versions of:

-   your local images located within the `src/` folder
-   [configured remote images](#authorizing-remote-images) from authorized sources

`<Image />` can transform a local or authorized remote image's dimensions, file type, and quality for control over your displayed image. This transformation happens at build time for prerendered pages. When your page is rendered on demand, this transformation will occur on the fly when the page is viewed. The resulting `<img>` tag includes `alt`, `loading`, and `decoding` attributes and infers image dimensions to avoid Cumulative Layout Shift (CLS).

:::note\[What is Cumulative Layout Shift?\] [Cumulative Layout Shift (CLS)](https://web.dev/cls/) is a Core Web Vital metric for measuring how much content shifted on your page during loading. The `<Image />` component optimizes for CLS by automatically setting the correct `width` and `height` for your images. :::

```
---
// import the Image component and the image

---

<!-- `alt` is mandatory on the Image component -->
<Image src={myImage} alt="" class="my-class" />
```

```
<!-- Prerendered output -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  class="my-class"
  alt=""
/>
```

:::tip You can also use the `<Image />` component for images in the `public/` folder, or remote images not specifically configured in your project, even though these images will not be optimized or processed. The resulting image will be the same as using the HTML `<img>`.

However, using the image component for all images provides a consistent authoring experience and prevents Cumulative Layout Shift (CLS) even for your unoptimized images. :::

### `<Picture />`

Use the built-in `<Picture />` Astro component to generate a `<picture>` tag with multiple formats and/or sizes of your image. This allows you to specify preferred file formats to display and at the same time, provide a fallback format. Like the [`<Image />` component](#image-), images will be processed at build time for prerendered pages. When your page is rendered on demand, processing will occur on the fly when the page is viewed.

The following example uses the `<Picture />` component to transform a local `.png` file into a web-friendly `avif` and `webp` format as well as the `.png` `<img>` that can be displayed as a fallback when needed:

```
---

---
<Image src={myImage} alt="A description of my image." layout='constrained' width={800} height={600} />
```

This `<Image />` component will generate the following HTML output on a prerendered page:

```
<img
  src="/_astro/my_image.hash3.webp"
  srcset="/_astro/my_image.hash1.webp 640w,
      /_astro/my_image.hash2.webp 750w,
      /_astro/my_image.hash3.webp 800w,
      /_astro/my_image.hash4.webp 828w,
      /_astro/my_image.hash5.webp 1080w,
      /_astro/my_image.hash6.webp 1280w,
      /_astro/my_image.hash7.webp 1600w"
  alt="A description of my image"
  sizes="(min-width: 800px) 800px, 100vw"
  loading="lazy"
  decoding="async"
  fetchpriority="auto"
  width="800"
  height="600"
  style="--fit: cover; --pos: center;"
  data-astro-image="constrained"
>
```

#### Responsive image styles

Setting [`image.responsiveStyles: true`](/en/reference/configuration-reference/#imageresponsivestyles) applies a small number of global styles to ensure that your images resize correctly. In most cases, you will want to enable these as a default; your images will not be responsive without additional styles.

However, if you prefer to handle responsive image styling yourself, or need to [override these defaults when using Tailwind 4](#responsive-images-with-tailwind-4), leave the default `false` value configured.

The global styles applied by Astro will depend on the layout type, and are designed to produce the best result for the generated `srcset` and `sizes` attributes. These are the default styles:

```
:where([data-astro-image]) {
	object-fit: var(--fit);
	object-position: var(--pos);
}
:where([data-astro-image='full-width']) {
	width: 100%;
}
:where([data-astro-image='constrained']) {
	max-width: 100%;
}
```

The styles use the [`:where()` pseudo-class](https://developer.mozilla.org/en-US/docs/Web/CSS/:where), which has a [specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascade/Specificity) of 0, meaning that it is easy to override with your own styles. Any CSS selector will have a higher specificity than `:where()`, so you can easily override the styles by adding your own styles to target the image.

You can override the `object-fit` and `object-position` styles on a per-image basis by setting the `fit` and `position` props on the `<Image />` or `<Picture />` component.

#### Responsive images with Tailwind 4

Tailwind 4 is compatible with Astro's default responsive styles. However, Tailwind uses [cascade layers](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer), meaning that its rules are always lower specificity than rules that don't use layers, including Astro's responsive styles. Therefore, Astro's styling will take precedence over Tailwind styling. To use Tailwind rules instead of Astro's default styling, do not enable [Astro's default responsive styles](/en/reference/configuration-reference/#imageresponsivestyles).

### SVG components

Astro allows you to import SVG files and use them as Astro components. Astro will inline the SVG content into your HTML output.

Reference the default import of any local `.svg` file. Since this import is treated as an Astro component, you must use the same conventions (e.g. capitalization) as when [using dynamic tags](/en/reference/astro-syntax/#dynamic-tags).

```
---

---

<Logo />
```

Your SVG component, like `<Image />` or any other Astro component, is unavailable inside UI framework components, but can [be passed to a framework component](#images-in-ui-framework-components) inside a `.astro` component.

#### SVG component attributes

You can pass props such as `width`, `height`, `fill`, `stroke`, and any other attribute accepted by the [native `<svg>` element](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/svg). These attributes will automatically be applied to the underlying `<svg>` element. If a property is present in the original `.svg` file and is passed to the component, the value passed to the component will override the original value.

```
---

---

<Logo width={64} height={64} fill="currentColor" />
```

#### `SvgComponent` Type

You can also enforce type safety for your `.svg` assets using the `SvgComponent` type:

```
---

interface Link {
  url: string;
  text: string;
  icon: SvgComponent;
}

const links: Link[] = [
  {
    url: "/",
    text: "Home",
    icon: HomeIcon,
  },
];
---
```

### Creating custom image components

You can create a custom, reusable image component by wrapping the `<Image />` or `<Picture/>` component in another Astro component. This allows you to set default attributes and styles only once.

For example, you could create a component for your blog post images that receives attributes as props and applies consistent styles to each image:

```
---

const { alt, src, ...attrs } = Astro.props;
---

<Image alt={alt} src={src} {...attrs} />

<style>
  img {
    margin-block: 2.5rem;
    border-radius: 0.75rem;
  }
</style>
```

## Display unprocessed images with the HTML `<img>` tag

The [Astro template syntax](/en/reference/astro-syntax/) also supports writing an `<img>` tag directly, with full control over its final output. These images will not be processed and optimized. It accepts all HTML `<img>` tag properties, and the only required property is `src`. However, it is strongly recommended to include [the `alt` property for accessibility](#alt-text).

### images in `src/`

Local images must be imported from the relative path from the existing `.astro` file, or you can configure and use an [import alias](/en/guides/imports/#aliases). Then, you can access the image's `src` and other properties to use in the `<img>` tag.

Imported image assets match the [`ImageMetadata` type](/en/reference/modules/astro-assets/#imagemetadata-1) and have the following signature:

```
interface ImageMetadata {
  src: string;
  width: number;
  height: number;
  format: string;
}
```

The following example uses the image's own `height` and `width` properties to avoid Cumulative Layout Shift (CLS) and improve Core Web Vitals:

```
---
// import local images

---
// access the image properties
<img src={myDog.src} width={myDog.width} height={myDog.height} alt="A barking dog." />
```

### Images in `public/`

For images located within `public/` use the image's file path relative to the public folder as the `src` value:

```
<img src="/images/public-cat.jpg" alt="A sleeping cat." >
```

### Remote images

For remote images, use the image's full URL as the `src` value:

```
<img src="https://example.com/remote-cat.jpg" alt="A sleeping cat." >
```

### Choosing `<Image />` vs `<img>`

The `<Image />` component optimizes your image and infers width and height (for images it can process) based on the original aspect ratio to avoid CLS. It is the preferred way to use images in `.astro` files whenever possible.

Use the HTML `<img>` element when you cannot use the `<Image />` component, for example:

-   for unsupported image formats
-   when you do not want your image optimized by Astro
-   to access and change the `src` attribute dynamically client-side

## Using Images from a CMS or CDN

Image CDNs work with [all Astro image options](#images-in-astro-files). Use an image's full URL as the `src` attribute in the `<Image />` component, an `<img>` tag, or in Markdown notation. For image optimization with remote images, also [configure your authorized domains or URL patterns](#authorizing-remote-images).

Alternatively, the CDN may provide its own SDKs to more easily integrate in an Astro project. For example:

-   Cloudinary supports an [Astro SDK](https://astro.cloudinary.dev/) which allows you to easily drop in images with their `CldImage` component or a [Node.js SDK](https://cloudinary.com/documentation/node_integration) that can generate URLs to use with an `<img>` tag in a Node.js environment.
-   ImageKit provides an [Astro integration](https://github.com/imagekit-developer/imagekit-astro) that registers an image service. This means Astro's built-in `<Image />` and `<Picture />` components, along with Markdown `![]()` and MDX images, are all routed through ImageKit automatically. It adds CDN delivery, automatic AVIF/WebP conversion, responsive `srcset`, and on-the-fly transformations without changing your existing image syntax.

See the full API reference for the [`<Image />`](/en/reference/modules/astro-assets/#image-) and [`<Picture />`](/en/reference/modules/astro-assets/#picture-) components.

## Authorizing remote images

You can configure lists of authorized image source URL domains and patterns for image optimization using [`image.domains`](/en/reference/configuration-reference/#imagedomains) and [`image.remotePatterns`](/en/reference/configuration-reference/#imageremotepatterns). This configuration is an extra layer of safety to protect your site when showing images from an external source.

Remote images from other sources will not be optimized, but using the `<Image />` component for these images will prevent Cumulative Layout Shift (CLS).

For example, the following configuration will only allow remote images from `astro.build` to be optimized:

```
// astro.config.mjs
```

The following configuration will only allow remote images from HTTPS hosts:

```
// astro.config.mjs
```

## Images in content collections

You can declare an associated image for a content collections entry, such as a blog post's cover image, in your frontmatter using its path relative to the current folder:

```
---
title: "My first blog post"
cover: "./firstpostcover.jpeg" # will resolve to "src/content/blog/firstpostcover.jpeg"
coverAlt: "A photograph of a sunset behind a mountain range."
---

This is a blog post
```

The `image` helper for the content collections schema lets you validate and import the image.

```

const blogCollection = defineCollection({
	schema: ({ image }) => z.object({
		title: z.string(),
		cover: image(),
		coverAlt: z.string(),
	}),
});
```

The image will be imported and transformed into metadata, allowing you to pass it as a `src` to `<Image/>`, `<img>`, or `getImage()` in an Astro component.

The example below shows a blog index page that renders the cover photo and title of each blog post from the previous schema:

```
---

const allBlogPosts = await getCollection("blog");
---

{
	allBlogPosts.map((post) => (
		<div>
			<Image src={post.data.cover} alt={post.data.coverAlt} />
			<h2>
				<a href={"/blog/" + post.id}>{post.data.title}</a>
			</h2>
		</div>
	))
}
```

## Generating images with `getImage()`

The `getImage()` function is intended for generating images destined to be used somewhere else than directly in HTML, for example in an [API Route](/en/guides/endpoints/#server-endpoints-api-routes). When you need options that the `<Picture>` and `<Image>` components do not currently support, you can use the `getImage()` function to create your own custom `<Image />` component.

`getImage()` can only be used on the server. If you need to use the resulting image URL on the client (e.g. in a client-side script or framework component), call `getImage()` inside the frontmatter and pass the resulting `src` to the client:

```
---

const optimizedBackground = await getImage({ src: myBackground, format: "avif" });
---

<div id="background" data-src={optimizedBackground.src}></div>

<script>
  const src = document.getElementById("background")?.dataset.src;
  // use src client-side as needed
</script>
```

See more in the [`getImage()` reference](/en/reference/modules/astro-assets/#getimage).

<RecipeLinks slugs={\["en/recipes/build-custom-img-component" \]}/>

## Alt Text

Not all users can see images in the same way, so accessibility is an especially important concern when using images. Use the `alt` attribute to provide [descriptive alt text](https://www.w3.org/WAI/tutorials/images/) for images.

This attribute is required for both the `<Image />` and `<Picture />` components. If no alt text is provided, a helpful error message will be provided reminding you to include the `alt` attribute.

If the image is merely decorative (i.e. doesn’t contribute to the understanding of the page), set `alt=""` so that screen readers know to ignore the image.

## Default image service

[Sharp](https://github.com/lovell/sharp) is the default image service used for `astro:assets`. You can further configure the image service using the [`image.service`](/en/reference/configuration-reference/#imageservice) option.

:::note When using a [strict package manager](https://pnpm.io/pnpm-vs-npm#npms-flat-tree) like `pnpm`, you may need to manually install Sharp into your project even though it is an Astro dependency:

```
pnpm add sharp
```

:::

### Configure no-op passthrough service

If your [adapter](https://astro.build/integrations/?search=&categories%5B%5D=adapters) does not support Astro's built-in Sharp image optimization (e.g. Cloudflare), you can configure a no-op image service to allow you to use the `<Image />` and `<Picture />` components. Note that Astro does not perform any image transformation and processing in these environments. However, you can still enjoy the other benefits of using `astro:assets`, including no Cumulative Layout Shift (CLS), the enforced `alt` attribute, and a consistent authoring experience.

Configure the `passthroughImageService()` to avoid Sharp image processing:

## Asset Caching

Astro stores processed image assets in a cache directory during site builds for both local and [remote images from authorized sources](#authorizing-remote-images). By preserving the cache directory between builds, processed assets are reused, improving build time and bandwidth usage.

The default cache directory is `./node_modules/.astro`, however this can be changed using the [`cacheDir`](/en/reference/configuration-reference/#cachedir) configuration setting.

### Remote Images

Remote images in the asset cache are managed based on [HTTP Caching](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching), and respect the [Cache-Control header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) returned by the remote server. Images are cached if the Cache-Control header allows, and will be used until they are no longer [fresh](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching#fresh_and_stale_based_on_age).

#### Revalidation

[Revalidation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching#validation) reduces bandwidth usage and build time by checking with the remote server whether an expired cached image is still up-to-date. If the server indicates that the image is still fresh, the cached version is reused, otherwise the image is redownloaded.

Revalidation requires that the remote server send [Last-Modified](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Last-Modified) and/or [Etag (entity tag)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) headers with its responses. This feature is available for remote servers that support the [If-Modified-Since](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Modified-Since) and [If-None-Match](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-None-Match) headers.

## Community Integrations

There are several third-party [community image integrations](https://astro.build/integrations?search=images) for optimizing and working with images in your Astro project.

## [Imports reference](https://docharvest.github.io/docs/astro/guides/imports/)

Contents

astro

Imports reference

Astro

Imports reference

````

JavaScript can be imported using normal ESM `import` & `export` syntax.

:::note[Importing JSX files]

An appropriate [UI framework](/en/guides/framework-components/) ([React](/en/guides/integrations-guide/react/), [Preact](/en/guides/integrations-guide/preact/), or [Solid](/en/guides/integrations-guide/solid-js/)) is required to render JSX/TSX files.
Use `.jsx`/`.tsx` extensions where appropriate, as Astro does not support JSX in `.js`/`.ts` files.

:::

### TypeScript

```js
````

Astro includes built-in support for [TypeScript](https://www.typescriptlang.org/). You can import `.ts` and `.tsx` files directly in your Astro project, and even write TypeScript code directly inside your [Astro component script](/en/basics/astro-components/#the-component-script) and any [script tags](/en/guides/client-side-scripts/).

**Astro doesn't perform any type checking itself.** Type checking should be taken care of outside of Astro, either by your IDE or through a separate script. For type checking Astro files, the [`astro check` command](/en/reference/cli-reference/#astro-check) is provided.

:::note\[TypeScript and file extensions\] Per [TypeScript's module resolution rules](https://www.typescriptlang.org/docs/handbook/module-resolution.html), `.ts` and `.tsx` file extensions should not be used when importing TypeScript files. Instead, either use `.js`/`.jsx` file extensions or completely omit the file extension.

```

---
```

If a package was published using a legacy format, Astro will try to convert the package to ESM so that `import` statements work. In some cases, you may need to adjust your [`vite` config](/en/reference/configuration-reference/#vite) for it to work.

:::caution Some packages rely on a browser environment. Astro components runs on the server, so importing these packages in the frontmatter may [lead to errors](/en/guides/troubleshooting/#document-or-window-is-not-defined). :::

### JSON

```
// Load the JSON object via the default export
```

Astro supports importing JSON files directly into your application. Imported files return the full JSON object in the default import.

### CSS

```
// Load and inject 'style.css' onto the page
```

Astro supports importing CSS files directly into your application. Imported styles expose no exports, but importing one will automatically add those styles to the page. This works for all CSS files by default, and can support compile-to-CSS languages like Sass & Less via plugins.

Read more about advanced CSS import use cases such as a direct URL reference for a CSS file, or importing CSS as a string in the [Styling guide](/en/guides/styling/#advanced).

### CSS Modules

```
// 1. Converts './style.module.css' classnames to unique, scoped values.
// 2. Returns an object mapping the original classnames to their final, scoped value.

// This example uses JSX, but you can use CSS Modules with any framework.
return <div className={styles.error}>Your Error Message</div>;
```

Astro supports CSS Modules using the `[name].module.css` naming convention. Like any CSS file, importing one will automatically apply that CSS to the page. However, CSS Modules export a special default `styles` object that maps your original classnames to unique identifiers.

CSS Modules help you enforce component scoping & isolation on the frontend with uniquely-generated class names for your stylesheets.

### Other Assets

```
// Returns an object with `src` and other properties

// HTML or UI Framework components use this to render the image
<img src={imgReference.src} alt="image description" />;

// The Astro `<Image />` and `<Picture />` components access `src` by default
<Image src={imgReference} alt="image description">
```

All other assets not explicitly mentioned above can be imported via ESM `import` and will return a URL reference to the final built asset (e.g. `/_astro/my-video.C7vXpQtF.mp4`) instead of an object.

This can be useful for referencing non-JS assets by URL, like creating a video element with a `src` attribute pointing to that image.

It can also be useful to place images and other assets in the `public/` folder as explained on the [project-structure page](/en/basics/project-structure/#public).

Read more about appending Vite import parameters (e.g. `?url`, `?raw`) in [Vite's static asset handling guide](https://vite.dev/guide/assets.html).

:::note Adding **alt text** to `<img>` tags is encouraged for accessibility! Don't forget to add an `alt="a helpful description"` attribute to your image elements. You can just leave the attribute empty if the image is purely decorative. :::

## Aliases

An **alias** is a way to create shortcuts for your imports.

Aliases can help improve the development experience in codebases with many directories or relative imports.

```
---

---
```

In this example, a developer would need to understand the tree relationship between `src/pages/about/company.astro`, `src/components/controls/Button.astro`, and `src/assets/logo.png`. And then, if the `company.astro` file were to be moved, these imports would also need to be updated.

You can add import aliases in `tsconfig.json`.

```
{
  "compilerOptions": {
    "paths": {
      "@components/*": ["./src/components/*"],
      "@assets/*": ["./src/assets/*"]
    }
  }
}
```

The development server will automatically restart after this configuration change. You can now import using the aliases anywhere in your project:

```
---

---
```

## `import.meta.glob()`

[Vite's `import.meta.glob()`](https://vite.dev/guide/features.html#glob-import) is a way to import many files at once using glob patterns to find matching file paths.

`import.meta.glob()` takes a relative [glob pattern](#glob-patterns) matching the local files you'd like to import as a parameter. It returns an array of each matching file's exports. To load all matched modules up front, pass `{ eager: true }` as the second argument:

```
---
// imports all files that end with `.md` in `./src/pages/post/`
const matches = import.meta.glob('../pages/post/*.md', { eager: true }); 
const posts = Object.values(matches);
---
<!-- Renders an <article> for the first 5 blog posts -->
<div>
{posts.slice(0, 4).map((post) => (
  <article>
    <h2>{post.frontmatter.title}</h2>
    <p>{post.frontmatter.description}</p>
    <a href={post.url}>Read more</a>
  </article>
))}
</div>
```

Astro components imported using `import.meta.glob` are of type [`AstroInstance`](#astro-files). You can render each component instance using its `default` property:

```
---
// imports all files that end with `.astro` in `./src/components/`
const components = Object.values(import.meta.glob('../components/*.astro', { eager: true }));
---
<!-- Display all of our components -->
{components.map((component) => (
  <div>
    <component.default size={24} />
  </div>
))}
```

### Supported Values

Vite's `import.meta.glob()` function only supports static string literals. It does not support dynamic variables and string interpolation.

A common workaround is to instead import a larger set of files that includes all the files you need, then filter them:

```
---
// src/components/featured.astro
const { postSlug } = Astro.props;
const pathToMyFeaturedPost = `src/pages/blog/${postSlug}.md`;

const posts = Object.values(import.meta.glob("../pages/blog/*.md", { eager: true }));
const myFeaturedPost = posts.find(post => post.file.includes(pathToMyFeaturedPost));
---

<p>
  Take a look at my favorite post, <a href={myFeaturedPost.url}>{myFeaturedPost.frontmatter.title}</a>!
</p>
```

### Import type utilities

#### Markdown files

Markdown files loaded with `import.meta.glob()` return the following `MarkdownInstance` interface:

```

  /* The absolute file path of this file */
	file: string;
  /* The rendered path of this file */
	url: string | undefined;
  /* Astro Component that renders the contents of this file */
	Content: AstroComponentFactory;
  /** (Markdown only) Raw Markdown file content, excluding layout HTML and YAML/TOML frontmatter */
	rawContent(): string;
  /** (Markdown only) Markdown file compiled to HTML, excluding layout HTML */
	compiledContent(): string;
  /* Function that returns an array of the h1...h6 elements in this file */
	getHeadings(): Promise<{ depth: number; slug: string; text: string }[]>;
	default: AstroComponentFactory;
}
```

You can optionally provide a type for the `frontmatter` variable using a TypeScript generic.

```
---

interface Frontmatter {
    title: string;
    description?: string;
}

const posts = Object.values(import.meta.glob<MarkdownInstance<Frontmatter>>('./posts/**/*.md', { eager: true }));
---

<ul>
  {posts.map(post => <li>{post.frontmatter.title}</li>)}
</ul>
```

#### Astro files

Astro files have the following interface:

```

  /* The URL for this file (if it is in the pages directory) */
	url: string | undefined;
	default: AstroComponentFactory;
}
```

#### Other files

Other files may have various different interfaces, but `import.meta.glob()` accepts a TypeScript generic if you know exactly what an unrecognized file type contains.

```
---
interface CustomDataFile {
  default: Record<string, any>;
}
const data = import.meta.glob<CustomDataFile>('../data/**/*.js');
---
```

### Glob Patterns

A glob pattern is a file path that supports special wildcard characters. This is used to reference multiple files in your project at once.

For example, the glob pattern `./pages/**/*.{md,mdx}` starts within the pages subdirectory, looks through all of its subdirectories (`/**`), and matches any filename (`/*`) that ends in either `.md` or `.mdx` (`.{md,mdx}`).

#### Glob Patterns in Astro

To use with `import.meta.glob()`, the glob pattern must be a string literal and cannot contain any variables.

Additionally, glob patterns must begin with one of the following:

-   `./` (to start in the current directory)
-   `../` (to start in the parent directory)
-   `/` (to start at the root of the project)

[Read more about the glob pattern syntax](https://github.com/micromatch/picomatch#globbing-features).

### `import.meta.glob()` vs `getCollection()`

[Content collections](/en/guides/content-collections/) provide [performant, content-focused APIs](/en/reference/modules/astro-content/) for loading multiple files instead of `import.meta.glob()`. Use `getCollection()` and `getLiveCollection()` to query your collections and return content entries.

## WASM

```
// Loads and initializes the requested WASM file
const wasm = await WebAssembly.instantiateStreaming(fetch('/example.wasm'));
```

Astro supports loading WASM files directly into your application using the browser’s [`WebAssembly`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly) API.

## Node Builtins

Astro supports Node.js built-ins, with some limitations, using Node’s newer `node:` prefix. There may be differences between development and production, and some features may be incompatible with on-demand rendering. Some [adapters](/en/guides/on-demand-rendering/) may also be incompatible with these built-ins modules or require configuration to support a subset (e.g., [Cloudflare Workers](/en/guides/integrations-guide/cloudflare/) or [Deno](https://github.com/denoland/deno-astro-adapter)).

The following example imports the `util` module from Node to parse a media type (MIME):

```
---
// Example: import the "util" built-in from Node.js

export interface Props {
  mimeType: string,
}

const mime = new util.MIMEType(Astro.props.mimeType)
---

<span>Type: {mime.type}</span>
<span>SubType: {mime.subtype}</span>
```

## Extending file type support

With **Vite** and compatible **Rollup** plugins, you can import file types which aren't natively supported by Astro. Learn where to find the plugins you need in the [Finding Plugins](https://vite.dev/guide/using-plugins.html#finding-plugins) section of the Vite Documentation.

:::note\[Plugin configuration\] Refer to your plugin's documentation for configuration options, and how to correctly install it. :::

<RecipeLinks slugs={\["en/recipes/add-yaml-support"\]} />

## [Working with integrations](https://docharvest.github.io/docs/astro/guides/integrations/)



## [@astrojs/alpinejs](https://docharvest.github.io/docs/astro/guides/integrations-guide/alpinejs/)

Contents

astro

@astrojs/alpinejs

Astro

@astrojs/alpinejs

This **[Astro integration](/en/guides/integrations/)** adds [Alpine.js](https://alpinejs.dev/) to your project so that you can use Alpine.js anywhere on your page.

## Installation

Astro includes an `astro add` command to automate the setup of official integrations. If you prefer, you can [install integrations manually](#manual-install) instead.

To install `@astrojs/alpinejs`, run the following from your project directory and follow the prompts:

\`\`\`sh npx astro add alpinejs \`\`\` \`\`\`sh pnpm astro add alpinejs \`\`\` \`\`\`sh yarn astro add alpinejs \`\`\`

If you run into any issues, [feel free to report them to us on GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.

### Manual Install

First, install the `@astrojs/alpinejs` package.

\`\`\`sh npm install @astrojs/alpinejs \`\`\` \`\`\`sh pnpm add @astrojs/alpinejs \`\`\` \`\`\`sh yarn add @astrojs/alpinejs \`\`\`

Most package managers will install associated peer dependencies as well. However, if you see a `Cannot find package 'alpinejs'` (or similar) warning when you start up Astro, you'll need to manually install Alpine.js yourself:

\`\`\`sh npm install alpinejs @types/alpinejs \`\`\` \`\`\`sh pnpm add alpinejs @types/alpinejs \`\`\` \`\`\`sh yarn add alpinejs @types/alpinejs \`\`\`

Then, apply the integration to your `astro.config.*` file using the `integrations` property:

## Configuration Options

### `entrypoint`

**Type:** `string`  

You can extend Alpine by setting the `entrypoint` option to a root-relative import specifier (e.g. `entrypoint: "/src/entrypoint"`).

The default export of this file should be a function that accepts an Alpine instance prior to starting. This allows the use of custom directives, plugins and other customizations for advanced use cases.

```

}
```

## Examples

-   The [Astro Alpine.js example](https://github.com/withastro/astro/tree/main/examples/framework-alpine) shows how to use Alpine.js in an Astro project.

## [@astrojs/cloudflare](https://docharvest.github.io/docs/astro/guides/integrations-guide/cloudflare/)

Contents

astro

@astrojs/cloudflare

Astro

@astrojs/cloudflare

This adapter allows Astro to deploy your [on-demand rendered routes and features](/en/guides/on-demand-rendering/) to [Cloudflare](https://www.cloudflare.com/), including [server islands](/en/guides/server-islands/), [actions](/en/guides/actions/), and [sessions](/en/guides/sessions/).

If you're using Astro as a static site builder, you don't need an adapter.

Learn how to deploy your Astro site in our [Cloudflare deployment guide](/en/guides/deploy/cloudflare/).

:::tip\[Upgrading to Astro 6?\] Astro 6 requires an upgrade to v13 of this adapter. See the [Cloudflare adapter upgrade instructions for Astro 6](#upgrading-to-v13-and-astro-6) for breaking changes and migration guidance. :::

## Why Astro Cloudflare

Cloudflare's [Developer Platform](https://developers.cloudflare.com/) lets you develop full-stack applications with access to resources such as storage and AI, all deployed to a global edge network. This adapter builds your Astro project for deployment through Cloudflare.

## Installation

Astro includes an `astro add` command to automate the setup of official integrations. If you prefer, you can [install integrations manually](#manual-install) instead.

Add the Cloudflare adapter to enable server-rendering in your Astro project with the `astro add` command. This will install `@astrojs/cloudflare` and make the appropriate changes to your `astro.config.mjs` file in one step.

\`\`\`sh npx astro add cloudflare \`\`\` \`\`\`sh pnpm astro add cloudflare \`\`\` \`\`\`sh yarn astro add cloudflare \`\`\`

Now, you can enable [on-demand rendering per page](/en/guides/on-demand-rendering/#enabling-on-demand-rendering), or set your build output configuration to `output: 'server'` to [server-render all your pages by default](/en/guides/on-demand-rendering/#server-mode).

### Manual Install

1.  Add the `@astrojs/cloudflare` adapter to your project's dependencies using your preferred package manager.
    
    \`\`\`sh npm install @astrojs/cloudflare \`\`\` \`\`\`sh pnpm add @astrojs/cloudflare \`\`\` \`\`\`sh yarn add @astrojs/cloudflare \`\`\`
2.  Add the adapter to your `astro.config.mjs` file:
    
    ```
    import { defineConfig } from 'astro/config';
    import cloudflare from '@astrojs/cloudflare';
    
    export default defineConfig({
      adapter: cloudflare(),
    });
    ```
    
3.  Astro will automatically generate a default configuration, using the package.json name field or the folder name as the Worker name. You can optionally create a [Wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/configuration/) if you need custom settings. This example declares Cloudflare KV bindings:
    
    ```
    {
      "name": "my-astro-app",
      // Add your bindings here, e.g.:
      // "kv_namespaces": [{ "binding": "MY_KV", "id": "<namespace_id>" }]
    }
    ```
    

## Options

The Cloudflare adapter accepts the following options from [`@cloudflare/vite-plugin`](https://developers.cloudflare.com/workers/vite-plugin/):

-   `auxiliaryWorkers`
-   `configPath`
-   `inspectorPort`
-   `persistState`
-   `remoteBindings`
-   `experimental.headersAndRedirectsDevModeSupport`

It also accepts the following:

### `imageService`

\*\*Type:\*\* \`'passthrough' | 'cloudflare' | 'cloudflare-binding' | 'compile' | 'custom' | { build: 'compile', runtime?: 'cloudflare-binding' | 'passthrough' }\`  
\*\*Default:\*\* \`'cloudflare-binding'\`

Determines which image service is used by the adapter. The adapter will default to `cloudflare-binding` mode when an incompatible image service is configured. Otherwise, it will use the globally configured image service:

-   **`cloudflare`:** Uses the [Cloudflare Image Resizing](https://developers.cloudflare.com/images/image-resizing/) service.
-   **`cloudflare-binding`:** Uses the [Cloudflare Images binding](https://developers.cloudflare.com/images/transform-images/bindings/) for image transformation. The binding is automatically provisioned when you deploy.
-   **`passthrough`:** Uses the existing [`noop`](/en/guides/images/#configure-no-op-passthrough-service) service.
-   **`compile`:** Uses the [configured image service](/en/reference/configuration-reference/#imageservice) or falls back to a combination of internal dependencies to transform images locally at build time for prerendered routes. The noop `passthrough` option is configured for on-demand rendered pages.
-   **`custom`:** Uses the [configured image service](/en/reference/configuration-reference/#imageservice) (defaults to Sharp) to process assets at build time for prerendered routes. Bundles the image service for runtime image handling, without checking its compatibility with Cloudflare's `workerd` runtime.

It is also possible to configure your image service as an object, setting both a build time and runtime service independently. Currently, `'compile'` is the only available build-time option. The supported runtime options are `'passthrough'` (default) and `'cloudflare-binding'`:

### `sessionKVBindingName`

\*\*Type:\*\* \`string\`  
\*\*Default:\*\* \`SESSION\`

Sets the name of the KV binding used for session storage. By default, the KV namespace is automatically provisioned when you deploy, and is named `SESSION`. You can change this name by setting the binding manually in your wrangler config. See [Sessions](#sessions) for more information.

```
{
  "kv_namespaces": [
    {
      "binding": "MY_SESSION_BINDING",
    }
  ]
}
```

### `imagesBindingName`

\*\*Type:\*\* \`string\`  
\*\*Default:\*\* \`IMAGES\`

Sets the name of the Images binding used when [`imageService`](#imageservice) is set to `cloudflare-binding`. By default, the binding is automatically provisioned with the name `IMAGES` when you deploy. You can change it by setting the binding manually in your wrangler config:

```
{
  "images": {
    "binding": "MY_IMAGES"
  }
}
```

### `prerenderEnvironment`

\*\*Type:\*\* \`'workerd' | 'node'\`  
\*\*Default:\*\* \`'workerd'\`

Controls which runtime is used for [prerendering](/en/guides/on-demand-rendering/) static pages at build time and during development.

By default, prerendered pages are built using Cloudflare's `workerd` runtime to match the production environment as closely as possible. Set this option to `'node'` when your prerendered pages depend on Node.js APIs or NPM packages that are not compatible with `workerd`:

For example, if a prerendered page reads from the file system using `node:fs`, set `prerenderEnvironment` to `'node'`. On-demand rendered pages are unaffected by this option and always run in `workerd`.

## Cloudflare runtime

The Cloudflare runtime gives you access to environment variables, bindings to Cloudflare resources, and other Cloudflare-specific APIs.

### Environment variables and bindings

Environment variables and bindings are defined in your `wrangler.jsonc` configuration file.

Define [environment variables](https://developers.cloudflare.com/workers/configuration/environment-variables/#add-environment-variables-via-wrangler) that do not store sensitive information in `wrangler.jsonc`:

```
{
  "vars": {
    "MY_VARIABLE": "test",
  },
}
```

[Secrets](https://developers.cloudflare.com/workers/configuration/secrets/) are a special type of environment variable that allow you to attach encrypted text values to your Worker. They need to be defined differently to ensure they are not visible within Wrangler or Cloudflare dashboard after you set them.

To define `secrets`, add them through the [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/) rather than in your Wrangler config file:

```
npx wrangler secret put <KEY>
```

To set secrets for local development, add a `.dev.vars` file to the root of the Astro project:

```
DB_PASSWORD=myPassword
```

Cloudflare environment variables and secrets can be imported from `"cloudflare:workers"`:

```
---

const myVariable = env.MY_VARIABLE;
const myKVNamespace = env.MY_KV;
---
```

They are also compatible with the [`astro:env` API](/en/guides/environment-variables/#type-safe-environment-variables):

See the [list of all supported bindings](https://developers.cloudflare.com/workers/wrangler/api/#supported-bindings) in the Cloudflare documentation.

### The `cf` object

The Cloudflare [`cf` object](https://developers.cloudflare.com/workers/runtime-apis/request/#incomingrequestcfproperties) contains request metadata such as geolocation information. Access it directly from the request:

```
---
const cf = Astro.request.cf;
const country = cf?.country;
---
```

### Execution context

Access the Cloudflare [`ExecutionContext`](https://developers.cloudflare.com/workers/runtime-apis/context/) through `Astro.locals.cfContext`. This is useful for operations like [`waitUntil()`](https://developers.cloudflare.com/workers/runtime-apis/context/#waituntil), or accessing [Durable Object exports](https://developers.cloudflare.com/workers/runtime-apis/context/#exports) within your page.

```
---
const cfContext = Astro.locals.cfContext;
cfContext.exports.Greeter.greet('Astro');
cfContext.waitUntil(someAsyncOperation());
---
```

### Typing

`wrangler` provides a [`types`](https://developers.cloudflare.com/workers/wrangler/commands/#types) command to generate TypeScript types for your bindings. This allows you to type your environment without the need for manual type definitions.

Run `wrangler types` every time you change your configuration files (e.g. `wrangler.jsonc`, `.dev.vars`).

:::note The following example shows a script configuration to run `wrangler types` automatically before other commands:

```
{
  "scripts": {
    "dev": "wrangler types && astro dev",
    "start": "wrangler types && astro dev",
    "build": "wrangler types && astro check && astro build",
    "preview": "wrangler types && astro preview",
    "astro": "astro"
  }
}
```

:::

## Cloudflare Platform

### Headers

Add [custom headers](https://developers.cloudflare.com/workers/static-assets/headers/) for static assets by creating a `_headers` file in your Astro project's `public/` folder. This file will be copied to the build output directory. Headers in `_headers` are not applied to responses generated by your Worker code.

### Assets

Assets built by Astro are all named with a hash and, therefore, can be given long cache headers. By default, Astro on Cloudflare will add such a header for these files.

### Redirects

Declare [custom redirects for static assets](https://developers.cloudflare.com/workers/static-assets/redirects/) by adding a `_redirects` file in your Astro project's `public/` folder. This file will be copied to your build output directory. For dynamic routes, [configure redirects in Astro directly](/en/guides/routing/#configured-redirects) instead.

### Routes

Routing for static assets is based on the file structure in the build directory (e.g. `./dist`). If no match is found, this will fall back to the Worker for on-demand rendering. Read more about [static asset routing with Cloudflare Workers](https://developers.cloudflare.com/workers/static-assets/routing/).

## Sessions

The Astro [Sessions API](/en/guides/sessions/) allows you to easily store user data between requests. This can be used for things like user data and preferences, shopping carts, and authentication credentials. Unlike cookie storage, there are no size limits on the data, and it can be restored on different devices.

Astro automatically configures [Workers KV](https://developers.cloudflare.com/kv/) for session storage when using the Cloudflare adapter. Wrangler can [automatically provision](https://developers.cloudflare.com/workers/wrangler/configuration/#automatic-provisioning) the KV namespace when you deploy, so no manual setup is required. Alternatively, you can define the KV binding manually in your `wrangler.jsonc` file and set a custom binding name using the [`sessionKVBindingName`](#sessionkvbindingname) adapter option.

```
---

---

<a href="/checkout">🛒 {cart?.length ?? 0} items</a>
```

By default, the KV binding is named `SESSION`. To use a different name, set the [`sessionKVBindingName`](#sessionkvbindingname) option in the adapter config.

:::note Writes to Cloudflare KV are [eventually consistent](https://developers.cloudflare.com/kv/concepts/how-kv-works/#consistency) between regions. This means that changes are available immediately within the same region but may take up to 60 seconds to propagate globally. This won't affect most users as they are unlikely to switch regions between requests, but it may be a consideration for some use cases, such as VPN users. :::

## Cloudflare Module Imports

The Cloudflare `workerd` runtime supports imports of some [non-standard module types](https://developers.cloudflare.com/workers/wrangler/bundling/#including-non-javascript-modules). Most additional file types are also available in Astro:

-   `.wasm` or `.wasm?module`: exports a [`WebAssembly.Module`](https://developer.mozilla.org/en-US/docs/WebAssembly/JavaScript_interface/Module) that can then be instantiated
-   `.bin`: exports an [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) of the raw binary contents of the file
-   `.txt`: exports a string of the file contents

All module types export a single default value. Modules can be imported both from server-side rendered pages, or from prerendered pages for static site generation.

The following is an example of importing a Wasm module that then responds to requests by adding the request's number parameters together.

```
// Import the WebAssembly module

// Instantiate first in order to use it
const addModule: any = new WebAssembly.Instance(mod);

  const b = Number.parseInt(context.params.b);
  return new Response(`${addModule.exports.add(a, b)}`);
}
```

While this example is trivial, Wasm can be used to accelerate computationally intensive operations which do not involve significant I/O such as embedding an image processing library, or embedding a small pre-indexed database for search over a read-only dataset.

## Node.js compatibility

Cloudflare Workers support most Node.js runtime APIs through the `nodejs_compat` compatibility flag. This includes commonly used modules like `node:buffer`, `node:crypto`, `node:path`, and many others. See the [full list of supported Node.js APIs](https://developers.cloudflare.com/workers/runtime-apis/nodejs) in Cloudflare's documentation.

To enable Node.js compatibility, add the `nodejs_compat` flag to your Wrangler configuration:

```
{
  "compatibility_flags": ["nodejs_compat"],
}
```

Then use the `node:*` import syntax in your server-side code:

## Using advanced routing

The Cloudflare adapter provides companion handlers that apply Cloudflare-specific setup to your [advanced routing pipeline](/en/guides/routing/#advanced-routing). These handlers configure session KV binding injection, static asset serving via the `ASSETS` binding, `Astro.locals.cfContext`, client address from the `cf-connecting-ip` header, `waitUntil`, and prerendered error page fetching.

You can use the [`astro/fetch`](/en/reference/modules/astro-fetch/) and [`astro/hono`](/en/reference/modules/astro-hono/) APIs from `src/fetch.ts` on Cloudflare without these handlers. The adapter's default entrypoint takes care of Cloudflare-specific setup for you. These companion handlers are useful when you already have a [custom worker entrypoint](https://developers.cloudflare.com/workers/wrangler/configuration/#inheritable-keys) (`src/worker.ts`), for example, to export a Durable Object, and want to use the advanced routing APIs directly from that file instead.

When using these handlers in your worker entrypoint, they replace the functionality of the adapter's default handler, so you should not use both at the same time. Place the Cloudflare handler before other Astro handlers so that bindings and locals are available to the rest of the pipeline.

### With the Fetch API

For use with [`astro/fetch`](/en/reference/modules/astro-fetch/). The `cf()` function imported from `@astrojs/cloudflare/fetch` receives a [`FetchState`](/en/reference/modules/astro-fetch/#fetchstate), the Cloudflare `env`, and the `ExecutionContext`. It returns a `Response` for static asset hits, or `undefined` when the request should continue to Astro rendering:

```

    const asset = await cf(state, env, ctx);
    if (asset) return asset;
    return astro(state);
  },
};
```

### With Hono

For use with [`astro/hono`](/en/reference/modules/astro-hono/). The `cf()` function imported from `@astrojs/cloudflare/hono` returns a Hono middleware that reads `env` and `executionCtx` from the Hono context automatically:

```

const app = new Hono<{ Bindings: Env }>();

app.use(cf());
app.use(actions());
app.use(middleware());
app.use(pages());
app.use(i18n());
```

## Upgrading to v13 and Astro 6

Astro 6 brings significant improvements to the Cloudflare development experience and requires `@astrojs/cloudflare` v13 or later. Now, `astro dev` uses Cloudflare's Vite plugin and `workerd` runtime to closely mirror production behavior.

See [the Astro 6 upgrade guide](/en/guides/upgrade-to/v6/) for full instructions on upgrading Astro itself.

### Development server now uses workerd

The biggest change for Cloudflare users in Astro 6 is that `astro dev` and `astro preview` now use the Cloudflare Vite plugin to run your site using the real Workers runtime (`workerd`) instead of Node.js. This means your development environment is now a much closer replica of your production environment, with the same runtime, APIs, and behavior.

This change helps you catch issues during development that would have previously only appeared in production, and features like Durable Objects, R2 bindings, and Workers AI now work exactly as they do when deployed to Cloudflare's platform.

This change is transparent for most projects. If your project had special configuration for `astro dev` or was relying on Node.js-specific behavior in development, adjust your code or configuration accordingly.

### New: `prerenderEnvironment` option

In Astro 6, prerendered pages now run in Cloudflare's `workerd` runtime by default during development and build. Previously, these pages always ran in Node.js.

If your prerendered pages depend on Node.js APIs (for example `node:fs`) or NPM packages that are not compatible with `workerd`, set `prerenderEnvironment: 'node'` in your Cloudflare adapter config to restore the previous behavior for prerendering.

On-demand rendered pages are not affected by this option and continue to run in `workerd`.

See [`prerenderEnvironment`](#prerenderenvironment) for configuration details.

### Some dependencies might need to be pre-compiled

The new workerd environment does not support CommonJS syntax, including Node.js specific syntax such as `require` and `module.exports`. This means that some of your project dependencies may throw errors in the development server or during the build.

If you have control over the dependency, you can create a Vite plugin and pre-compile the dependency using the `optimizeDeps.include` option.

For example, you can create a Vite plugin to pre-compile the dependency `postcss` in order to use the Expressive Code syntax highlighter:

```
function noExternalPlugin() {
  return {
    name: "optimize-dependencies",
    configEnvironment(environment) {
      // We're only interested in server environments
      if (environment !== 'client') {
        return {
          optimizeDeps: {
            include: [
              "postcss"
              // Or you can use this syntax if you don't depend directly on a dependency
              // "expressive-code > postcss"
            ]
          }
        }
      }
    }
  }
}
```

### Changed: Wrangler entrypoint configuration

Previously, the `main` field in your Wrangler configuration pointed to the built worker file (e.g. `dist/_worker.js/index.js`). With Astro 6, this has changed to point to a new unified entrypoint provided by the Cloudflare adapter: `@astrojs/cloudflare/entrypoints/server`.

Update your `wrangler.jsonc` to use the new entrypoint:

```
{
  "main": "dist/_worker.js/index.js",
  "main": "@astrojs/cloudflare/entrypoints/server",
  "name": "my-astro-app",
  // ... rest of config
}
```

This single entrypoint handles both `astro dev` and production deployments.

### Removed: `Astro.locals.runtime` API

The `Astro.locals.runtime` object has been removed in favor of direct access to Cloudflare Workers APIs. Access environment variables, the `cf` object, caches, and execution context directly through the provided interfaces.

**Accessing environment variables:**

Previously, environment variables were accessed through `Astro.locals.runtime.env`. Now import `env` directly instead:

```
const { env } = Astro.locals.runtime;
```

**Accessing the `cf` object:**

Previously, the `cf` object was accessed through `Astro.locals.runtime.cf`. Now access it directly from the request:

```
const { cf } = Astro.locals.runtime;
const cf = Astro.request.cf;
```

**Accessing the caches API:**

Previously, the caches API was accessed through `Astro.locals.runtime.caches`. Now use the global `caches` object directly:

```
const { caches } = Astro.locals.runtime;

caches.default.put(request, response);
```

**Accessing the execution context:**

The `Astro.locals.runtime.ctx` object is replaced with `Astro.locals.cfContext`, which contains the Cloudflare `ExecutionContext`:

```
const ctx = Astro.locals.runtime.ctx;
const ctx = Astro.locals.cfContext;
```

### Changed: Wrangler configuration file is now optional

The Wrangler configuration file is now optional for simple projects. If you don't have custom configuration, such as Cloudflare bindings (KV, D1, Durable Objects, etc.), Astro will automatically generate a default configuration for you.

If your `wrangler.jsonc` only contains basic configuration like this:

```
{
  "main": "@astrojs/cloudflare/entrypoints/server",
  "compatibility_date": "2025-05-21",
  "assets": {
    "directory": "./dist",
    "binding": "ASSETS",
  },
}
```

You can safely delete this file. Astro handles this configuration automatically. Alternatively, create a minimal `wrangler.jsonc` with just your project name and other custom settings:

```
{
  "name": "my-astro-app",
}
```

### Changed: Custom entrypoint API

If you were using a custom `workerEntryPoint` configuration in the adapter options, this has been removed. Instead, specify your custom entrypoint in your Wrangler configuration and create a standard Cloudflare Worker export object directly, rather than using the `createExports()` function.

1\. Remove the \`workerEntryPoint\` option from your adapter config:

````
```js title="astro.config.mjs" del={6-9}
import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  adapter: cloudflare({
    workerEntryPoint: {
      path: 'src/worker.ts',
      namedExports: ['MyDurableObject'],
    },
  }),
});
```
````

2.  Specify the entrypoint in `wrangler.jsonc` instead:
    
    ```
    {
      "main": "./src/worker.ts"
    }
    ```
    
3.  Update your custom worker entry file to use standard Worker syntax. Import the handler from `@astrojs/cloudflare/handler` and export a standard Cloudflare Worker object, alongside any custom exports like Durable Objects:
    
    ```
    import { handle } from '@astrojs/cloudflare/handler';
    import { DurableObject } from 'cloudflare:workers';
    
    export class MyDurableObject extends DurableObject<Env> {
      // ...
    }
    
    export default {
      async fetch(request, env, ctx) {
        await env.MY_QUEUE.send('log');
        return handle(request, env, ctx);
      },
      async queue(batch, _env) {
        let messages = JSON.stringify(batch.messages);
        console.log(`consumed from our queue: ${messages}`);
      },
    } satisfies ExportedHandler<Env>;
    ```
    

The manifest is now created internally by the adapter, so it does not need to be passed to your handler.

### Removed: `cloudflareModules` option

The `cloudflareModules` adapter option has been removed because it is no longer necessary. Cloudflare natively supports importing `.sql`, `.wasm`, and other module types.

Remove the `cloudflareModules` option from your Cloudflare adapter configuration if you were using it:

### New: `astro preview` support

Use `astro preview` to test your Cloudflare Workers application locally before deploying. The preview runs using Cloudflare's `workerd` runtime, closely mirroring production behavior. Run `astro build` followed by `astro preview` to start the preview server.

### Removed: Cloudflare Pages support

The Astro Cloudflare adapter no longer supports deployment on Cloudflare Pages. For the best experience and feature support, you should migrate to Cloudflare Workers.

See Cloudflare's [migration guide from Pages to Workers](https://developers.cloudflare.com/workers/static-assets/migration-guides/migrate-from-pages/) for detailed migration instructions.

### Changed: `imageService` default

The default value of `imageService` has changed from `'compile'` to `'cloudflare-binding'` for an improved experience when working with images.

The `cloudflare-binding` service uses the [Cloudflare Images binding](https://developers.cloudflare.com/images/transform-images/bindings/) to transform images at runtime, and the binding is automatically provisioned when you deploy.

To revert to the previous behavior, where image transformation was only available on prerendered routes at build time, set `imageService: 'compile'` explicitly in your adapter config.

### Changed: Deploy to Cloudflare Environment

In Astro 5.x, you could build your Astro project once and deploy it to a specific Cloudflare environment with `wrangler deploy --env some-env`.

Since Astro 6.0, the integration relies on the Cloudflare Vite plugin and this behavior has changed. The environment is now determined during the build phase. Therefore, you must build your project separately for each environment.

To deploy to a specific Cloudflare environment, prefix your command with the `CLOUDFLARE_ENV` variable. For example, the command `CLOUDFLARE_ENV=some-env astro build && wrangler deploy` will build your Astro project and deploy it with Wrangler using the `some-env` environment.

Learn how to update your [Cloudflare environments](https://developers.cloudflare.com/workers/vite-plugin/reference/cloudflare-environments/) in the [Migrate from wrangler dev guide](https://developers.cloudflare.com/workers/vite-plugin/reference/migrating-from-wrangler-dev/#cloudflare-environments).

## [@astrojs/db](https://docharvest.github.io/docs/astro/guides/integrations-guide/db/)

Contents

astro

@astrojs/db

Astro

@astrojs/db

:::caution\[Removed\] The Astro DB integration was deprecated in v6.4 and has been removed since Astro v7.0.

If you were using this integration in your project, we recommend migrating to a third-party library for database functionality. See the [Astro v7.0 migration guide](/en/guides/upgrade-to/v7/#removed-astrojsdb) for more details and recommendations on how to update your project. :::

## [@deno/astro-adapter](https://docharvest.github.io/docs/astro/guides/integrations-guide/deno/)

Contents

astro

@deno/astro-adapter

Astro

@deno/astro-adapter

The Deno adapter allows Astro to deploy your SSR site to Deno targets including Deno Deploy.

The Deno adapter was previously maintained by Astro but now is maintained by Deno directly. Usage is now documented [in the Deno adapter repository](https://github.com/denoland/deno-astro-adapter).

If you are currently using this Astro adapter, you will need to migrate to the new Deno version or to [add another adapter](/en/guides/on-demand-rendering/) to continue using SSR in your project.

## [Lit](https://docharvest.github.io/docs/astro/guides/integrations-guide/lit/)

Contents

astro

Lit

Astro

Lit

:::caution\[Deprecated\] This Astro integration to enable on-demand rendering and client-side hydration for your [Lit](https://lit.dev/) custom elements was deprecated in Astro 5.0. :::

You can continue to use Lit for client components by adding a client-side script tag. For example:

```
<script>
  import "../components/MyTabs";
</script>

<my-tabs title="These are my tabs">...</my-tabs>
```

If you're interested in maintaining a Lit integration yourself, you may wish to use the [last published version of `@astrojs/lit`](https://github.com/withastro/astro/tree/astro%404.13.0/packages/integrations/lit) as a starting point and upgrade the relevant packages.

## [@astrojs/markdoc](https://docharvest.github.io/docs/astro/guides/integrations-guide/markdoc/)

Contents

astro

@astrojs/markdoc

Astro

@astrojs/markdoc

This **[Astro integration](/en/guides/integrations/)** enables the usage of [Markdoc](https://markdoc.dev/) to create components, pages, and content collection entries.

## Why Markdoc?

Markdoc allows you to enhance your Markdown with [Astro components](/en/basics/astro-components/). If you have existing content authored in Markdoc, this integration allows you to bring those files to your Astro project using content collections.

## Installation

Astro includes an `astro add` command to automate the setup of official integrations. If you prefer, you can [install integrations manually](#manual-install) instead.

Run one of the following commands in a new terminal window.

\`\`\`sh npx astro add markdoc \`\`\` \`\`\`sh pnpm astro add markdoc \`\`\` \`\`\`sh yarn astro add markdoc \`\`\`

If you run into any issues, [feel free to report them to us on GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.

### Manual Install

First, install the `@astrojs/markdoc` package:

\`\`\`sh npm install @astrojs/markdoc \`\`\` \`\`\`sh pnpm add @astrojs/markdoc \`\`\` \`\`\`sh yarn add @astrojs/markdoc \`\`\`

Then, apply the integration to your `astro.config.*` file using the `integrations` property:

### VS Code Editor Integration

If you are using VS Code, there is an official [Markdoc language extension](https://marketplace.visualstudio.com/items?itemName=Stripe.markdoc-language-support) that includes syntax highlighting and autocomplete for configured tags. [See the language server on GitHub](https://github.com/markdoc/language-server.git) for more information.

To set up the extension, create a `markdoc.config.json` file in the project root with following content:

```
[
  {
    "id": "my-site",
    "path": "src/content",
    "schema": {
      "path": "markdoc.config.mjs",
      "type": "esm",
      "property": "default",
      "watch": true
    }
  }
]
```

Set `markdoc.config.mjs` as your configuration file with the `schema` object, and define where your Markdoc files are stored using the `path` property. Since Markdoc is specific to content collections, you can use `src/content`.

## Usage

Markdoc files can only be used within content collections. Add entries to any content collection using the `.mdoc` extension:

\- src/ - content/ - docs/ - why-markdoc.mdoc - quick-start.mdoc

Then, [query and display your posts and collections](/en/guides/content-collections/#querying-build-time-collections):

```
---

const entry = await getEntry('docs', 'why-markdoc');
const { Content } = await render(entry);
---

<!--Access frontmatter properties with `data`-->
<h1>{entry.data.title}</h1>
<!--Render Markdoc contents with the Content component-->
<Content />
```

See the [Astro Content Collection docs](/en/guides/content-collections/) for more information.

## Pass Markdoc variables

You may need to pass [variables](https://markdoc.dev/docs/variables) to your content. This is useful when passing SSR parameters like A/B tests.

Variables can be passed as props via the `Content` component:

```
---

const entry = await getEntry('docs', 'why-markdoc');
const { Content } = await render(entry);
---

<!--Pass the `abTest` param as a variable-->
<Content abTestGroup={Astro.params.abTestGroup} />
```

Now, `abTestGroup` is available as a variable in `docs/why-markdoc.mdoc`:

```
{% if $abTestGroup === 'image-optimization-lover' %}

Let me tell you about image optimization...

{% /if %}
```

To make a variable global to all Markdoc files, you can use the `variables` attribute from your `markdoc.config.mjs|ts`:

### Access frontmatter from your Markdoc content

To access frontmatter, you can pass the entry `data` property as a variable where you render your content:

```
---

const entry = await getEntry('docs', 'why-markdoc');
const { Content } = await render(entry);
---

<Content frontmatter={entry.data} />
```

This can now be accessed as `$frontmatter` in your Markdoc.

## Render components

`@astrojs/markdoc` offers configuration options to use all of Markdoc's features and connect UI components to your content.

### Use Astro components as Markdoc tags

You can configure [Markdoc tags](https://markdoc.dev/docs/tags) that map to `.astro` components. You can add a new tag by creating a `markdoc.config.mjs|ts` file at the root of your project and configuring the `tag` attribute.

This example renders an `Aside` component, and allows a `type` prop to be passed as a string:

This component can now be used in your Markdoc files with the `{% aside %}` tag. Children will be passed to your component's default slot:

```
# Welcome to Markdoc 👋

{% aside type="tip" %}

Use tags like this fancy "aside" to add some _flair_ to your docs.

{% /aside %}
```

### Use client-side UI components

Tags and nodes are restricted to `.astro` files. To embed client-side UI components in Markdoc, [use a wrapper `.astro` component that renders a framework component](/en/guides/framework-components/#nesting-framework-components) with your desired `client:` directive.

This example wraps a React `Aside.tsx` component with a `ClientAside.astro` component:

```
---

---

<Aside {...Astro.props} client:load />
```

This Astro component can now be passed to the `render` prop for any [tag](https://markdoc.dev/docs/tags) or [node](https://markdoc.dev/docs/nodes) in your config:

### Use Astro components from npm packages and TypeScript files

You may need to use Astro components exposed as named exports from TypeScript or JavaScript files. This is common when using npm packages and design systems.

You can pass the import name as the second argument to the `component()` function:

This generates the following import statement internally:

## Markdoc Partials

The `{% partial /%}` tag allows you to render other `.mdoc` files inside your Markdoc content.

This is useful for reusing content across multiple documents, and allows you to have `.mdoc` content files that do not follow your collection schema.

:::tip Use an underscore `_` prefix for partial files or directories. This excludes partials from content collection queries. :::

This example shows a Markdoc partial for a footer to be used inside blog collection entries:

```
Social links:

- [Twitter / X](https://twitter.com/astrodotbuild)
- [Discord](https://astro.build/chat)
- [GitHub](https://github.com/withastro/astro)
```

Use the `{% partial /%}` tag with to render the footer at the bottom of a blog post entry. Apply the `file` attribute with the path to the file, using either a relative path or an import alias:

```
# My Blog Post

{% partial file="./_footer.mdoc" /%}
```

## Syntax highlighting

`@astrojs/markdoc` provides [Shiki](https://shiki.style) and [Prism](https://github.com/PrismJS) extensions to highlight your code blocks.

### Shiki

Apply the `shiki()` extension to your Markdoc config using the `extends` property. You can optionally pass a shiki configuration object:

### Prism

Apply the `prism()` extension to your Markdoc config using the `extends` property.

To learn about configuring Prism stylesheets, [see our syntax highlighting guide](/en/guides/syntax-highlighting/#add-a-prism-stylesheet).

## Custom Markdoc nodes / elements

You may want to render standard Markdown elements, such as paragraphs and bolded text, as Astro components. For this, you can configure a [Markdoc node](https://markdoc.dev/docs/nodes). If a given node receives attributes, they will be available as component props.

This example renders blockquotes with a custom `Quote.astro` component:

See the [Markdoc nodes documentation](https://markdoc.dev/docs/nodes#built-in-nodes) to learn about all the built-in nodes and attributes.

### Custom headings

`@astrojs/markdoc` automatically adds anchor links to your headings, and [generates a list of `headings` via the content collections API](/en/guides/content-collections/#rendering-body-content). To further customize how headings are rendered, you can apply an Astro component [as a Markdoc node](https://markdoc.dev/docs/nodes).

This example renders a `Heading.astro` component using the `render` property:

All Markdown headings will render the `Heading.astro` component and pass the following `attributes` as component props:

-   `level: number` The heading level 1 - 6
-   `id: string` An `id` generated from the heading's text contents. This corresponds to the `slug` generated by the [content `render()` function](/en/guides/content-collections/#rendering-body-content).

For example, the heading `### Level 3 heading!` will pass `level: 3` and `id: 'level-3-heading'` as component props.

### Custom image components

Astro's `<Image />` component cannot be used directly in Markdoc. However, you can configure an Astro component to override the default image node every time the native `![]()` image syntax is used, or as a custom Markdoc tag to allow you to specify additional image attributes.

#### Override Markdoc's default image node

To override the default image node, you can configure an `.astro` component to be rendered in place of a standard `<img>`.

1\. Build a custom \`MarkdocImage.astro\` component to pass the required \`src\` and \`alt\` properties from your image to the \`\` component:

````
```astro title="src/components/MarkdocImage.astro"
---
import type { ImageMetadata } from "astro";
import { Image } from "astro:assets";
interface Props {
  src: ImageMetadata;
  alt: string;
}
const { src, alt } = Astro.props;
---
<Image src={src} alt={alt} />
```
````

2.  The `<Image />` component requires a `width` and `height` for remote images which cannot be provided using the `![]()` syntax. To avoid errors when using remote images, update your component to render a standard HTML `<img>` tag when a remote URL `src` is found:
    
    ```
    ---
    import type { ImageMetadata } from "astro";
    import { Image } from "astro:assets";
    interface Props {
      src: ImageMetadata | string;
      alt: string;
    }
    const { src, alt } = Astro.props;
    ---
    <Image src={src} alt={alt} />
    {
      typeof src === 'string' ? <img src={src} alt={alt} /> : <Image src={src} alt={alt} />
    }
    ```
    
3.  Configure Markdoc to override the default image node and render `MarkdocImage.astro`:
    
    ```
    import { defineMarkdocConfig, nodes, component } from '@astrojs/markdoc/config';
    
    export default defineMarkdocConfig({
      nodes: {
        image: {
          ...nodes.image, // Apply Markdoc's defaults for other options
          render: component('./src/components/MarkdocImage.astro'),
        },
      },
    });
    ```
    
4.  The native image syntax in any `.mdoc` file will now use the `<Image />` component to optimize your local images. Remote images may still be used, but will not be rendered by Astro's `<Image />` component.
    
    ```
    
    <!-- Optimized by <Image /> -->
    ![A picture of a cat](/cat.jpg)
    
    <!-- Unoptimized <img> -->
    ![A picture of a dog](https://example.com/dog.jpg) 
    ``` 

#### Create a custom Markdoc image tag

A Markdoc `image` tag allows you to set additional attributes on your image that are not possible with the `![]()` syntax. For example, custom image tags allow you to use Astro's `<Image />` component for remote images that require a `width` and `height`.

The following steps will create a custom Markdoc image tag to display a `<figure>` element with a caption, using the Astro `<Image />` component to optimize the image.

1\. Create a \`MarkdocFigure.astro\` component to receive the necessary props and render an image with a caption:

````
```astro title="src/components/MarkdocFigure.astro"
---
import type { ImageMetadata } from "astro";
import { Image } from "astro:assets";

interface Props {
  src: ImageMetadata | string;
  alt: string;
  width: number;
  height: number;
  caption: string;
}

const { src, alt, width, height, caption } = Astro.props;
---
<figure>
    <Image {src} {alt} {width} {height}  />
    {caption && <figcaption>{caption}</figcaption>}
</figure>
```
````

2.  Configure your custom image tag to render your Astro component:
    
    ```
    import { component, defineMarkdocConfig, nodes } from '@astrojs/markdoc/config';
    
    export default defineMarkdocConfig({
      tags: {
        image: {
          attributes: {
            width: {
              type: String,
            },
            height: {
              type: String,
            },
            caption: {
              type: String,
            },
            ...nodes.image.attributes
          },
          render: component('./src/components/MarkdocFigure.astro'),
        },
      },
    });
    ```
    
3.  Use the `image` tag in Markdoc files to display a figure with caption, providing all the necessary attributes for your component:
    
    ```
    {% image src="./astro-logo.png" alt="Astro Logo" width="100" height="100" caption="a caption!" /%}
    ```
    

## Advanced Markdoc configuration

The `markdoc.config.mjs|ts` file accepts [all Markdoc configuration options](https://markdoc.dev/docs/config), including [tags](https://markdoc.dev/docs/tags) and [functions](https://markdoc.dev/docs/functions).

You can pass these options from the default export in your `markdoc.config.mjs|ts` file:

```

        const countryToEmojiMap = {
          japan: '🇯🇵',
          spain: '🇪🇸',
          france: '🇫🇷',
        };
        return countryToEmojiMap[country] ?? '🏳';
      },
    },
  },
});
```

Now, you can call this function from any Markdoc content entry:

```
¡Hola {% getCountryEmoji("spain") %}!
```

[See the Markdoc documentation](https://markdoc.dev/docs/functions#creating-a-custom-function) for more on using variables or functions in your content.

### Set the root HTML element

Markdoc wraps documents with an `<article>` tag by default. This can be changed from the `document` Markdoc node. This accepts an HTML element name or `null` if you prefer to remove the wrapper element:

## Integration config options

The Astro Markdoc integration handles configuring Markdoc options and capabilities that are not available through the `markdoc.config.js` file.

### `allowHTML`

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

Enables writing HTML markup alongside Markdoc tags and nodes.

By default, Markdoc will not recognize HTML markup as semantic content.

To achieve a more Markdown-like experience, where HTML elements can be included alongside your content, set `allowHTML:true` as a `markdoc` integration option. This will enable HTML parsing in Markdoc markup.

```
  import { defineConfig } from 'astro/config';
  import markdoc from '@astrojs/markdoc';

  export default defineConfig({
    // ...
    integrations: [markdoc({ allowHTML: true })],
  });
```

:::caution When `allowHTML` is enabled, HTML markup inside Markdoc documents will be rendered as actual HTML elements (including `<script>`), making attack vectors like XSS possible. Ensure that any HTML markup comes from trusted sources. :::

### `ignoreIndentation`

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

By default, any content that is indented by four spaces is treated as a code block. Unfortunately, this behavior makes it difficult to use arbitrary levels of indentation to improve the readability of documents with complex structure.

When using nested tags in Markdoc, it can be helpful to indent the content inside of tags so that the level of depth is clear. To support arbitrary indentation, we have to disable the indent-based code blocks and modify several other markdown-it parsing rules that account for indent-based code blocks. These changes can be applied by enabling the ignoreIndentation option.

```
  import { defineConfig } from 'astro/config';
  import markdoc from '@astrojs/markdoc';

  export default defineConfig({
    // ...
    integrations: [markdoc({ ignoreIndentation: true })],
  });
```

```
# Welcome to Markdoc with indented tags 👋

# Note: Can use either spaces or tabs for indentation

{% custom-tag %}
{% custom-tag %} ### Tags can be indented for better readability

    {% another-custom-tag %}
      This is easier to follow when there is a lot of nesting
    {% /another-custom-tag %}

{% /custom-tag %}
{% /custom-tag %}
```

## Examples

-   The [Astro Markdoc starter template](https://github.com/withastro/astro/tree/latest/examples/with-markdoc) shows how to use Markdoc files in your Astro project.

## [@astrojs/mdx](https://docharvest.github.io/docs/astro/guides/integrations-guide/mdx/)

Contents

astro

@astrojs/mdx

Astro

@astrojs/mdx

````

### Editor Integration

For editor support in [VS Code](https://code.visualstudio.com/), install the [official MDX extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx).

For other editors, use the [MDX language server](https://github.com/mdx-js/mdx-analyzer/tree/main/packages/language-server).

## Usage

Visit the [MDX docs](https://mdxjs.com/docs/what-is-mdx/) to learn about using standard MDX features.

## MDX in Astro

Adding the MDX integration enhances your Markdown authoring with JSX variables, expressions and components.

It also adds extra features to standard MDX, including support for Markdown-style frontmatter in MDX. This allows you to use most of [Astro's built-in Markdown features](/en/guides/markdown-content/).

`.mdx` files must be written in [MDX syntax](https://mdxjs.com/docs/what-is-mdx/#mdx-syntax) rather than Astro’s HTML-like syntax.

### Using local MDX with content collections

To include your local MDX files in a content collection, make sure that your [collection loader](/en/guides/content-collections/#build-time-collection-loaders) is configured to load content from `.mdx` files:

```js title="src/content.config.ts" ins="mdx"

const blog = defineCollection({
  loader: glob({ pattern: "**/*.{md,mdx}", base: "./src/blog" }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
  })
});
````

### Using Exported Variables in MDX

MDX supports using `export` statements to add variables to your MDX content or to export data to a component that imports it.

For example, you can export a `title` field from an MDX page or component to use as a heading with `{JSX expressions}`:

```

const posts = Object.values(matches);
---

{posts.map(post => <p>{post.title}</p>)}
```

#### Exported Properties

The following properties are available to a `.astro` component when using an `import` statement or `import.meta.glob()`:

-   **`file`** - The absolute file path (e.g. `/home/user/projects/.../file.mdx`).
-   **`url`** - The URL of the page (e.g. `/en/guides/markdown-content`).
-   **`frontmatter`** - Contains any data specified in the file’s YAML/TOML frontmatter.
-   **`getHeadings()`** - An async function that returns an array of all headings (`<h1>` to `<h6>`) in the file with the type: `{ depth: number; slug: string; text: string }[]`. Each heading’s `slug` corresponds to the generated ID for a given heading and can be used for anchor links. Headings from imported files are not included.
-   **`<Content />`** - A component that returns the full, rendered contents of the file.
-   **(any `export` value)** - MDX files can also export data with an `export` statement.

### Using Frontmatter Variables in MDX

The Astro MDX integration includes support for using frontmatter in MDX by default. Add frontmatter properties just as you would in Markdown files, and these variables are available to use in the template, and as named properties when importing the file somewhere else.

```
---
title: 'My first MDX post'
author: 'Houston'
---

# {frontmatter.title}

Written by: {frontmatter.author}
```

### Using Components in MDX

After installing the MDX integration, you can import and use both [Astro components](/en/basics/astro-components/) and [UI framework components](/en/guides/framework-components/#using-framework-components) in MDX (`.mdx`) files just as you would use them in any other Astro component.

Don't forget to include a `client:directive` on your UI framework components, if necessary!

See more examples of using import and export statements in the [MDX docs](https://mdxjs.com/docs/what-is-mdx/#esm).

```
---
title: My first post
---

I just started my new Astro blog! 

Here is my counter component, working in MDX:
<ReactCounter client:load />
```

#### Assigning Custom Components to HTML elements

With MDX, you can map Markdown syntax to custom components instead of their standard HTML elements. This allows you to write in standard Markdown syntax, but apply special component styling to selected elements.

For example, you can create a `Blockquote.astro` component to provide custom styling for `<blockquote>` content:

```
---
const props = Astro.props;
---
<blockquote {...props} class="bg-blue-50 p-4">
  <span class="text-4xl text-blue-600 mb-2">“</span>
  <slot /> <!-- Be sure to add a `<slot/>` for child content! -->
</blockquote>
```

Import your custom component into your `.mdx` file, then export a `components` object that maps the standard HTML element to your custom component:

```

const { Content } = await render(entry);
---
<Content components={{ h1: CustomHeading }} />
```

## Configuration

Once the MDX integration is installed, no configuration is necessary to use `.mdx` files in your Astro project.

You can configure how your MDX is rendered with the following options:

-   [Options inherited from Markdown config](#options-inherited-from-markdown-config)
-   [`processor`](#processor)
-   [`extendMarkdownConfig`](#extendmarkdownconfig)
-   [`recmaPlugins`](#recmaplugins)
-   [`optimize`](#optimize)

### Options inherited from Markdown config

All [`markdown` configuration options](/en/reference/configuration-reference/#markdown-options) can be configured separately in the MDX integration, including the [Markdown processor](#processor), syntax highlighting, and more. Options will default to those in your Markdown config ([see the `extendMarkdownConfig` option](#extendmarkdownconfig) to modify this).

See the [Markdown Options reference](/en/reference/configuration-reference/#markdown-options) for a complete list of options.

### `processor`

**Type:** `MarkdownProcessor`  
**Default:** inherited from [`markdown.processor`](/en/reference/configuration-reference/#markdownprocessor)  

By default, `.mdx` files render through the same [Markdown processor](/en/guides/markdown-content/#choosing-a-markdown-processor) as your `.md` files. Set `processor` to use a different processor, or the same processor with different options, for `.mdx` files only.

For example, to keep the default [Sätteri](https://satteri.bruits.org/) processor for `.md` files while rendering `.mdx` files with remark and rehype using `@astrojs/markdown-remark`:

### `extendMarkdownConfig`

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

MDX will extend [your project's existing Markdown configuration](/en/reference/configuration-reference/#markdown-options) by default. To override individual options, you can specify their equivalent in your MDX configuration.

For example, say you need a different syntax highlighter and a different set of plugins for `.mdx` files. You can apply these options like so, with `extendMarkdownConfig` enabled by default:

You may also need to disable `markdown` config extension in MDX. For this, set `extendMarkdownConfig` to `false`:

### `recmaPlugins`

**Type:** `PluggableList`  
**Default:** `[]`  

These are plugins that modify the output [estree](https://github.com/estree/estree) directly. This is useful for modifying or injecting JavaScript variables in your MDX files.

Since Astro v7, the default Markdown processor does not support Recma plugins. If your project depends on them, you can [use the `unified()` processor](/en/guides/markdown-content/#switching-to-the-unified-processor).

We suggest [using AST Explorer](https://astexplorer.net/) to play with estree outputs, and trying [`estree-util-visit`](https://unifiedjs.com/explore/package/estree-util-visit/) for searching across JavaScript nodes.

### `optimize`

**Type:** `boolean | { ignoreElementNames?: string[] }`  
**Default:** `false`  

This is an optional configuration setting to optimize the MDX output for faster builds and rendering via an internal rehype plugin. This may be useful if you have many MDX files and notice slow builds. However, this option may generate some unescaped HTML, so make sure your site's interactive parts still work correctly after enabling it.

This is disabled by default. To enable MDX optimization, add the following to your MDX integration configuration:

#### `ignoreElementNames`

**Type:** `string[]`  

Previously known as `customComponentNames`.

An optional property of `optimize` to prevent the MDX optimizer from handling certain element names, like [custom components passed to imported MDX content via the components prop](#passing-components-to-mdx-content).

You will need to exclude these components from optimization as the optimizer eagerly converts content into a static string, which will break custom components that needs to be dynamically rendered.

For example, the intended MDX output of the following is `<Heading>...</Heading>` in place of every `"<h1>...</h1>"`:

```
---

---

<Content components={{ ...components, h1: Heading }} />
```

To configure optimization for this using the `ignoreElementNames` property, specify an array of HTML element names that should be treated as custom components:

Note that if your MDX file [configures custom components using `export const components = { ... }`](/en/guides/integrations-guide/mdx/#assigning-custom-components-to-html-elements), then you do not need to manually configure this option. The optimizer will automatically detect them.

## Examples

-   The [Astro MDX starter template](https://github.com/withastro/astro/tree/latest/examples/with-mdx) shows how to use MDX files in your Astro project.

## [@astrojs/netlify](https://docharvest.github.io/docs/astro/guides/integrations-guide/netlify/)

Contents

astro

@astrojs/netlify

Astro

@astrojs/netlify

This adapter allows Astro to deploy your [on-demand rendered routes and features](/en/guides/on-demand-rendering/) to [Netlify](https://www.netlify.com/), including [server islands](/en/guides/server-islands/), [actions](/en/guides/actions/), and [sessions](/en/guides/sessions/).

If you're using Astro as a static site builder, you only need this adapter if you are using additional Netlify services that require a server (e.g. [Netlify Image CDN](#netlify-image-cdn-support)). Otherwise, you do not need an adapter to deploy your static site.

Learn how to deploy your Astro site in our [Netlify deployment guide](/en/guides/deploy/netlify/).

## Why Astro Netlify

[Netlify](https://www.netlify.com/) is a deployment platform that allows you to host your site by connecting directly to your GitHub repository. This adapter enhances the Astro build process to prepare your project for deployment through Netlify.

## Installation

Astro includes an `astro add` command to automate the setup of official integrations. If you prefer, you can [install integrations manually](#manual-install) instead.

Add the Netlify adapter to enable on-demand rendering in your Astro project with the `astro add` command. This will install `@astrojs/netlify` and make the appropriate changes to your `astro.config.mjs` file in one step.

\`\`\`sh npx astro add netlify \`\`\` \`\`\`sh pnpm astro add netlify \`\`\` \`\`\`sh yarn astro add netlify \`\`\`

Now, you can enable [on-demand rendering per page](/en/guides/on-demand-rendering/#enabling-on-demand-rendering), or set your build output configuration to `output: 'server'` to [server-render all your pages by default](/en/guides/on-demand-rendering/#server-mode).

### Manual Install

First, install the Netlify adapter to your project’s dependencies using your preferred package manager:

\`\`\`sh npm install @astrojs/netlify \`\`\` \`\`\`sh pnpm add @astrojs/netlify \`\`\` \`\`\`sh yarn add @astrojs/netlify \`\`\`

Then, add the adapter to your `astro.config.*` file:

```
 import { defineConfig } from 'astro/config';
 import netlify from '@astrojs/netlify';

 export default defineConfig({
    // ...
    adapter: netlify(),
 });
```

## Usage

[Read the full deployment guide here.](/en/guides/deploy/netlify/)

Follow the instructions to [build your site locally](/en/guides/deploy/#building-your-site-locally). After building, you will have a `.netlify/` folder containing both [Netlify Functions](https://docs.netlify.com/functions/overview/) in the `.netlify/functions-internal/` folder and [Netlify Edge Functions](https://docs.netlify.com/edge-functions/overview/) in the`.netlify/edge-functions/` folder.

To deploy your site, install the [Netlify CLI](https://docs.netlify.com/cli/get-started/) and run:

```
netlify deploy
```

The [Netlify Blog post on Astro](https://www.netlify.com/blog/how-to-deploy-astro/) and the [Netlify Docs](https://docs.netlify.com/integrations/frameworks/astro/) provide more information on how to use this integration to deploy to Netlify.

### Running Astro middleware on Netlify Edge Functions

By default, Astro middleware is applied to pre-rendered pages at build-time and to on-demand-rendered pages at runtime.

To implement redirects, access control, or custom response headers for pre-rendered pages, run your middleware on Netlify Edge Functions by setting the [`middlewareMode` option](/en/reference/adapter-reference/#middlewaremode) to `edge`:

When `middlewareMode` is set to `'edge'`, an edge function will execute your middleware code for all requests, including static assets, prerendered pages, and on-demand rendered pages.

For on-demand rendered pages, the `context.locals` object is serialized using JSON and sent in a header for the serverless function, which performs the rendering. As a security measure, the serverless function will refuse to serve requests with a `403 Forbidden` response unless they come from the generated edge function.

### Accessing edge context from your site

Netlify Edge Functions provide a [context object](https://docs.netlify.com/edge-functions/api/#netlify-specific-context-object) that includes metadata about the request such as a user’s IP, geolocation data, and cookies.

This can be accessed through the `Astro.locals.netlify.context` object:

```
---
const {
  geo: { city },
} = Astro.locals.netlify.context;
---

<h1>Hello there, friendly visitor from {city}!</h1>
```

If you're using TypeScript, you can [get proper typings](/en/guides/typescript/#extending-global-types) by updating `src/env.d.ts` to use `NetlifyLocals`:

```
type NetlifyLocals = import('@astrojs/netlify').NetlifyLocals

declare namespace App {
  interface Locals extends NetlifyLocals {
    // ...
  }
}
```

This is not available on prerendered pages.

### Netlify Image CDN support

This adapter by default uses the [Netlify Image CDN](https://docs.netlify.com/image-cdn/overview/) to transform images on-the-fly without impacting build times. It's implemented using an [Astro Image Service](/en/reference/image-service-reference/) under the hood.

To opt out of Netlify's Image CDN remote image optimization, use the `imageCDN` option:

If you are using images hosted on another domain, you must authorize the domain or URL patterns using the [`image.domains`](/en/reference/configuration-reference/#imagedomains) or [`image.remotePatterns`](/en/reference/configuration-reference/#imageremotepatterns) configuration options:

For more information, see [the guide to authorizing remote images](/en/guides/images/#authorizing-remote-images). This is not required for images hosted on the same domain as your site.

### Static sites with the Netlify Adapter

For static sites (`output: 'static'`) hosted on Netlify, you usually don't need an adapter. However, some deployment features are only available through an adapter.

Static sites will need to install this adapter to use and configure Netlify's [image service](#netlify-image-cdn-support).

If you use `redirects` configuration in your Astro config, the Netlify adapter can be used to translate this to the proper `_redirects` format.

Once you run `astro build` there will be a `dist/_redirects` file. Netlify will use that to properly route pages in production.

:::note You can still include a `public/_redirects` file for manual redirects. Any redirects you specify in the redirects config are appended to the end of your own. :::

### Sessions

The Astro [Sessions API](/en/guides/sessions/) allows you to easily store user data between requests. This can be used for things like user data and preferences, shopping carts, and authentication credentials. Unlike cookie storage, there are no size limits on the data, and it can be restored on different devices.

Astro automatically configures [Netlify Blobs](https://docs.netlify.com/blobs/overview/) for session storage when using the Netlify adapter. If you would prefer to use a different session storage driver, you can specify it in your Astro config. See [the `session` configuration reference](/en/reference/configuration-reference/#sessiondriver) for more details.

### Caching Pages

On-demand rendered pages without any dynamic content can be cached to improve performance and lower resource usage. Enabling the `cacheOnDemandPages` option in the adapter will cache all server-rendered pages for up to one year:

This can be changed on a per-page basis by adding caching headers to your response:

```
---

Astro.response.headers.set('CDN-Cache-Control', 'public, max-age=45, must-revalidate');
---

<Layout title="Astro on Netlify">
  {new Date()}
</Layout>
```

With [fine-grained cache control](https://www.netlify.com/blog/swr-and-fine-grained-cache-control/), Netlify supports standard caching headers like `CDN-Cache-Control` or `Vary`. Refer to the docs to learn about implementing e.g. time to live (TTL) or stale while revalidate (SWR) caching: [https://docs.netlify.com/platform/caching](https://docs.netlify.com/platform/caching)

### Skew Protection

Netlify's skew protection ensures that users accessing your site during a deployment continue to receive content from the same deploy version. The Netlify adapter automatically configures skew protection for Astro features like actions, server islands, view transitions, and prefetch requests by injecting the current deploy ID into internal requests. This prevents version mismatches between the client and server during active deployments.

While Astro automatically adds the skew protection header for its built-in features, if you are making your own fetch requests to your site, you can include the header manually using the `DEPLOY_ID` environment variable:

```
const response = await fetch('/api/endpoint', {
  headers: {
    'X-Netlify-Deploy-ID': import.meta.env.DEPLOY_ID,
  },
});
```

### Including or excluding files from Netlify Functions

When deploying an Astro site with on-demand rendering to Netlify, the generated functions automatically trace and include server dependencies. However, you may need to customize which files are included in your Netlify Functions.

#### `includeFiles`

\*\*Type:\*\* \`string\[\]\`  
\*\*Default:\*\* \`\[\]\`  

The `includeFiles` property allows you to explicitly specify additional files that should be bundled with your function. This is useful for files that aren't automatically detected as dependencies, such as:

-   Data files loaded using `fs` operations
-   Configuration files
-   Template files

Provide an array of additional files to include with file paths relative to your project's [`root`](/en/reference/configuration-reference/#root). Absolute paths may not work as expected.

#### `excludeFiles`

\*\*Type:\*\* \`string\[\]\`  
\*\*Default:\*\* \`\[\]\`  

You can use the `excludeFiles` property to prevent specific files from being bundled that would otherwise be included. This is helpful for:

-   Reducing bundle size
-   Excluding large binaries
-   Preventing unwanted files from being deployed

Provide an array of specific files to exclude with file paths relative to your project's [`root`](/en/reference/configuration-reference/#root). Absolute paths may not work as expected.

#### Using glob patterns

Both `includeFiles` and `excludeFiles` support [glob patterns](/en/guides/imports/#glob-patterns) for matching multiple files:

### Local development features

When running `astro dev`, the adapter enables several Netlify platform features to ensure the environment matches production as closely as possible. These include:

-   A local [Netlify Image CDN](https://docs.netlify.com/build/image-cdn/overview/) server. This is used for [images](#netlify-image-cdn-support) by default.
-   A local [Netlify Blobs](https://docs.netlify.com/build/data-and-storage/netlify-blobs/) server. This is used for [sessions](#sessions) by default
-   [Redirects, rewrites](https://docs.netlify.com/manage/routing/redirects/overview/) and [headers](https://docs.netlify.com/manage/routing/headers/) from your Netlify config
-   Access to [Netlify Edge Context](#accessing-edge-context-from-your-site) in on-demand pages
-   Emulation of [Netlify Edge Functions](https://docs.netlify.com/build/edge-functions/overview/) defined in your project's `netlify/edge-functions` directory
-   [Environment variables](https://docs.netlify.com/build/environment-variables/overview/) from your Netlify site

These work best when your local site is [linked to a Netlify site](https://docs.netlify.com/api-and-cli-guides/cli-guides/get-started-with-cli/#link-and-unlink-sites) using `netlify link`.

You can enable or disable some of these features using the [`devFeatures`](#devfeatures) option in your adapter configuration. By default, all features are enabled except for environment variables.

#### `devFeatures`

\*\*Type:\*\* \`boolean | object\`  
\*\*Default:\*\* \`{ images: true, environmentVariables: false, edgeFunctions: true }\`  

The `devFeatures` option can be either a boolean to enable or disable all features, or an object to enable specific features.

##### `devFeatures.images`

\*\*Type:\*\* \`boolean\`  
\*\*Default:\*\* \`true\`  

Enables support for the local [Netlify Image CDN](https://docs.netlify.com/build/image-cdn/overview/) in development.

This uses a local version of the Netlify Image CDN, rather than the default Astro image service.

##### `devFeatures.environmentVariables`

\*\*Type:\*\* \`boolean\`  
\*\*Default:\*\* \`false\`  

Injects environment variables from your Netlify site into the development environment.

This allows you to use the same values in development as you would in production. See [the Netlify docs on environment variables](https://docs.netlify.com/build/environment-variables/overview/) for more information, including how to use different variables for different environments.

##### `devFeatures.edgeFunctions`

\*\*Type:\*\* \`boolean\`  
\*\*Default:\*\* \`true\`  

Emulates [Netlify Edge Functions](https://docs.netlify.com/build/edge-functions/overview/) defined in your project's `netlify/edge-functions` directory during development.

Some npm packages that access the filesystem when they are initialized do not work inside the edge function sandbox and fail with an error such as `Reading or writing files with Edge Functions is not supported yet`. If you encounter these errors, set `edgeFunctions` to `false` to disable edge function emulation and use `netlify dev` instead. Edge functions will still work in production builds.

### `staticHeaders`

\*\*Type:\*\* \`boolean\`  
\*\*Default:\*\* \`false\`  

Enables specifying custom headers for prerendered pages in Netlify's configuration.

If enabled, the adapter will save [static headers in the Framework API config file](https://docs.netlify.com/frameworks-api/#headers) when provided by Astro features, such as Content Security Policy.

For example, when [Content Security Policy](/en/reference/configuration-reference/#securitycsp) is enabled, `staticHeaders` can be used to add the CSP `headers` to your Netlify configuration, instead of creating a `<meta>` element:

## Examples

-   The [Astro Netlify Edge Starter](https://github.com/sarahetter/astro-netlify-edge-starter) provides an example and a guide in the README.
    
-   [Browse Astro Netlify projects on GitHub](https://github.com/search?q=path%3A**%2Fastro.config.mjs+%40astrojs%2Fnetlify&type=code) for more examples!

## [@astrojs/node](https://docharvest.github.io/docs/astro/guides/integrations-guide/node/)



## [@astrojs/partytown](https://docharvest.github.io/docs/astro/guides/integrations-guide/partytown/)

Contents

astro

@astrojs/partytown

Astro

@astrojs/partytown

This **[Astro integration](/en/guides/integrations/)** enables [Partytown](https://partytown.qwik.dev/) in your Astro project.

## Why Astro Partytown

Partytown is a lazy-loaded library to help relocate resource intensive scripts into a [web worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API), and off of the [main thread](https://developer.mozilla.org/en-US/docs/Glossary/Main_thread).

If you're using third-party scripts for things like analytics or ads, Partytown is a great way to make sure that they don't slow down your site.

The Astro Partytown integration installs Partytown for you and makes sure it's enabled on all of your pages.

## Installation

Astro includes an `astro add` command to automate the setup of official integrations. If you prefer, you can [install integrations manually](#manual-install) instead.

Run one of the following commands in a new terminal window.

\`\`\`sh npx astro add partytown \`\`\` \`\`\`sh pnpm astro add partytown \`\`\` \`\`\`sh yarn astro add partytown \`\`\`

If you run into any issues, [feel free to report them to us on GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.

### Manual Install

First, install the `@astrojs/partytown` package:

\`\`\`sh npm install @astrojs/partytown \`\`\` \`\`\`sh pnpm add @astrojs/partytown \`\`\` \`\`\`sh yarn add @astrojs/partytown \`\`\`

Then, apply the integration to your `astro.config.*` file using the `integrations` property:

## Usage

Partytown should be ready to go with zero config. If you have an existing 3rd party script on your site, try adding the `type="text/partytown"` attribute:

```
<script type="text/partytown" src="fancy-analytics.js"></script>
```

If you open the "Network" tab from [your browser's dev tools](https://developer.chrome.com/docs/devtools/open/), you should see the `partytown` proxy intercepting this request.

## Configuration

To configure this integration, pass a 'config' object to the `partytown()` function call in `astro.config.mjs`.

This mirrors the [Partytown config object](https://partytown.qwik.dev/configuration/) and all options can be set in `partytown.config`. Some common configuration options for Astro projects are described on this page.

### Enabling debug mode

Partytown ships with a `debug` mode; enable or disable it by passing `true` or `false` to `config.debug`. If [`debug` mode](https://partytown.qwik.dev/debugging) is enabled, it will output detailed logs to the browser console.

If this option isn't set, `debug` mode will be on by default in [dev](/en/reference/cli-reference/#astro-dev) or [preview](/en/reference/cli-reference/#astro-preview) mode.

### Forwarding variables

Third-party scripts typically add variables to the `window` object so that you can communicate with them throughout your site. But when a script is loaded in a web-worker, it doesn't have access to that global `window` object.

To solve this, Partytown can "patch" variables to the global window object and forward them to the appropriate script.

You can specify which variables to forward with the `config.forward` option. [Read more in Partytown's documentation.](https://partytown.qwik.dev/forwarding-events)

### Proxying requests

Some third-party scripts may require [proxying](https://partytown.qwik.dev/proxying-requests/) through `config.resolveUrl()`, which runs inside the service worker. You can set this configuration option to check for a specific URL, and optionally return a proxied URL instead:

```

          return url;
        },
      }
    }),
  ],
});
```

However since the `config` object is serialized when sent to the client, some limitations on functions passed to your configuration apply:

-   Functions cannot reference anything outside of the function scope.
-   Functions can only be written in JavaScript.

In some advanced use cases, you may need to pass data to this function while initializing Partytown. To do so, you can set `resolveUrl()` on `window.partytown` instead of the integration config:

```
---
const proxyMap = {
  "connect.facebook.net": "my-proxy.com"
};
---

<script is:inline set:html={`
  window.partytown = {
    resolveUrl: (url) => {
      const proxyMap = ${JSON.stringify(proxyMap)};
      url.hostname = proxyMap[url.hostname] || url.hostname;
      return url;
    },
  };
`} />
```

Note that the integration config will override `window.partytown` if you set a property in both.

## Examples

-   [Browse projects with Astro Partytown on GitHub](https://github.com/search?q=%22%40astrojs%2Fpartytown%22+path%3A**%2Fpackage.json&type=code) for more examples!

## Community Resources

-   [Implementing Google Tag Manager with Partytown and Astro](https://medium.com/@tagperfect/implementing-google-tag-manager-with-partytown-js-in-astro-my-modest-experience-983388907b35)
-   [Optimise Google Analytics using Partytown in Astro](https://ricostacruz.com/posts/google-analytics-in-astro)

## [@astrojs/preact](https://docharvest.github.io/docs/astro/guides/integrations-guide/preact/)

Contents

astro

@astrojs/preact

Astro

@astrojs/preact

This **[Astro integration](/en/guides/integrations/)** enables rendering and client-side hydration for your [Preact](https://preactjs.com/) components.

## Why Preact?

Preact is a library that lets you build interactive UI components for the web. If you want to build interactive features on your site using JavaScript, you may prefer using its component format instead of using browser APIs directly.

Preact is also a great choice if you have previously used React. Preact provides the same API as React, but in a much smaller 3kB package. It even supports rendering many React components using the `compat` configuration option (see below).

**Want to learn more about Preact before using this integration?**  
Check out [“Learn Preact”](https://preactjs.com/tutorial), an interactive tutorial on their website.

## Installation

Astro includes an `astro add` command to automate the setup of official integrations. If you prefer, you can [install integrations manually](#manual-install) instead.

To install `@astrojs/preact`, run the following from your project directory and follow the prompts:

\`\`\`sh npx astro add preact \`\`\` \`\`\`sh pnpm astro add preact \`\`\` \`\`\`sh yarn astro add preact \`\`\`

If you run into any issues, [feel free to report them to us on GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.

### Manual Install

First, install the `@astrojs/preact` package:

\`\`\`sh npm install @astrojs/preact \`\`\` \`\`\`sh pnpm add @astrojs/preact \`\`\` \`\`\`sh yarn add @astrojs/preact \`\`\`

Most package managers will install associated peer dependencies as well. If you see a `Cannot find package 'preact'` (or similar) warning when you start up Astro, you'll need to install Preact:

\`\`\`sh npm install preact \`\`\` \`\`\`sh pnpm add preact \`\`\` \`\`\`sh yarn add preact \`\`\`

Then, apply the integration to your `astro.config.*` file using the `integrations` property:

And add the following code to the `tsconfig.json` file.

```
{
  "extends": "astro/tsconfigs/strict",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"],
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "preact"
  }
}
```

## Usage

To use your first Preact component in Astro, head to our [UI framework documentation](/en/guides/framework-components/#using-framework-components). You'll explore:

-   📦 how framework components are loaded,
-   💧 client-side hydration options, and
-   🤝 opportunities to mix and nest frameworks together

Also check our [Astro Integration Documentation](/en/guides/integrations/) for more on integrations.

## Configuration

The Astro Preact integration handles how Preact components are rendered and it has its own options. Change these in the `astro.config.mjs` file which is where your project's integration settings live.

For basic usage, you do not need to configure the Preact integration.

### `compat`

**Type:** `boolean`  

You can enable `preact/compat`, Preact’s compatibility layer for rendering React components without needing to install or ship React’s larger libraries to your users’ web browsers.

To do so, pass an object to the Preact integration and set `compat: true`.

With the `compat` option enabled, the Preact integration will render React components as well as Preact components in your project and also allow you to import React components inside Preact components. Read more in [“Switching to Preact (from React)”](https://preactjs.com/guide/v10/switching-to-preact) on the Preact website.

When importing React component libraries, in order to swap out the `react` and `react-dom` dependencies as `preact/compat`, you can use [`overrides`](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#overrides) to do so.

```
{
  "overrides": {
    "react": "npm:@preact/compat@latest",
    "react-dom": "npm:@preact/compat@latest"
  }
}
```

Check out the [`pnpm` overrides](https://pnpm.io/package_json#pnpmoverrides) and [`yarn` resolutions](https://yarnpkg.com/configuration/manifest#resolutions) docs for their respective overrides features.

:::note Currently, the `compat` option only works for React libraries that export code as ESM. If an error happens during build-time, try adding the library to `vite.ssr.noExternal: ['the-react-library']` in your `astro.config.mjs` file. :::

### `babel`

**Type:** [`BabelOptions`](https://github.com/preactjs/preset-vite#babel-configuration)  

You can pass additional [Babel configuration options](https://babeljs.io/docs/options) to the Preact Vite plugin. This allows you to customize the Babel transformation applied to your Preact components.

For example, the following configuration tells Babel to load `.babelrc` when processing your Preact components:

### `devtools`

**Type:** `boolean`  

You can enable [Preact devtools](https://preactjs.github.io/preact-devtools/) in development by passing an object with `devtools: true` to your `preact()` integration config:

## Options

### Combining multiple JSX frameworks

When you are using multiple JSX frameworks (React, Preact, Solid) in the same project, Astro needs to determine which JSX framework-specific transformations should be used for each of your components. If you have only added one JSX framework integration to your project, no extra configuration is needed.

Use the `include` (required) and `exclude` (optional) configuration options to specify which files belong to which framework. Provide an array of files and/or folders to `include` for each framework you are using. Wildcards may be used to include multiple file paths.

We recommend placing common framework components in the same folder (e.g. `/components/react/` and `/components/solid/`) to make specifying your includes easier, but this is not required:

## Examples

-   The [Astro Preact example](https://github.com/withastro/astro/tree/latest/examples/framework-preact) shows how to use an interactive Preact component in an Astro project.
-   The [Astro Nanostores example](https://github.com/withastro/astro/tree/latest/examples/with-nanostores) shows how to share state between different components — and even different frameworks! — in an Astro project.

## [@astrojs/prefetch](https://docharvest.github.io/docs/astro/guides/integrations-guide/prefetch/)

Contents

astro

@astrojs/prefetch

Astro

@astrojs/prefetch

:::caution\[Removed\] `@astrojs/prefetch` has been replaced by the [built-in `prefetch` feature](/en/guides/prefetch/) introduced in Astro 3.5. See the [migration guide](/en/guides/prefetch/#migrating-from-astrojsprefetch) for instructions on updating an older project.

If you are still using this integration in a pre-v3.5 Astro project, you can read an archived copy of [the `@astrojs/prefetch` README](https://github.com/withastro/astro/blob/c47478bbf6b21973419f25234c68efb59466b368/packages%2Fintegrations%2Fprefetch%2FREADME.md) on GitHub. :::

## [@astrojs/react](https://docharvest.github.io/docs/astro/guides/integrations-guide/react/)

Contents

astro

@astrojs/react

Astro

@astrojs/react

This **[Astro integration](/en/guides/integrations/)** enables rendering and client-side hydration for your [React](https://react.dev/) components.

## Installation

Astro includes an `astro add` command to automate the setup of official integrations. If you prefer, you can [install integrations manually](#manual-install) instead.

To install `@astrojs/react`, run the following from your project directory and follow the prompts:

\`\`\`sh npx astro add react \`\`\` \`\`\`sh pnpm astro add react \`\`\` \`\`\`sh yarn astro add react \`\`\`

If you run into any issues, [feel free to report them to us on GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.

### Manual Install

First, install the `@astrojs/react` package:

\`\`\`sh npm install @astrojs/react \`\`\` \`\`\`sh pnpm add @astrojs/react \`\`\` \`\`\`sh yarn add @astrojs/react \`\`\`

Most package managers will install associated peer dependencies as well. If you see a `Cannot find package 'react'` (or similar) warning when you start up Astro, you'll need to install `react` and `react-dom` with its type definitions:

\`\`\`sh npm install react react-dom @types/react @types/react-dom \`\`\` \`\`\`sh pnpm add react react-dom @types/react @types/react-dom \`\`\` \`\`\`sh yarn add react react-dom @types/react @types/react-dom \`\`\`

Then, apply the integration to your `astro.config.*` file using the `integrations` property:

And add the following code to the `tsconfig.json` file.

```
{
  "extends": "astro/tsconfigs/strict",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"],
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "react"
  }
}
```

## Getting started

To use your first React component in Astro, head to our [UI framework documentation](/en/guides/framework-components/#using-framework-components). You'll explore:

-   📦 how framework components are loaded,
-   💧 client-side hydration options, and
-   🤝 opportunities to mix and nest frameworks together

## Integrate Actions with `useActionState()`

The `@astrojs/react` integration provides two functions for use with [Astro Actions](/en/guides/actions/): `withState()` and `getActionState()`.

These are used with [React's useActionState() hook](https://react.dev/reference/react/useActionState) to read and update client-side state when triggering actions during form submission.

### `withState()`

**Type:** `(action: FormFn<T>) => (state: T, formData: FormData) => FormFn<T>`  

You can pass `withState()` and the action you want to trigger to React's `useActionState()` hook as the form action function. The example below passes a `like` action to increase a counter along with an initial state of `0` likes.

```

  return (
    <form action={action}>
      <input type="hidden" name="postId" value={postId} />
      <button disabled={pending}>{state.data} ❤️</button>
    </form>
  );
}
```

The `withState()` function will match the action's types with React's expectations and preserve metadata used for progressive enhancement, allowing it to work even when JavaScript is disabled on the user's device.

### `getActionState()`

**Type:** `(context: ActionAPIContext) => Promise<T>`  

You can access the state stored by `useActionState()` on the server in your action `handler` with `getActionState()`. It accepts the [Astro API context](/en/reference/api-reference/#the-context-object), and optionally, you can apply a type to the result.

The example below gets the current value of likes from a counter, typed as a number, in order to create an incrementing `like` action:

```

      // handle errors
      if (error) throw error;

      // write to database
      return currentLikes + 1;
    },
  })
};
```

## Options

### Combining multiple JSX frameworks

When you are using multiple JSX frameworks (React, Preact, Solid) in the same project, Astro needs to determine which JSX framework-specific transformations should be used for each of your components. If you have only added one JSX framework integration to your project, no extra configuration is needed.

Use the `include` (required) and `exclude` (optional) configuration options to specify which files belong to which framework. Provide an array of files and/or folders to `include` for each framework you are using. Wildcards may be used to include multiple file paths.

We recommend placing common framework components in the same folder (e.g. `/components/react/` and `/components/solid/`) to make specifying your includes easier, but this is not required:

### Children parsing

Children passed into a React component from an Astro component are parsed as plain strings, not React nodes.

For example, the `<ReactComponent />` below will only receive a single child element:

```
---

---

<ReactComponent>
  <div>one</div>
  <div>two</div>
</ReactComponent>
```

If you are using a library that _expects_ more than one child element to be passed, for example so that it can slot certain elements in different places, you might find this to be a blocker.

You can set the experimental flag `experimentalReactChildren` to tell Astro to always pass children to React as React virtual DOM nodes. There is some runtime cost to this, but it can help with compatibility.

You can enable this option in the configuration for the React integration:

### Disable streaming (experimental)

Astro streams the output of React components by default. However, you can disable this behavior by enabling the `experimentalDisableStreaming` option. This is particularly helpful for supporting libraries that don’t work well with streaming, like some CSS-in-JS solutions.

To disable streaming for all React components in your project, configure `@astrojs/react` with `experimentalDisableStreaming: true`:

## [@astrojs/sitemap](https://docharvest.github.io/docs/astro/guides/integrations-guide/sitemap/)

Contents

astro

@astrojs/sitemap

Astro

@astrojs/sitemap

This **[Astro integration](/en/guides/integrations/)** generates a sitemap based on your pages when you build your Astro project.

## Why Astro Sitemap

A Sitemap is an XML file that outlines all of the pages, videos, and files on your site. Search engines like Google read this file to crawl your site more efficiently. [See Google's own advice on sitemaps](https://developers.google.com/search/docs/advanced/sitemaps/overview) to learn more.

A sitemap file is recommended for large multi-page sites. If you don't use a sitemap, most search engines will still be able to list your site's pages, but a sitemap is a great way to ensure that your site is as search engine friendly as possible.

With Astro Sitemap, you don't have to worry about creating this XML file yourself: the Astro Sitemap integration will crawl your statically-generated routes and create the sitemap file, including [dynamic routes](/en/guides/routing/#dynamic-routes) like `[...slug]` or `src/pages/[lang]/[version]/info.astro` generated by `getStaticPaths()`.

This integration cannot generate sitemap entries for dynamic routes in [SSR mode](/en/guides/on-demand-rendering/).

## Installation

Astro includes an `astro add` command to automate the setup of official integrations. If you prefer, you can [install integrations manually](#manual-install) instead.

Run one of the following commands in a new terminal window.

\`\`\`sh npx astro add sitemap \`\`\` \`\`\`sh pnpm astro add sitemap \`\`\` \`\`\`sh yarn astro add sitemap \`\`\`

If you run into any issues, [feel free to report them to us on GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.

### Manual Install

First, install the `@astrojs/sitemap` package using your package manager.

\`\`\`sh npm install @astrojs/sitemap \`\`\` \`\`\`sh pnpm add @astrojs/sitemap \`\`\` \`\`\`sh yarn add @astrojs/sitemap \`\`\`

Then, apply the integration to your `astro.config.*` file using the `integrations` property:

## Usage

`@astrojs/sitemap` needs to know your site’s deployed URL to generate a sitemap.

Add your site's URL as the [`site`](/en/reference/configuration-reference/#site) option in `astro.config.mjs`. This must begin with `http://` or `https://`.

With the sitemap integration configured, `sitemap-index.xml` and `sitemap-0.xml` files will be added to your output directory when building your site.

`sitemap-index.xml` links to all the numbered sitemap files. `sitemap-0.xml` lists the pages on your site. For extremely large sites, there may also be additional numbered files like `sitemap-1.xml` and `sitemap-2.xml`.

Example of generated files for a two-page website

```
<?xml version="1.0" encoding="UTF-8"?>
  <sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <sitemap>
    <loc>https://example.com/sitemap-0.xml</loc>
  </sitemap>
</sitemapindex>
```

```
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:news="http://www.google.com/schemas/sitemap-news/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1" xmlns:video="http://www.google.com/schemas/sitemap-video/1.1">
  <url>
    <loc>https://example.com/</loc>
  </url>
  <url>
    <loc>https://example.com/second-page/</loc>
  </url>
</urlset>
```

### Sitemap discovery

You can make it easier for crawlers to find your sitemap with links in your site's `<head>` and `robots.txt` file.

#### Sitemap link in `<head>`

Add a `<link rel="sitemap">` element to your site’s `<head>` pointing to the sitemap index file:

```
<head>
  <link rel="sitemap" href="/sitemap-index.xml" />
</head>
```

#### Sitemap link in `robots.txt`

If you have a `robots.txt` for your website, you can add the URL for the sitemap index to help crawlers:

```
# public/robots.txt
User-agent: *
Allow: /

Sitemap: https://<YOUR SITE>/sitemap-index.xml
```

If you want to reuse the `site` value from `astro.config.mjs`, you can also generate `robots.txt` dynamically. Instead of using a static file in the `public/` directory, create a `src/pages/robots.txt.ts` file and add the following code:

```

const getRobotsTxt = (sitemapURL: URL) => `\
User-agent: *
Allow: /

Sitemap: ${sitemapURL.href}
`;

  return new Response(getRobotsTxt(sitemapURL));
};
```

## Configuration

To configure this integration, pass an object to the `sitemap()` function in `astro.config.mjs`.

### `filter()`

**Type:** `(page: string) => boolean`

All pages are included in your sitemap by default. By adding a custom `filter()` function, you can filter included pages by URL.

The function will be called for every page on your site. The `page` function parameter is the full URL of the page currently under consideration, including your `site` domain. Return `true` to include the page in your sitemap, and `false` to leave it out.

To filter multiple pages, add arguments with target URLs.

### `customPages`

**Type:** `string[]`

An array of externally-generated pages to be included in the generated sitemap file.

Use this option to include pages in your sitemap that are a part of your deployed site but are not created by Astro.

### `customSitemaps`

**Type:** `string[]`  
**Default:** `[]`  

An array of externally-generated sitemaps to be included in the `sitemap-index.xml` file along with the generated sitemap entries.

Use this option to include external sitemaps in the `sitemap-index.xml` file created by Astro for sections of your deployed site that have their own sitemaps not created by Astro. This is helpful when you host multiple services under the same domain.

### `entryLimit`

**Type:** `number`  
**Default:** `45000`

The maximum number entries per sitemap file. The default value is 45000. A sitemap index and multiple sitemaps are created if you have more entries. See this [explanation of splitting up a large sitemap](https://developers.google.com/search/docs/advanced/sitemaps/large-sitemaps).

### `changefreq`, `lastmod`, and `priority`

**Type:** `{ changefreq?: [ChangeFreq](#changefreq); lastmod?: Date; priority?: number; }`

These options correspond to the `<changefreq>`, `<lastmod>`, and `<priority>` tags in the [Sitemap XML specification.](https://www.sitemaps.org/protocol.html)

Note that `changefreq` and `priority` are ignored by Google.

:::note Due to limitations of Astro's [Integration API](/en/reference/integrations-reference/), this integration can't analyze a given page's source code. This configuration option can set `changefreq`, `lastmod` and `priority` on a _site-wide_ basis; see the next option **serialize** for how you can set these values on a per-page basis. :::

### `serialize()`

**Type:** `(item: [SitemapItem](#sitemapitem)) => SitemapItem | Promise<SitemapItem | undefined> | undefined`

Generates an editable representation of each sitemap entry before returning either a [`SitemapItem`](#sitemapitem) or `undefined` to remove it from the sitemap. This function can be asynchronous and is called for each sitemap entry just before writing to disk.

The following example filters a page from the sitemap and updates a specific entry to modify its `changefreq`, `lastmod`, and `priority` properties:

```

        }
        if (/your-special-page/.test(item.url)) {
          item.changefreq = ChangeFreqEnum.DAILY;
          item.lastmod = new Date().toISOString();
          item.priority = 0.9;
        }
        return item;
      },
    }),
  ],
});
```

### `chunks`

**Type:** `Record<string, (item: [SitemapItem](#sitemapitem)) => SitemapItem | undefined>`

A map of functions that allows you to split your sitemap into multiple files based on custom logic. Each key in the object becomes the name of a separate sitemap file, and its corresponding function determines which URLs will be included in that chunk. This can be useful for instance if a specific section of your website changes very often and you'd like to specify a different change frequency for its entries.

Each chunk function receives a [`SitemapItem`](#sitemapitem) and for each item returns either:

-   the modified `SitemapItem`, if the URL should be included in this chunk
-   `undefined`, if the URL should not be included in this chunk

The example below shows how to split URLs into different sitemap files based on their path:

```

            item.lastmod = new Date().toISOString();
            item.priority = 0.9;
            return item;
          }
        },
        'glossary': (item) => {
          if (/glossary/.test(item.url)) {
            item.changefreq = ChangeFreqEnum.MONTHLY;
            item.lastmod = new Date().toISOString();
            item.priority = 0.7;
            return item;
          }
        }
      },
    }),
  ],
});
```

This configuration will generate the following files:

-   `sitemap-blog-0.xml`
-   `sitemap-glossary-0.xml`

URLs that don't match any chunk will be placed in a default `sitemap-pages-0.xml` file.

### `i18n`

**Type:** `{ defaultLocale: string; locales: Record<string, string>; }`

To [localize a sitemap](https://developers.google.com/search/docs/advanced/crawling/localized-versions#all-method-guidelines), pass an object to this `i18n` option.

This object has two required properties:

-   `defaultLocale`: Its value must exist as one of `locales` keys.
-   `locales`: key/value - pairs. The key is used to look for a locale part in a page path. The value is a [language attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang), only English alphabet and hyphen allowed.

The resulting sitemap looks like this:

```
...
  <url>
    <loc>https://example.com/</loc>
    <xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/"/>
    <xhtml:link rel="alternate" hreflang="es-ES" href="https://example.com/es/"/>
    <xhtml:link rel="alternate" hreflang="fr-CA" href="https://example.com/fr/"/>
  </url>
  <url>
    <loc>https://example.com/es/</loc>
    <xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/"/>
    <xhtml:link rel="alternate" hreflang="es-ES" href="https://example.com/es/"/>
    <xhtml:link rel="alternate" hreflang="fr-CA" href="https://example.com/fr/"/>
  </url>
  <url>
    <loc>https://example.com/fr/</loc>
    <xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/"/>
    <xhtml:link rel="alternate" hreflang="es-ES" href="https://example.com/es/"/>
    <xhtml:link rel="alternate" hreflang="fr-CA" href="https://example.com/fr/"/>
  </url>
  <url>
    <loc>https://example.com/es/second-page/</loc>
    <xhtml:link rel="alternate" hreflang="es-ES" href="https://example.com/es/second-page/"/>
    <xhtml:link rel="alternate" hreflang="fr-CA" href="https://example.com/fr/second-page/"/>
    <xhtml:link rel="alternate" hreflang="en-US" href="https://example.com/second-page/"/>
  </url>
...
```

### `xslURL`

**Type:** `string`  

The URL of an XSL stylesheet to style and prettify your sitemap.

The value set can be either a path relative to your configured `site` URL for a local stylesheet, or can be an absolute URL link to an external stylesheet.

### `filenameBase`

**Type:** `string`  
**Default:** `sitemap`  

The name prefix string used when generating the sitemap XML files. The default value is `sitemap`.

This option may be useful when integrating an Astro site into a domain with preexisting sitemap files.

The given configuration will generate sitemap files at `https://example.com/astronomy-sitemap-0.xml` and `https://example.com/astronomy-sitemap-index.xml`.

### `namespaces`

**Type:** `{ news?: boolean; xhtml?: boolean; image?: boolean; video?: boolean; }`  
**Default:** `{ news: true, xhtml: true, image: true, video: true }`  

An object of XML namespaces to exclude from the generated sitemap.

Excluding unused namespaces can help create more focused sitemaps that are faster for search engines to parse and use less bandwidth. For example, if your site doesn't have news content, videos, or multiple languages, you can exclude those namespaces to reduce XML bloat.

By default, all configurable namespaces (`news`, `xhtml`, `image`, and `video`) are included in your generated sitemap XML. To exclude one or more of these namespaces from your sitemap generation, add a `namespaces` configuration object and set individual options to `false`:

## Astro Sitemap utilities reference

### `ChangeFreqEnum`

A [TypeScript enumeration](https://www.typescriptlang.org/docs/handbook/enums.html) where each key is the uppercase version of a valid value defined in the [specification of `<changefreq>`](https://www.sitemaps.org/protocol.html#changefreqdef).

The following example uses `serialize()` to update the [`changefreq`](#sitemapitemchangefreq) of the blog index:

```

        }

        return item;
      },
    }),
  ],
});
```

## Astro Sitemap types reference

### `ChangeFreq`

**Type:** `"daily" | "monthly" | "always" | "hourly" | "weekly" | "yearly" | "never"`

A union of valid values to specify the update frequency of an entry.

### `LinkItem`

**Type:** `{ lang: string; hreflang?: string; url: string; }`

Describes the URL of a page. This could be the default version of the document or one of its translations.

#### `LinkItem.lang`

**Type:** `string`

Specifies the language code supported by this version of the page. When a value is set, you do not need to also set [`hreflang`](#linkitemhreflang).

#### `LinkItem.hreflang`

**Type:** `string`

Specifies the language code supported by this version of the page. When a value is set, you do not need to also set [`lang`](#linkitemlang).

#### `LinkItem.url`

**Type:** `string`

Specifies the absolute URL of the page for the specified language.

### `SitemapItem`

**Type:** `{ url: string; lastmod?: string | undefined; changefreq?: ChangeFreqEnum | undefined; priority?: number | undefined; links?: LinkItem[] | undefined; }`

Describes an entry in a sitemap. This contains its `url` and additional optional properties.

#### `SitemapItem.url`

**Type:** `string`

Specifies the absolute page URL.

#### `SitemapItem.lastmod`

**Type:** `string | undefined`

Defines the ISO formatted date of last modification of the page as a string.

#### `SitemapItem.changefreq`

**Type:** `[ChangeFreqEnum](#changefreqenum) | undefined`

Defines how frequently the page is likely to change.

#### `SitemapItem.priority`

**Type:** `number | undefined`

Defines the priority of this URL relative to other URLs on your site. The value should be a number in the range from `0.0` to `1.0`.

#### `SitemapItem.links`

**Type:** `[LinkItem](#linkitem)[] | undefined`

Defines a list of alternate pages, including the current page.

### `SitemapOptions`

**Type:** `object`

Describes the [configuration options](#configuration).

## Examples

-   The official Astro website uses Astro Sitemap to generate [its sitemap](https://astro.build/sitemap-index.xml).
-   [Browse projects with Astro Sitemap on GitHub](https://github.com/search?q=%22%40astrojs%2Fsitemap%22+path%3Apackage.json&type=Code) for more examples!

## [@astrojs/solid-js](https://docharvest.github.io/docs/astro/guides/integrations-guide/solid-js/)

Contents

astro

@astrojs/solid-js

Astro

@astrojs/solid-js

This **[Astro integration](/en/guides/integrations/)** enables rendering and client-side hydration for your [SolidJS](https://www.solidjs.com/) components.

## Installation

Astro includes an `astro add` command to automate the setup of official integrations. If you prefer, you can [install integrations manually](#manual-install) instead.

To install `@astrojs/solid-js`, run the following from your project directory and follow the prompts:

\`\`\`sh npx astro add solid \`\`\` \`\`\`sh pnpm astro add solid \`\`\` \`\`\`sh yarn astro add solid \`\`\`

If you run into any issues, [feel free to report them to us on GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.

### Manual Install

First, install the `@astrojs/solid-js` package:

\`\`\`sh npm install @astrojs/solid-js \`\`\` \`\`\`sh pnpm add @astrojs/solid-js \`\`\` \`\`\`sh yarn add @astrojs/solid-js \`\`\`

Most package managers will install associated peer dependencies as well. If you see a `Cannot find package 'solid-js'` (or similar) warning when you start up Astro, you'll need to install SolidJS:

\`\`\`sh npm install solid-js \`\`\` \`\`\`sh pnpm add solid-js \`\`\` \`\`\`sh yarn add solid-js \`\`\`

Then, apply the integration to your `astro.config.*` file using the `integrations` property:

And add the following code to the `tsconfig.json` file.

```
{
  "extends": "astro/tsconfigs/strict",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"],
  "compilerOptions": {
    "jsx": "preserve",
    "jsxImportSource": "solid-js"
  }
}
```

## Getting started

To use your first SolidJS component in Astro, head to our [UI framework documentation](/en/guides/framework-components/#using-framework-components). You'll explore:

-   📦 how framework components are loaded,
-   💧 client-side hydration options, and
-   🤝 opportunities to mix and nest frameworks together

## Configuration

### `devtools`

**Type:** `boolean`  

You can enable [Solid DevTools](https://github.com/thetarnav/solid-devtools) in development by passing an object with `devtools: true` to your `solid()` integration config and adding `solid-devtools` to your project dependencies:

\`\`\`sh npm install solid-devtools \`\`\` \`\`\`sh pnpm add solid-devtools \`\`\` \`\`\`sh yarn add solid-devtools \`\`\`

## Options

### Combining multiple JSX frameworks

When you are using multiple JSX frameworks (React, Preact, Solid) in the same project, Astro needs to determine which JSX framework-specific transformations should be used for each of your components. If you have only added one JSX framework integration to your project, no extra configuration is needed.

Use the `include` (required) and `exclude` (optional) configuration options to specify which files belong to which framework. Provide an array of files and/or folders to `include` for each framework you are using. Wildcards may be used to include multiple file paths.

We recommend placing common framework components in the same folder (e.g. `/components/react/` and `/components/solid/`) to make specifying your includes easier, but this is not required:

## Usage

Use a SolidJS component as you would any [UI framework component](/en/guides/framework-components/).

### Suspense Boundaries

In order to support Solid Resources and Lazy Components without excessive configuration, server-only and hydrating components are automatically wrapped in top-level Suspense boundaries and rendered on the server using the [`renderToStringAsync`](https://www.solidjs.com/docs/latest/api#rendertostringasync) function. Therefore, you do not need to add a top-level Suspense boundary around async components.

For example, you can use Solid's [`createResource`](https://www.solidjs.com/docs/latest/api#createresource) to fetch async remote data on the server. The remote data will be included in the initial server-rendered HTML from Astro:

```
// CharacterName.tsx
function CharacterName() {
  const [name] = createResource(() =>
    fetch('https://swapi.dev/api/people/1')
      .then((result) => result.json())
      .then((data) => data.name)
  );

  return (
    <>
      <h2>Name:</h2>
      {/* Luke Skywalker */}
      <div>{name()}</div>
    </>
  );
}
```

Similarly, Solid's [Lazy Components](https://www.solidjs.com/docs/latest/api#lazy) will also be resolved and their HTML will be included in the initial server-rendered page.

Non-hydrating [`client:only` components](/en/reference/directives-reference/#clientonly) are not automatically wrapped in Suspense boundaries.

Feel free to add additional Suspense boundaries according to your preference.

## [@astrojs/svelte](https://docharvest.github.io/docs/astro/guides/integrations-guide/svelte/)

Contents

astro

@astrojs/svelte

Astro

@astrojs/svelte

This **[Astro integration](/en/guides/integrations/)** enables rendering and client-side hydration for your [Svelte](https://svelte.dev/) 5 components. For Svelte 3 and 4 support, install `@astrojs/svelte@5` instead.

## Installation

Astro includes an `astro add` command to automate the setup of official integrations. If you prefer, you can [install integrations manually](#manual-install) instead.

To install `@astrojs/svelte`, run the following from your project directory and follow the prompts:

\`\`\`sh npx astro add svelte \`\`\` \`\`\`sh pnpm astro add svelte \`\`\` \`\`\`sh yarn astro add svelte \`\`\`

If you run into any issues, [feel free to report them to us on GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.

### Manual Install

First, install the `@astrojs/svelte` package:

\`\`\`sh npm install @astrojs/svelte \`\`\` \`\`\`sh pnpm add @astrojs/svelte \`\`\` \`\`\`sh yarn add @astrojs/svelte \`\`\`

Most package managers will install associated peer dependencies as well. If you see a `Cannot find package 'svelte'` (or similar) warning when you start up Astro, you'll need to install Svelte and TypeScript:

\`\`\`sh npm install svelte typescript \`\`\` \`\`\`sh pnpm add svelte typescript \`\`\` \`\`\`sh yarn add svelte typescript \`\`\`

Then, apply the integration to your `astro.config.*` file using the `integrations` property:

And create a new file called `svelte.config.js` in your project root directory and add the following code:

## Preprocessors

If you're using SCSS or Stylus in your Svelte files, you can create a `svelte.config.js` file so that they are preprocessed by Svelte, and the Svelte IDE extension can correctly parse the Svelte files.

This config file will be automatically added for you when you run `astro add svelte`. See the [`@sveltejs/vite-plugin-svelte` docs](https://github.com/sveltejs/vite-plugin-svelte/blob/HEAD/docs/preprocess.md) for more details about `vitePreprocess`.

## [@astrojs/tailwind](https://docharvest.github.io/docs/astro/guides/integrations-guide/tailwind/)

Contents

astro

@astrojs/tailwind

Astro

@astrojs/tailwind

:::caution\[Deprecated\] Tailwind CSS now offers a Vite plugin which is the preferred way to use Tailwind 4 in Astro. :::

To use Tailwind in Astro, follow the [styling guide for Tailwind](/en/guides/styling/#tailwind).

## [@astrojs/vercel](https://docharvest.github.io/docs/astro/guides/integrations-guide/vercel/)

Contents

astro

@astrojs/vercel

Astro

@astrojs/vercel

This adapter allows Astro to deploy your [on-demand rendered routes and features](/en/guides/on-demand-rendering/) to [Vercel](https://www.vercel.com/), including [server islands](/en/guides/server-islands/), [actions](/en/guides/actions/), and [sessions](/en/guides/sessions/).

If you're using Astro as a static site builder, you only need this adapter if you are using additional Vercel services (e.g. [Vercel Web Analytics](https://vercel.com/docs/analytics), [Vercel Image Optimization](https://vercel.com/docs/image-optimization)). Otherwise, you do not need an adapter to deploy your static site.

Learn how to deploy your Astro site in our [Vercel deployment guide](/en/guides/deploy/vercel/).

## Why Astro Vercel?

[Vercel](https://www.vercel.com/) is a deployment platform that allows you to host your site by connecting directly to your GitHub repository. This adapter enhances the Astro build process to prepare your project for deployment through Vercel.

## Installation

Astro includes an `astro add` command to automate the setup of official integrations. If you prefer, you can [install integrations manually](#manual-install) instead.

Add the Vercel adapter to enable on-demand rendering in your Astro project with the following `astro add` command. This will install `@astrojs/vercel` and make the appropriate changes to your `astro.config.mjs` file in one step.

\`\`\`sh npx astro add vercel \`\`\` \`\`\`sh pnpm astro add vercel \`\`\` \`\`\`sh yarn astro add vercel \`\`\`

Now, you can enable [on-demand rendering per page](/en/guides/on-demand-rendering/#enabling-on-demand-rendering), or set your build output configuration to `output: 'server'` to [server-render all your pages by default](/en/guides/on-demand-rendering/#server-mode).

### Manual Install

First, add the `@astrojs/vercel` adapter to your project’s dependencies using your preferred package manager:

\`\`\`sh npm install @astrojs/vercel \`\`\` \`\`\`sh pnpm add @astrojs/vercel \`\`\` \`\`\`sh yarn add @astrojs/vercel \`\`\`

Then, add the adapter to your `astro.config.*` file:

## Usage

Find out more about [deploying your project to Vercel](/en/guides/deploy/vercel/).

You can deploy by CLI (`vercel deploy`) or by connecting your new repo in the [Vercel Dashboard](https://vercel.com/). Alternatively, you can create a production build locally:

```
astro build
vercel deploy --prebuilt
```

## Configuration

To configure this adapter, pass an object to the `vercel()` function call in `astro.config.mjs`:

### `webAnalytics`

**Type:** `VercelWebAnalyticsConfig`  
**Available for:** Serverless, Static  

With `@vercel/analytics@1.3.x` or earlier, you can set `webAnalytics: { enabled: true }` in your Astro config to inject Vercel’s tracking scripts into all of your pages.

For `@vercel/analytics@1.4.0` and later, use Vercel's Analytics component to enable [Vercel Web Analytics](https://vercel.com/docs/concepts/analytics) instead.

### `imagesConfig`

**Type:** `VercelImageConfig`  
**Available for:** Serverless, Static  

Configuration options for [Vercel's Image Optimization API](https://vercel.com/docs/concepts/image-optimization). See [Vercel's image configuration documentation](https://vercel.com/docs/build-output-api/v3/configuration#images) for a complete list of supported parameters.

The `domains` and `remotePatterns` properties will automatically be filled using [the Astro corresponding `image` settings](/en/reference/configuration-reference/#image-options).

### `imageService`

**Type:** `boolean`  
**Available for:** Serverless, Static  

When enabled, an [Image Service](/en/reference/image-service-reference/) powered by the Vercel Image Optimization API will be automatically configured and used in production. In development, the image service specified by [`devImageService`](#devimageservice) will be used instead.

```
---

---

<!-- This component -->
<Image src={astroLogo} alt="My super logo!" />

<!-- will become the following HTML -->
<img
  src="/_vercel/image?url=_astro/logo.hash.png&w=...&q=..."
  alt="My super logo!"
  loading="lazy"
  decoding="async"
  width="..."
  height="..."
/>
```

### `devImageService`

**Type:** `'sharp' | string`  
**Default:** `sharp`  
**Available for:** Serverless, Static  

Allows you to configure which image service to use in development when [imageService](#imageservice) is enabled. This can be useful if you cannot install Sharp's dependencies on your development machine, but using another image service like Squoosh would allow you to preview images in your dev environment. Build is unaffected and will always use Vercel's Image Optimization.

It can also be set to any arbitrary value in order to use a custom image service instead of Astro's built-in ones.

### `isr`

**Type:** `boolean | VercelISRConfig`  
**Default:** `false`  
**Available for:** Serverless  

Allows your project to be deployed as an [ISR (Incremental Static Regeneration)](https://vercel.com/docs/incremental-static-regeneration) function, which caches your on-demand rendered pages in the same way as prerendered pages after first request.

To enable this feature, set `isr` to true in your Vercel adapter configuration in `astro.config.mjs`:

Note that ISR function requests do not include search params, similar to [requests](/en/reference/api-reference/#request) in static mode.

#### ISR cache invalidation

By default, an ISR function caches for the duration of your deployment. You can further control caching by setting an expiration time, or by excluding particular routes from caching entirely.

##### Time-based invalidation

By default, when ISR is enabled, routes use [Vercel's cache shielding](https://vercel.com/docs/incremental-static-regeneration#differences-between-isr-and-cache-control-headers) and any Cache-Control headers are ignored. Configuring an `expiration` value (in seconds) allows you to control how long routes are cached. This means Cache-Control directives set by your application are also respected.

The following example defines `expiration` to cache all pages on first request and save them for 1 day:

##### On-demand invalidation

To programmatically invalidate cached pages, create a bypass token and provide it to the `isr` config:

### `excludeFiles`

**Type:** `string[]`  
**Available for:** Serverless

Use this property to exclude any files from the bundling process that would otherwise be included.

### `maxDuration`

**Type:** `number`  
**Available for:** Serverless

Use this property to extend or limit the maximum duration (in seconds) that Serverless Functions can run before timing out. See the [Vercel documentation](https://vercel.com/docs/functions/serverless-functions/runtimes#maxduration) for the default and maximum limit for your account plan.

### `skewProtection`

**Type:** `boolean`  
**Available for:** Serverless  

Use this property to enable [Vercel Skew protection](https://vercel.com/docs/deployments/skew-protection) (available with Vercel Pro and Enterprise accounts).

### `staticHeaders`

\*\*Type:\*\* \`boolean\`  
\*\*Default:\*\* \`false\`  
\*\*Available for:\*\* Serverless  

Enables specifying custom headers for prerendered pages in Vercel's configuration.

If enabled, the adapter will save [static headers in the Vercel `vercel.json` file](https://vercel.com/docs/project-configuration#headers) when provided by Astro features, such as Content Security Policy.

For example, when [Content Security Policy](/en/reference/configuration-reference/#securitycsp) is enabled, `staticHeaders` can be used to add the CSP `headers` to your Vercel configuration, instead of creating a `<meta>` element:

### Running Astro middleware on Vercel Edge Functions

The `@astrojs/vercel` adapter can create an [edge function](https://vercel.com/docs/functions/edge-functions) from an Astro middleware in your code base. When [`middlewareMode`](/en/reference/adapter-reference/#middlewaremode) is set to `'edge'`, an edge function will execute your middleware code for all requests, including static assets, prerendered pages, and on-demand rendered pages.

For on-demand rendered pages, the `context.locals` object is serialized using JSON and sent in a header for the serverless function, which performs the rendering. As a security measure, the serverless function will refuse to serve requests with a `403 Forbidden` response unless they come from the generated edge function.

This is an opt-in feature. To enable it, set `middlewareMode` to `'edge'`:

The edge middleware has access to Vercel's [`RequestContext`](https://vercel.com/docs/functions/edge-middleware/middleware-api#requestcontext) as `ctx.locals.vercel.edge`. If you’re using TypeScript, you can [get proper typings](/en/guides/typescript/#extending-global-types) by updating `src/env.d.ts` to use `EdgeLocals`:

```
type EdgeLocals = import('@astrojs/vercel').EdgeLocals

declare namespace App {
  interface Locals extends EdgeLocals {
    // ...
  }
}
```

### Sessions

The Astro [Sessions API](/en/guides/sessions/) allows you to easily store user data between requests. This can be used for things like user data and preferences, shopping carts, and authentication credentials. Unlike cookie storage, there are no size limits on the data, and it can be restored on different devices.

When using sessions on Vercel, you need to [configure a driver](/en/reference/configuration-reference/#sessiondriver) for session storage. You can install a storage provider from [the Vercel marketplace](https://vercel.com/marketplace?category=storage).

For example, if you have installed [a Redis integration](https://vercel.com/marketplace?category=storage&search=redis) and linked a database to your site:

1.  Install the `ioredis` package:
    
    \`\`\`sh npm install ioredis \`\`\` \`\`\`sh pnpm install ioredis \`\`\` \`\`\`sh yarn add ioredis \`\`\`
2.  Use [the Vercel CLI](https://vercel.com/docs/cli) to load your environment variables:
    
    ```
    vercel env pull .env.local
    ```
    
    This will create a `.env.local` file in your project root with the environment variables needed to connect to your Redis database when developing locally.
    
3.  Configure the session driver:
    
    ```
    import { defineConfig } from 'astro/config';
    import vercel from '@astrojs/vercel';
    
    export default defineConfig({
      adapter: vercel(),
      session: {
        driver: 'redis',
        options: {
          url: process.env.REDIS_URL,
        },
      },
    });
    ```
    

## Node.js Version Support

The `@astrojs/vercel` adapter supports specific Node.js versions for deploying your Astro project on Vercel. To view the supported Node.js versions on Vercel, click on the settings tab for a project and scroll down to "Node.js Version" section.

Check out the [Vercel documentation](https://vercel.com/docs/functions/serverless-functions/runtimes/node-js#default-and-available-versions) to learn more.

## [@astrojs/vue](https://docharvest.github.io/docs/astro/guides/integrations-guide/vue/)

Contents

astro

@astrojs/vue

Astro

@astrojs/vue

This **[Astro integration](/en/guides/integrations/)** enables rendering and client-side hydration for your [Vue 3](https://vuejs.org/) components.

## Installation

Astro includes an `astro add` command to automate the setup of official integrations. If you prefer, you can [install integrations manually](#manual-install) instead.

To install `@astrojs/vue`, run the following from your project directory and follow the prompts:

\`\`\`sh npx astro add vue \`\`\` \`\`\`sh pnpm astro add vue \`\`\` \`\`\`sh yarn astro add vue \`\`\`

If you run into any issues, [feel free to report them to us on GitHub](https://github.com/withastro/astro/issues) and try the manual installation steps below.

### Manual Install

First, install the `@astrojs/vue` package:

\`\`\`sh npm install @astrojs/vue \`\`\` \`\`\`sh pnpm add @astrojs/vue \`\`\` \`\`\`sh yarn add @astrojs/vue \`\`\`

Most package managers will install associated peer dependencies as well. If you see a `Cannot find package 'vue'` (or similar) warning when you start up Astro, you'll need to install Vue:

\`\`\`sh npm install vue \`\`\` \`\`\`sh pnpm add vue \`\`\` \`\`\`sh yarn add vue \`\`\`

Then, apply the integration to your `astro.config.*` file using the `integrations` property:

## Getting started

To use your first Vue component in Astro, head to our [UI framework documentation](/en/guides/framework-components/#using-framework-components). You'll explore:

-   📦 how framework components are loaded,
-   💧 client-side hydration options, and
-   🤝 opportunities to mix and nest frameworks together

## Troubleshooting

For help, check out the `#support` channel on [Discord](https://astro.build/chat). Our friendly Support Squad members are here to help!

You can also check our [Astro Integration Documentation](/en/guides/integrations/) for more on integrations.

## Contributing

This package is maintained by Astro's Core team. You're welcome to submit an issue or PR!

## Options

This integration is powered by `@vitejs/plugin-vue`. To customize the Vue compiler, options can be provided to the integration. See the `@vitejs/plugin-vue` [docs](https://www.npmjs.com/package/@vitejs/plugin-vue) for more details.

### `appEntrypoint`

**Type:** `string`  

You can extend the Vue `app` instance setting the `appEntrypoint` option to a root-relative import specifier (for example, `appEntrypoint: "/src/pages/_app"`).

The default export of this file should be a function that accepts a Vue `App` instance prior to rendering, allowing the use of [custom Vue plugins](https://vuejs.org/guide/reusability/plugins.html), `app.use`, and other customizations for advanced use cases.

```

};
```

### `jsx`

**Type:** `boolean | object`  

You can use Vue JSX by setting `jsx: true`.

This will enable rendering for both Vue and Vue JSX components. To customize the Vue JSX compiler, pass an options object instead of a boolean. See the `@vitejs/plugin-vue-jsx` [docs](https://www.npmjs.com/package/@vitejs/plugin-vue-jsx) for more details.

### `devtools`

**Type:** `boolean | object`  

You can enable [Vue DevTools](https://devtools-next.vuejs.org/) in development by passing an object with `devtools: true` to your `vue()` integration config:

#### Customizing Vue DevTools

For more customization, you can instead pass options that the [Vue DevTools Vite Plugin](https://devtools-next.vuejs.org/guide/vite-plugin#options) supports. (Note: `appendTo` is not supported.)

For example, you can set `launchEditor` to your preferred editor if you are not using Visual Studio Code:

## [Internationalization (i18n) Routing](https://docharvest.github.io/docs/astro/guides/internationalization/)

Contents

astro

Internationalization (i18n) Routing

Astro

Internationalization (i18n) Routing

## // defaultLocale is "es" const aboutURL = getRelativeLocaleUrl("es", "about");

[¡Vamos!](/get-started/) <a href={getRelativeLocaleUrl('es', 'blog')}>Blog [Acerca]({aboutURL})

````

## `routing`

Astro's built-in file-based routing automatically creates URL routes for you based on your file structure within `src/pages/`.

When you configure i18n routing, information about this file structure (and the corresponding URL paths generated) is available to the i18n helper functions so they can generate, use, and verify the routes in your project. Many of these options can be used together for even more customization and per-language flexibility.

You can even choose to [implement your own routing logic manually](#manual) for even greater control.

### `prefixDefaultLocale`

<p><Since v="3.5.0" /></p>

This routing option defines whether or not your default language's URLs should use a language prefix (e.g. `/en/about/`).

All non-default supported languages **will** use a localized prefix (e.g. `/fr/` or `/french/`) and content files must be located in appropriate folders. This configuration option allows you to specify whether your default language should also follow a localized URL structure.

This setting also determines where the page files for your default language must exist (e.g. `src/pages/about/` or `src/pages/en/about`) as the file structure and URL structure must match for all languages.

- `"prefixDefaultLocale: false"` (default): URLs in your default language will **not** have a `/[locale]/` prefix. All other locales will.

- `"prefixDefaultLocale: true"`: All URLs, including your default language, will have a `/[locale]/` prefix.

#### `prefixDefaultLocale: false`

```js title="astro.config.mjs" ins={7}

  } else {
    return redirectToDefaultLocale(ctx, 302);
  }
})
````

#### middleware function

The [`middleware()`](/en/reference/modules/astro-i18n/#middleware) function manually creates Astro's i18n middleware. This allows you to extend Astro's i18n routing instead of completely replacing it.

You can run `middleware()` with [routing options](#routing) in combination with your own middleware, using the [`sequence()`](/en/reference/modules/astro-middleware/#sequence) utility to determine the order:

```

  // the /about page is an exception and we want to render it
  if (ctx.url.pathname.startsWith("/about")) {
    return new Response("About page", {
      status: 200,
    });
  } else {
    return response;
  }
});
```

## `domains`

This routing option allows you to customize your domains on a per-language basis for `server` rendered projects using the [`@astrojs/node`](/en/guides/integrations-guide/node/) or [`@astrojs/vercel`](/en/guides/integrations-guide/vercel/) adapter with a `site` configured.

Add `i18n.domains` to map any of your supported `locales` to custom URLs:

```
import { defineConfig } from "astro/config"
export default defineConfig({
  site: "https://example.com",
  output: "server", // required, with no prerendered pages
  adapter: node({
    mode: 'standalone',
  }),
  i18n: {
    locales: ["es", "en", "fr", "ja"],
    defaultLocale: "en",
    routing: {
      prefixDefaultLocale: false
    },
    domains: {
      fr: "https://fr.example.com",
      es: "https://example.es"
    }
  }
})
```

All non-mapped `locales` will follow your `prefixDefaultLocales` configuration.

With the above configuration:

-   The file `/fr/about.astro` will create the URL `https://fr.example.com/about`.
-   The file `/es/about.astro` will create the URL `https://example.es/about`.
-   The file `/ja/about.astro` will create the URL `https://example.com/ja/about`.
-   The file `/about.astro` will create the URL `https://example.com/about`.

The above URLs will also be returned by the `getAbsoluteLocaleUrl()` and `getAbsoluteLocaleUrlList()` functions.

## Fallback

When a page in one language doesn't exist (e.g. a page that is not yet translated), instead of displaying a 404 page, you can choose to display fallback content from another `locale` on a per-language basis. This is useful when you do not yet have a page for every route, but you want to still provide some content to your visitors.

Your fallback strategy consists of two parts: choosing which languages should fallback to which other languages ([`i18n.fallback`](/en/reference/configuration-reference/#i18nfallback)) and choosing whether to perform a [redirect](/en/guides/routing/#redirects) or a [rewrite](/en/guides/routing/#rewrites) to show the fallback content ([`i18n.routing.fallbackType`](/en/reference/configuration-reference/#i18nroutingfallbacktype) added in Astro v4.15.0).

For example, when you configure `i18n.fallback: { fr: "es" }`, Astro will ensure that a page is built in `src/pages/fr/` for every page that exists in `src/pages/es/`.

If any page does not already exist, then a page will be created depending on your `fallbackType`:

-   With a redirect to the corresponding `es` route (default behavior).
-   With the content of the `/es/` page (`i18n.routing.fallbackType: "rewrite"`).

For example, the configuration below sets `es` as the fallback locale for any missing `fr` routes. This means that a user visiting `example.com/fr/my-page/` will be shown the content for `example.com/es/my-page/` (without being redirected) instead of being taken to a 404 page when `src/pages/fr/my-page.astro` does not exist.

```
import { defineConfig } from "astro/config"
export default defineConfig({
  i18n: {
    locales: ["es", "en", "fr"],
    defaultLocale: "en",
    fallback: {
      fr: "es"  
    },
    routing: {
      fallbackType: "rewrite"
    }
  }
})
```

## Custom locale paths

In addition to defining your site's supported `locales` as strings (e.g. "en", "pt-br"), Astro also allows you to map an arbitrary number of [browser-recognized language `codes`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language#syntax) to a custom URL `path`. While locales can be strings of any format as long as they correspond to your project folder structure, `codes` must follow the browser's accepted syntax.

Pass an object to the `locales` array with a `path` key to define a custom URL prefix, and `codes` to indicate the languages mapped to this URL. In this case, your `/[locale]/` folder name must match exactly the value of the `path` and your URLs will be generated using the `path` value.

This is useful if you support multiple variations of a language (e.g. `"fr"`, `"fr-BR"`, and `"fr-CA"`) and you want to have all these variations mapped under the same URL `/fr/`, or even customize it entirely (e.g. `/french/`):

```
import { defineConfig } from "astro/config"
export default defineConfig({
  i18n: {
    locales: ["es", "en", "fr"],
    locales: ["es", "en", {
      path: "french", // no slashes included
      codes: ["fr", "fr-BR", "fr-CA"]
    }],
    defaultLocale: "en",
    routing: {
        prefixDefaultLocale: true
    }
  }
})
```

When using functions from the [`astro:i18n` virtual module](/en/reference/modules/astro-i18n/) to compute valid URL paths based on your configuration (e.g. `getRelativeLocaleUrl()`), [use the `path` as the value for `locale`](/en/reference/modules/astro-i18n/#getlocalebypath).

#### Limitations

This feature has some restrictions:

-   The `site` option is mandatory.
-   The `output` option must be set to `"server"`.
-   There cannot be any individual prerendered pages.

Astro relies on the following headers in order to support the feature:

-   [`X-Forwarded-Host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host) and [`Host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Host). Astro will use the former, and if not present, will try the latter.
-   [`X-Forwarded-Proto`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto) and [`URL#protocol`](https://developer.mozilla.org/en-US/docs/Web/API/URL/protocol) of the server request.

Make sure that your server proxy/hosting platform is able to provide this information. Failing to retrieve these headers will result in a 404 (status code) page.

## Browser language detection

Astro’s i18n routing allows you to access two properties for browser language detection in pages rendered on demand: `Astro.preferredLocale` and `Astro.preferredLocaleList`. All pages, including static prerendered pages, have access to `Astro.currentLocale`.

These combine the browser's `Accept-Language` header, and your `locales` (strings or `codes`) to automatically respect your visitor's preferred languages.

-   [`Astro.preferredLocale`](/en/reference/api-reference/#preferredlocale): Astro can compute a **preferred locale** for your visitor if their browser's preferred locale is included in your `locales` array. This value is undefined if no such match exists.
    
-   [`Astro.preferredLocaleList`](/en/reference/api-reference/#preferredlocalelist): An array of all locales that are both requested by the browser and supported by your website. This produces a list of all compatible languages between your site and your visitor. The value is `[]` if none of the browser's requested languages are found in your `locales` array. If the browser does not specify any preferred languages, then this value will be [`i18n.locales`](/en/reference/configuration-reference/#i18nlocales).
    
-   [`Astro.currentLocale`](/en/reference/api-reference/#currentlocale): The locale computed from the current URL, using the syntax specified in your `locales` configuration. If the URL does not contain a `/[locale]/` prefix, then the value will default to [`i18n.defaultLocale`](/en/reference/configuration-reference/#i18ndefaultlocale).
    

In order to successfully match your visitors' preferences, provide your `codes` using the same pattern [used by the browser](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language#syntax).

## [Markdown in Astro](https://docharvest.github.io/docs/astro/guides/markdown-content/)

Contents

astro

Markdown in Astro

Astro

Markdown in Astro

[Markdown](https://daringfireball.net/projects/markdown/) is commonly used to author text-heavy content like blog posts and documentation. Astro includes built-in support for Markdown files that can also include [frontmatter YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f) (or [TOML](https://toml.io)) to define custom properties such as a title, description, and tags.

In Astro, you can author content in [GitHub Flavored Markdown](https://github.github.com/gfm/), then render it in `.astro` components. This combines a familiar writing format designed for content with the flexibility of Astro's component syntax and architecture.

:::tip For additional functionality, such as including components and JSX expressions in Markdown, add the [`@astrojs/mdx` integration](/en/guides/integrations-guide/mdx/) to write your Markdown content using [MDX](https://mdxjs.com/). :::

## Organizing Markdown files

Your local Markdown files can be kept anywhere within your `src/` directory. Markdown files located within `src/pages/` will automatically generate [Markdown pages on your site](#individual-markdown-pages).

Your Markdown content and frontmatter properties are available to use in components through [local file imports](#importing-markdown) or when [queried and rendered from data fetched by a content collections helper function](#markdown-from-content-collections-queries).

### File imports vs content collections queries

Local Markdown can be imported into `.astro` components using an `import` statement for a single file and [Vite's `import.meta.glob()`](/en/guides/imports/#importmetaglob) to query multiple files at once. The [exported data from these Markdown files](#importing-markdown) can then be used in the `.astro` component.

If you have groups of related Markdown files, consider [defining them as collections](/en/guides/content-collections/). This gives you several advantages, including the ability to store Markdown files anywhere on your filesystem or remotely.

Collections use content-specific, optimized APIs for [querying and rendering your Markdown content](#markdown-from-content-collections-queries) instead of file imports. Collections are intended for sets of data that share the same structure, such as blog posts or product items. When you define that shape in a schema, you additionally get validation, type safety, and Intellisense in your editor.

See more about [when to use content collections](/en/guides/content-collections/#when-to-create-a-collection) instead of file imports.

## Dynamic JSX-like expressions

After importing or querying Markdown files, you can write dynamic HTML templates in your `.astro` components that include frontmatter data and body content.

```
---
title: 'The greatest post of all time'
author: 'Ben'
---

Here is my _great_ post!
```

```
---

const compiled = await greatPost.compiledContent();
const posts = Object.values(import.meta.glob("./posts/*.md", { eager: true }));
---

<p>{greatPost.frontmatter.title}</p>
<p>Written by: {greatPost.frontmatter.author}</p>

<Fragment set:html={compiled} />

<p>Post Archive:</p>
<ul>
  {
    posts.map((post: any) => (
      <li>
        <a href={post.url}>{post.frontmatter.title}</a>
      </li>
    ))
  }
</ul>
```

### Available Properties

#### Markdown from content collections queries

When fetching data from your collections with the helper functions `getCollection()` or `getEntry()`, your Markdown's frontmatter properties are available on a `data` object (e.g. `post.data.title`). Additionally, `body` contains the raw, uncompiled body content as a string.

The [`render()`](/en/reference/modules/astro-content/#render) function returns your Markdown body content, a generated list of headings, as well as a modified frontmatter object after any Markdown plugins have been applied.

Read more about [using content returned by a collections query](/en/guides/content-collections/#using-content-in-astro-templates).

#### Importing Markdown

The following exported properties are available in your `.astro` component when importing Markdown using `import` or `import.meta.glob()`:

-   **`file`** - The absolute file path (e.g. `/home/user/projects/.../file.md`).
-   **`url`** - The URL of the page (e.g. `/en/guides/markdown-content`).
-   **`frontmatter`** - Contains any data specified in the file’s YAML (or TOML) frontmatter.
-   **`<Content />`** - A component that returns the full, rendered contents of the file.
-   **`rawContent()`** - A function that returns the raw Markdown document as a string.
-   **`compiledContent()`** - An async function that returns the Markdown document compiled to an HTML string.
-   **`getHeadings()`** - An async function that returns an array of all headings (`<h1>` to `<h6>`) in the file with the type: `{ depth: number; slug: string; text: string }[]`. Each heading’s `slug` corresponds to the generated ID for a given heading and can be used for anchor links.

An example Markdown blog post may pass the following `Astro.props` object:

```
Astro.props = {
  file: "/home/user/projects/.../file.md",
  url: "/en/guides/markdown-content/",
  frontmatter: {
    /** Frontmatter from a blog post */
    title: "Astro 0.18 Release",
    date: "Tuesday, July 27 2021",
    author: "Matthew Phillips",
    description: "Astro 0.18 is our biggest release since Astro launch.",
  },
  getHeadings: () => [
    {"depth": 1, "text": "Astro 0.18 Release", "slug": "astro-018-release"},
    {"depth": 2, "text": "Responsive partial hydration", "slug": "responsive-partial-hydration"}
    /* ... */
  ],
  rawContent: () => "# Astro 0.18 Release\nA little over a month ago, the first public beta [...]",
  compiledContent: () => "<h1>Astro 0.18 Release</h1>\n<p>A little over a month ago, the first public beta [...]</p>",
}
```

## The `<Content />` Component

The `<Content />` component is available by importing `Content` from a Markdown file. This component returns the file's full body content, rendered to HTML. You can optionally rename `Content` to any component name you prefer.

You can similarly [render the HTML content of a Markdown collection entry](/en/guides/content-collections/#rendering-body-content) by rendering a `<Content />` component.

```
---
// Import statement

// Collections query

const product = await getEntry('products', 'shirt');
const { Content } = await render(product);
---
<h2>Today's promo</h2>
<PromoBanner />

<p>Sale Ends: {product.data.saleEndDate.toDateString()}</p>
<Content />
```

## Heading IDs

Writing headings in Markdown will automatically give you anchor links so you can link directly to certain sections of your page.

```
---
title: My page of content
---
## Introduction

I can link internally to [my conclusion](#conclusion) on the same page when writing Markdown.

## Conclusion

I can visit `https://example.com/page-1/#introduction` in a browser to navigate directly to my Introduction.
```

Astro generates heading `id`s based on `github-slugger`. You can find more examples in [the github-slugger documentation](https://github.com/Flet/github-slugger#usage).

### Heading IDs and plugins

Astro injects an `id` attribute into all heading elements (`<h1>` to `<h6>`) in Markdown and MDX files. You can retrieve this data from the `getHeadings()` utility available as a [Markdown exported property](#available-properties) from an imported file, or from the `render()` function when [using Markdown returned from a content collections query](#markdown-from-content-collections-queries).

You can customize these heading IDs with a [Markdown processor](#choosing-a-markdown-processor) plugin that injects `id` attributes (e.g. `rehype-slug`). Your custom IDs, instead of Astro's defaults, will be reflected in the HTML output and the items returned by `getHeadings()`.

Astro injects `id` attributes after your custom plugins have run, so any ID set by a plugin is preserved. If one of your custom plugins needs to access the IDs injected by Astro, you can import Astro's heading ids plugin and place it before any plugins that rely on it:

\`\`\`js title="astro.config.mjs" ins={2-3, 9} import { defineConfig } from 'astro/config'; import { satteri, satteriHeadingIdsPlugin } from '@astrojs/markdown-satteri'; import { otherPluginThatReliesOnHeadingIDs } from 'some/plugin/source';

````
export default defineConfig({
  markdown: {
    processor: satteri({
      hastPlugins: [
        satteriHeadingIdsPlugin(),
        otherPluginThatReliesOnHeadingIDs,
      ],
    }),
  },
});
```
````

\`\`\`js title="astro.config.mjs" ins={2-3, 9} import { defineConfig } from 'astro/config'; import { unified, rehypeHeadingIds } from '@astrojs/markdown-remark'; import { otherPluginThatReliesOnHeadingIDs } from 'some/plugin/source';

````
export default defineConfig({
  markdown: {
    processor: unified({
      rehypePlugins: [
        rehypeHeadingIds,
        otherPluginThatReliesOnHeadingIDs,
      ],
    }),
  },
});
```
````

## Markdown Plugins

Astro renders Markdown using a configurable **Markdown processor**. By default, this is [Sätteri](https://satteri.bruits.org/), Astro's native Markdown and MDX pipeline, included with Astro.

Astro applies [GitHub-Flavored Markdown](https://github.github.com/gfm/) and [SmartyPants](https://daringfireball.net/projects/smartypants/) automatically. This brings some niceties like generating clickable links from text, and formatting for quotations and em-dashes.

You can extend Markdown processing with plugins, enable additional parser features, or [switch to a different processor entirely](#switching-to-the-unified-processor). See the full list of [Markdown configuration options](/en/reference/configuration-reference/#markdown-options).

### Choosing a Markdown processor

The [`markdown.processor` option](/en/reference/configuration-reference/#markdownprocessor) controls which engine renders your `.md` and `.mdx` files. Astro provides two official options:

-   **`satteri()`** (default): the native [Sätteri](https://satteri.bruits.org/) pipeline, a fast Markdown and MDX compiler with its own plugin model. Included with Astro, so no extra installation is needed.
-   **`unified()`**: the [remark](https://remark.js.org/) and [rehype](https://github.com/rehypejs/rehype) pipeline, with its large plugin ecosystem. Provided by `@astrojs/markdown-remark`, which you install separately.

### Using Sätteri plugins and features

The default `satteri()` processor accepts its own plugins through `mdastPlugins` and `hastPlugins`, and toggles optional parser features through `features`. See the [Sätteri documentation](https://satteri.bruits.org/docs/) for the available plugins and features.

Import `satteri` from `@astrojs/markdown-satteri` and pass your options to it through `markdown.processor`. This example adds an mdast plugin and enables the `directive` parser feature:

### Switching to the unified processor

To use [remark and rehype](https://unifiedjs.com/) instead of Sätteri, install `@astrojs/markdown-remark`, then import `unified` and pass it to `markdown.processor`:

\`\`\`shell npm install @astrojs/markdown-remark \`\`\` \`\`\`shell pnpm add @astrojs/markdown-remark \`\`\` \`\`\`shell yarn add @astrojs/markdown-remark \`\`\`

Switching processors replaces Sätteri for both `.md` and `.mdx` files. Any Sätteri plugins in your config will not apply. To use remark and rehype only for `.mdx` files, set the [`processor` option on the MDX integration](/en/guides/integrations-guide/mdx/#processor) instead.

#### Using remark and rehype plugins

The `unified()` processor accepts third-party [remark](https://github.com/remarkjs/remark) and [rehype](https://github.com/rehypejs/rehype) plugins. These plugins allow you to extend your Markdown with new capabilities, like [auto-generating a table of contents](https://github.com/remarkjs/remark-toc), [applying accessible emoji labels](https://github.com/florianeckerstorfer/remark-a11y-emoji), and [styling your Markdown](/en/guides/styling/#markdown-styling).

We encourage you to browse [awesome-remark](https://github.com/remarkjs/awesome-remark) and [awesome-rehype](https://github.com/rehypejs/awesome-rehype) for popular plugins! See each plugin's own README for specific installation instructions.

After [switching to the `unified()` processor](#switching-to-the-unified-processor), pass your plugins to it through `markdown.processor`. This example applies [`remark-toc`](https://github.com/remarkjs/remark-toc) and [`rehype-accessible-emojis`](https://www.npmjs.com/package/rehype-accessible-emojis) to Markdown files:

#### Customizing a remark or rehype plugin

In order to customize a plugin, provide an options object after it in a nested array.

The example below adds the [heading option to the `remarkToc` plugin](https://github.com/remarkjs/remark-toc#options) to change where the table of contents is placed, and the [`behavior` option to the `rehype-autolink-headings` plugin](https://github.com/rehypejs/rehype-autolink-headings#options) in order to add the anchor tag after the headline text.

### Modifying frontmatter programmatically

When using the [remark/rehype processor](#using-remark-and-rehype-plugins), you can add frontmatter properties to all of your Markdown and MDX files with a remark or rehype plugin.

1\. Append a \`customProperty\` to the \`data.astro.frontmatter\` property from your plugin's \`file\` argument:

````
```js title="example-remark-plugin.mjs"
export function exampleRemarkPlugin() {
  // All remark and rehype plugins return a separate function
  return function (tree, file) {
    file.data.astro.frontmatter.customProperty = 'Generated property';
  }
}
```

:::tip
<Since v="2.0.0" />

`data.astro.frontmatter` contains all properties from a given Markdown or MDX document. This allows you to modify existing frontmatter properties, or compute new properties from this existing frontmatter.
:::
````

2.  Apply this plugin to your `markdown` or `mdx` integration config:
    
    ```
    import { defineConfig } from 'astro/config';
    import { unified } from '@astrojs/markdown-remark';
    import { exampleRemarkPlugin } from './example-remark-plugin.mjs';
    
    export default defineConfig({
      markdown: {
        processor: unified({ remarkPlugins: [exampleRemarkPlugin] }),
      },
    });
    ```
    
    or
    
    ```
    import { defineConfig } from 'astro/config';
    import mdx from '@astrojs/mdx';
    import { unified } from '@astrojs/markdown-remark';
    import { exampleRemarkPlugin } from './example-remark-plugin.mjs';
    
    export default defineConfig({
      integrations: [
        mdx({
          processor: unified({ remarkPlugins: [exampleRemarkPlugin] }),
        }),
      ],
    });
    ```
    

Now, every Markdown or MDX file will have `customProperty` in its frontmatter, making it available when [importing your markdown](#importing-markdown) and from [the `Astro.props.frontmatter` property in your layouts](#frontmatter-layout-property).

<RecipeLinks slugs={\["en/recipes/reading-time"\]} />

### Extending Markdown config from MDX

Astro's MDX integration will extend [your project's existing Markdown configuration](/en/reference/configuration-reference/#markdown-options) by default, including the [Markdown processor](#choosing-a-markdown-processor). To override individual options, you can specify their equivalent in your MDX configuration.

The following example uses a different syntax highlighter and a different set of plugins for `.mdx` files than for `.md` files:

To avoid extending your Markdown config from MDX, set [the `extendMarkdownConfig` option](/en/guides/integrations-guide/mdx/#extendmarkdownconfig) (enabled by default) to `false`:

## Individual Markdown pages

:::tip [Content collections](/en/guides/content-collections/) and [importing Markdown into `.astro` components](#dynamic-jsx-like-expressions) provide more features for rendering your Markdown and are the recommended way to handle most of your content. However, there may be times when you want the convenience of just adding a file to `src/pages/` and having a simple page automatically created for you. :::

Astro treats [any supported file inside of the `/src/pages/` directory](/en/basics/astro-pages/#supported-page-files) as a page, including `.md` and other Markdown file types.

Placing a file in this directory, or any sub-directory, will automatically build a page route using the pathname of the file and display the Markdown content rendered to HTML. Astro will automatically add a `<meta charset="utf-8">` tag to your page to allow easier authoring of non-ASCII content.

```
---
title: Hello, World
---

# Hi there!

This Markdown file creates a page at `your-domain.com/page-1/`

It probably isn't styled much, but Markdown does support:
- **bold** and _italics._
- lists
- [links](https://astro.build)
- <p>HTML elements</p>
- and more!
```

### Frontmatter `layout` property

To help with the limited functionality of individual Markdown pages, Astro provides a special frontmatter `layout` property which is a relative path to an Astro [Markdown layout component](/en/basics/layouts/#markdown-layouts). `layout` is not a special property when using [content collections](/en/guides/content-collections/) to query and render your Markdown content, and is not guaranteed to be supported outside of its intended use case.

If your Markdown file is located within `src/pages/`, create a layout component and add it in this layout property to provide a page shell around your Markdown content.

```
---
layout: ../../layouts/BlogPostLayout.astro
title: Astro in brief
author: Himanshu
description: Find out what makes Astro awesome!
---
This is a post written in Markdown.
```

This layout component is a regular Astro component with [specific properties automatically available](/en/basics/layouts/#markdown-layout-props) through `Astro.props` for your Astro template. For example, you can access your Markdown file's frontmatter properties through `Astro.props.frontmatter`:

```
---
const {frontmatter} = Astro.props;
---
<html>
  <head>
    <!-- ... -->
    <meta charset="utf-8"> // no longer added by default
  </head>
  <!-- ... -->
  <h1>{frontmatter.title}</h1>
  <h2>Post author: {frontmatter.author}</h2>
  <p>{frontmatter.description}</p>
  <slot /> <!-- Markdown content is injected here -->
  <!-- ... -->
</html>
```

When using the frontmatter `layout` property, you must include the `<meta charset="utf-8">` tag in your layout as Astro will no longer add it automatically. You can now also [style your Markdown](/en/guides/styling/#markdown-styling) in your layout component.

Learn more about [Markdown Layouts](/en/basics/layouts/#markdown-layouts).

## Fetching Remote Markdown

Astro's internal Markdown processor is not available for processing remote Markdown.

To fetch remote Markdown for use in [content collections](/en/guides/content-collections/), you can [build a custom loader](/en/guides/content-collections/#custom-build-time-loaders) with access to a [`renderMarkdown()` function](/en/reference/content-loader-reference/#loadercontextrendermarkdown).

To fetch remote Markdown directly and render it to HTML, you will need to install and configure your own Markdown parser from NPM. This will not inherit from any of Astro's built-in Markdown settings that you have configured.

Be sure that you understand these limitations before implementing this in your project, and consider fetching your remote Markdown using a content collections loader instead.

```
---
// Example: Fetch Markdown from a remote API
// and render it to HTML, at runtime.
// Using "marked" (https://github.com/markedjs/marked)

const response = await fetch('https://raw.githubusercontent.com/wiki/adam-p/markdown-here/Markdown-Cheatsheet.md');
const markdown = await response.text();
const content = marked.parse(markdown);
---
<article set:html={content} />
```

## [Image and video hosting with Astro](https://docharvest.github.io/docs/astro/guides/media/)

Contents

astro

Image and video hosting with Astro

Astro

Image and video hosting with Astro

import Badge from "~/components/Badge.astro"

Follow one of our guides to integrate images and videos from a hosted media service.

## Hosted Media Guides

## Why use hosted media?

Hosted media helps individuals, teams, and organizations store, manage, optimize, and deliver their image and video assets with dedicated APIs from a central location.

This centralization can be useful, particularly when using a single source of truth for your assets between multiple web or mobile properties. This is important if you're part of an organization that requires multiple teams to use the same assets, or are integrating into other content systems like a PIM (Product Information Manager) to connect your assets to products.

Image hosting services can transform and optimize your images, automatically delivering optimized versions for your visitors. These [remote images](/en/guides/images/#remote-images) can be used in Astro's built-in `<Image />` and `<Picture />` components, and are available to all file types in your project, including Markdown, MDX, and UI Framework components.

Video hosting services like [Mux](/en/guides/media/mux/) can provide performant on-demand and live-streaming video delivery along with customizable video players, giving significant reliability and scaling benefits over handling local content. They will handle video transcoding, compression, and transformation to provide a smooth user experience. A platform like Mux may also include data analysis to help you understand your user engagement.

## Which hosted media systems work well with Astro?

Much like when using a CMS, you'll want to use hosted services that allow you to fetch and interact with your assets via an API or SDK. Some services may additionally include Astro-native components for displaying your images or videos.

## Can I use Astro without a hosted media system?

Yes! Astro provides built-in ways to [store images](/en/guides/images/#where-to-store-images), including support for referencing remote images.

However, there is no native video support in Astro, and we recommend choosing a service like [Mux](/en/guides/media/mux/) to handle the demands of optimizing and streaming video content.

## [Cloudinary & Astro](https://docharvest.github.io/docs/astro/guides/media/cloudinary/)

Contents

astro

Cloudinary & Astro

Astro

Cloudinary & Astro

[Cloudinary](https://cloudinary.com) is an image and video platform and headless Digital Asset Manager (DAM) that lets you host assets and deliver them from their content delivery network (CDN).

When delivering from Cloudinary, you additionally get access to their Transformation API, giving you the ability to edit your assets with tools like background removal, dynamic cropping and resizing, and generative AI.

## Using Cloudinary in Astro

Cloudinary supports a wide variety of SDKs that can be used depending on your Astro environment.

The [Cloudinary Astro SDK](https://astro.cloudinary.dev/) provides native Astro components, including image, video, and upload components, as well as a content loader that can be used with Astro content collections.

Alternatively, both the Cloudinary [Node.js SDK](https://cloudinary.com/documentation/node_integration) and [JavaScript SDK](https://cloudinary.com/documentation/javascript_integration) can be used to generate URLs for your images. The Node.js SDK can additionally make requests to the Cloudinary API including uploading assets, requesting resources, and running content analysis.

## Prerequisites

-   An existing Astro project
-   A Cloudinary account

## Installing Astro Cloudinary

Install the Cloudinary Astro SDK by running the appropriate command for your package manager:

\`\`\`shell npm install astro-cloudinary \`\`\` \`\`\`shell pnpm add astro-cloudinary \`\`\` \`\`\`shell yarn add astro-cloudinary \`\`\`

## Configuring your account

Create a new `.env` file in the root of your project and add your Cloudinary credentials:

```
PUBLIC_CLOUDINARY_CLOUD_NAME="<Your Cloud Name>"

// Only needed if using CldUploadWidget or cldAssetsLoader
PUBLIC_CLOUDINARY_API_KEY="<Your API Key>"
CLOUDINARY_API_SECRET="<Your API Secret>"
```

## Using Cloudinary images

Add images in `.astro` components by passing image data (e.g. `src`, `width`, `alt`) to the `<CldImage>` component. This will automatically optimize your image and give you access to the Transformations API.

```
---

---
<CldImage
  src="<Public ID>"
  width="<Width>"
  height="<Height>"
  alt="<Description>"
/>
```

See [Cloudinary's `<CldImage>` documentation](https://astro.cloudinary.dev/cldimage/basic-usage) for more information.

## Using Cloudinary videos

To add video to your `.astro` components, add the `<CldVideoPlayer>` and pass the appropriate properties. This component will automatically optimize and embed your video using the [Cloudinary Video Player](https://cloudinary.com/documentation/cloudinary_video_player).

```
---

---
<CldVideoPlayer
  src="<Public ID>"
  width="<Width>"
  height="<Height>"
/>
```

See [Cloudinary's `<CldVideoPlayer>` documentation](https://astro.cloudinary.dev/cldvideoplayer/basic-usage) for more information.

## Enabling Cloudinary uploads

To enable file uploading in your website or app's UI, add the `<CldUploadWidget>` which will embed the [Cloudinary Upload Widget](https://cloudinary.com/documentation/upload_widget).

The following example creates a widget to allow unsigned uploads by passing an unsigned [Upload Preset](https://cloudinary.com/documentation/upload_presets):

```
---

---
<CldUploadWidget uploadPreset="<Upload Preset>">
  <button>Upload</button>
</CldUploadWidget>
```

For signed uploads, you can find [a guide and example](https://astro.cloudinary.dev/clduploadwidget/signed-uploads) on the Astro Cloudinary docs.

See [Cloudinary's `<CldUploadWidget>` documentation](https://astro.cloudinary.dev/clduploadwidget/basic-usage) for more information.

## Cloudinary content loader

The Cloudinary Astro SDK provides the `cldAssetsLoader` content loader to load Cloudinary assets for content collections.

To load a collection of images or videos, set `loader: cldAssetsLoader ({})` with a `folder`, if required:

```

---
<meta property="og:image" content={ogImageUrl} />
<meta property="og:image:secure_url" content={ogImageUrl} />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta property="twitter:title" content="<Twitter Title>" />
<meta property="twitter:card" content="summary_large_image" />
<meta property="twitter:image" content={ogImageUrl} />
```

Find [Cloudinary Social Media Card templates](https://astro.cloudinary.dev/templates/social-media-cards) on the Cloudinary docs.

See [Cloudinary's `getCldOgImageUrl()` documentation](https://astro.cloudinary.dev/getcldogimageurl/basic-usage) for more information.

## Using Cloudinary in Node.js

For more complex asset management, uploading, or analysis, you can use the Cloudinary Node.js SDK when working in an Astro Node.js environment.

Install the Cloudinary Node.js SDK by running the appropriate command for your package manager:

\`\`\`shell npm install cloudinary \`\`\` \`\`\`shell pnpm add cloudinary \`\`\` \`\`\`shell yarn add cloudinary \`\`\`

Add the following environment variables in your `.env` file:

```
PUBLIC_CLOUDINARY_CLOUD_NAME="<Your Cloud Name>"
PUBLIC_CLOUDINARY_API_KEY="<Your API Key>"
CLOUDINARY_API_SECRET="<Your API Secret>"
```

Configure your account with a new Cloudinary instance by adding the following code between the fences of your Astro component:

```
---

cloudinary.config({
  cloud_name: import.meta.env.PUBLIC_CLOUDINARY_CLOUD_NAME,
  api_key: import.meta.env.PUBLIC_CLOUDINARY_API_KEY,
  api_secret: import.meta.env.CLOUDINARY_API_SECRET,
});
---
```

This will give you access to all of the Cloudinary APIs to allow you to interact with your images, videos, and other supported files.

```
await cloudinary.uploader.upload('./path/to/file');
```

Learn how to [upload files using the Cloudinary Node.js SDK with Astro Forms](https://www.youtube.com/watch?v=DQUYMyT2MTM).

## Official Resources

-   [Cloudinary Astro SDK](https://astro.cloudinary.dev/)
-   [Cloudinary Node.js SDK](https://cloudinary.com/documentation/node_integration)
-   [Using Cloudinary with Astro (YouTube)](https://www.youtube.com/playlist?list=PL8dVGjLA2oMqnpf2tShn1exf5GkSWuu5-)
-   [Code Examples Using Cloudinary Astro SDK (GitHub)](https://github.com/cloudinary-community/cloudinary-examples/tree/main/examples/astro-cloudinary)

## [ImageKit & Astro](https://docharvest.github.io/docs/astro/guides/media/imagekit/)

Contents

astro

ImageKit & Astro

Astro

ImageKit & Astro

[ImageKit](https://imagekit.io) is a real-time media optimization and delivery platform with a global CDN, a built-in Digital Asset Manager (DAM), and a URL-based transformation API for images and videos.

When delivering through ImageKit, you get automatic format conversion (AVIF, WebP), automatic quality, responsive images, AI-powered transformations (background removal, generative fill, upscaling), and adaptive video streaming.

## Using ImageKit in Astro

The [ImageKit Astro SDK](https://github.com/imagekit-developer/imagekit-astro) registers a custom [image service](/en/reference/image-service-reference/) that re-routes Astro's built-in `<Image />` and `<Picture />` components, plus Markdown and MDX images, through ImageKit. Local imports continue to be processed by Astro's built-in Sharp service. This means an existing project can add the integration without breaking existing assets.

The SDK also provides a `<Video />` component, an `<OgImage />` component for social cards, and a server-side helper for issuing client-side upload tokens.

For pure URL building or browser uploads in any framework, you can also use the lower-level [ImageKit JavaScript SDK](https://github.com/imagekit-developer/imagekit-javascript). For server-side asset management (uploading, listing, deleting, metadata), use the [ImageKit Node.js SDK](https://github.com/imagekit-developer/imagekit-nodejs).

## Prerequisites

-   An existing Astro project
-   An [ImageKit account](https://imagekit.io/registration/)

## Installing the ImageKit Astro SDK

Install the SDK by running the appropriate command for your package manager:

\`\`\`shell npm install @imagekit/astro \`\`\` \`\`\`shell pnpm add @imagekit/astro \`\`\` \`\`\`shell yarn add @imagekit/astro \`\`\`

## Configuring your account

Create a new `.env` file in the root of your project and add your ImageKit credentials:

```
IMAGEKIT_URL_ENDPOINT="https://ik.imagekit.io/<your_imagekit_id>"

# Only needed if you generate upload auth tokens on the server
PUBLIC_IMAGEKIT_PUBLIC_KEY="<Your Public Key>"
IMAGEKIT_PRIVATE_KEY="<Your Private Key>"
```

Then register the integration in `astro.config.mjs`:

You can also pass `urlEndpoint` directly to the integration instead of using the environment variable:

```
imagekit({
  urlEndpoint: 'https://ik.imagekit.io/<your_imagekit_id>',
}),
```

## Using ImageKit images

With the integration installed, Astro's built-in `<Image />` and `<Picture />` components route requests through ImageKit and apply automatic format and quality optimization, responsive `srcset`, and lazy loading.

```
---

---
<Image
  src="/sample.jpg"
  width={800}
  height={600}
  alt="A sample image"
/>
```

The integration adds an additional `transformation` prop on `<Image />`, `<Picture />`, and `getImage()` for applying any [ImageKit transformation](https://imagekit.io/docs/transformations) (e.g. cropping, focus, AI effects, overlays):

```
---

---
<Image
  src="/portrait.jpg"
  width={500}
  height={500}
  alt="Cropped portrait"
  transformation={[{ width: 500, height: 500, focus: 'face' }]}
/>
```

The component-level `width` and `height` set the rendered HTML dimensions. The values inside `transformation` control the ImageKit server-side resize.

### AI-powered transformations

ImageKit transformations include AI effects that can be applied through the same `transformation` prop:

```
---

---
<!-- Remove background -->
<Image
  src="/product.jpg"
  width={500}
  height={500}
  alt="Product with background removed"
  transformation={[{ aiRemoveBackground: true }]}
/>

<!-- Upscale a low-resolution image -->
<Image
  src="/thumbnail.jpg"
  width={1024}
  height={1024}
  alt="Upscaled image"
  transformation={[{ aiUpscale: true }]}
/>

<!-- Generative fill to extend an image to a new aspect ratio -->
<Image
  src="/portrait.jpg"
  width={1600}
  height={900}
  alt="Image extended with generative fill"
  transformation={[
    { width: 1600, height: 900, cropMode: 'pad_resize', background: 'genfill' },
  ]}
/>

<!-- AI drop shadow -->
<Image
  src="/product.png"
  width={500}
  height={500}
  alt="Product with AI drop shadow"
  transformation={[{ aiDropShadow: true }]}
/>
```

See the [supported transformations reference in ImageKit documentation](https://imagekit.io/docs/integration/astro#supported-transformations) for the full list, including overlays, smart cropping (`focus: 'auto'`, `focus: 'face'`), and other effects.

## Using ImageKit videos

Add videos to your `.astro` components with the `<Video />` component. It accepts standard HTML video attributes alongside [ImageKit-specific props](https://imagekit.io/docs/integration/astro#video-component) such as `transformation` and `urlEndpoint`.

```
---

---
<Video
  src="/sample.mp4"
  width={1280}
  height={720}
  controls
/>
```

To resize the video on ImageKit's side, pass dimensions inside `transformation`:

```
<Video
  src="/sample.mp4"
  width={640}
  height={360}
  transformation={[{ width: 640, height: 360 }]}
  controls
/>
```

## ImageKit Video Player

The [`@imagekit/video-player`](https://github.com/imagekit-developer/imagekit-video-player) package exports a dedicated Astro integration through the `@imagekit/video-player/astro` subpath. It provides a native `IKVideoPlayer` Astro component with full TypeScript types ([`IKPlayerOptions`](https://imagekit.io/docs/video-player/overview#ikplayer-options), [`SourceOptions`](https://imagekit.io/docs/video-player/overview#source-options)). You can use it directly in `.astro` files without any framework adapter.

The player is built on [Video.js](https://videojs.com/) and includes AI-generated subtitles and chapters, automatic translation into 50+ languages, word-level karaoke-style highlighting, seek thumbnails, a floating sticky player, and adaptive bitrate streaming (HLS/DASH). No manual transcription work is required.

Install the package:

\`\`\`shell npm install @imagekit/video-player \`\`\` \`\`\`shell pnpm add @imagekit/video-player \`\`\` \`\`\`shell yarn add @imagekit/video-player \`\`\`

Then use the `IKVideoPlayer` component in any `.astro` file:

```
---

const ikOptions = {
  imagekitId: 'YOUR_IMAGEKIT_ID',
  seekThumbnails: true,
};

const source = {
  src: 'https://ik.imagekit.io/your_imagekit_id/video.mp4',
  chapters: true,          // AI-generated chapter markers
  textTracks: [{
    autoGenerate: true,    // AI speech-to-text subtitles
    default: true,
    highlightWords: true,  // word-level highlighting
    translations: [
      { langCode: 'es', label: 'Spanish' },
      { langCode: 'fr', label: 'French' },
    ],
  }],
};
---

<IKVideoPlayer ikOptions={ikOptions} source={source} />
```

With `chapters: true`, the player auto-generates chapter markers from the video content. Setting `autoGenerate: true` in `textTracks` creates AI speech-to-text subtitles without any `.srt` files. Each entry in `translations` adds an automatically generated subtitle track in that language.

:::note The Video Player SDK is currently in beta. Test thoroughly before using it in production. See the [Video Player overview in ImageKit documentation](https://imagekit.io/docs/video-player/overview) for the full list of options, including playlists, shoppable videos, and signed URL support. :::

## Generating Open Graph image URLs

Use the `<OgImage />` component to render OpenGraph and Twitter Card `<meta>` tags pointing at an ImageKit-optimized image. Place it inside your layout's `<head>`.

```
---

---
<html>
  <head>
    <OgImage
      src="/og-banner.jpg"
      title="My page title"
      description="Preview description for social cards"
      alt="OG image description"
    />
  </head>
  <body><slot /></body>
</html>
```

If you need just a URL instead of the rendered tags, use the `getOgImageUrl()` helper:

```
---

const ogImage = getOgImageUrl({
  src: '/og-banner.jpg',
  transformation: [{ width: 1200, height: 630 }],
});
---
<meta property="og:image" content={ogImage} />
```

See the [ImageKit OG component documentation](https://imagekit.io/docs/integration/astro#og-image-component) for a complete list of supported props.

## Enabling client-side uploads

To upload files directly from the browser, generate a short-lived authentication token on the server using the `getUploadAuthParams()` helper from `@imagekit/astro/server`. The private key stays server-side and is never sent to the browser.

This requires an [adapter](/en/guides/on-demand-rendering/) so the endpoint runs on demand:

```

  return new Response(JSON.stringify(authParams), {
    headers: { 'Content-Type': 'application/json' },
  });
};
```

The browser then fetches this endpoint and passes the returned `signature`, `token`, `expire`, and `publicKey` to the `upload()` function from [`@imagekit/javascript`](https://github.com/imagekit-developer/imagekit-javascript). Install it as a direct dependency:

\`\`\`shell npm install @imagekit/javascript \`\`\` \`\`\`shell pnpm add @imagekit/javascript \`\`\` \`\`\`shell yarn add @imagekit/javascript \`\`\`

A minimal upload form on a `.astro` page:

```
<input type="file" id="file-input" />
<button id="upload-btn">Upload</button>
<progress id="upload-progress" value="0" max="100"></progress>

<script>
  import { upload } from '@imagekit/javascript';

  const fileInput = document.getElementById('file-input') as HTMLInputElement;
  const uploadBtn = document.getElementById('upload-btn') as HTMLButtonElement;
  const progress = document.getElementById('upload-progress') as HTMLProgressElement;

  uploadBtn.addEventListener('click', async () => {
    const file = fileInput.files?.[0];
    if (!file) return;

    const auth = await fetch('/api/upload-auth').then((r) => r.json());

    const result = await upload({
      ...auth,
      file,
      fileName: file.name,
      onProgress: (e) => {
        progress.value = (e.loaded / e.total) * 100;
      },
    });

    console.log('Uploaded:', result);
  });
</script>
```

See [the ImageKit guide](https://imagekit.io/docs/integration/astro#uploading-files) for full error handling and abort signals.

## Loading from your ImageKit Media Library

You can use [Astro Content Collections](/en/guides/content-collections/) together with the [`@imagekit/nodejs`](https://www.npmjs.com/package/@imagekit/nodejs) SDK to power gallery and listing pages directly from your ImageKit Media Library.

Install the Node SDK as a dev dependency:

\`\`\`shell npm install -D @imagekit/nodejs \`\`\` \`\`\`shell pnpm add -D @imagekit/nodejs \`\`\` \`\`\`shell yarn add -D @imagekit/nodejs \`\`\`

Then define a collection backed by `client.assets.list()`. The Node SDK returns an array of `File | Folder` objects. To limit results to images, pass `type: 'file'` to exclude folders and `fileType: 'image'`. Use the `Files.File` type guard so each entry is correctly typed before mapping it into your collection schema:

```

const client = new ImageKit({
  privateKey: import.meta.env.IMAGEKIT_PRIVATE_KEY,
});

const gallery = defineCollection({
  loader: async () => {
    const assets = await client.assets.list({
      type: 'file',       // exclude folders
      fileType: 'image',  // only image files
      skip: 0,
      limit: 50,
    });

    return assets
      .filter((asset): asset is Files.File =>
        asset.type === 'file' && !!asset.fileId && !!asset.url
      )
      .map((asset) => ({
        id: asset.fileId ?? '',
        url: asset.url ?? '',
        width: asset.width ?? 0,
        height: asset.height ?? 0,
        name: asset.name ?? '',
        tags: asset.tags ?? [],
      }));
  },
  schema: z.object({
    url: z.string().url(),
    width: z.number(),
    height: z.number(),
    name: z.string(),
    tags: z.array(z.string()),
  }),
});
```

After adding the collection, run [`astro sync`](/en/reference/cli-reference/#astro-sync) (or start the dev server) to generate the collection types used by `getCollection()`.

Render the collection with `<Image>` from `astro:assets`. The integration generates the ImageKit CDN URL with the requested transformations:

```
---

const photos = await getCollection('gallery');
---
{photos.map(({ data }) => (
  <Image
    src={data.url}
    width={data.width}
    height={data.height}
    alt={data.name}
    transformation={[{ width: 400, height: 300, focus: 'auto' }]}
  />
))}
```

## Using ImageKit in Node.js

For server-side workflows such as bulk uploads, listing assets, or deleting files, use the official [`@imagekit/nodejs`](https://www.npmjs.com/package/@imagekit/nodejs) SDK directly:

```

const client = new ImageKit({
  privateKey: import.meta.env.IMAGEKIT_PRIVATE_KEY,
});

await client.files.upload({
  file: '<file path, buffer, or URL>',
  fileName: 'sample.jpg',
});
```

## Official resources

-   [ImageKit Astro SDK](https://github.com/imagekit-developer/imagekit-astro)
-   [ImageKit Astro integration documentation](https://imagekit.io/docs/integration/astro)
-   [ImageKit JavaScript SDK](https://github.com/imagekit-developer/imagekit-javascript)
-   [ImageKit Node.js SDK](https://github.com/imagekit-developer/imagekit-nodejs)
-   [ImageKit transformation reference](https://imagekit.io/docs/transformations)

## [Mux & Astro](https://docharvest.github.io/docs/astro/guides/media/mux/)

Contents

astro

Mux & Astro

Astro

Mux & Astro

[Mux](https://www.mux.com?utm_campaign=21819274-Astro&utm_source=astro-docs) is a hosted media service that provides video streaming infrastructure and performance analytics for businesses of all scales.

When you use Mux to store and host your video content, you'll have access to Astro-native video components for [Mux Player](#mux-player), a drop-in component for adding Mux videos in your Astro project, and [Mux Uploader](#mux-uploader) for uploading videos to Mux from your website. These components integrate seamlessly with [Mux Data](https://www.mux.com/docs/guides/data?utm_campaign=21819274-Astro&utm_source=astro-docs) to track your video engagement and performance.

You can also interact with your content through the [Mux Node SDK](#mux-node-sdk).

:::tip Learn more about features such as embedding, storing, streaming, and customizing video at [Mux's dedicated page for video in Astro](https://www.mux.com/video-for/astro?utm_campaign=21819274-Astro&utm_source=astro-docs)! :::

## Using Mux in Astro

Mux's APIs and web components work in Astro to compress and optimize your videos and streams for the web, adapt the quality of your video to network conditions, and integrate additional features like captions, thumbnails, and analytics. The [Mux Node SDK](https://www.mux.com/docs/integrations/mux-node-sdk?utm_campaign=21819274-Astro&utm_source=astro-docs) supports both Mux Data and the Mux Video API.

## Prerequisites

-   An existing Astro project. Some features may additionally require an adapter installed for [on-demand server rendering](/en/guides/on-demand-rendering/).
-   A Mux account. If you don’t have an account, you can [sign up with Mux](https://dashboard.mux.com/login?utm_campaign=21819274-Astro&utm_source=astro-docs) using the code `ASTRO` to receive a $50 credit.

## Mux Player

In Astro, you can use the full-featured [Mux Player](https://www.mux.com/docs/guides/mux-player-web?utm_campaign=21819274-Astro&utm_source=astro-docs) as a native Astro component for optimized, responsive video playback and live streams.

Mux Player provides a responsive UI based on video player dimensions and stream type, automatic thumbnail previews and poster images, and modern video player capabilities (e.g. fullscreen, picture-in-picture, Chromecast, AirPlay).

```
---

---
<MuxPlayer
  playbackId="DS00Spx1CV902MCtPj5WknGlR102V5HFkDe"
  metadata={{ video_title: 'My Astro Video' }}
/>
```

Mux Player has built-in support for Mux Data analytics, and will automatically show visitor engagement and video quality metrics in your dashboard once your video has views on your deployed site.

### Installation

Install the Astro version of Mux Player using your preferred package manager:

\`\`\`shell npm install @mux/mux-player-astro \`\`\` \`\`\`shell pnpm add @mux/mux-player-astro \`\`\` \`\`\`shell yarn add @mux/mux-player-astro \`\`\`

Mux Player can also be used in your Astro project as:

-   a web component (`<mux-player>` from `@mux/mux-player` )
-   a React component (`<MuxPlayer />` from `@mux/mux-player-react`)
-   an HTML web embed (`<iframe>`)

### Play a video from Mux

Import and use the native `<MuxPlayer />` Astro component directly in your `.astro` files like any other Astro component.

You will need the `playbackId` for your asset, which can be found in your Mux dashboard or [retrieved from its `ASSET_ID`](#retrieve-asset-data).

All other [options to control the Mux web player](https://www.mux.com/docs/guides/player-api-reference/?utm_campaign=21819274-Astro&utm_source=astro-docs) (e.g. hide or display controls, style elements, disable cookies) are optional:

```
<MuxPlayer
  playbackId="FOTbeIxKeMPzyhrob722wytaTGI02Y3zbV00NeFQbTbK00"
  metadata={{
    video_title: 'Starlight by Astro',
  }}
  style={{
    display: 'block',
    aspectRatio: '16/9',
    backgroundColor: '#000',
    margin: '1rem 0 2rem',
  }}
  primaryColor="#f2ec3a"
  secondaryColor="#0caa09"
  accentColor="#6e1e99"
  defaultShowRemainingTime={true}
/>
```

If your `playbackId` belongs to a live stream instead of a prerecorded video on demand, then the Mux Player will allow you to further customize the player with options such as whether or not to enable [DVR mode](https://www.mux.com/docs/guides/stream-recordings-of-live-streams#dvr-mode-vs-non-dvr-mode?utm_campaign=21819274-Astro&utm_source=astro-docs).

```
<MuxPlayer
  playbackId="FOTbeIxKeMPzyhrob722wytaTGI02Y3zbV00NeFQbTbK00"
  metadata={{
    video_title: 'Starlight stream with Astro',
  }}
  streamType="live:dvr"
/>
```

Every live stream is recorded and saved on Mux as a video asset for future on-demand playback.

## Mux video Element

The [Mux video element](https://www.mux.com/docs/guides/play-your-videos#mux-video-element?utm_campaign=21819274-Astro&utm_source=astro-docs) is a drop-in replacement for the HTML5 `<video>` element that provides browser support for HLS playback, and has Mux Data automatically configured to show visitor and performance metrics. Use this when you do not need or want all the features of [Mux Player](#mux-player).

To use the `<mux-video>` web component, first install `mux-video` using your preferred package manager:

\`\`\`shell npm install @mux/mux-video \`\`\` \`\`\`shell pnpm add @mux/mux-video \`\`\` \`\`\`shell yarn add @mux/mux-video \`\`\`

Then, you can import and render the web component in a `<script>` tag in your `.astro` file.

You will need the `playback-id` for your video asset, which can be found in your Mux dashboard or [retrieved from its `ASSET_ID`](#retrieve-asset-data).

All attributes for the HTML 5 `<video>` element (e.g. `poster`, `controls`, `muted`) are available, as well as additional Mux video player controls (e.g. to provide metadata, control the resolution, disable cookies):

```
<script>import '@mux/mux-video'</script>

<mux-video
  playback-id="FOTbeIxKeMPzyhrob722wytaTGI02Y3zbV00NeFQbTbK00"
  metadata-video-title="Starlight by Astro"
  controls
  disable-tracking
></mux-video>
```

## Mux Node SDK

The [Mux Node SDK](https://www.mux.com/docs/integrations/mux-node-sdk?utm_campaign=21819274-Astro&utm_source=astro-docs) provides authenticated access to the Mux REST API from server-side TypeScript or JavaScript. This allows you to interact with your Mux assets and data in the component script of your `.astro` files.

While the Mux Player and Mux Video components do not require authentication and can play any publicly accessible video given its `playbackId`, connecting to your hosted Mux data via the Node SDK requires [a Mux API access token](#mux-environment-api-access).

### Installation

Install the Mux Node SDK using your preferred package manager:

\`\`\`shell npm install @mux/mux-node \`\`\` \`\`\`shell pnpm add @mux/mux-node \`\`\` \`\`\`shell yarn add @mux/mux-node \`\`\`

### Mux Environment API access

API tokens are tied to a specific Mux Environment, which is essentially a container for your videos and related data. When you sign up for Mux, an Environment is created for you automatically. If you’ve created additional Environments, make sure you select the correct one before generating your tokens. From there, you can [get your ID and SECRET tokens](https://www.mux.com/docs/core/stream-video-files#1-get-an-api-access-token) and provide them to the Node SDK. These tokens can be passed into your Astro components as environment variables stored in a `.env` file.

This will allow you to create an instance of the Mux Node SDK for retrieving information about your videos, creating new assets, accessing metrics and real-time performance, and more:

```
---

const mux = new Mux ({
  tokenId: import.meta.env.MUX_TOKEN_ID,
  tokenSecret: import.meta.env.MUX_TOKEN_SECRET,
})
---
```

Read more about using [environment variables](/en/guides/environment-variables/) in your Astro project, including creating a [type-safe schema](/en/guides/environment-variables/#type-safe-environment-variables) for your Mux credentials.

### Retrieve asset data

To fetch information about your video to use in your Astro project, provide the video's `ASSET_ID` (available in the Mux dashboard) to the `retrieve()` helper function. This will allow you to pass values to both your Mux components and your HTML template, such as the video's title or duration:

```
---

const mux = new Mux({
  tokenId: import.meta.env.MUX_TOKEN_ID,
  tokenSecret: import.meta.env.MUX_TOKEN_SECRET,
})

const ASSET_ID = "E01irAaN8c6dk1010153uC2mzst7RVbAdJJWtHECAHFvDo";
const asset = await mux.video.assets.retrieve(ASSET_ID);

const playbackId = asset.playback_ids?.find((id)=> id.policy=== "public")?.id;
const videoTitle = asset?.meta?.title;
const createdAt = Number(asset?.created_at);
const duration = Number(asset?.duration)

const date = new Date(createdAt * 1000).toDateString()
const time = new Date(Math.round(duration) * 1000).toISOString().substring(14, 19)
---
<h1>My Video Page</h1>
<p>Title: {videoTitle}</p>
<p>Upload Date: {date}</p>
<p>Length: {time}</p>

<MuxPlayer 
  playbackId={playbackId}
  metadata={{video_title: videoTitle}}
/>
```

See all asset properties in the [Mux Asset API documentation](https://www.mux.com/docs/api-reference/video/assets?utm_campaign=21819274-Astro&utm_source=astro-docs).

## Mux Uploader

[Mux Uploader](https://www.mux.com/docs/guides/mux-uploader?utm_campaign=21819274-Astro&utm_source=astro-docs) is a fully-functional, customizable video upload UI for your Astro website. The native Astro `<MuxUpload />` component allows you to build video upload functionality into your web app.

Mux Uploader supports both manual file selection and drag and drop for file uploads, optional pausing and resuming of uploads, and more.

### Installation

Install the Astro version of Mux Uploader using your preferred package manager:

\`\`\`shell npm install @mux/mux-uploader-astro \`\`\` \`\`\`shell pnpm add @mux/mux-uploader-astro \`\`\` \`\`\`shell yarn add @mux/mux-uploader-astro \`\`\`

### Upload a video to Mux

Before uploading a video, make sure you have your [Mux API access tokens](#mux-environment-api-access) configured. With those in place, you can use the `create()` function from the Mux Node SDK to start a new video upload:

```
---

const mux = new Mux({
  tokenId: import.meta.env.MUX_TOKEN_ID,
  tokenSecret: import.meta.env.MUX_TOKEN_SECRET
});

const upload = await mux.video.uploads.create({
  new_asset_settings: {
    playback_policy: ['public'],
    video_quality: 'basic'
  },
  cors_origin: '*',
});
---
<Layout title="Upload a video to Mux">
  <MuxUploader endpoint={upload.url} />
</Layout>
```

### Customize the uploader

You can customize the functionality and appearance of the `<MuxUploader />` with additional component attributes. In addition to styling your element, this allows you to control options such as the ability to pause a download or set a maximum file size.

```
---

---

<MuxUploader
  endpoint="https://my-authenticated-url/storage?your-url-params"
  pausable
  maxFileSize={1000000000}
  chunkSize={8192}
  style={{
    '--progress-bar-fill-color': '#7e22ce',
    '--button-background-color': '#f0f0f0',
  }}
/>
```

See the [Mux Uploader customization guide](https://www.mux.com/docs/guides/uploader-web-customize-look-and-feel?utm_campaign=21819274-Astro&utm_source=astro-docs) for more options.

### Event handling for uploads

Mux Uploader provides a feature-rich, dynamic UI that changes based on the current state of your media upload. The uploader's behavior responds to both user-driven events (e.g. selecting a file, retrying after an error) and state-driven events (e.g. upload in-progress, upload successfully completed).

You can listen for these events and handle them in your Astro component with [client-side scripts](/en/guides/client-side-scripts/). A `MuxUploaderElement` type is also available.

```
---

---

<MuxUploader
  id="my-uploader"
  endpoint="https://my-authenticated-url/storage?your-url-params"
  pausable
/>

<script>
  import type { MuxUploaderElement } from '@mux/mux-uploader-astro';
  
  const uploader = document.getElementById('my-uploader') as MuxUploaderElement;
  
  uploader.addEventListener('uploadstart', (event) => {
    console.log('Upload started!', event.detail);
  });
  
  uploader.addEventListener('success', (event) => {
    console.log('Upload successful!', event.detail);
  });
  
  uploader.addEventListener('uploaderror', (event) => {
    console.error('Upload error!', event.detail);
  });
  
  uploader.addEventListener('progress', (event) => {
    console.log('Upload progress: ', event.detail);
  });
</script>
```

## Official Resources

For the full API and webhook reference, usage guides, and information about additional topics, such as integrating with a CMS, building custom video workflows, and more, please see:

-   [The official Mux documentation for Astro](https://www.mux.com/docs/integrations/astro?utm_campaign=21819274-Astro&utm_source=astro-docs)
-   [`@mux/mux-player-astro` API reference](https://github.com/muxinc/elements/blob/main/packages/mux-player-astro/README.md)
-   [`@mux/mux-uploader-astro` API reference](https://github.com/muxinc/elements/blob/main/packages/mux-uploader-astro/REFERENCE.md)
-   [Building a video uploader with Mux and Astro (YouTube)](https://www.youtube.com/watch?v=aaL1k5FsWfE)
-   [Astro uploader and player code example (GitHub)](https://github.com/muxinc/examples/tree/main/astro-uploader-and-player)

## [Middleware](https://docharvest.github.io/docs/astro/guides/middleware/)

Contents

astro

Middleware

Astro

Middleware

**Middleware** allows you to intercept requests and responses and inject behaviors dynamically every time a page or endpoint is about to be rendered. This rendering occurs at build time for all prerendered pages, but occurs when the route is requested for pages rendered on demand, making [additional SSR features like cookies and headers](/en/guides/on-demand-rendering/#on-demand-rendering-features) available.

Middleware also allows you to set and share request-specific information across endpoints and pages by mutating a `locals` object that is available in all Astro components and API endpoints. This object is available even when this middleware runs at build time.

## Basic Usage

1\. Create \`src/middleware.js|ts\` (Alternatively, you can create \`src/middleware/index.js|ts\`.)

2.  Inside this file, export an [`onRequest()`](/en/reference/modules/astro-middleware/#onrequest) function that can be passed a [`context` object](#the-context-object) and `next()` function. This must not be a default export.
    
    ```
    export function onRequest (context, next) {
        // intercept data from a request
        // optionally, modify the properties in `locals`
        context.locals.title = "New title";
        context.locals.property = "information";
    
        // return a Response or the result of calling `next()`
        return next();
    };
    ```
    
3.  Inside any `.astro` file, access response data using `Astro.locals`.
    
    ```
    ---
    const data = Astro.locals;
    ---
    <h1>{data.title}</h1>
    <p>This {data.property} is from middleware.</p>
    ```
    

### The `context` object

The [`context`](/en/reference/api-reference/) object includes information to be made available to other middleware, API routes and `.astro` routes during the rendering process.

This is an optional argument passed to `onRequest()` that may contain the `locals` object as well as any additional properties to be shared during rendering. For example, the `context` object may include cookies used in authentication.

### Storing data in `context.locals`

`context.locals` is an object that can be manipulated inside the middleware.

This `locals` object is forwarded across the request handling process and is available as a property to [`APIContext`](/en/reference/api-reference/#locals) and [`AstroGlobal`](/en/reference/api-reference/#locals). This allows data to be shared between middlewares, API routes, and `.astro` pages. This is useful for storing request-specific data, such as user data, across the rendering step.

:::tip\[Integration properties\] [Integrations](/en/guides/integrations/) may set properties and provide functionality through the `locals` object. If you are using an integration, check its documentation to ensure you are not overriding any of its properties or doing unnecessary work. :::

You can store any type of data inside `locals`: strings, numbers, and even complex data types such as functions and maps.

```

    context.locals.welcomeTitle = () => {
        return "Welcome back " + context.locals.user.name;
    };
    context.locals.orders = new Map([["1", { product: "socks" }]]);
    context.locals.property = "information";

    // return a Response or the result of calling `next()`
    return next();
};
```

Then you can use this information inside any `.astro` file with `Astro.locals`.

```
---
const title = Astro.locals.welcomeTitle();
const orders = Array.from(Astro.locals.orders.entries());
const data = Astro.locals;
---
<h1>{title}</h1>
<p>This {data.property} is from middleware.</p>
<ul>
    {orders.map(order => {
        return <li>{/* do something with each order */}</li>;
    })}
</ul>
```

`locals` is an object that lives and dies within a single Astro route; when your route page is rendered, `locals` won't exist anymore and a new one will be created. Information that needs to persist across multiple page requests must be stored elsewhere.

:::note The value of `locals` cannot be overridden at run time. Doing so would risk wiping out all the information stored by the user. Astro performs checks and will throw an error if `locals` are overridden. :::

## Example: redacting sensitive information

The example below uses middleware to replace "PRIVATE INFO" with the word "REDACTED" to allow you to render modified HTML on your page:

```

    const html = await response.text();
    const redactedHtml = html.replaceAll("PRIVATE INFO", "REDACTED");
    
    return new Response(redactedHtml, {
        status: 200,
        headers: response.headers
    });
};
```

## Middleware types

You can import and use the utility function [`defineMiddleware()`](/en/reference/modules/astro-middleware/#definemiddleware) to take advantage of type safety:

```
// src/middleware.ts

// `context` and `next` are automatically typed
```

Instead, if you're using JsDoc to take advantage of type safety, you can use `MiddlewareHandler`:

```
// src/middleware.js
/**
 * @type {import("astro").MiddlewareHandler}
 */
// `context` and `next` are automatically typed
```

To type the information inside `Astro.locals`, which gives you autocompletion inside `.astro` files and middleware code, [extend the global types](/en/guides/typescript/#extending-global-types) by declaring a global namespace in the `env.d.ts` file:

```
type User = {
  id: number;
  name: string;
};

declare namespace App {
  interface Locals {
    user: User;
    welcomeTitle: () => string;
    orders: Map<string, object>;
    session: import("./lib/server/session").Session | null;
  }
}
```

Then, inside the middleware file, you can take advantage of autocompletion and type safety.

## Chaining middleware

Multiple middlewares can be joined in a specified order using [`sequence()`](/en/reference/modules/astro-middleware/#sequence):

```

async function validation(_, next) {
    console.log("validation request");
    const response = await next();
    console.log("validation response");
    return response;
}

async function auth(_, next) {
    console.log("auth request");
    const response = await next();
    console.log("auth response");
    return response;
}

async function greeting(_, next) {
    console.log("greeting request");
    const response = await next();
    console.log("greeting response");
    return response;
}
```

This will result in the following console order:

```
validation request
auth request
greeting request
greeting response
auth response
validation response
```

## Rewriting

The `APIContext` exposes a method called [`rewrite()`](/en/reference/api-reference/#rewrite) which works the same way as [Astro.rewrite](/en/guides/routing/#rewrites).

Use `context.rewrite()` inside middleware to display a different page's content without [redirecting](/en/guides/routing/#dynamic-redirects) your visitor to a new page. This will trigger a new rendering phase, causing any middleware to be re-executed.

```

  }

  return next();
};
```

You can also pass the `next()` function an optional URL path parameter to rewrite the current `Request` without retriggering a new rendering phase. The location of the rewrite path can be provided as a string, URL, or `Request`:

```

  }

  return next();
};
```

The `next()` function accepts the same payload of [the `Astro.rewrite()` function](/en/reference/api-reference/#rewrite). The location of the rewrite path can be provided as a string, URL, or `Request`.

When you have multiple middleware functions chained via [sequence()](#chaining-middleware), submitting a path to `next()` will rewrite the `Request` in place and the middleware will not execute again. The next middleware function in the chain will receive the new `Request` with its updated `context`.

Calling `next()` with this signature will create a new `Request` object using the old `ctx.request`. This means that trying to consume `Request.body`, either before or after this rewrite, will throw a runtime error. This error is often raised with [Astro Actions that use HTML forms](/en/guides/actions/#call-actions-from-an-html-form-action). In these cases, we recommend handling rewrites from your Astro templates using `Astro.rewrite()` instead of using middleware.

```

// Current URL is https://example.com/blog

// First middleware function
async function first(context, next) {
  console.log(context.url.pathname) // this will log "/blog"
  // Rewrite to a new route, the homepage 
  // Return updated `context` which is passed to next function
  return next("/")
}

// Current URL is still https://example.com/blog

// Second middleware function
async function second(context, next) {
  // Receives updated `context`
  console.log(context.url.pathname) // this will log  "/"    
  return next()
}
```

## Error pages

Middleware will attempt to run for all on-demand rendered pages, even when a matching route cannot be found. This includes Astro's default (blank) 404 page and any custom 404 pages. However, it is up to the [adapter](/en/guides/on-demand-rendering/) to decide whether that code runs. Some adapters may serve a platform-specific error page instead.

Middleware will also attempt to run before serving a 500 error page, including a custom 500 page, unless the server error occurred in the execution of the middleware itself. If your middleware does not run successfully, then you will not have access to `Astro.locals` to render your 500 page.

## [Migrate an existing project to Astro](https://docharvest.github.io/docs/astro/guides/migrate-to-astro/)

Contents

astro

Migrate an existing project to Astro

Astro

Migrate an existing project to Astro

**Ready to convert your site to Astro?** See one of our guides for migration tips.

## Migration Guides

Note that many of these pages are **stubs**: they're collections of resources waiting for your contribution!

## Why migrate your site to Astro?

Astro provides many benefits: performance, simplicity, and many of the features you want built right into the framework. When you do need to extend your site, Astro provides several [official and 3rd-party community integrations](https://astro.build/integrations).

Migrating may be less work than you think!

Depending on your existing project, you may be able to use your existing:

-   [UI framework components](/en/guides/framework-components/) directly in Astro.
    
-   [CSS stylesheets or libraries](/en/guides/styling/) including Tailwind.
    
-   [Markdown/MDX files](/en/guides/markdown-content/), with a [configurable Markdown processor](/en/guides/markdown-content/#markdown-plugins) that supports plugins.
    
-   [Content from a CMS](/en/guides/cms/) through an integration or API.
    

## Which projects can I convert to Astro?

[Many existing sites can be built with Astro](/en/concepts/why-astro/). Astro is ideally suited for your existing content-based sites like blogs, landing pages, marketing sites and portfolios. Astro integrates with several popular headless CMSes, and allows you to connect eCommerce shop carts.

Astro allows you have a fully statically-generated website, a dynamic app with routes rendered on demand, or a combination of both with [complete control over your project rendering](/en/guides/on-demand-rendering/), making it a great replacement for SSGs or for sites that need to fetch some page data on the fly.

## How will my project design change?

Depending on your existing project, you may need to think differently about:

-   Designing in [Astro Islands](/en/concepts/islands/#what-is-an-island) to avoid sending unnecessary JavaScript to the browser.
    
-   Providing client-side interactivity with [client-side `<script>` tags](/en/guides/client-side-scripts/) or [UI framework components](/en/guides/framework-components/).
    
-   Managing [shared state](/en/recipes/sharing-state-islands/) with Nano Stores or local storage instead of app-wide hooks or wrappers.

## [Migrating from Create React App (CRA)](https://docharvest.github.io/docs/astro/guides/migrate-to-astro/from-create-react-app/)

Contents

astro

Migrating from Create React App (CRA)

Astro

Migrating from Create React App (CRA)

Astro's [React integration](/en/guides/integrations-guide/react/) provides support for [using React components inside Astro components](/en/guides/framework-components/), including entire React apps like Create React App (CRA)!

```
---
// Import your root App component

---
<!-- Use a client directive to load your app -->
<App client:load />
```

See how to [Build a Single Page Application (SPA) with Astro](https://logsnag.com/blog/react-spa-with-astro) using React Router.

Many apps will "just work" as full React apps when you add them directly to your Astro project with the React integration installed. This is a great way to get your project up and running immediately and keep your app functional while you migrate to Astro.

Over time, you can convert your structure piece-by-piece to a combination of `.astro` and `.jsx` components. You will probably discover you need fewer React components than you think!

Here are some key concepts and migration strategies to help you get started. Use the rest of our docs and our [Discord community](https://astro.build/chat) to keep going!

## Key Similarities between CRA and Astro

-   The [syntax of `.astro` files is similar to JSX](/en/reference/astro-syntax/#differences-between-astro-and-jsx). Writing Astro should feel familiar.
    
-   Astro uses file-based routing, and [allows specially named pages to create dynamic routes](/en/guides/routing/#dynamic-routes).
    
-   Astro is [component-based](/en/basics/astro-components/), and your markup structure will be similar before and after your migration.
    
-   Astro has [official integrations for React, Preact, and Solid](/en/guides/integrations-guide/react/) so you can use your existing JSX components. Note that in Astro, these files **must** have a `.jsx` or `.tsx` extension.
    
-   Astro has support for [installing NPM packages](/en/guides/imports/#npm-packages), including React libraries. Many of your existing dependencies will work in Astro.
    

## Key Differences between CRA and Astro

When you rebuild your CRA site in Astro, you will notice some important differences:

-   CRA is a single-page application that uses `index.js` as your project's root. Astro is a multi-page site, and `index.astro` is your home page.
    
-   [`.astro` components](/en/basics/astro-components/) are not written as exported functions that return page templating. Instead, you'll split your code into a "code fence" for your JavaScript and a body exclusively for the HTML you generate.
    
-   [content-driven](/en/concepts/why-astro/#content-driven): Astro was designed to showcase your content and to allow you to opt-in to interactivity only as needed. An existing CRA app might be built for high client-side interactivity and may require advanced Astro techniques to include items that are more challenging to replicate using `.astro` components, such as dashboards.
    

## Add your CRA to Astro

Your existing app can be rendered directly inside a new Astro project, often with no changes to your app's code.

### Create a new Astro project

Use the `create astro` command for your package manager to launch Astro's CLI wizard and select a new "empty" Astro project.

\`\`\`shell npm create astro@latest \`\`\` \`\`\`shell pnpm create astro@latest \`\`\` \`\`\`shell yarn create astro@latest \`\`\`

### Add integrations and dependencies

Add the React integration using the `astro add` command for your package manager. If your app uses other packages supported by the `astro add` command, like Tailwind and MDX, you can add them all with one command:

\`\`\`shell npx astro add react npx astro add react tailwind mdx \`\`\` \`\`\`shell pnpm astro add react pnpm astro add react tailwind mdx \`\`\` \`\`\`shell yarn astro add react yarn astro add react tailwind mdx \`\`\`

If your CRA requires any dependencies (e.g. NPM packages), then install them individually using the command line or by adding them to your new Astro project's `package.json` manually and then running an install command. Note that many, but not all, React dependencies will work in Astro.

### Add your existing app files

Copy your existing Create React App (CRA) project source files and folders (e.g. `components`, `hooks`, `styles`, etc.) into a new folder inside `src/`, keeping its file structure so your app will continue to work. Note that all `.js` file extensions must be renamed to `.jsx` or `.tsx`.

Do not include any configuration files. You will use Astro's own `astro.config.mjs`, `package.json`, and `tsconfig.json`.

Move the contents of your app's `public/` folder (e.g. static assets) into Astro's `public/` folder.

\- public/ - logo.png - favicon.ico - ... - src/ - cra-project/ - App.jsx - ... - pages/ - index.astro - astro.config.mjs - package.json - tsconfig.json

### Render your app

Import your app's root component in the frontmatter section of `index.astro`, then render the `<App />` component in your page template:

```
---

---
<App client:load />
```

:::note\[Client directives\] Your app needs a [client directive](/en/reference/directives-reference/#client-directives) for interactivity. Astro will render your React app as static HTML until you opt-in to client-side JavaScript.

Use `client:load` to ensure your app loads immediately from the server, or `client:only="react"` to skip rendering on the server and run your app entirely client-side. :::

## Convert your CRA to Astro

After [adding your existing app to Astro](#add-your-cra-to-astro), you will probably want to convert your app itself to Astro!

You will replicate a similar component-based design [using Astro HTML templating components for your basic structure](/en/basics/astro-components/) while importing and including individual React components (which may themselves be entire apps!) for islands of interactivity.

Every migration will look different and can be done incrementally without disrupting your working app. Convert individual pieces at your own pace so that more and more of your app is powered by Astro components over time.

As you convert your React app, you will decide which React components you will [rewrite as Astro components](#converting-jsx-files-to-astro-files). Your only restriction is that Astro components can import React components, but React components must only import other React components:

```
---

---
<html>
  <body>
    <h1>Use React components directly in Astro!</h1>
    <MyReactComponent />
  </body>
</html>
```

Instead of importing Astro components into React components, you can nest React components inside a single Astro component:

```
---

---
<MyReactSidebar>
  <p>Here is a sidebar with some text and a button.</p>
  <div slot="actions">
    <MyReactButton client:idle />
  </div>
</MyReactSidebar>
```

You may find it helpful to learn about [Astro islands](/en/concepts/islands/) and [Astro components](/en/basics/astro-components/) before restructuring your CRA as an Astro project.

### Compare: JSX vs Astro

Compare the following CRA component and a corresponding Astro component:

\`\`\`jsx title="StarCount.jsx" import React, { useState, useEffect } from 'react';

const Component = () => { const \[stars, setStars\] = useState(0); const \[message, setMessage\] = useState('');

```
useEffect(() => {
    const fetchData = async () => {
        const res = await fetch('https://api.github.com/repos/withastro/astro');
        const json = await res.json();

        setStars(json.stargazers_count || 0);
        setMessage(json.message);
    };

    fetchData();
}, []);

return (
    <>
        <Header />
        <p style={{
            backgroundColor: `#f4f4f4`,
            padding: `1em 1.5em`,
            textAlign: `center`,
            marginBottom: `1em`
        }}>Astro has {stars} 🧑‍🚀</p>
        <Footer />
    </>
)
```

};

````
```
````

\`\`\`astro title="StarCount.astro" --- import Header from './Header.astro'; import Footer from './Footer.astro'; import './layout.css'; const res = await fetch('https://api.github.com/repos/withastro/astro') const json = await res.json(); const message = json.message; const stars = json.stargazers\_count || 0; ---

Astro has {stars} 🧑‍🚀

\`\`\`

### Converting JSX files to `.astro` files

Here are some tips for converting a CRA `.js` component into a `.astro` component:

1.  Use the returned JSX of the existing CRA component function as the basis for your HTML template.
    
2.  Change any [CRA or JSX syntax to Astro](#reference-convert-cra-syntax-to-astro) or to HTML web standards. This includes `{children}` and `className`, for example.
    
3.  Move any necessary JavaScript, including import statements, into a ["code fence" (`---`)](/en/basics/astro-components/#the-component-script). Note: JavaScript to [conditionally render content](/en/reference/astro-syntax/#dynamic-html) is often written inside the HTML template directly in Astro.
    
4.  Use [`Astro.props`](/en/reference/api-reference/#props) to access any additional props that were previously passed to your CRA function.
    
5.  Decide whether any imported components also need to be converted to Astro. You can keep them as React components for now, or forever. But, you may eventually want to convert them to `.astro` components, especially if they do not need to be interactive!
    
6.  Replace `useEffect()` with import statements or [`import.meta.glob()`](/en/guides/imports/#importmetaglob) to query your local files. Use `fetch()` to fetch external data.
    

### Migrating Tests

As Astro outputs raw HTML, it is possible to write end-to-end tests using the output of the build step. Any end-to-end tests written previously might work out-of-the-box if you have been able to match the markup of your CRA site. Testing libraries such as Jest and React Testing Library can be imported and used in Astro to test your React components.

See Astro's [testing guide](/en/guides/testing/) for more.

## Reference: Convert CRA Syntax to Astro

### CRA Imports to Astro

Update any [file imports](/en/guides/imports/) to reference relative file paths exactly. This can be done using [import aliases](/en/guides/typescript/#import-aliases), or by writing out a relative path in full.

Note that `.astro` and several other file types must be imported with their full file extension.

```
---

---
<Card />
```

### CRA Children Props to Astro

Convert any instances of `{children}` to an Astro `<slot />`. Astro does not need to receive `{children}` as a function prop and will automatically render child content in a `<slot />`.

```
---
---

}

<div>
  <slot />
</div>
```

React components that pass multiple sets of children can be migrated to an Astro component using [named slots](/en/basics/astro-components/#named-slots).

See more about [specific `<slot />` usage in Astro](/en/basics/astro-components/#slots).

### CRA Data Fetching to Astro

Fetching data in a Create React App component is similar to Astro, with some slight differences.

You will need to remove any instances of a side effect hook (`useEffect`) for either `import.meta.glob()` or `getCollection()`/`getEntry()` to access data from other files in your project source.

To [fetch remote data](/en/guides/data-fetching/), use `fetch()`.

These data requests are made in the frontmatter of the Astro component and use top-level await.

```
---

// Get all `src/content/blog/` entries
const allBlogPosts = await getCollection('blog');

// Get all `src/pages/posts/` entries
const allPosts = Object.values(import.meta.glob('../pages/post/*.md', { eager: true }));

// Fetch remote data
const response = await fetch('https://randomuser.me/api/');
const data = await response.json();
const randomUser = data.results[0];
---
```

See more about local files imports with [`import.meta.glob()`](/en/guides/imports/#importmetaglob), [querying with content collections](/en/guides/content-collections/#querying-build-time-collections) or [fetching remote data](/en/guides/data-fetching/).

### CRA Styling to Astro

You may need to replace any [CSS-in-JS libraries](https://github.com/withastro/astro/issues/4432) (e.g. styled-components) with other available CSS options in Astro.

If necessary, convert any inline style objects (`style={{ fontWeight: "bold" }}`) to inline HTML style attributes (`style="font-weight:bold;"`). Or, use an [Astro `<style>` tag](/en/guides/styling/#styling-in-astro) for scoped CSS styles.

```
<div style={{backgroundColor: `#f4f4f4`, padding: `1em`}}>{message}</div>
<div style="background-color: #f4f4f4; padding: 1em;">{message}</div>
```

Tailwind is supported after installing the [Tailwind Vite plugin](/en/guides/styling/#tailwind). No changes to your existing Tailwind code are required!

See more about [Styling in Astro](/en/guides/styling/).

## Troubleshooting

Your CRA might "just work" in Astro! But, you may likely need to make minor adjustments to duplicate your existing app's functionality and/or styles.

If you cannot find your answers within these docs, please visit the [Astro Discord](https://astro.build/chat) and ask questions in our support forum!

## Community Resources

:::note\[Have a resource to share?\] If you found (or made!) a helpful video or blog post about converting a Create React App to Astro, [add it to this list](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/migrate-to-astro/from-create-react-app.mdx)! :::

## [Migrating from Docusaurus](https://docharvest.github.io/docs/astro/guides/migrate-to-astro/from-docusaurus/)

Contents

astro

Migrating from Docusaurus

Astro

Migrating from Docusaurus

[Docusaurus](https://Docusaurus.io) is a popular documentation website builder built on React.

## Key Similarities between Docusaurus and Astro

Docusaurus and Astro share some similarities that will help you migrate your project:

-   Both Astro and Docusaurus are modern, JavaScript-based (Jamstack) site builders intended for [content-driven websites](/en/concepts/why-astro/#content-driven), like documentation sites.
    
-   Both Astro and Docusaurus support [MDX pages](/en/guides/markdown-content/). You should be able to use your existing `.mdx` files with Astro.
    
-   Both Astro and Docusaurus use [file-based routing](/en/guides/routing/) to generate page routes automatically for any MDX file located in `src/pages`. Using Astro's file structure for your existing content and when adding new pages should feel familiar.
    
-   Astro has an [official integration for using React components](/en/guides/integrations-guide/react/). Note that in Astro, React files **must** have a `.jsx` or `.tsx` extension.
    
-   Astro supports [installing NPM packages](/en/guides/imports/#npm-packages), including several for React. You may be able to keep some or all of your existing React components and dependencies.
    
-   [Astro's JSX-like syntax](/en/basics/astro-components/#the-component-template) should feel familiar if you are used to writing React.
    

## Key Differences between Docusaurus and Astro

When you rebuild your Docusaurus site in Astro, you will notice some important differences:

-   Docusaurus is a React-based single-page application (SPA). Astro sites are multi-page apps built using [`.astro` components](/en/basics/astro-components/), but can also support [React, Preact, Vue.js, Svelte, SolidJS, AlpineJS](/en/guides/framework-components/) and raw HTML templating.
    
-   Docusaurus was designed to build documentation websites and has some built-in, documentation-specific website features that you would have to build yourself in Astro. Instead, Astro offers some of these features through [Starlight: an official docs theme](https://starlight.astro.build). This website was the inspiration for Starlight, and now runs on it! You can also find more [community docs themes](https://astro.build/themes?search=&categories%5B%5D=docs) with built-in features in our Themes Showcase.
    
-   Docusaurus sites use MDX pages for content. Astro's docs theme uses Markdown (`.md`) files by default and does not require you to use MDX. You can optionally [install Astro's MDX integration](/en/guides/integrations-guide/mdx/) (included in our Starlight theme by default) and use `.mdx` files in addition to standard Markdown files.
    

## Switch from Docusaurus to Astro

To convert a Docusaurus documentation site to Astro, start with our official [Starlight docs theme starter template](https://starlight.astro.build), or explore more community docs themes in our [theme showcase](https://astro.build/themes?search=&categories%5B%5D=docs).

You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#install-from-the-cli-wizard).

\`\`\`shell npm create astro@latest -- --template starlight \`\`\` \`\`\`shell pnpm create astro@latest --template starlight \`\`\` \`\`\`shell yarn create astro --template starlight \`\`\`

Astro's MDX integration is included by default, so you can [bring your existing content files to Starlight](https://starlight.astro.build/getting-started/#add-content) right away.

You can find Astro's docs starter, and other official templates, on [astro.new](https://astro.new). You'll find a link to each project's GitHub repository, as well as one-click links to open a working project in StackBlitz and CodeSandbox online development environments.

## Community Resources

:::note\[Have a resource to share?\] If you found (or made!) a helpful video or blog post about converting a Docusaurus site to Astro, [add it to this list](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/migrate-to-astro/from-docusaurus.mdx)! :::

## [Migrating from Eleventy](https://docharvest.github.io/docs/astro/guides/migrate-to-astro/from-eleventy/)

Contents

astro

Migrating from Eleventy

Astro

Migrating from Eleventy

[Eleventy](https://11ty.dev) is an open-source static site generator that works with multiple template languages.

## Key Similarities between Eleventy (11ty) and Astro

Eleventy (11ty) and Astro share some similarities that will help you migrate your project:

-   Both Astro and Eleventy are modern, JavaScript-based (Jamstack) site builders.
    
-   Astro and Eleventy both allow you to use a [headless CMS, APIs or Markdown files for data](/en/guides/data-fetching/). You can continue to use your preferred content authoring system, and will be able to keep your existing content.
    

## Key Differences between Eleventy (11ty) and Astro

When you rebuild your Eleventy (11ty) site in Astro, you will notice some important differences:

-   Eleventy supports a variety of templating languages. Astro supports [including components from several popular JS Frameworks (e.g. React, Svelte, Vue, Solid)](/en/guides/framework-components/), but uses [Astro layouts, pages and components](/en/basics/astro-components/) for most page templating.
    
-   Astro uses a [`src/` directory](/en/basics/project-structure/#src) for all files, including site metadata, that are available for querying and processing during site build. Within this is a [special `src/pages/` folder for file-based routing](/en/basics/astro-pages/).
    
-   Astro uses a [`public/` folder for static assets](/en/basics/project-structure/#public) that do not need to be processed nor transformed during the build.
    
-   In Eleventy, bundling CSS, JavaScript, and other assets needs to be configured manually. [Astro handles this for you out-of-the-box](/en/concepts/why-astro/#easy-to-use).
    

## Switch from Eleventy to Astro

To convert an Eleventy blog to Astro, start with our blog theme starter template, or explore more community blog themes in our [theme showcase](https://astro.build/themes/).

You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#install-from-the-cli-wizard).

\`\`\`shell npm create astro@latest -- --template blog \`\`\` \`\`\`shell pnpm create astro@latest --template blog \`\`\` \`\`\`shell yarn create astro --template blog \`\`\`

Bring your existing Markdown (or MDX, with our optional integration) files as content to [create Markdown or MDX pages](/en/guides/markdown-content/).

Your Eleventy project allowed you to use a variety of templating languages to build your site. In an Astro project, your page templating will mostly be achieved with Astro components, which can be used as UI elements, layouts and even full pages. You may want to explore [Astro's component syntax](/en/basics/astro-components/) to see how to template in Astro using components.

To convert other types of sites, such as a portfolio or documentation site, see more official starter templates on [astro.new](https://astro.new). You'll find a link to each project's GitHub repository, as well as one-click links to open a working project in StackBlitz and CodeSandbox online development environments.

## Community Resources

:::note\[Have a resource to share?\] If you found (or made!) a helpful video or blog post about converting an Eleventy site to Astro, [add it to this list](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/migrate-to-astro/from-eleventy.mdx)! :::

## [Migrating from Gatsby](https://docharvest.github.io/docs/astro/guides/migrate-to-astro/from-gatsby/)



## [Migrating from GitBook](https://docharvest.github.io/docs/astro/guides/migrate-to-astro/from-gitbook/)

Contents

astro

Migrating from GitBook

Astro

Migrating from GitBook

import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'

[GitBook](https://gitbook.com) is a web-based platform for creating and publishing documentation and books in a collaborative manner, with version control integration and customizable features.

## Key Similarities between GitBook and Astro

GitBook and Astro share some similarities that will help you migrate your project:

-   Both Astro and GitBook support [Markdown](/en/guides/markdown-content/). You can migrate all your existing documentation utilizing GitBook's Git Sync feature.
    
-   Both Astro and GitBook use some form of [file-based routing](/en/guides/routing/). Using Astro's file structure for your existing content and when adding new pages should feel familiar.
    

## Key Differences between GitBook and Astro

When you migrate your GitBook docs to Astro, you will notice some important differences:

-   A GitBook site is edited using an online dashboard. In Astro, you will use a [code editor](/en/editor-setup/) and development environment to maintain your site. You can develop locally on your machine, or choose a cloud editor/development environment like StackBlitz or CodeSandbox.
    
-   GitBook stores your content in a database. In Astro, you will have individual files (typically Markdown or MDX) in your [project directory](/en/basics/project-structure/) for each page's content. Or, you can choose to use a [CMS for your content](/en/guides/cms/) and use Astro to fetch and present the data.
    
-   GitBook uses a custom syntax on top of Markdown for content. Astro supports Markdoc via the optional [Markdoc integration](/en/guides/integrations-guide/markdoc/), which features a similar syntax to the one you would use in GitBook.
    

## Switch from GitBook to Astro

To convert a GitBook documentation site to Astro, start with our official [Starlight docs theme starter template](https://starlight.astro.build), or explore more community docs themes in our [theme showcase](https://astro.build/themes?search=&categories%5B%5D=docs).

You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#install-from-the-cli-wizard).

\`\`\`shell npm create astro@latest -- --template starlight \`\`\` \`\`\`shell pnpm create astro@latest --template starlight \`\`\` \`\`\`shell yarn create astro --template starlight \`\`\`

Once you have a new Astro project, you can sync your existing GitBook content to your new Astro project. GitBook has a [Git Sync feature](https://docs.gitbook.com/product-tour/git-sync) that will automatically sync your GitBook content to a GitHub/GitLab repository.

To sync directly to the docs template's content collection, specify `src/content/docs/en` or `src/content/docs` as the project directory.

:::caution When enabling Git Sync be sure to specify "**GitBook to GitHub**" as the priority. This will ensure that your GitBook content is synced to your GitHub repository. Otherwise, you will overwrite your existing GitBook content. :::

After syncing the content, you will now have a copy of your GitBook content in your Astro repository. Disable git sync to prevent future syncing with GitBook.

Note that although you now have your content migrated to your Astro project, it will not be immediately usable. To use this content in your Astro site, you will need to spend some time manually changing GitBook's syntax into a format compatible with Astro. In particular:

-   Astro's [Markdoc integration](/en/guides/integrations-guide/markdoc/) requires that the file extension be `.mdoc`. This is to avoid conflicts with other Markdown extensions like `.mdx` and `.md`.
-   GitBook syntax differs from Markdoc where the `/` prefix denoting a closing tag is replaced with `end` for GitBook files. You will need to update this notation throughout your files.
-   Some features of GitBook rely on custom components. These components will not exist in Astro and must be created and added to your project through [Markdoc's config `tags` attribute](/en/guides/integrations-guide/markdoc/#use-astro-components-as-markdoc-tags) or removed from your files.

## Community Resources

:::note\[Have a resource to share?\] If you found (or made!) a helpful video or blog post about converting a GitBook site to Astro, [add it to this list](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/migrate-to-astro/from-gitbook.mdx)! :::

## [Migrating from Gridsome](https://docharvest.github.io/docs/astro/guides/migrate-to-astro/from-gridsome/)

Contents

astro

Migrating from Gridsome

Astro

Migrating from Gridsome

[Gridsome](https://gridsome.org) is an open-source static site generator built on Vue and GraphQL.

## Key Similarities between Gridsome and Astro

Gridsome and Astro share some similarities that will help you migrate your project:

-   Both Gridsome and Astro are modern JavaScript static-site generators with similar [project file structures](/en/basics/project-structure/#directories-and-files).
    
-   Both Gridsome and Astro use a `src/` folder for your project files and a [special `src/pages/` folder for file-based routing](/en/basics/astro-pages/). Creating and managing pages for your site should feel familiar.
    
-   Astro has [an official integration for using Vue components](/en/guides/integrations-guide/vue/) and supports [installing NPM packages](/en/guides/imports/#npm-packages), including several for Vue. You will be able to write Vue UI components, and may be able to keep some or all of your existing Gridsome Vue components and dependencies.
    
-   Astro and Gridsome both allow you to use a [headless CMS, APIs or Markdown files for data](/en/guides/data-fetching/). You can continue to use your preferred content authoring system, and will be able to keep your existing content.
    

## Key Differences between Gridsome and Astro

When you rebuild your Gridsome site in Astro, you will notice some important differences:

-   Gridsome is a Vue-based single-page application (SPA). Astro sites are multi-page apps built using [`.astro` components](/en/basics/astro-components/), but can also support [React, Preact, Vue.js, Svelte, SolidJS, AlpineJS](/en/guides/framework-components/) and raw HTML templating.
    
-   As an SPA, Gridsome uses `vue-router` for SPA routing, and `vue-meta` for managing `<head>`. In Astro, you will create separate HTML pages and control your page `<head>` directly, or in a [layout component](/en/basics/layouts/).
    
-   [Local file data](/en/guides/imports/): Gridsome uses GraphQL to retrieve data from your project files. Astro uses ESM imports and [`import.meta.glob()`](/en/guides/imports/#importmetaglob) to import data from local project files. Remote resources can be loaded using the standard `fetch()` API. GraphQL may be optionally added to your project, but is not included by default.
    

## Switch from Gridsome to Astro

To convert a Gridsome blog to Astro, start with our blog theme starter template, or explore more community blog themes in our [theme showcase](https://astro.build/themes/).

You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#install-from-the-cli-wizard).

\`\`\`shell npm create astro@latest -- --template blog \`\`\` \`\`\`shell pnpm create astro@latest --template blog \`\`\` \`\`\`shell yarn create astro --template blog \`\`\`

Bring your existing Markdown (or MDX, with our optional integration) files as content to [create Markdown or MDX pages](/en/guides/markdown-content/).

Since Gridsome's project structure is similar to Astro's, you may be able to copy several existing files from your project into the same location in your new Astro project. However, the two project structures are not identical. You may want to examine [Astro's project structure](/en/basics/project-structure/) to see what the differences are.

Since Astro queries and imports your local files differently than Gridsome, you may want to read about how to load files using [`import.meta.glob()`](/en/guides/imports/#importmetaglob) to understand how to work with your local files.

To convert other types of sites, such as a portfolio or documentation site, see more official starter templates on [astro.new](https://astro.new). You'll find a link to each project's GitHub repository, as well as one-click links to open a working project in StackBlitz and CodeSandbox online development environments.

## Community Resources

:::note\[Have a resource to share?\] If you found (or made!) a helpful video or blog post about converting a Gridsome site to Astro, [add it to this list](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/migrate-to-astro/from-gridsome.mdx)! :::

## [Migrating from Hugo](https://docharvest.github.io/docs/astro/guides/migrate-to-astro/from-hugo/)

Contents

astro

Migrating from Hugo

Astro

Migrating from Hugo

[Hugo](https://gohugo.io) is an open-source static site generator built on Go.

## Key Similarities between Hugo and Astro

Hugo and Astro share some similarities that will help you migrate your project:

-   Hugo and Astro are both modern static-site generators, ideally suited to [content-driven websites](/en/concepts/why-astro/#content-driven) like blogs.
    
-   Hugo and Astro both allow you to [author your content in Markdown](/en/guides/markdown-content/). However, Hugo includes several special frontmatter properties and allows you to write frontmatter in YAML, TOML or JSON. Even though many of your existing Hugo frontmatter properties will not be "special" in Astro, you can continue to use your existing Markdown files and YAML (or TOML) frontmatter values.
    
-   Hugo and Astro both allow you to enhance your site with a variety of [integrations and external packages](https://astro.build/integrations/).
    

## Key Differences between Hugo and Astro

When you rebuild your Hugo site in Astro, you will notice some important differences:

-   Hugo uses Go Templating for page templating. [Astro syntax](/en/basics/astro-components/) is a JSX-like superset of HTML.
    
-   Astro does not use shortcodes for dynamic content in standard Markdown files, but [Astro's MDX integration](/en/guides/integrations-guide/mdx/) does allow you to use JSX and import components in MDX files.
    
-   While Hugo can use "partials" for reusable layout elements, [Astro is entirely component-based](/en/basics/astro-components/). Any `.astro` file can be a component, a layout or an entire page, and can import and render any other Astro components. Astro components can also include [other UI framework components (e.g. React, Svelte, Vue, Solid)](/en/guides/framework-components/) as well as content or metadata from [other files in your project](/en/guides/imports/), such as Markdown or MDX.
    

## Switch from Hugo to Astro

To convert a Hugo blog to Astro, start with our blog theme starter template, or explore more community blog themes in our [theme showcase](https://astro.build/themes/).

You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#install-from-the-cli-wizard).

\`\`\`shell npm create astro@latest -- --template blog \`\`\` \`\`\`shell pnpm create astro@latest --template blog \`\`\` \`\`\`shell yarn create astro --template blog \`\`\`

Bring your existing Markdown (or MDX, with our optional integration) files as content to [create Markdown or MDX pages](/en/guides/markdown-content/). Astro allows YAML or TOML frontmatter in these files, so if you are using JSON frontmatter, you will need to convert it.

To continue to use dynamic content such as variables, expressions or UI components within your Markdown content, add Astro's optional MDX integration and convert your existing Markdown files to [MDX pages](/en/guides/markdown-content/). MDX supports YAML and TOML frontmatter, so you can keep your existing frontmatter properties. But, you must replace any shortcode syntax with [MDX's own syntax](https://mdxjs.com/docs/what-is-mdx/#mdx-syntax), which allows JSX expressions and/or component imports.

To convert other types of sites, such as a portfolio or documentation site, see more official starter templates on [astro.new](https://astro.new). You'll find a link to each project's GitHub repository, as well as one-click links to open a working project in StackBlitz and CodeSandbox online development environments.

## Community Resources

:::note\[Have a resource to share?\] If you found (or made!) a helpful video or blog post about converting a Hugo site to Astro, [add it to this list](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/migrate-to-astro/from-hugo.mdx)! :::

## [Migrating from Jekyll](https://docharvest.github.io/docs/astro/guides/migrate-to-astro/from-jekyll/)

Contents

astro

Migrating from Jekyll

Astro

Migrating from Jekyll

[Jekyll](https://jekyllrb.com) is a static site generator built on Ruby.

## Key Similarities between Jekyll and Astro

Jekyll and Astro share some similarities that will help you migrate your project:

-   Both Jekyll and Astro are static-site generators, commonly used to create blogs.
    
-   Both Jekyll and Astro allow you to write your content in Markdown and HTML. Jekyll and Astro both provide some special frontmatter YAML properties for page layout and unpublished draft posts. You can continue to use your existing Markdown files in Astro.
    
-   Both Jekyll and Astro use [file-based routing](/en/guides/routing/) for creating pages from your blog posts. Astro provides a [special `src/pages/` directory for all pages and posts](/en/basics/project-structure/#srcpages). Jekyll uses a similar special folder called `_posts/` for your Markdown blog posts, however your site pages can exist elsewhere. Creating new blog posts should feel familiar.
    

## Key Differences between Jekyll and Astro

When you rebuild your Jekyll site in Astro, you will notice some important differences:

-   As Jekyll is primarily a blogging platform, several blog features are built-in that you may have to build yourself in Astro. Or, choose a [blog starter template theme](https://astro.build/themes?search=&categories%5B%5D=blog) that includes these features. For example, Jekyll has built-in support for tags and categories which you will find in several Astro blog themes, but is not included in a minimal Astro project.
    
-   Jekyll uses Liquid templates for reusable layout elements and templating. Astro uses JSX-like [`.astro` files for templating and components](/en/basics/astro-components/). Any `.astro` file can be a component, a layout or an entire page, and can import and render any other Astro components. You can also build using [other UI framework components (e.g. React, Svelte, Vue, Solid)](/en/guides/framework-components/) as well as content or metadata from [other files in your project](/en/guides/imports/), such as Markdown or MDX.
    

## Switch from Jekyll to Astro

To convert a Jekyll blog to Astro, start with our blog theme starter template, or explore more community blog themes in our [theme showcase](https://astro.build/themes/).

You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#install-from-the-cli-wizard).

\`\`\`shell npm create astro@latest -- --template blog \`\`\` \`\`\`shell pnpm create astro@latest --template blog \`\`\` \`\`\`shell yarn create astro --template blog \`\`\`

Bring your existing Markdown files as content to [create Markdown pages](/en/guides/markdown-content/), using an [Astro Markdown layout](/en/basics/layouts/#markdown-layouts) instead of a Liquid template.

Much of your existing HTML page content can be converted into [Astro pages](/en/basics/astro-pages/), and you will additionally be able to [use variables, JSX-like expressions and component imports directly in your HTML templating](/en/reference/astro-syntax/#jsx-like-expressions).

Astro does not have a `permalink` property that accepts placeholders. You may need to read more about [Astro's page routing](/en/guides/routing/) if you want to keep your existing URL structure. Or, consider [setting redirects at a host like Netlify](https://docs.netlify.com/routing/redirects/).

To convert other types of sites, such as a portfolio or documentation site, see more official starter templates on [astro.new](https://astro.new). You'll find a link to each project's GitHub repository, as well as one-click links to open a working project in StackBlitz and CodeSandbox online development environments.

## Community Resources

:::note\[Have a resource to share?\] If you found (or made!) a helpful video or blog post about converting a Jekyll site to Astro, [add it to this list](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/migrate-to-astro/from-jekyll.mdx)! :::

## [Migrating from Next.js](https://docharvest.github.io/docs/astro/guides/migrate-to-astro/from-nextjs/)



## [Migrating from NuxtJS](https://docharvest.github.io/docs/astro/guides/migrate-to-astro/from-nuxtjs/)



## [Migrating from Pelican](https://docharvest.github.io/docs/astro/guides/migrate-to-astro/from-pelican/)

Contents

astro

Migrating from Pelican

Astro

Migrating from Pelican

import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'

[Pelican](https://getpelican.com) is an open-source static site generator built on Python.

## Key Similarities between Pelican and Astro

Pelican and Astro share some similarities that will help you migrate your project:

-   Pelican and Astro are both static-site generators, ideally suited to [content-driven websites](/en/concepts/why-astro/#content-driven) like blogs.
    
-   Pelican and Astro both have built-in support for [writing in Markdown](/en/guides/markdown-content/), including frontmatter YAML properties for page metadata. However, Astro has very few reserved frontmatter properties compared to Pelican. Even though many of your existing Pelican frontmatter properties will not be "special" in Astro, you can continue to use your existing Markdown files and frontmatter values.
    

## Key Differences between Pelican and Astro

When you rebuild your Pelican site in Astro, you will notice some important differences:

-   Pelican supports writing content in Markdown and reStructured Text (`.rst`). Astro supports [creating pages from Markdown and MDX](/en/guides/markdown-content/) files, but does not support reStructured Text.
    
-   Pelican uses HTML files and Jinja syntax for templating. [Astro syntax](/en/basics/astro-components/) is a JSX-like superset of HTML. All valid HTML is valid `.astro` syntax.
    
-   Pelican was designed to build content-rich websites like blogs and has some built-in, blog features that you would have to build yourself in Astro. Instead, Astro offers some of these features included in an [official blog theme](https://github.com/withastro/astro/tree/latest/examples/blog).
    

## Switch from Pelican to Astro

To convert a Pelican documentation site to Astro, start with our official [Starlight docs theme starter template](https://starlight.astro.build), or explore more community themes in our [theme showcase](https://astro.build/themes/).

You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#install-from-the-cli-wizard).

\`\`\`shell npm create astro@latest -- --template starlight \`\`\` \`\`\`shell pnpm create astro@latest --template starlight \`\`\` \`\`\`shell yarn create astro --template starlight \`\`\`

Bring your existing Markdown content files to [create Markdown pages](/en/guides/markdown-content/). You can still take advantage of [file-based routing](/en/guides/routing/) by copying these documents from Pelican's `content/` folder into `src/pages/` in Astro. You may wish to read about [Astro's project structure](/en/basics/project-structure/) to learn where files should be located.

Pelican may have handled much of your site layout and metadata for you. You may wish to read about [building Astro Layouts as Markdown page wrappers](/en/basics/layouts/#markdown-layouts) to see how to manage templating yourself in Astro, including your page `<head>`.

Like Pelican, Astro has many plugins that extend its functionality. Explore the [official list of integrations](/en/guides/integrations/) for adding features such as MDX support, and find hundreds more of community-maintained integrations in the [Astro Integrations Directory](https://astro.build/integrations/). You can even use the [Astro Integration API](/en/reference/integrations-reference/) to build your own custom integration to extend your project's features.

To convert other types of sites, such as a portfolio or a blog, see more official starter templates on [astro.new](https://astro.new). You'll find a link to each project's GitHub repository, as well as one-click links to open a working project in StackBlitz and CodeSandbox online development environments.

## Community Resources

:::note\[Have a resource to share?\] If you found (or made!) a helpful video or blog post about converting a Pelican site to Astro, [add it to this list](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/migrate-to-astro/from-pelican.mdx)! :::

## [Migrating from SvelteKit](https://docharvest.github.io/docs/astro/guides/migrate-to-astro/from-sveltekit/)

Contents

astro

Migrating from SvelteKit

Astro

Migrating from SvelteKit

[SvelteKit](https://kit.svelte.dev) is a framework for building web applications on top of Svelte.

## Key Similarities between SvelteKit and Astro

SvelteKit and Astro share some similarities that will help you migrate your project:

-   Both SvelteKit and Astro are modern JavaScript static-site generators and server-side rendering frameworks.
    
-   Both SvelteKit and Astro use a [`src/` folder for your project files](/en/basics/project-structure/#src) and a [special folder for file-based routing](/en/basics/astro-pages/). Creating and managing pages for your site should feel familiar.
    
-   Astro has [an official integration for using Svelte components](/en/guides/integrations-guide/svelte/) and supports [installing NPM packages](/en/guides/imports/#npm-packages), including several for Svelte. You will be able to write Svelte UI components, and may be able to keep some or all of your existing components and dependencies.
    
-   Astro and SvelteKit both allow you to use a [headless CMS, APIs or Markdown files for data](/en/guides/data-fetching/). You can continue to use your preferred content authoring system, and will be able to keep your existing content.
    

## Key Differences between SvelteKit and Astro

When you rebuild your SvelteKit site in Astro, you will notice some important differences:

-   Astro sites are multi-page apps, whereas SvelteKit defaults to SPAs (single-page applications) with server-side rendering, but can also create MPAs, traditional SPAs, or you can mix and match these techniques within an app.
    
-   [Components](/en/basics/astro-components/): SvelteKit uses [Svelte](https://svelte.dev). Astro pages are built using [`.astro` components](/en/basics/astro-components/), but can also support [React, Preact, Vue.js, Svelte, SolidJS, AlpineJS](/en/guides/framework-components/) and raw HTML templating.
    
-   [content-driven](/en/concepts/why-astro/#content-driven): Astro was designed to showcase your content and to allow you to opt-in to interactivity only as needed. An existing SvelteKit app might be built for high client-side interactivity. Astro has built-in capabilities for working with your content, such as page generation, but may require advanced Astro techniques to include items that are more challenging to replicate using `.astro` components, such as dashboards.
    
-   [Markdown-ready](/en/guides/markdown-content/): Astro includes built-in Markdown support, and includes a [special frontmatter YAML `layout` property](/en/basics/layouts/#markdown-layouts) used per-file for page templating. If you are converting a SvelteKit Markdown-based blog, you will not have to install a separate Markdown integration and you will not set a layout via a configuration file. You can bring your existing Markdown files, but you may need to reorganize as Astro's file-based routing does not require a folder for each page route.
    

## Switch from SvelteKit to Astro

To convert a SvelteKit blog to Astro, start with our blog theme starter template, or explore more community blog themes in our [theme showcase](https://astro.build/themes/).

You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#install-from-the-cli-wizard).

\`\`\`shell npm create astro@latest -- --template blog \`\`\` \`\`\`shell pnpm create astro@latest --template blog \`\`\` \`\`\`shell yarn create astro --template blog \`\`\`

Bring your existing Markdown (or MDX, with our optional integration) files as content to [create Markdown or MDX pages](/en/guides/markdown-content/).

While file-based routing and layout components are similar in Astro, you may wish to read about [Astro's project structure](/en/basics/project-structure/) to learn where files should be located.

To convert other types of sites, such as a portfolio or documentation site, see more official starter templates on [astro.new](https://astro.new). You'll find a link to each project's GitHub repository, as well as one-click links to open a working project in StackBlitz and CodeSandbox online development environments.

## Community Resources

:::note\[Have a resource to share?\] If you found (or made!) a helpful video or blog post about converting a SvelteKit site to Astro, [add it to this list](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/migrate-to-astro/from-sveltekit.mdx)! :::

## [Migrating from VuePress](https://docharvest.github.io/docs/astro/guides/migrate-to-astro/from-vuepress/)

Contents

astro

Migrating from VuePress

Astro

Migrating from VuePress

import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'

[VuePress](https://vuePress.vuejs.org) is an open-source static site generator built on Vue.

## Key Similarities between VuePress and Astro

VuePress and Astro share some similarities that will help you migrate your project:

-   Both VuePress and Astro are modern JavaScript static-site generators with similar project file structures. Both use a [special `src/pages/` folder for file-based routing](/en/basics/astro-pages/). Creating and managing pages for your site should feel familiar.
    
-   Astro and VuePress are both designed for [content-driven websites](/en/concepts/why-astro/#content-driven), with excellent built-in support for Markdown files. Writing in Markdown will feel familiar, and you will be able to keep your existing content.
    
-   Astro has [an official integration for using Vue components](/en/guides/integrations-guide/vue/) and supports [installing NPM packages](/en/guides/imports/#npm-packages), including several for Vue. You will be able to write Vue UI components, and may be able to keep some or all of your existing Vue components and dependencies.
    

## Key Differences between VuePress and Astro

When you rebuild your VuePress site in Astro, you will notice some important differences.

-   VuePress is a Vue-based single-page application (SPA). Astro sites are multi-page apps built using [`.astro` components](/en/basics/astro-components/), but can also support [React, Preact, Vue.js, Svelte, SolidJS, AlpineJS](/en/guides/framework-components/) and raw HTML templating.
    
-   [Layout templates](/en/basics/layouts/): VuePress sites are created using Markdown (`.md`) files for page content and HTML (`.html`) templates for layout. Astro is component-based, and uses Astro components, which include HTML templating for pages, layouts and individual UI elements. Astro can also create [pages from `.md` and `.mdx` files](/en/guides/markdown-content/), using an Astro layout component for wrapping Markdown content in a page template.
    
-   VuePress was designed to build content-heavy, Markdown-centric sites and has some built-in, documentation-specific website features that you would have to build yourself in Astro. Instead, Astro offers some documentation-specific features through an [official docs theme](https://starlight.astro.build). This website was the inspiration for that template! You can also find more [community docs themes](https://astro.build/themes?search=&categories%5B%5D=docs) with built-in features in our Themes Showcase.
    

## Switch from VuePress to Astro

To convert a VuePress documentation site to Astro, start with our official [Starlight docs theme starter template](https://starlight.astro.build), or explore more community docs themes in our [theme showcase](https://astro.build/themes?search=&categories%5B%5D=docs).

You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#install-from-the-cli-wizard).

\`\`\`shell npm create astro@latest -- --template starlight \`\`\` \`\`\`shell pnpm create astro@latest --template starlight \`\`\` \`\`\`shell yarn create astro --template starlight \`\`\`

Bring your existing Markdown content files to [create Markdown pages](/en/guides/markdown-content/). You can still take advantage of [file-based routing](/en/guides/routing/) by moving these documents from `docs` in VuePress to `src/pages/` in Astro. Create folders with names that correspond to your existing VuePress project, and you should be able to keep your existing URLs.

VuePress, or any theme you installed, probably handled much of your site layout and metadata for you. You may wish to read about [building Astro Layouts as Markdown page wrappers](/en/basics/layouts/#markdown-layouts) to see how to manage templating yourself in Astro, including your page `<head>`.

You can find Astro's docs starter, and other templates, on [astro.new](https://astro.new). You'll find a link to each project's GitHub repository, as well as one-click links to open a working project in StackBlitz and CodeSandbox online development environments.

## Community Resources

:::note\[Have a resource to share?\] If you found (or made!) a helpful video or blog post about converting a VuePress site to Astro, [add it to this list](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/migrate-to-astro/from-vuepress.mdx)! :::

## [Migrating from WordPress](https://docharvest.github.io/docs/astro/guides/migrate-to-astro/from-wordpress/)

Contents

astro

Migrating from WordPress

Astro

Migrating from WordPress

[WordPress](https://wordpress.org) is an open-source, personal publishing system built on PHP and MySQL.

:::tip You can [use WordPress as a headless CMS for your Astro project](/en/guides/cms/wordpress/). Follow our guide to use your existing WordPress content in a new Astro project. :::

## Key Similarities between WordPress and Astro

WordPress and Astro share some similarities that will help you migrate your project:

-   Both WordPress and Astro are ideal for [content-driven websites](/en/concepts/why-astro/#content-driven) like blogs and support writing your content in Markdown (requires a plugin in WordPress). Although the process for adding new content is different, [writing in Markdown files](/en/guides/markdown-content/) for your Astro blog should feel familiar if you have used Markdown syntax in your WordPress editor.
    
-   Both WordPress and Astro encourage you to [think about the design of your site in "blocks"](/en/concepts/islands/) (components). In Astro you will probably [write more of your own code to create these blocks](/en/basics/astro-components/) rather than rely on pre-built plugins. But thinking about the individual pieces of your site and how they are presented on the page should feel familiar.
    

## Key Differences between WordPress and Astro

When you rebuild your WordPress site in Astro, you will notice some important differences:

-   A WordPress site is edited using an online dashboard. In Astro, you will use a [code editor](/en/editor-setup/) and development environment to maintain your site. You can develop locally on your machine, or choose a cloud editor/development environment like StackBlitz or CodeSandbox.
    
-   WordPress has an extensive plugin and theme market. In Astro, you will find some themes and [integrations](https://astro.build/integrations/) available, but you may now have to build many of your existing features yourself instead of looking for third-party solutions. Or, you can choose to start with an [Astro theme](https://astro.build/themes) with built-in features!
    
-   WordPress stores your content in a database. In Astro, you will have individual files (typically Markdown or MDX) in your [project directory](/en/basics/project-structure/) for each page's content. Or, you can choose to use a [CMS for your content](/en/guides/cms/), even your existing WordPress site, and use Astro to fetch and present the data.
    

## Switch from WordPress to Astro

To convert a WordPress blog to Astro, start with our blog theme starter template, or explore more community blog themes in our [theme showcase](https://astro.build/themes).

You can pass a `--template` argument to the `create astro` command to start a new Astro project with one of our official starters. Or, you can [start a new project from any existing Astro repository on GitHub](/en/install-and-setup/#install-from-the-cli-wizard).

\`\`\`shell npm create astro@latest -- --template blog \`\`\` \`\`\`shell pnpm create astro@latest --template blog \`\`\` \`\`\`shell yarn create astro --template blog \`\`\`

You can continue to [use your existing WordPress blog as your CMS for Astro](/en/guides/cms/wordpress/), which means you will keep using your WordPress dashboard for writing your posts. Your content will be managed at WordPress, but all other aspects of your Astro site will be built in your code editing environment, and you will [deploy your Astro site](/en/guides/deploy/) separately from your WordPress site. (Be sure to update your domain at your host to keep the same website URL!)

You may wish to take [Astro's Build a Blog Tutorial](/en/tutorial/0-introduction/) if you are new to working in a code editor and using GitHub to store and deploy your site. It will walk you through all the accounts and setup you need! You will also learn how to [build Astro components yourself](/en/tutorial/3-components/), and it will show you how to [add blog posts directly in Astro](/en/tutorial/2-pages/2/) if you choose not to use WordPress to write your content.

If you want to move all of your existing post content to Astro, you may find this [tool for exporting Markdown from WordPress helpful](https://github.com/lonekorean/wordpress-export-to-markdown). You may need to make some adjustments to the result if you have to [convert a large or complicated WordPress site to Markdown](https://swizec.com/blog/how-to-export-a-large-wordpress-site-to-markdown/).

To convert other types of sites, such as a portfolio or documentation site, see more official starter templates on [astro.new](https://astro.new). You'll find a link to each project's GitHub repository, as well as one-click links to open a working project in StackBlitz and CodeSandbox online development environments.

## Community Resources

:::note\[Have a resource to share?\] If you found (or made!) a helpful video or blog post about converting a WordPress site to Astro, [add it to this list](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/migrate-to-astro/from-wordpress.mdx)! :::

## [On-demand rendering](https://docharvest.github.io/docs/astro/guides/on-demand-rendering/)

Contents

astro

On-demand rendering

Astro

On-demand rendering

Your Astro project code must be **rendered** to HTML in order to be displayed on the web.

By default, Astro pages, routes, and API endpoints will be pre-rendered at build time as static pages. However, you can choose to render some or all of your routes on demand by a server when a route is requested.

On-demand rendered pages and routes are generated per visit, and can be customized for each viewer. For example, a page rendered on demand can show a logged-in user their account information or display freshly updated data without requiring a full-site rebuild.

On-demand rendering on the server at request time is also known as **server-side rendering (SSR)**.

## Server adapters

To render any page on demand, you need to add an **adapter**. Each adapter allows Astro to output a script that runs your project on a specific **runtime**: the environment that runs code on the server to generate pages when they are requested (e.g. Netlify, Cloudflare).

You may also wish to add an adapter even if your site is entirely static and you are not rendering any pages on demand. For example, the [Netlify adapter](/en/guides/integrations-guide/netlify/) enables Netlify's Image CDN, and [server islands](/en/guides/server-islands/) require an adapter installed to use `server:defer` on a component.

Astro maintains official adapters for [Node.js](https://nodejs.org/), [Netlify](https://www.netlify.com/), [Vercel](https://vercel.com/), and [Cloudflare](https://www.cloudflare.com/). You can find both [official and community adapters in our integrations directory](https://astro.build/integrations/?search=&categories%5B%5D=adapters). Choose the one that corresponds to your [deployment environment](/en/guides/deploy/).

### Add an Adapter

You can add any of the [official adapter integrations maintained by Astro](/en/guides/integrations/#official-integrations) with the following `astro add` command. This will install the adapter and make the appropriate changes to your `astro.config.mjs` file in one step.

For example, to install the Netlify adapter, run:

\`\`\`shell npx astro add netlify \`\`\` \`\`\`shell pnpm astro add netlify \`\`\` \`\`\`shell yarn astro add netlify \`\`\`

You can also [add an adapter manually by installing the NPM package](/en/guides/integrations/#installing-an-npm-package) (e.g. `@astrojs/netlify`) and updating `astro.config.mjs` yourself.

Note that different adapters may have different configuration settings. Read each adapter's documentation, and apply any necessary config options to your chosen adapter in `astro.config.mjs`

## Enabling on-demand rendering

**By default, your entire Astro site will be prerendered**, and static HTML pages will be sent to the browser. However, you may opt out of prerendering on any routes that require server rendering, for example, a page that checks for cookies and displays personalized content.

First, [add an adapter integration](#add-an-adapter) for your server runtime to enable on-demand server rendering in your Astro project.

Then, add `export const prerender = false` at the top of the individual page or endpoint you want to render on demand. The rest of your site will remain a static site:

```
---

  return new Response(
    JSON.stringify({
      number,
      message: `Here's a random number: ${number}`,
    }),
  );
}
```

### `'server'` mode

For a **highly dynamic app**, after adding an adapter, you can [set your build output configuration to `output: 'server'`](/en/reference/configuration-reference/#output) to **server-render all your pages by default**. This is the equivalent of opting out of prerendering on every page.

Then, if needed, you can choose to prerender any individual pages that do not require a server to execute, such as a privacy policy or about page.

```
---

}
```

:::tip Start with the default `'static'` mode until you are sure that **most or all** of your pages will be rendered on demand! This ensures that your site is as performant as possible, not relying on a server function to render static content.

The `'server'` output mode does not bring any additional functionality. It only switches the default rendering behavior. :::

See more about the [`output` setting](/en/reference/configuration-reference/#output) in the configuration reference.

## On-demand rendering features

### HTML streaming

With HTML streaming, a document is broken up into chunks, sent over the network in order, and rendered on the page in that order. Astro uses HTML streaming in on-demand rendering to send each component to the browser as it renders them. This makes sure the user sees your HTML as fast as possible, although network conditions can cause large documents to be downloaded slowly, and waiting for data fetches can block page rendering.

<RecipeLinks slugs={\["en/recipes/streaming-improve-page-performance"\]}/>

:::caution Features that modify the [Response headers](https://developer.mozilla.org/en-US/docs/Glossary/Response_header) are only available at the **page level**. (You can't use them inside of components, including layout components.) By the time Astro runs your component code, it has already sent the Response headers and they cannot be modified.

:::

### Cookies

A page or API endpoint rendered on demand can check, set, get, and delete cookies.

The example below updates the value of a cookie for a page view counter:

```
---

// No product found
if (!product) {
  Astro.response.status = 404;
  Astro.response.statusText = 'Not found';
}
---
<html>
  <!-- Page here... -->
</html>
```

#### `Astro.response.headers`

You can set headers using the `Astro.response.headers` object:

```
---

---
<html>
  <!-- Page here... -->
</html>
```

#### Return a `Response` object

You can also return a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) object directly from any page using on-demand rendering either manually or with [`Astro.redirect`](/en/reference/api-reference/#redirect).

The example below looks up an ID in the database on a dynamic page and either it returns a 404 if the product does not exist, or it redirects the user to another page if the product is no longer available, or it displays the product:

```
---

// No product found
if (!product) {
  return new Response(null, {
    status: 404,
    statusText: 'Not found'
  });
}

// The product is no longer available
if (!product.isAvailable) {
  return Astro.redirect("/products", 301);
}
---
<html>
  <!-- Page here... -->
</html>
```

### `Request`

`Astro.request` is a standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object. It can be used to get the `url`, `headers`, `method`, and even the body of the request.

You can access additional information from this object for pages that are not statically generated.

#### `Astro.request.headers`

The headers for the request are available on `Astro.request.headers`. This works like the browser's [`Request.headers`](https://developer.mozilla.org/en-US/docs/Web/API/Request/headers). It is a [Headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers) object where you can retrieve headers such as the cookie.

```
---

// ...
---
<html>
  <!-- Page here... -->
</html>
```

#### `Astro.request.method`

The HTTP method used in the request is available as `Astro.request.method`. This works like the browser's [`Request.method`](https://developer.mozilla.org/en-US/docs/Web/API/Request/method). It returns the string representation of the HTTP method used in the request.

```
---
export const prerender = false; // Not needed in 'server' mode

console.log(Astro.request.method) // GET (when navigated to in the browser)
---
```

See more details about [`Astro.request`](/en/reference/api-reference/#request) in the API reference.

### Server Endpoints

A server endpoint, also known as an **API route**, is a special function exported from a `.js` or `.ts` file within the `src/pages/` folder. A powerful feature of server-side rendering on demand, API routes are able to securely execute code on the server.

The function takes an [endpoint context](/en/reference/api-reference/) and returns a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response).

To learn more, see our [Endpoints Guide](/en/guides/endpoints/#server-endpoints-api-routes).

## [Prefetch](https://docharvest.github.io/docs/astro/guides/prefetch/)

Contents

astro

Prefetch

Astro

Prefetch

````

A prefetch script will be added to all pages of your site. You can then add the `data-astro-prefetch` attribute to any `<a />` links on your site to opt-in to prefetching. When you hover over the link, the script will fetch the page in the background.

```html
<a href="/about" data-astro-prefetch>
````

Note that prefetching only works for links within your site, and not external links.

## Prefetch configuration

The `prefetch` config also accepts an option object to further customize prefetching.

### Prefetch strategies

Astro supports 4 prefetch strategies for various use cases:

-   `hover` (default): Prefetch when you hover over or focus on the link.
-   `tap`: Prefetch just before you click on the link.
-   `viewport`: Prefetch as the links enter the viewport.
-   `load`: Prefetch all links on the page after the page is loaded.

You can specify a strategy for an individual link by passing it to the `data-astro-prefetch` attribute:

```
<a href="/about" data-astro-prefetch="tap">About</a>
```

Each strategy is fine-tuned to only prefetch when needed and save your users' bandwidth. For example:

-   If a visitor is using [data saver mode](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/saveData) or has a [slow connection](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/effectiveType), prefetch will fallback to the `tap` strategy.
-   Quickly hovering or scrolling over links will not prefetch them.

### Default prefetch strategy

The default prefetch strategy when adding the `data-astro-prefetch` attribute is `hover`. To change it, you can configure [`prefetch.defaultStrategy`](/en/reference/configuration-reference/#prefetchdefaultstrategy) in your `astro.config.mjs` file:

### Prefetch all links by default

If you want to prefetch all links, including those without the `data-astro-prefetch` attribute, you can set [`prefetch.prefetchAll`](/en/reference/configuration-reference/#prefetchprefetchall) to `true`:

You can then opt-out of prefetching for individual links by setting `data-astro-prefetch="false"`:

```
<a href="/about" data-astro-prefetch="false">About</a>
```

The default prefetch strategy for all links can be changed with `prefetch.defaultStrategy` as shown in the [Default prefetch strategy section](#default-prefetch-strategy).

## Prefetch programmatically

As some navigation might not always appear as `<a />` links, you can also prefetch programmatically with the `prefetch()` API from the `astro:prefetch` module:

```
<button id="btn">Click me</button>

<script>
  import { prefetch } from 'astro:prefetch';

  const btn = document.getElementById('btn');
  btn?.addEventListener('click', () => {
    prefetch('/about');
  });
</script>
```

The `prefetch()` API includes the same [data saver mode](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/saveData) and [slow connection](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/effectiveType) detection so that it only prefetches when needed.

To ignore slow connection detection, you can use the `ignoreSlowConnection` option:

```
// Prefetch even on data saver mode or slow connection
prefetch('/about', { ignoreSlowConnection: true });
```

### `eagerness`

\*\*Type:\*\* \`'immediate' | 'eager' | 'moderate' | 'conservative'\`  
\*\*Default:\*\* \`'immediate'\`  

With the experimental [`clientPrerender`](/en/reference/experimental-flags/client-prerender/) flag enabled, you can use the `eagerness` option on `prefetch()` to suggest to the browser how eagerly it should prefetch/prerender link targets.

This follows the same API described in the [Speculation Rules API](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/speculationrules#eagerness) and defaults to `immediate` (the most eager option). In decreasing order of eagerness, the other options are `eager`, `moderate`, and `conservative`.

The `eagerness` option allows you to balance the benefit of reduced wait times against bandwidth, memory, and CPU costs for your site visitors. Some browsers, such as Chrome, have [limits in place to guard against over-speculating](https://developer.chrome.com/blog/speculation-rules-improvements#chrome-limits) (prerendering/prefetching too many links).

```
---
---
<script>
// Control prefetching eagerness with `experimental.clientPrerender`

// This page is resource-intensive
prefetch('/data-heavy-dashboard', { eagerness: 'conservative' });

// This page is critical to the visitor's journey
prefetch('/getting-started'); // defaults to `{ eagerness: 'immediate' }`

// This page may not be visited
prefetch('/terms-of-service', { eagerness: 'moderate' });
</script>
```

To use `prefetch()` programmatically with large sets of links, you can set `eagerness: 'moderate'` to take advantage of [First In, First Out (FIFO)](https://en.wikipedia.org/wiki/FIFO_\(computing_and_electronics\)) strategies and browser heuristics to let the browser decide when to prerender/prefetch them and in what order:

```
<a class="link-moderate" href="/nice-link-1">A Nice Link 1</a>
<a class="link-moderate" href="/nice-link-2">A Nice Link 2</a>
<a class="link-moderate" href="/nice-link-3">A Nice Link 3</a>
<a class="link-moderate" href="/nice-link-4">A Nice Link 4</a>
...
<a class="link-moderate" href="/nice-link-20">A Nice Link 20</a>

<script>
  import { prefetch } from "astro:prefetch";

  const linkModerate = document.getElementsByClassName("link-moderate");
  for (const link of linkModerate) {
    const href = link.getAttribute("href");
    if (href) prefetch(href, { eagerness: "moderate" });
  }
</script>
```

Make sure to only import `prefetch()` in client-side scripts as it relies on browser APIs.

## Using with View Transitions

When you use [Astro’s `<ClientRouter />`](/en/guides/view-transitions/#enabling-view-transitions-spa-mode) on a page, prefetching will also be enabled by default. It sets a default configuration of `{ prefetchAll: true }` which enables [prefetching for all links](#prefetch-all-links-by-default) on the page.

You can customize the prefetch configuration in `astro.config.mjs` to override the default. For example:

## Browser support

Astro's prefetching uses [`<link rel="prefetch">`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/prefetch) if supported by the browser, and falls back to the [`fetch()` API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) otherwise.

The most common browsers support Astro's prefetching with subtle differences:

### Chrome

Chrome supports `<link rel="prefetch">`. Prefetching works as intended.

It also fully supports `<script type="speculationrules">` from the [Speculation Rules API](https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API), which can be used to further describe [prefetching strategies and rules](#eagerness), enhancing user experience for your Chrome users. You'll need to enable [`clientPrerender`](/en/reference/experimental-flags/client-prerender/) experiment to utilize this functionality with `prefetch()`

### Firefox

Firefox supports `<link rel="prefetch">` but may display errors or fail entirely:

-   Without an explicit cache header (e.g. [`Cache-Control`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) or [`Expires`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Expires)), prefetching will error with `NS_BINDING_ABORTED`.
-   Even in the event of an error, if the response has a proper [`ETag`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag) header, it will be re-used on navigation.
-   Otherwise, if it errors with no other cache headers, the prefetch will not work.

### Safari

Safari does not support `<link rel="prefetch">` and will fall back to the `fetch()` API which requires cache headers (e.g. [`Cache-Control`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control), [`Expires`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Expires), and [`ETag`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag)) to be set. Otherwise, the prefetch will not work.

**Edge case:** `ETag` headers do not work in private windows.

### Recommendations

To best support all browsers, make sure your pages have the proper cache headers.

For static or prerendered pages, the `ETag` header is often automatically set by the deployment platform and is expected to work out of the box.

For dynamic and server-side rendered pages, set the appropriate cache headers yourself based on the page content. Visit the [MDN documentation on HTTP caching](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching) for more information.

## Migrating from `@astrojs/prefetch`

The `@astrojs/prefetch` integration was deprecated in v3.5.0 and is no longer maintained. Use the following instructions to migrate to Astro's built-in prefetching which replaces this integration.

1\. Remove the \`@astrojs/prefetch\` integration and enable the \`prefetch\` config in \`astro.config.mjs\`:

````
```js title="astro.config.mjs" ins={6} del={2,5}
import { defineConfig } from 'astro/config';
import prefetch from '@astrojs/prefetch';

export default defineConfig({
  integrations: [prefetch()],
  prefetch: true
});
```
````

2.  Convert from `@astrojs/prefetch`'s configuration options:
    
    -   The deprecated integration used the `selector` config option to specify which links should be prefetched upon entering the viewport.
        
        Add `data-astro-prefetch="viewport"` to these individual links instead.
        
        ```
        <a href="/about" data-astro-prefetch="viewport">
        ```
        
    -   The deprecated integration used the `intentSelector` config option to specify which links should be prefetched when they were hovered over or focused.
        
        Add `data-astro-prefetch` or `data-astro-prefetch="hover"` to these individual links instead:
        
        ```
        <!-- You can omit the value if `defaultStrategy` is set to `hover` (default) -->
        <a href="/about" data-astro-prefetch>
        
        <!-- Otherwise, you can explicitly define the prefetch strategy -->
        <a href="/about" data-astro-prefetch="hover">
        ```
        
    -   The `throttles` option from `@astrojs/prefetch` is no longer needed as the new prefetch feature will automatically schedule and prefetch optimally.

## [Routing](https://docharvest.github.io/docs/astro/guides/routing/)

Contents

astro

Routing

Astro

Routing

}

## const { dog } = Astro.params;

Good dog, {dog}!

\`\`\`

This will generate three pages: `/dogs/clifford`, `/dogs/rover`, and `/dogs/spot`, each displaying the corresponding dog name.

The filename can include multiple parameters, which must all be included in the `params` objects in `getStaticPaths()`:

```
---

}

const { lang, version } = Astro.params;
---
```

This will generate `/en-v1/info` and `/fr-v2/info`.

Parameters can be included in separate parts of the path. For example, the file `src/pages/[lang]/[version]/info.astro` with the same `getStaticPaths()` above will generate the routes `/en/v1/info` and `/fr/v2/info`.

#### Decoding `params`

`params` returned by a `getStaticPaths()` function are not decoded. Use [`decodeURI()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURI) when you need to decode parameter values.

```
--- 

---
```

This will generate `/sequences/one/two/three`, `/sequences/four`, and `/sequences`. (Setting the rest parameter to `undefined` allows it to match the top level page.)

Rest parameters can be used with **other named parameters**. For example, GitHub's file viewer can be represented with the following dynamic route:

```
/[org]/[repo]/tree/[branch]/[...file]
```

In this example, a request for `/withastro/astro/tree/main/docs/public/favicon.svg` would be split into the following named parameters:

```
{
	org: "withastro",
	repo: "astro",
	branch: "main",
	file: "docs/public/favicon.svg"
}
```

#### Example: Dynamic pages at multiple levels

In the following example, a rest parameter (`[...slug]`) and the [`props`](/en/reference/routing-reference/#data-passing-with-props) feature of `getStaticPaths()` generate pages for slugs of different depths.

```
---

  return pages.map(({ slug, title, text }) => {
    return {
      params: { slug },
      props: { title, text },
    };
  });
}

const { title, text } = Astro.props;
---
<html>
  <head>
    <title>{title}</title>
  </head>
  <body>
    <h1>{title}</h1>
    <p>{text}</p>
  </body>
</html>
```

### On-demand dynamic routes

For [on-demand rendering](/en/guides/on-demand-rendering/) with an adapter, dynamic routes are defined the same way: include `[param]` or `[...path]` brackets in your file names to match arbitrary strings or paths. But because the routes are no longer built ahead of time, the page will be served to any matching route. Since these are not "static" routes, `getStaticPaths` should not be used.

For on-demand rendered routes, only one rest parameter using the spread notation may be used in the file name (e.g. `src/pages/[locale]/[...slug].astro` or `src/pages/[...locale]/[slug].astro`, but not `src/pages/[...locale]/[...slug].astro`).

```
---

---
<h1>{resource}: {id}</h1>
```

This page will be served for any value of `resource` and `id`: `resources/users/1`, `resources/colors/blue`, etc.

#### Modifying the `[...slug]` example for SSR

Because SSR pages can't use `getStaticPaths()`, they can't receive props. The [previous example](#example-dynamic-pages-at-multiple-levels) can be adapted for SSR mode by looking up the value of the `slug` param in an object. If the route is at the root ("/"), the `slug` param will be `undefined`. If the value doesn't exist in the object, we redirect to a 404 page.

```
---
const pages = [
	{
		slug: undefined,
		title: 'Astro Store',
		text: 'Welcome to the Astro store!',
	},
	{
		slug: 'products',
		title: 'Astro products',
		text: 'We have lots of products for you',
	},
	{
		slug: 'products/astro-handbook',
		title: 'The ultimate Astro handbook',
		text: 'If you want to learn Astro, you must read this book.',
	}
];

const { slug } = Astro.params;
const page = pages.find((page) => page.slug === slug);
if (!page) return Astro.redirect("/404");
const { title, text } = page;
---
<html>
  <head>
    <title>{title}</title>
  </head>
  <body>
    <h1>{title}</h1>
    <p>{text}</p>
  </body>
</html>
```

## Redirects

Sometimes you will need to redirect your readers to a new page, either permanently because your site structure has changed or in response to an action such as logging in to an authenticated route.

You can define rules to [redirect users to permanently-moved pages](#configured-redirects) in your Astro config. Or, [redirect users dynamically](#dynamic-redirects) as they use your site.

### Configured Redirects

You can specify a mapping of permanent redirects in your Astro config with the [`redirects`](/en/reference/configuration-reference/#redirects) value.

For internal redirects, this is a mapping of an old route path to the new route. As of Astro v5.2.0, it is also possible to redirect to external URLs that start with `http` or `https` and [can be parsed](https://developer.mozilla.org/en-US/docs/Web/API/URL/canParse_static):

These redirects follow [the same priority rules as file-based routes](#route-priority-order) and will always take lower precedence than an existing page file of the same name in your project. For example, `/old-page` will not redirect to `/new-page` if your project contains the file `src/pages/old-page.astro`.

Dynamic routes are allowed as long as both the new and old routes contain the same parameters, for example:

```
{
  "/blog/[...slug]": "/articles/[...slug]"
}
```

Using SSR or a static adapter, you can also provide an object as the value, allowing you to specify the `status` code in addition to the new `destination`:

When running `astro build`, Astro will output HTML files with the [meta refresh](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta#examples) tag by default. Supported adapters will instead write out the host's configuration file with the redirects.

The status code is `301` by default. If building to HTML files the status code is not used by the server.

### Dynamic redirects

On the `Astro` global, the `Astro.redirect` method allows you to redirect to another page dynamically. You might do this after checking if the user is logged in by getting their session from a cookie.

```
---

const cookie = Astro.request.headers.get("cookie");

// If the user is not logged in, redirect them to the login page
if (!isLoggedIn(cookie)) {
  return Astro.redirect("/login");
}
---
```

Because Astro uses [HTML streaming](/en/guides/on-demand-rendering/#html-streaming) in on-demand rendering, redirects must be done at the page level, not inside child components.

## Rewrites

A rewrite allows you to serve a different route without redirecting the browser to a different page. The browser will show the original address in the URL bar, but will instead display the content of the URL provided to [`Astro.rewrite()`](/en/reference/api-reference/#rewrite).

:::tip For content that has permanently moved, or to direct your user to a different page with a new URL (e.g. a user dashboard after logging in), use a [redirect](#redirects) instead. :::

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 different source files.

Rewrites are also useful for SEO purposes and user experience. They allow you to display content that otherwise would require redirecting your visitor to a different page or would return a 404 status. One common use of rewrites is to show the same localized content for different variants of a language.

The following example uses a rewrite to render the `/es/` version of a page when the `/es-CU/` (Cuban Spanish) URL path is visited. When a visitor navigates to the URL `/es-cu/articles/introduction`, Astro will render the content generated by the file `src/pages/es/articles/introduction.astro`.

```
---
return Astro.rewrite("/es/articles/introduction");
---
```

Use `context.rewrite()` in your endpoint files to reroute to a different page:

```

  }
}
```

If the URL passed to `Astro.rewrite()` emits a runtime error, Astro will show the overlay error in development and return a 500 status code in production. If the URL does not exist in your project, a 404 status code will be returned.

You can intentionally create a rewrite to render your `/404` page, for example to indicate that a product in your e-commerce shop is no longer available:

```
---
const { item } = Astro.params;

if (!itemExists(item)) {
  return Astro.rewrite("/404");
}
---
```

You can also conditionally rewrite based on an HTTP response status, for example to display a certain page on your site when visiting a URL that doesn't exist:

```

  if (response.status === 404) {
    return context.rewrite("/");
  }
  return response;
}
```

Before displaying the content from the specified rewrite path, the function `Astro.rewrite()` will trigger a new, complete rendering phase. This re-executes any middleware for the new route/request.

See the [`Astro.rewrite()` API reference](/en/reference/api-reference/#rewrite) for more information.

## Route Priority Order

It's possible for multiple defined routes to attempt to build the same URL path. For example, all of these routes could build `/posts/create`:

\- src/pages/ - \[...slug\].astro - posts/ - create.astro - \[page\].astro - \[pid\].ts - \[...slug\].astro

Astro needs to know which route should be used to build the page. To do so, it sorts them according to the following rules in order:

-   Astro [reserved routes](#reserved-routes)
-   Routes with more path segments will take precedence over less specific routes. In the example above, all routes under `/posts/` take precedence over `/[...slug].astro` at the root.
-   Static routes without path parameters will take precedence over dynamic routes. E.g. `/posts/create.astro` takes precedence over all the other routes in the example.
-   Dynamic routes using named parameters take precedence over rest parameters. E.g. `/posts/[page].astro` takes precedence over `/posts/[...slug].astro`.
-   Pre-rendered dynamic routes take precedence over server dynamic routes.
-   Endpoints take precedence over pages.
-   File-based routes take precedence over redirects.
-   If none of the rules above decide the order, routes are sorted alphabetically based on the default locale of your Node installation.

Given the example above, here are a few examples of how the rules will match a requested URL to the route used to build the HTML:

-   `pages/posts/create.astro` - Will build only `/posts/create`
-   `pages/posts/[pid].ts` - Will build `/posts/abc`, `/posts/xyz`, etc. But not `/posts/create`
-   `pages/posts/[page].astro` - Will build `/posts/1`, `/posts/2`, etc. But not `/posts/create`, `/posts/abc` nor `/posts/xyz`
-   `pages/posts/[...slug].astro` - Will build `/posts/1/2`, `/posts/a/b/c`, etc. But not `/posts/create`, `/posts/1`, `/posts/abc`, etc.
-   `pages/[...slug].astro` - Will build `/abc`, `/xyz`, `/abc/xyz`, etc. But not `/posts/create`, `/posts/1`, `/posts/abc`, etc.

### Reserved routes

Internal routes take priority over any user-defined or integration-defined routes as they are required for Astro features to work. The following are Astro's reserved routes:

-   `_astro/`: Serves all of the static assets to the client, including CSS documents, bundled client scripts, optimized images, and any Vite assets.
-   `_server_islands/`: Serves the dynamic components deferred into a [server island](/en/guides/server-islands/).
-   `_actions/`: Serves any defined [actions](/en/guides/actions/).

## Pagination

Astro supports built-in pagination for large collections of data that need to be split into multiple pages. Astro will generate common pagination properties, including previous/next page URLs, total number of pages, and more.

Paginated route names should use the same `[bracket]` syntax as a standard dynamic route. For instance, the file name `/astronauts/[page].astro` will generate routes for `/astronauts/1`, `/astronauts/2`, etc, where `[page]` is the generated page number.

You can use the `paginate()` function to generate these pages for an array of values like so:

```
---

  // Generate pages from our array of astronauts, with 2 to a page
  return paginate(astronautPages, { pageSize: 2 });
}) satisfies GetStaticPaths;

// All paginated data is passed on the "page" prop
const { page } = Astro.props;
---

<!-- Display the current page number. `Astro.params.page` can also be used! -->
<h1>Page {page.currentPage}</h1>
<ul>
  <!-- List the array of astronaut info -->
  {page.data.map(({ astronaut }) => <li>{astronaut}</li>)}
</ul>
```

This generates the following pages, with 2 items to a page:

-   `/astronauts/1` - Page 1: Displays "Neil Armstrong" and "Buzz Aldrin"
-   `/astronauts/2` - Page 2: Displays "Sally Ride" and "John Glenn"

### The `page` prop

When you use the `paginate()` function, each page will be passed its data via a `page` prop. The `page` prop has many useful properties that you can use to build pages and links between them:

```
interface Page<T = any> {
	/** array containing the page’s slice of data that you passed to the paginate() function */
	data: T[];
	/** metadata */
	/** the count of the first item on the page, starting from 0 */
	start: number;
	/** the count of the last item on the page, starting from 0 */
	end: number;
	/** total number of results */
	total: number;
	/** the current page number, starting from 1 */
	currentPage: number;
	/** number of items per page (default: 10) */
	size: number;
	/** number of last page */
	lastPage: number;
	url: {
		/** url of the current page */
		current: string;
		/** url of the previous page (if there is one) */
		prev: string | undefined;
		/** url of the next page (if there is one) */
		next: string | undefined;
		/** url of the first page (if the current page is not the first page) */
		first: string | undefined;
		/** url of the last page (if the current page in not the last page) */
		last: string | undefined;
	};
}
```

The following example displays current information for the page along with links to navigate between pages:

```
---
// src/pages/astronauts/[page].astro

// Paginate same list of `{ astronaut }` objects as the previous example

const { page } = Astro.props;
---
<h1>Page {page.currentPage}</h1>
<ul>
  {page.data.map(({ astronaut }) => <li>{astronaut}</li>)}
</ul>
{page.url.first ? <a href={page.url.first}>First</a> : null}
{page.url.prev ? <a href={page.url.prev}>Previous</a> : null}
{page.url.next ? <a href={page.url.next}>Next</a> : null}
{page.url.last ? <a href={page.url.last}>Last</a> : null}
```

Learn more about [the pagination `page` prop](/en/reference/routing-reference/#the-pagination-page-prop).

### Nested Pagination

A more advanced use-case for pagination is **nested pagination.** This is when pagination is combined with other dynamic route params. You can use nested pagination to group your paginated collection by some property or tag.

For example, if you want to group your paginated Markdown posts by some tag, you would use nested pagination by creating a `/src/pages/[tag]/[page].astro` page that would match the following URLS:

-   `/red/1` (tag=red)
-   `/red/2` (tag=red)
-   `/blue/1` (tag=blue)
-   `/green/1` (tag=green)

Nested pagination works by returning an array of `paginate()` results from `getStaticPaths()`, one for each grouping.

In the following example, we will implement nested pagination to build the URLs listed above:

```
---

  const allPosts = Object.values(
    import.meta.glob("../pages/post/*.md", { eager: true }),
  );
  // For every tag, return a `paginate()` result.
  // Make sure that you pass `{ params: { tag }}` to `paginate()`
  // so that Astro knows which tag grouping the result is for.
  return allTags.flatMap((tag) => {
    const filteredPosts = allPosts.filter(
      (post: any) => post.frontmatter.tag === tag,
    );
    return paginate(filteredPosts, {
      params: { tag },
      pageSize: 10,
    });
  });
}) satisfies GetStaticPaths;

const { page } = Astro.props;
const params = Astro.params;
---
```

## Excluding pages

You can exclude pages or directories within `src/pages` from being built by prefixing their names with an underscore (`_`). Files with the `_` prefix won't be recognized by the router and won't be placed into the `dist/` directory.

You can use this to temporarily disable pages, and also to put tests, utilities, and components in the same folder as their related pages.

In this example, only `src/pages/index.astro` and `src/pages/projects/project1.md` will be built as page routes and HTML files.

\- src/pages/ - \_hidden-directory/ - page1.md - page2.md - \_hidden-page.astro - \*\*index.astro\*\* - projects/ - \_SomeComponent.astro - \_utils.js - \*\*project1.md\*\*

## Advanced routing

By default, Astro handles every request with a built-in pipeline that runs the handlers in a fixed order: trailing-slash normalization, redirects, sessions, actions, user middleware, page rendering, i18n, and caching. This pipeline is designed to cover the most common use cases for routing and request handling, but it may not fit every project’s needs.

Astro's advanced routing allows you to replace this pipeline with your own. You can choose which built-in features to use and where to use them. You can also add your own custom logic anywhere in the pipeline. This gives you full control over how Astro handles incoming requests.

### Creating a custom entrypoint

When the default pipeline does not fit your needs, you can override it by creating a `src/fetch.ts` file that default-exports an object with a `fetch()` method. This method receives a standard [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) and must return a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response).

```

  }
} satisfies Fetchable;
```

Astro supports several file formats for its advanced routing entrypoint: `.ts`, `.js`, `.mjs`, and `.mts`. We recommend using `.js` in most cases or `.ts` if you need TypeScript support.

### Changing the entrypoint filename

By default, Astro looks for `src/fetch.ts` as the advanced routing entrypoint. You can change this by setting the [`fetchFile`](/en/reference/configuration-reference/#fetchfile) option in your Astro config file.

The following example tells Astro to look for `src/handler.ts` instead of `src/fetch.ts`:

Set `fetchFile` to `null` to disable the entrypoint entirely. This is useful if you already have a `src/fetch.ts` file used for other purposes:

### Adding custom logic

The main benefit of advanced routing is the ability to insert custom logic into the request pipeline. You can run code before Astro touches the request, between pipeline stages, or after the response is produced.

You can do this in two ways:

-   Use the [`astro()` handler](/en/reference/modules/astro-fetch/#astro) to run the full built-in pipeline, and add logic before or after it.
-   Compose individual handlers from [`astro/fetch`](/en/reference/modules/astro-fetch/) or [`astro/hono`](/en/reference/modules/astro-hono/) for more control over execution order.

#### Running the full pipeline with `astro()`

Use [`astro()`](/en/reference/modules/astro-fetch/#astro) when you want to keep Astro's built-in routing behavior, but need custom logic around it. This approach preserves the default pipeline order and lets you add pre-processing and post-processing in one place. For many use cases, such as adding auth guards, request logging, and custom headers, `astro()` is all you need.

The following example checks if a user can access a dashboard before running the Astro pipeline, and adds a custom header to the response once Astro has finished running:

```

    // Custom pre-processing, runs before any Astro handler
    const url = new URL(request.url);
    if (url.pathname.startsWith('/dashboard')) {
      const cookie = request.headers.get('cookie') ?? '';
      if (!cookie.includes('session=')) {
        return new Response(null, {
          status: 302,
          headers: { Location: '/login' },
        });
      }
    }

    const response = await astro(state);

    // Custom post-processing, runs after Astro renders
    response.headers.set('X-Powered-By', 'Astro');
    return response;
  },
};
```

#### Composing individual handlers

When you need more control over the pipeline execution order, or want to omit certain features, you can compose individual handler functions from [`astro/fetch`](/en/reference/modules/astro-fetch/). Each handler operates on a [`FetchState` object](/en/reference/modules/astro-fetch/#fetchstate) that tracks per-request data, such as the matched route, cookies, and session. You can call handlers in any order and insert custom logic between stages.

The following example runs only the handlers used in the project and adds custom logic after actions and before page rendering:

```

    const actionResponse = await actions(state);
    if (actionResponse) return actionResponse;

    // Custom logic between actions and page rendering
    console.log(`Rendering ${new URL(request.url).pathname}`);

    const response = await middleware(state, (s) => pages(s));
    return i18n(state, response);
  },
};
```

### Using with Hono

Astro also provides Hono-compatible wrappers for all handler functions via [`astro/hono`](/en/reference/modules/astro-hono/). If you prefer to use [Hono](https://hono.dev/) as your routing framework, you can export a Hono app from `src/fetch.ts`:

```

const app = new Hono();

// Hono middleware
app.use(logger());

// Astro handlers (as Hono middleware)
app.use(actions());
app.use(middleware());
app.use(pages());
app.use(i18n());
```

## [Server islands](https://docharvest.github.io/docs/astro/guides/server-islands/)

Contents

astro

Server islands

Astro

Server islands

Server islands allow you to on-demand render dynamic or personalized "islands" individually, without sacrificing the performance of the rest of the page.

This means your visitor will see the most important parts of your page sooner, and allows your main content to be more aggressively cached, providing faster performance.

## Server island components

A server island is a normal server-rendered [Astro component](/en/basics/astro-components/) that is instructed to delay rendering until its contents are available.

Your page will be rendered immediately with any specified [fallback content as a placeholder](#server-island-fallback-content). Then, the component's own contents are fetched on the client and displayed when available.

With [an adapter installed](/en/guides/on-demand-rendering/#server-adapters) to perform the delayed rendering, add the [`server:defer` directive](/en/reference/directives-reference/#server-directives) to any component on your page to turn it into its own island:

```
---

---
<Avatar server:defer />
```

These components can do [anything you normally would in an on-demand rendered page](/en/guides/on-demand-rendering/#on-demand-rendering-features) using an adapter, such as fetch content, and access cookies:

```
---

const userSession = Astro.cookies.get('session');
const avatarURL = await getUserAvatar(userSession);
---
<img alt="User avatar" src={avatarURL} />
```

### Passing props to server islands

Props provided to server island components must be [serializable](https://developer.mozilla.org/en-US/docs/Glossary/Serialization): able to be translated into a format suitable for transfer over a network, or storage. Additionally, Astro does not serialize every type of serializable data structure. Therefore, there are some limitations on what can be passed as props to a server island.

Notably, functions cannot be passed to components marked with `server:defer` as they cannot be serialized. Objects with circular references are also not serializable.

The following prop types are supported: plain object, `number`, `string`, `Array`, `Map`, `Set`, `RegExp`, `Date`, `BigInt`, `URL`, `Uint8Array`, `Uint16Array`, `Uint32Array`, and `Infinity`

## Server island fallback content

When using the `server:defer` attribute on a component to delay its rendering, you can "slot" in default loading content using the included named `"fallback"` slot.

Your fallback content will be rendered along with the rest of the page initially on page load and will be replaced with your component's content when available.

To add fallback content, add `slot="fallback"` on a child (other components or HTML elements) passed to your server island component:

```
---

---
<Avatar server:defer>
  <GenericAvatar slot="fallback" />
</Avatar>
```

This fallback content can be things like:

-   A generic avatar instead of the user's own.
-   Placeholder UI such as custom messages.
-   Loading indicators such as spinners.

## How it works

Server island implementation happens mostly at build-time where component content is swapped out for a small script.

Each of the islands marked with `server:defer` is split off into its own special route which the script fetches at run time. When Astro builds your site it will omit the component and inject a script in its place, and any content you’ve marked with `slot="fallback"`.

When the page loads in the browser, these components will be requested to a special endpoint that renders them and returns the HTML. This means that users will see the most critical parts of the page instantly. Fallback content will be visible for a short amount of time before the dynamic islands are then loaded.

Each island is loaded independently from the rest. This means a slower island won't delay the rest of your personalized content from being available.

This rendering pattern was built to be portable. It does not depend on any server infrastructure so it will work with any host you have, from a Node.js server in a Docker container to the serverless provider of your choice.

## Caching

The data for server islands is retrieved via a `GET` request, passing props as an encrypted string in the URL query. This allows caching data with the [`Cache-Control` HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control) using standard `Cache-Control` directives.

However, [the browser limits URLs to a maximum length of 2048 bytes](https://chromium.googlesource.com/chromium/src/+/master/docs/security/url_display_guidelines/url_display_guidelines.md#url-length) for practical reasons and to avoid causing denial-of-service problems. If your query string causes your URL to exceed this limit, Astro will instead send a `POST` request that contains all props in the body.

`POST` requests are not cached by browsers because they are used to submit data, and could cause data integrity or security issues. Therefore, any existing caching logic in your project will break. Whenever possible, pass only necessary props to your server islands and avoid sending entire data objects and arrays to keep your query small.

## Accessing the page URL in a server island

In most cases you, your server island component can get information about the page rendering it by [passing props](/en/basics/astro-components/#component-props) like in normal components.

However, server islands run in their own isolated context outside of the page request. `Astro.url` and `Astro.request.url` in a server island component both return a URL that looks like `/_server-islands/Avatar` instead of the current page's URL in the browser. Additionally, if you are prerendering the page you will not have access to information such as query parameters in order to pass as props.

To access information from the page's URL, you can check the [Referer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) header, which will contain the address of the page that is loading the island in the browser:

```
---
const referer = Astro.request.headers.get("Referer");

if (!referer) {
  throw new Error("Referer header is missing");
}

const url = new URL(referer);
const productId = url.searchParams.get("product");
---
```

## Reusing the encryption key

Astro uses [cryptography](https://developer.mozilla.org/en-US/docs/Glossary/Cryptography) to encrypt props passed to server islands, protecting sensitive data from accidental exposure. This encryption relies on a new, random key that is generated on each build and embedded in the server bundle.

Most deploy hosts will handle keeping your front end and back end in sync automatically. However, you may need a constant encryption key if you are using rolling deployments, multi-region hosting or a CDN that caches pages containing server islands.

In environments with rolling deployments (e.g., Kubernetes) where your frontend assets (which encrypt props) and your backend functions (which decrypt props) may be temporarily using different keys, or when a CDN is still serving pages built with an old key, encrypted props passed to your server island cannot be decrypted.

In these situations, use the Astro CLI to generate a reusable, encoded encryption key to set as an environment variable in your build environment:

```
astro create-key
```

Use this value to configure the `ASTRO_KEY` environment variable (e.g. in a `.env` file) and include it in your CI/CD or host's build settings. This ensures the same key is always reused in the generated bundle so that encryption and decryption remain in sync.

## [Sessions](https://docharvest.github.io/docs/astro/guides/sessions/)

Contents

astro

Sessions

Astro

Sessions

Sessions are used to share data between requests for [on-demand rendered pages](/en/guides/on-demand-rendering/).

Unlike [`cookies`](/en/guides/on-demand-rendering/#cookies), sessions are stored on the server, so you can store larger amounts of data without worrying about size limits or security issues. They are useful for storing things like user data, shopping carts, and form state, and they work without any client-side JavaScript:

```
---

---

<a href="/checkout">🛒 {cart?.length ?? 0} items</a>
```

## Configuring sessions

Sessions require a storage driver to store the session data. The [Node](/en/guides/integrations-guide/node/#sessions), [Cloudflare](/en/guides/integrations-guide/cloudflare/#sessions), and [Netlify](/en/guides/integrations-guide/netlify/#sessions) adapters automatically configure a default driver for you, but other adapters currently require you to [specify a driver manually](/en/reference/configuration-reference/#sessiondriver).

````

    import redisDriver from "unstorage/drivers/redis";
    import { REDIS_HOST, REDIS_PORT } from "astro:env";

    export default function (): SessionDriver {
      return redisDriver({
        host: REDIS_HOST,
        port: REDIS_PORT,
      });
    }
    ```

3. Use this file as the driver's entrypoint in your Astro configuration:
    ```js title="astro.config.mjs" {11-13}
    import { defineConfig, envField, sessionDrivers } from "astro/config";
    import vercel from "@astrojs/vercel";

    export default defineConfig({
      adapter: vercel(),
      env: {
        REDIS_HOST: envField.string({ context: "server", access: "public", default: "localhost" }),
        REDIS_PORT: envField.number({ context: "server", access: "public", default: 6379 }),
      },
      session: {
        driver: {
          entrypoint: new URL('./src/session-driver.ts', import.meta.url),
        }
      }
    });
    ```
</Steps>

## Interacting with session data

The [`session` object](/en/reference/api-reference/#session) allows you to interact with the stored user state (e.g. adding items to a shopping cart) and the session ID (e.g. deleting the session ID cookie when logging out). The object is accessible as `Astro.session` in your Astro components and pages and as `context.session` object in API endpoints, middleware, and actions.

The session is generated automatically when it is first used and can be regenerated at any time with [`session.regenerate()`](/en/reference/api-reference/#sessionregenerate) or destroyed with [`session.destroy()`](/en/reference/api-reference/#sessiondestroy).

For many use cases, you will only need to use [`session.get()`](/en/reference/api-reference/#sessionget) and [`session.set()`](/en/reference/api-reference/#sessionset). 

<ReadMore>
See [the Sessions API reference](/en/reference/api-reference/#session) for more details.
</ReadMore>

### Astro components and pages

In `.astro` components and pages, you can access the session object via the global `Astro` object. For example, to display the number of items in a shopping cart:

```astro title="src/components/CartButton.astro" "Astro.session"
---

---

<a href="/checkout">🛒 {cart?.length ?? 0} items</a>
````

### API endpoints

In API endpoints, the session object is available on the `context` object. For example, to add an item to a shopping cart:

```

  const data = await context.request.json();
  if(!data?.item) {
    return new Response('Item is required', { status: 400 });
  }
  cart.push(data.item);
  await context.session?.set('cart', cart);
  return Response.json(cart);
}
```

### Actions

In actions, the session object is available on the `context` object. For example, to add an item to a shopping cart:

```

      cart.push(input.productId);
      await context.session?.set('cart', cart);
      return cart;
    },
  }),
};
```

### Middleware

:::note Sessions are not supported in edge middleware. :::

In middleware, the session object is available on the `context` object. For example, to set the last visit time in the session:

```

  return next();
});
```

## Session data types

By default session data is untyped, and you can store arbitrary data in any key. Values are serialized and deserialized using [devalue](https://github.com/Rich-Harris/devalue), which is the same library used in content collections and actions. This means that supported types are the same, and include strings, numbers, `Date`, `Map`, `Set`, `URL`, arrays, and plain objects.

You can optionally [define TypeScript types](/en/guides/typescript/#extending-global-types) for your session data by creating a `src/env.d.ts` file and adding a declaration for the `App.SessionData` type:

```
declare namespace App {
  interface SessionData {
    user: {
      id: string;
      name: string;
    };
    cart: string[];
  }
}
```

This will allow you to access the session data with type-checking and auto-completion in your editor:

```
---
const cart = await Astro.session?.get('cart');
// const cart: string[] | undefined

const something = await Astro.session?.get('something');
// const something: any

Astro.session?.set('user', { id: 1, name: 'Houston' });
// Error: Argument of type '{ id: number; name: string }' is not assignable to parameter of type '{ id: string; name: string; }'.
---
```

:::caution This is only used for type-checking and does not affect the runtime behavior of the session. Take extra care if you change the type when users have stored data in the session, as this could cause runtime errors. :::

## [Styles and CSS](https://docharvest.github.io/docs/astro/guides/styling/)



## [Syntax Highlighting](https://docharvest.github.io/docs/astro/guides/syntax-highlighting/)



## [Testing](https://docharvest.github.io/docs/astro/guides/testing/)



## [Troubleshooting](https://docharvest.github.io/docs/astro/guides/troubleshooting/)

Contents

astro

Troubleshooting

Astro

Troubleshooting

Astro provides several different tools to help you troubleshoot and debug your code.

## Tips and tricks

### Debugging with `console.log()`

`console.log()` is a simple-but-popular method of debugging your Astro code. Where you write your `console.log()` statement will determine where your debugging output is printed:

```
---
console.log('Hi! I’m the server. This is logged in the terminal where Astro is running.');
---

<script>
console.log('Hi! I’m the client. This is logged in browser dev console.');
</script>
```

A `console.log()` statement in Astro frontmatter will always output to the **terminal** running the Astro CLI. This is because Astro runs on the server, and never in the browser.

Code that is written or imported inside of an Astro `<script>` tag is run in the browser. Any `console.log()` statements or other debug output will be printed to the **console in your browser**.

### Debugging framework components

[Framework components](/en/guides/framework-components/) (like React and Svelte) are unique: They render server-side by default, meaning that `console.log()` debug output will be visible in the terminal. However, they can also be hydrated for the browser, which may cause your debug logs to also appear in the browser.

This can be useful for debugging differences between the server output and the hydrated components in the browser.

### Astro `<Debug />` component

To help you debug your Astro components, Astro provides a built-in `<Debug />` component which renders any value directly into your component HTML template.

This component provides a way to inspect values on the client-side, without any JavaScript. It can be useful for quick debugging in the browser without having to flip back-and-forth between your terminal and your browser.

```
---

const sum = (a, b) => a + b;
---

<!-- Example: Outputs {answer: 6} to the browser -->
<Debug answer={sum(2, 4)} />
```

The Debug component supports a variety of syntax options for even more flexible and concise debugging:

```
---

const sum = (a, b) => a + b;
const answer = sum(2, 4);
---
<!-- Example: All three examples are equivalent. -->
<Debug answer={sum(2, 4)} />
<Debug {...{answer: sum(2, 4)}} />
<Debug {answer} />
```

## Common Error Messages

Here are some common error messages you might see in the terminal, what they might mean, and what to do about them. See our [full error reference guide](/en/reference/error-reference/) for a complete list of Astro errors you may encounter.

### Cannot use import statement outside a module

In Astro components, `<script>` tags are loaded as [JS modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) by default. If you have included the [`is:inline` directive](/en/reference/directives-reference/#isinline) or any other attribute in your tag, this default behavior is removed.

**Solution**: If you have added any attributes to your `<script>` tag, you must also add the `type="module"` attribute to be able to use import statements.

**Status**: Expected Astro behavior, as intended.

**Not sure that this is your problem?**  
Check to see if anyone else has reported [this issue](https://github.com/withastro/astro/issues?q=is%3Aissue+is%3Aopen+Cannot+use+import+statement)!

### `document` (or `window`) is not defined

This error occurs when trying to access `document` or `window` on the server.

Astro components run on the server, so you can't access these browser-specific objects within the frontmatter.

Framework components run on the server by default, so this error can occur when accessing `document` or `window` during rendering.

**Solution**: Determine the code that calls `document` or `window`. If you aren't using `document` or `window` directly and still getting this error, check to see if any packages you're importing are meant to run on the client.

-   If the code is in an Astro component, move it to a `<script>` tag outside of the frontmatter. This tells Astro to run this code on the client, where `document` and `window` are available.
    
-   If the code is in a framework component, try to access these objects after rendering using lifecycle methods (e.g. [`useEffect()`](https://react.dev/reference/react/useEffect) in React, [`onMounted()`](https://vuejs.org/api/composition-api-lifecycle.html#onmounted) in Vue, and [`onMount()`](https://svelte.dev/docs#run-time-svelte-onmount) in Svelte). Tell the framework component to hydrate client-side by using a [client:](/en/reference/directives-reference/#client-directives) directive, like `client:load`, to run these lifecycle methods. You can also prevent the component from rendering on the server at all by adding the [`client:only`](/en/reference/directives-reference/#clientonly) directive.
    

**Status**: Expected Astro behavior, as intended.

### Expected a default export

This error can be thrown when trying to import or render an invalid component, or one that is not working properly. (This particular message occurs because of the way importing a UI component works in Astro.)

**Solution**: Try looking for errors in any component you are importing and rendering, and make sure it's working correctly. Consider opening an Astro starter template from [astro.new](https://astro.new) and troubleshooting just your component in a minimal Astro project.

**Status**: Expected Astro behavior, as intended.

### Refused to execute inline script

You may see the following error logged in the browser console:

> Refused to execute inline script because it violates the following Content Security Policy directive: …

This means that your site’s [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) (CSP) disallows running inline `<script>` tags, which Astro outputs by default.

**Solution:** Update your CSP to include `script-src: 'unsafe-inline'` to allow inline scripts to run. Alternatively, you can use a third-party integration such as [`astro-shield`](https://github.com/KindSpells/astro-shield) to generate the CSP headers for you.

## Common gotchas

### My component is not rendering

First, check to see that you have **imported the component** in your [`.astro` component script](/en/basics/astro-components/#the-component-script) or [`.mdx` file](/en/guides/integrations-guide/mdx/#using-components-in-mdx).

Then check your import statement:

-   Is your import linking to the wrong place? (Check your import path.)
    
-   Does your import have the same name as the imported component? (Check your component name and that it [follows the `.astro` syntax](/en/reference/astro-syntax/#differences-between-astro-and-jsx).)
    
-   Have you included the extension in the import? (Check that your imported file contains an extension. e.g. `.astro`, `.md`, `.vue`, `.svelte`. Note: File extensions are **not** required for `.js(x)` and `.ts(x)` files only.)
    

### My component is not interactive

If your component is rendering (see above) but is not responding to user interaction, then you may be missing a [`client:*` directive](/en/reference/directives-reference/#client-directives) to hydrate your component.

By default, a [UI Framework component is not hydrated in the client](/en/guides/framework-components/#hydrating-interactive-components). If no `client:*` directive is provided, its HTML is rendered onto the page without JavaScript.

:::tip [Astro components](/en/basics/astro-components/) are HTML-only templating components with no client-side runtime. But, you can use a `<script>` tag in your Astro component template to send JavaScript to the browser that executes in the global scope. :::

### Cannot find package 'X'

If you see a `"Cannot find package 'react'"` (or similar) warning when you start up Astro, that means that you need to install that package into your project. Not all package managers will install peer dependencies for you automatically. If you are on Node v16+ and using npm, you should not need to worry about this section.

React, for example, is a peer dependency of the `@astrojs/react` integration. That means that you should install the official `react` and `react-dom` packages alongside your integration. The integration will then pull from these packages automatically.

```
# Example: Install integrations and frameworks together
npm install @astrojs/react react react-dom
```

See [Astro's integration guide](/en/guides/integrations/) for instructions on adding framework renderers, CSS tools and other packages to Astro.

### Using Astro with Yarn 2+ (Berry)

Yarn 2+, a.k.a. Berry, uses a technique called [Plug'n'Play (PnP)](https://yarnpkg.com/features/pnp) to store and manage Node modules, which can [cause problems](https://github.com/withastro/astro/issues/3450) while initializing a new Astro project using `create astro` or while working with Astro. A workaround is to set the [`nodeLinker` property](https://yarnpkg.com/configuration/yarnrc#nodeLinker) in `.yarnrc.yml` to `node-modules`:

```
nodeLinker: "node-modules"
```

### Adding dependencies to Astro in a monorepo

When working with Astro in a monorepo setup, project dependencies should be added in each project's own `package.json` file.

However, you may also want to use Astro in the root of the monorepo (e.g. [Nx projects recommend installing dependencies at the root](https://github.com/nrwl/nx/issues/3023#issuecomment-630558318)). In this case, manually add Astro-related dependencies (e.g. `@astrojs/vue`, `astro-component-lib`) to the `vite.ssr.noExternal` part of Astro's config to ensure that these dependencies are properly installed and bundled:

```
// astro.config.mjs
import { defineConfig } from 'astro/config'
export default defineConfig({
  vite: {
    ssr: {
      noExternal: [
        '@astrojs/vue',
        'astro-component-lib',
      ]
    }
  }
})
```

### Using `<head>` in a component

In Astro, using a `<head>` tag works like any other HTML tag: it does not get moved to the top of the page or merged with the existing `<head>`. Because of this, you usually only want to include one `<head>` tag throughout a page. We recommend writing that single `<head>` and its contents in a [layout component](/en/basics/layouts/).

### An unexpected `<style>` is included

You may notice an imported component's `<style>` tag included in your HTML source even if that component doesn't appear in the final output. For example, this will occur with [conditionally rendered](/en/reference/astro-syntax/#dynamic-html) components that are not displayed.

Astro's build process works on the module graph: once a component is included in the template, its `<style>` tag is processed, optimized, and bundled, whether it appears in the final output or not.

### Escaping special characters in Markdown

Certain characters have a special meaning in Markdown. You may need to use a different syntax if you want to display them. To do this, you can use [HTML entities](https://developer.mozilla.org/en-US/docs/Glossary/Entity) for these characters instead.

For example, to prevent `<` being interpreted as the beginning of an HTML element, write `&lt;`.

## Creating minimal reproductions

When troubleshooting your code, it can be helpful to create a **minimal reproduction** of the issue that you can share. This is a smaller, simplified Astro project that demonstrates your issue. Having a working reproduction in a new project helps to confirm that this is a repeatable problem, and is not caused by something else in your personal environment or existing project.

Sharing a minimal reproduction is helpful when asking for help in our support threads and is often required when filing a bug report to Astro.

### Create a StackBlitz via [astro.new](https://astro.new/repro)

You can use [astro.new](https://astro.new/repro) to create a new Astro project with a single click. For minimal reproductions, we strongly recommend starting from the minimal (empty) example running in [StackBlitz](https://stackblitz.com), with as little extra code as possible.

StackBlitz will run this Astro project in the browser, outside of your local environment. It will also provide you with a shareable link so that any Astro maintainer or support squad member can view your minimal reproduction outside of their own local environment. This means that everyone is viewing the exact same project, with the same configuration and dependencies. This makes it easy for someone else to help troubleshoot your code. If the issue is reproducible, it allows you to verify that the issue lies within the Astro code itself and you can feel confident submitting a bug report.

Note that not every issue is reproducible in StackBlitz. For example, your issue might be dependent on a specific environment or package manager, or it may involve HTML Streaming, which isn't supported in StackBlitz. In this case, create a new minimal (empty) Astro project using the CLI, reproduce the issue, and upload it to a GitHub repository. Instead of sharing a StackBlitz URL, provide a link to the GitHub repository of your minimal reproduction.

### Minimal code

Once your empty project is set up, go through the steps to reproduce the issue. This can include adding packages, changing configuration, and writing code.

You should only add the minimum amount of code necessary to reproduce the issue. Do not reproduce other elements of your existing project, and remove all code that is not directly related to the issue.

### Create an issue

If your issue can be reproduced, then it is time to create an issue and file a bug report!

Go to the appropriate Astro repository on GitHub and open a new issue. Most repositories have an issue template that will ask questions or require information in order to submit. It's important that you follow these templates because if you don't provide the information we need, then we have to ask you for it... and no one is working on your issue!

Include the link to your minimal reproduction on StackBlitz (or GitHub repository, if necessary). Start with a description of the expected versus actual behavior to provide context for the issue. Then, include clear, step-by-step instructions on how to replicate the issue in an Astro project.

## Need more?

Come and chat with us on [Discord](https://astro.build/chat) and explain your issue in the `#support` forum channel. We’re always happy to help!

Visit the current [open Issues in Astro](https://github.com/withastro/astro/issues/) to see if you are encountering a known problem or file a bug report.

You can also visit [Roadmap Discussions](https://github.com/withastro/roadmap/discussions) to see whether you've found a known limitation of Astro, and check to see whether there are current proposals related to your use case.

## [TypeScript](https://docharvest.github.io/docs/astro/guides/typescript/)

Contents

astro

TypeScript

Astro

TypeScript

````

This way, you avoid edge cases where Astro's bundler may try to incorrectly bundle your imported types as if they were JavaScript.

You can configure TypeScript to enforce type imports in your `tsconfig.json` file. Set [`verbatimModuleSyntax`](https://www.typescriptlang.org/tsconfig#verbatimModuleSyntax) to `true`. TypeScript will check your imports and tell you when `import type` should be used. This setting is enabled by default in all our presets.

```json title="tsconfig.json" ins={3}
{
  "compilerOptions": {
    "verbatimModuleSyntax": true
  }
}
````

## Import Aliases

Astro supports import aliases that you define in your `tsconfig.json` `paths` configuration. [Read our imports guide](/en/guides/imports/#aliases) to learn more.

```
---

---
```

```
{
  "compilerOptions": {
    "paths": {
      "@components/*": ["./src/components/*"],
      "@layouts/*": ["./src/layouts/*"]
    }
  }
}
```

## Extending global types

You can create `src/env.d.ts` as a convention for adding custom types declarations, or to benefit from Astro types if you don't have a `tsconfig.json`:

```
// Custom types declarations
declare var myString: string;

// Astro types, not necessary if you already have a `tsconfig.json`
/// <reference path="../.astro/types.d.ts" />
```

### `window` and `globalThis`

You may want to add a property to the global object. You can do this by adding top-level declarations using the `declare` keyword to your `env.d.ts` file:

```
declare var myString: string;
declare function myFunction(): boolean;
```

This will provide typing to `globalThis.myString` and `globalThis.myFunction`, as well as `window.myString` and `window.myFunction`.

Note that `window` is only available in client-side code. `globalThis` is available both server-side and client-side, but its server-side value won't be shared with the client.

If you only want to type a property on the `window` object, provide a `Window` interface instead:

```
interface Window {
	myFunction(): boolean;
}
```

### Add non-standard attributes

You may want to define a type for custom attributes or CSS properties. You can extend the default JSX definitions to add non-standard attributes by redeclaring the `astroHTML.JSX` namespace in a `.d.ts` file.

```
declare namespace astroHTML.JSX {
  interface HTMLAttributes {
    "data-count"?: number;
    "data-label"?: string;
  }

  // Add a CSS custom property to the style object
  interface CSSProperties {
    "--theme-color"?: "black" | "white";
  }
}
```

:::note `astroHTML` is injected globally inside `.astro` components. To use it in TypeScript files, use a [triple-slash directive](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html):

```
/// <reference types="astro/astro-jsx" />

type MyAttributes = astroHTML.JSX.ImgHTMLAttributes;
```

:::

### Using imports

You may want to extend global types by reusing types declared elsewhere in your project or from an external library. To do this, use [dynamic imports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import):

```
type Product = {
  id: string;
  name: string;
  price: number;
};

declare namespace App {
  interface Locals {
    orders: Map<string, Product[]>
    session: import("./lib/server/session").Session | null;
    user: import("my-external-library").User;
  }
}
```

A `.d.ts` file is an [ambient module](https://www.typescriptlang.org/docs/handbook/modules/reference.html#ambient-modules) declaration. While its syntax is similar to ES modules, these files do not allow top-level imports/exports. If TypeScript encounters one, the file will be considered a [module augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation) and this will break your global types.

## Component Props

Astro supports typing your component props via TypeScript. To enable, add a TypeScript `Props` interface to your component frontmatter. An `export` statement may be used, but is not necessary. The [Astro VS Code Extension](/en/editor-setup/) will automatically look for the `Props` interface and give you proper TS support when you use that component inside another template.

```
---
interface Props {
  name: string;
  greeting?: string;
}

const { greeting = "Hello", name } = Astro.props;
---
<h2>{greeting}, {name}!</h2>
```

### Common prop type patterns

-   If your component takes no props or slotted content, you can use `type Props = Record<string, never>`.
-   If your component must be passed children to its default slot, you can enforce this by using `type Props = { children: any; };`.

## Type Utilities

Astro comes with some built-in utility types for common prop type patterns. These are available under the `astro/types` entrypoint.

### Built-in HTML attributes

Astro provides the `HTMLAttributes` type to check that your markup is using valid HTML attributes. You can use these types to help build component props.

For example, if you were building a `<Link>` component, you could do the following to mirror the default HTML attributes for `<a>` tags in your component’s prop types.

```
---

// use a `type`
type Props = HTMLAttributes<"a">;

// or extend with an `interface`
interface Props extends HTMLAttributes<"a"> {
  myProp?: boolean;
}

const { href, ...attrs } = Astro.props;
---
<a href={href} {...attrs}>
  <slot />
</a>
```

### `ComponentProps` type

This type export allows you to reference the `Props` accepted by another component, even if that component doesn't export that `Props` type directly.

The following example shows using the `ComponentProps` utility from `astro/types` to reference a `<Button />` component's `Props` types:

```
---

type ButtonProps = ComponentProps<typeof Button>;
---
```

### Polymorphic type

Astro includes a helper to make it easier to build components that can render as different HTML elements with full type safety. This is useful for components like `<Link>` that can render as either `<a>` or `<button>` depending on the props passed to it.

The example below implements a fully-typed, polymorphic component that can render as any HTML element. The [`HTMLTag`](#built-in-html-attributes) type is used to ensure that the `as` prop is a valid HTML element.

```
---

type Props<Tag extends HTMLTag> = Polymorphic<{ as: Tag }>;

const { as: Tag, ...props } = Astro.props;
---
<Tag {...props} />
```

### Infer `getStaticPaths()` types

Astro includes helpers for working with the types returned by your [`getStaticPaths()`](/en/reference/routing-reference/#getstaticpaths) function for dynamic routes.

You can get the type of [`Astro.params`](/en/reference/api-reference/#params) with `InferGetStaticParamsType` and the type of [`Astro.props`](/en/reference/api-reference/#props) with `InferGetStaticPropsType` or you can use `GetStaticPaths` to infer both at once:

```
---

  return posts.map((post) => {
    return {
      params: { id: post.id },
      props: { draft: post.data.draft, title: post.data.title },
    };
  });
}) satisfies GetStaticPaths;

type Params = InferGetStaticParamsType<typeof getStaticPaths>;
type Props = InferGetStaticPropsType<typeof getStaticPaths>;

const { id } = Astro.params;
//                   ^? { id: string; }

const { title } = Astro.props;
//                      ^? { draft: boolean; title: string; }
---
```

## Type checking

To see type errors in your editor, please make sure that you have the [Astro VS Code extension](/en/editor-setup/) installed. Please note that the `astro start` and `astro build` commands will transpile the code with esbuild, but will not run any type checking. To prevent your code from building if it contains TypeScript errors, change your "build" script in `package.json` to the following:

```
{
  "scripts": {
    "build": "astro build",
    "build": "astro check && astro build",
  },
}
```

:::note `astro check` checks all the files included in your TypeScript project. To check types within Svelte and Vue files, you can use the [`svelte-check`](https://www.npmjs.com/package/svelte-check) and the [`vue-tsc`](https://www.npmjs.com/package/vue-tsc) packages respectively. :::

import ReadMore from '~/components/ReadMore.astro'

Read more about [`.ts` file imports](/en/guides/imports/#typescript) in Astro.

Read more about [TypeScript Configuration](https://www.typescriptlang.org/tsconfig/).

## Troubleshooting

### Errors typing multiple JSX frameworks at the same time

An issue may arise when using multiple JSX frameworks in the same project, as each framework requires different, sometimes conflicting, settings inside `tsconfig.json`.

**Solution**: Set the [`jsxImportSource` setting](https://www.typescriptlang.org/tsconfig#jsxImportSource) to `react` (default), `preact` or `solid-js` depending on your most-used framework. Then, use a [pragma comment](https://www.typescriptlang.org/docs/handbook/jsx.html#configuring-jsx) inside any conflicting file from a different framework.

For the default setting of `jsxImportSource: react`, you would use:

```
// For Preact
/** @jsxImportSource preact */

// For Solid
/** @jsxImportSource solid-js */
```

## [Legacy v0.x Upgrade Guide](https://docharvest.github.io/docs/astro/guides/upgrade-to/v1/)



## [Upgrade to Astro v2](https://docharvest.github.io/docs/astro/guides/upgrade-to/v2/)



## [Upgrade to Astro v3](https://docharvest.github.io/docs/astro/guides/upgrade-to/v3/)



## [Upgrade to Astro v4](https://docharvest.github.io/docs/astro/guides/upgrade-to/v4/)

Contents

astro

Upgrade to Astro v4

Astro

Upgrade to Astro v4

````

### Changed: `app.render` signature in Integrations API

In Astro v3.0, the `app.render()` method accepted `routeData` and `locals` as separate, optional arguments. 

Astro v4.0 changes the `app.render()` signature. These two properties are now available in a single object. Both the object and these two properties are still optional.

#### What should I do?

If you are maintaining an adapter, the current signature will continue to work until the next major version. To migrate to the new signature, pass `routeData` and `locals` as properties of an object instead of as multiple independent arguments.

```diff lang="js"
- app.render(request, routeData, locals)
+ app.render(request, { routeData, locals })
````

### Changed: adapters must now specify supported features

In Astro v3.x, adapters were not required to specify the features they support.

Astro v4.0 requires adapters to pass the `supportedAstroFeatures{}` property to specify a list of features they support. This property is no longer optional.

#### What should I do?

Adapter authors need to pass the `supportedAstroFeatures{}` option to specify a list of features they support.

```

      },
    },
  };
}
```

### Removed: Shiki language `path` property

In Astro v3.x, a Shiki language passed to `markdown.shikiConfig.langs` was automatically converted to a Shikiji-compatible language. Shikiji is the internal tooling used by Astro for syntax highlighting.

Astro v4.0 removes support for the `path` property of a Shiki language, which was confusing to configure. It is replaced by an import which can be passed to `langs` directly.

#### What should I do?

The language JSON file should be imported and passed to the option instead.

```
// astro.config.js
+ import customLang from './custom.tmLanguage.json'

+   return new Response(JSON.stringify({ "title": "Bob's blog" }));
  }
```

To remove usage of `ResponseWithEncoding`, refactor your code to use an `ArrayBuffer` instead:

```
  export async function GET() {
    const file = await fs.readFile('./bob.png');
-   return new ResponseWithEncoding(file.toString('binary'), undefined, 'binary');
+   return new Response(file.buffer);
  }
```

### Removed: `build.split` and `build.excludeMiddleware`

In Astro v3.0, `build.split` and `build.excludeMiddleware` build config options were deprecated and replaced with [adapter configuration options](/en/reference/adapter-reference/#adapter-features) to perform the same tasks.

Astro v4.0 removes these properties entirely.

#### What should I do?

If you are using the deprecated `build.split` or `build.excludeMiddleware`, you must now remove them as these no longer exist.

Please see the v3 migration guide to [update these deprecated middleware properties](/en/guides/upgrade-to/v3/#deprecated-buildexcludemiddleware-and-buildsplit) with adapter configurations.

### Removed: `Astro.request.params`

In Astro v3.0, the `Astro.request.params` API was deprecated, but preserved for backwards compatibility.

Astro v4.0 removes this option entirely.

#### What should I do?

Update all occurrences to [`Astro.params`](/en/reference/api-reference/#params), which is the supported replacement.

```
const { id } = Astro.request.params;
const { id } = Astro.params;
```

### Removed: `markdown.drafts`

In Astro v3.0, using `markdown.drafts` to control the building of draft posts was deprecated.

Astro v4.0 removes this option entirely.

#### What should I do?

If you are using the deprecated `markdown.drafts`, you must now remove it as it no longer exists.

To continue to mark some pages in your project as drafts, [migrate to content collections](/en/guides/content-collections/) and manually filter out pages with the `draft: true` frontmatter property instead.

### Removed: `getHeaders()`

In Astro v3.0, the `getHeaders()` Markdown export was deprecated and replaced with `getHeadings()`.

Astro v4.0 removes this option entirely.

#### What should I do?

If you are using the deprecated `getHeaders()`, you must now remove it as it no longer exists. Replace any instances with `getHeadings()`, which is the supported replacement.

```
const posts = await Astro.glob('../content/blog/*.mdx');
const firstPostHeadings = posts.at(0).getHeaders();
const firstPostHeadings = posts.at(0).getHeadings();
```

### Removed: using `rss` in `getStaticPaths()`

In Astro v3.0, using the deprecated `rss` helper in `getStaticPaths()` would throw an error.

Astro v4.0 removes this helper entirely.

#### What should I do?

If you are using the unsupported method for generating RSS feeds, you must now use the [`@astrojs/rss` integration](/en/recipes/rss/) for a complete RSS setup.

### Removed: lowercase HTTP method names

In Astro v3.0, using lowercase HTTP request method names (`get`, `post`, `put`, `all`, `del`) was deprecated.

Astro v4.0 removes support for lowercase names entirely. All HTTP request methods must now be written using uppercase.

#### What should I do?

If you are using the deprecated lowercase names, you must now replace them with their uppercase equivalents.

Please see the v3 migration guide [for guidance using uppercase HTTP request methods](/en/guides/upgrade-to/v3/#changed-http-request-methods-case).

### Removed: 301 redirects when missing a `base` prefix

In Astro v3.x, the Astro preview server returned a 301 redirect when accessing public directory assets without a base path.

Astro v4.0 returns a 404 status without a base path prefix for public directory assets when the preview server is running, matching the behavior of the dev server.

#### What should I do?

When using the Astro preview server, all of your static asset imports and URLs from the public directory must have [the base value](/en/reference/configuration-reference/#base) prefixed to the path.

The following example shows the `src` attribute required to display an image from the public folder when `base: '/docs'` is configured:

```
// To access public/images/my-image.png:

<img src="/docs/images/my-image.png" alt="">
```

### Removed: `astro/client-image` auto-conversion

In Astro v3.x, the `astro/client-image` type (used for the deprecated image integration) was removed but was auto-converted to the default Astro type `astro/client` if found in your `env.d.ts` file.

Astro v4.0 ignores `astro/client-image` and will no longer update `env.d.ts` for you automatically.

#### What should I do?

If you had types configured for `@astrojs/image` in `src/env.d.ts` and upgrading to v3.0 did not automatically convert the type for you, replace the `astro/client-image` type manually with `astro/client`.

```
  /// <reference types="astro/client-image" />
  /// <reference types="astro/client" />
```

## Community Resources

Know a good resource for Astro v4.0? [Edit this page](https://github.com/withastro/docs/edit/main/src/content/docs/en/guides/upgrade-to/v4.mdx) and add a link below!

## Known Issues

Please check [Astro's issues on GitHub](https://github.com/withastro/astro/issues/) for any reported issues, or to file an issue yourself.

## [Upgrade to Astro v5](https://docharvest.github.io/docs/astro/guides/upgrade-to/v5/)



## [Upgrade to Astro v6](https://docharvest.github.io/docs/astro/guides/upgrade-to/v6/)

Contents

astro

Upgrade to Astro v6

Astro

Upgrade to Astro v6

z.string().min(5, { error: "Too short." });

````

Also, if you use [`.default()` with transforms](https://zod.dev/v4/changelog#default-updates), you may need to update your schemas. In Zod 4, default values must match the output type (after transforms), not the input type. The default value short-circuits parsing when the input is `undefined`:

```ts title="src/content.config.ts" del={5-6} ins={7-8}

const blog = defineCollection({
  schema: z.object({
    // Zod 3: default matched input type (string)
    views: z.string().transform(Number).default("0"),
    // Zod 4: default must match output type (number)
    views: z.string().transform(Number).default(0),
  })
});
````

For the old behavior where defaults are parsed, use the new `.prefault()` method.

These are only some of the many changes upgrading from Zod 3 to Zod 4. If you encounter any issues with your Zod schemas after upgrading to Astro 6, please consult the [Zod 4 changelog](https://zod.dev/v4/changelog) for complete upgrade guidance.

Additionally, a [community codemod](https://github.com/nicoespeon/zod-v3-to-v4), which can potentially automate some of these changes when migrating from Zod 3 to Zod 4, is also available.

You can ensure you're the same version of Zod that Astro uses internally by [importing Zod from `astro/zod`](#deprecated-astroschema-and-z-from-astrocontent).

See more about [the `astro/zod` module](/en/reference/modules/astro-zod/).

### Shiki 4.0

Astro v6.0 upgrades to Shiki v4.0 for syntax highlighting.

#### What should I do?

If you are using Shiki-specific APIs, check the [Shiki migration guide](https://shiki.style/blog/v4) for their breaking changes and upgrade your project as needed.

### Official Astro integrations

All of [Astro's official server adapters](/en/guides/on-demand-rendering/#server-adapters) have also updated to a new major version to accompany the upgrade to Vite v7.0 with Vite's Environment API as the development server and production bundler.

In particular, Astro's Cloudflare adapter has undergone significant changes, and breaking changes to your existing Cloudflare setup are expected.

See the [Cloudflare adapter upgrade instructions](/en/guides/integrations-guide/cloudflare/#upgrading-to-v13-and-astro-6) for detailed migration guidance.

#### What should I do?

If you are using an Astro adapter for on-demand rendering or other platform-specific features, please check your specific adapter's changelog for upgrade guidance:

-   [`@astrojs/cloudflare` CHANGELOG](https://github.com/withastro/astro/blob/next/packages/integrations/cloudflare/CHANGELOG.md)
-   [`@astrojs/netlify` CHANGELOG](https://github.com/withastro/astro/blob/next/packages/integrations/netlify/CHANGELOG.md)
-   [`@astrojs/node` CHANGELOG](https://github.com/withastro/astro/blob/next/packages/integrations/node/CHANGELOG.md)
-   [`@astrojs/vercel` CHANGELOG](https://github.com/withastro/astro/blob/next/packages/integrations/vercel/CHANGELOG.md)

## Legacy

The following features are now considered legacy features. They should function normally but are no longer recommended and are in maintenance mode. They will see no future improvements and documentation will not be updated. These features will eventually be deprecated, and then removed entirely.

### Legacy: content collections backwards compatibility

In Astro 5.x, projects could delay upgrading to the new Content Layer API introduced for content collections because of some existing automatic backwards compatibility that was not previously behind a flag. This meant that it was possible to upgrade from Astro 4 to Astro 5 without updating your content collections, even if you had not enabled the `legacy.collections` flag. Projects would continue to build, and no errors or warnings would be displayed.

Astro v6.0 removes this automatic legacy content collections support, along with [the `legacy.collections` flag](#removed-legacy-content-collections). All content collections must now use [the Content Layer API introduced in Astro v5.0](https://astro.build/blog/content-layer-deep-dive/) that powers all content collections.

#### What should I do?

If you experience content collections errors after updating to v6, [check your project for any removed legacy features](#if-you-have) that may need updating to the Content Layer API.

See [the Astro v5 upgrade guide](/en/guides/upgrade-to/v5/#legacy-v20-content-collections-api) for detailed instructions on upgrading legacy collections to the new Content Layer API.

If you are unable to update immediately, you can enable [the `legacy.collectionsBackwardsCompat` flag](/en/reference/legacy-flags/#collectionsbackwardscompat) as a temporary migration helper:

This flag preserves some legacy v4 content collections features:

-   Supports the legacy configuration file `src/content/config.ts`
-   Supports `type: 'content'` and `type: 'data'` without loaders
-   Preserves legacy entry API: `entry.slug` and `entry.render()`
-   Uses path-based entry IDs instead of slug-based IDs

**This is a temporary migration helper.** Migrate your collections to the Content Layer API as soon as possible, then disable this flag.

## Deprecated

The following deprecated features are no longer supported and are no longer documented. Please update your project accordingly.

Some deprecated features may temporarily continue to function until they are completely removed. Others may silently have no effect, or throw an error prompting you to update your code.

### Deprecated: `Astro` in `getStaticPaths()`

In Astro 5.x, it was possible to access an `Astro` object inside `getStaticPaths()`. However, despite being typed the same as the `Astro` object accessible in the frontmatter, this object only had `site` and `generator` properties. This could lead to confusion about which `Astro` object properties were available inside `getStaticPaths()`.

Astro 6.0 deprecates this object for `getStaticPaths()` to avoid confusion and improves error handling when attempting to access `Astro` values that are unavailable. Using `Astro.site` or `Astro.generator` within `getStaticPaths()` will now log a deprecation warning, and accessing any other property will throw a specific error with a helpful message. In a future major version, this object will be removed entirely, and accessing `Astro.site` or `Astro.generator` will also throw an error.

#### What should I do?

Update your `getStaticPaths()` function if you were attempting to access any `Astro` properties inside its scope. Remove `Astro.generator` entirely, and replace all occurrences of `Astro.site` with `import.meta.env.SITE`:

```
---

  return getPages(Astro.site);
  return getPages(import.meta.env.SITE);
}
---
```

Read more about [built-in environment variables such as `import.meta.env.SITE`](/en/guides/environment-variables/#default-environment-variables) that are accessible when [using `getStaticPaths()` to dynamically generate static routes](/en/guides/routing/#static-ssg-mode).

### Deprecated: `import.meta.env.ASSETS_PREFIX`

In Astro 5.x, it was possible to access `build.assetsPrefix` in your Astro config via the built-in environment variable `import.meta.env.ASSETS_PREFIX`. However, Astro v5.7.0 introduced the `astro:config` virtual module to expose a non-exhaustive, serializable, type-safe version of the Astro configuration which included access to `build.assetsPrefix` directly. This became the preferred way to access the prefix for Astro-generated asset links when set, although the environment variable still existed.

Astro 6.0 deprecates this variable in favor of `build.assetsPrefix` from the `astro:config/server` module.

#### What should I do?

Replace any occurrences of `import.meta.env.ASSETS_PREFIX` with the `build.assetsPrefix` import from `astro:config/server`. This is a drop-in replacement to provide the existing value, and no other changes to your code should be necessary:

Update any occurrences of the other deprecated exports:

```

console.log(isTransitionBeforePreparationEvent(event));
console.log(event.type === 'astro:before-preparation');

console.log(TRANSITION_AFTER_SWAP);
console.log('astro:after-swap');
```

Learn more about all utilities available in the [View Transitions Router API Reference](/en/reference/modules/astro-transitions/).

### Deprecated: session driver string signature

In Astro 5.x, any [unstorage provider](https://unstorage.unjs.io/drivers) name or a custom entrypoint could be provided to define a session driver, and options were also provided directly to the `session` configuration. However, we felt that this API was limited and inconsistent with other parts of the Astro config.

Astro 6.0 deprecates the driver string signature and options in favor of a new object shape.

#### What should I do?

Update your session config to use the newly exported `sessionDrivers`:

```

  const handler = async (req, res) => {
    const response = await app.render(req);
    await NodeApp.writeResponse(response, res);
  };

  return { handler };
}

const app = createApp();

  const response = await app.render(request);
  await writeResponse(response, res);
}
```

Learn more about [the `astro/app/node` module](/en/reference/modules/astro-app/#imports-from-astroappnode).

### Deprecated: `loadManifest()` and `loadApp()` from `astro/app/node` (Adapter API)

In Astro 5.x, the `astro/app/node` exposed `loadManifest()` and `loadApp()` utilities to allow loading the SSR manifest or a `NodeApp` instance from a `URL` instance. However, these were not documented and are no longer recommended usage with the v6 Adapter API.

Astro 6.0 deprecates both functions.

#### What should I do?

If you have built an adapter, remove `loadManifest()` and replace `loadApp()` by `createApp()`:

```

const manifest = await loadManifest(new URL(import.meta.url));
const app1 = new NodeApp(loadManifest);
const app2 = await loadApp(new URL(import.meta.url));

const app = createApp();
```

Learn more about [the `astro/app/entrypoint` module](/en/reference/modules/astro-app/#imports-from-astroappentrypoint).

### Deprecated: `createExports()` and `start()` (Adapter API)

In Astro 5.x, adapters had to provide the exports required by the host in their server entrypoint using a `createExports()` function before passing them to `setAdapter()` as an `exports` list.

Astro 6.0 introduces a simpler yet more powerful way of making server entrypoints. This relies on passing a new option `entrypointResolution: "auto"` to `setAdapter()`.

However, for backwards compatibility with existing adapters, the default value of `entrypointResolution` (`"explicit"`) mimics Astro 5.x API behavior. This means that your adapters can continue to function until you can fully migrate your adapter to the `auto` value, as shown below.

Note that `entrypointResolution: "explicit"` (maintaining v5 API behavior) is considered deprecated usage, but the option has been provided so that no immediate change to your adapter is required and to allow adapter authors time to update. This option will be removed in a future major version in favor of all adapters using `entrypointResolution: "auto"`.

#### What should I do?

If you are an adapter author with a public repository and [include the `astro-adapter` keyword in your `package.json`](/en/guides/integrations/#categories), the Astro core team will attempt to make a PR to your repository directly to help you migrate your code if you have not yet followed the steps below.

If you are seeing warnings because you are using a community adapter that is not yet updated, please reach out to the adapter author directly to let them know. It is ultimately their responsibility to update their adapters. You can also let the Astro core team know in the [`#integrations` channel of our Discord](https://astro.build/chat) and we will attempt to help the adapter author upgrade.

If you have built an adapter, follow these steps to remove the legacy v5 behavior:

1.  Update your `setAdapter()`: set `entrypointResolution: "auto"`, remove `exports` and `args`
    
    ```
    setAdapter({
      // ...
      entrypointResolution: 'auto',
      exports: ['handler'],
      args: { assets: config.build.assets }
    })
    ```
    
2.  Update your server entrypoint to provide any required exports without `createExports()`:
    
    ```
    import { App } from 'astro/app';
    
    export function createExports(manifest) {
      const app = new App(manifest);
    
      const handler = (event, context) => {
        // ...
      };
    
      return { handler };
    }
    import { createApp } from 'astro/app/entrypoint';
    
    const app = createApp();
    
    export const handler = (event, context) => {
      // ...
    }
    ```
    
3.  If your adapter provides a `start()` function, update your server entrypoint to call the code directly:
    
    ```
    import { App } from 'astro/app';
    
    export function start(manifest) {
      const app = new App(manifest);
    
      addEventListener('fetch', event => {
        // ...
      });
    }
    import { createApp } from 'astro/app/entrypoint';
    
    const app = createApp();
    
    addEventListener('fetch', event => {
      // ...
    });
    ```
    
4.  If you were relying on `args`, [create a virtual module to pass the build time configuration](/en/reference/adapter-reference/#passing-build-time-configuration) and import them from the virtual module instead:
    
    ```
    export function createExports(manifest, { assets }) {
      // ...
    }
    import { assets } from 'virtual:@example/my-adapter:config';
    ```
    

Learn more about [the Adapter API](/en/reference/adapter-reference/).

## Removed

The following features have now been entirely removed from the code base and can no longer be used. Some of these features may have continued to work in your project even after deprecation. Others may have silently had no effect.

Projects now containing these removed features will be unable to build, and there will no longer be any supporting documentation prompting you to remove these features.

### Removed: legacy content collections

In Astro 5.x, it was still possible to use [the original Content Collections API first introduced in Astro v2.0](https://astro.build/blog/introducing-content-collections/), **either through a `legacy` configuration flag or via built-in backwards compatibility**. These methods allowed you to upgrade to Astro v5 even if you were not yet ready or able to update your existing content collections to those powered by the new Content Layer API.

Astro v6.0 removes this previously deprecated Content Collections API support entirely, including the `legacy.collections` flag **and some existing backwards compatibility that was not previously behind a flag**. All content collections must now use [the Content Layer API introduced in Astro v5.0](https://astro.build/blog/content-layer-deep-dive/) that powers all content collections. **No backwards compatibility support is available.**

#### What should I do?

If you had previously enabled the legacy flag, you must remove it.

a collection that defines a collection type (\`type: 'content'\` or \`type: 'data'\`) / (\[\`ContentCollectionInvalidTypeError\`\](/en/reference/errors/content-collection-invalid-type/)) There are no longer different types of collections. This must be deleted from your collection definition.

```
// src/content.config.ts

const blog = defineCollection({
  // For content layer you no longer define a `type`
  type: 'content',
  loader: glob({ pattern: '**/[^_]*.{md,mdx}', base: "./src/data/blog" }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
  }),
});
```

legacy collection querying methods \`getDataEntryById()\` and \`getEntryBySlug()\` / (\[\`GetEntryDeprecationError\`\](/en/reference/errors/get-entry-deprecation-error/)) Replace both methods with \[\`getEntry()\`\](/en/reference/modules/astro-content/#getentry). legacy collection querying and rendering methods that depend on a \`slug\` property / (\[\`ContentSchemaContainsSlugError\`\](/en/reference/errors/content-schema-contains-slug-error/)) Previously, the \`id\` was based on the filename, and there was a \`slug\` property that could be used in a URL. Now the \[\`CollectionEntry\`\](/en/reference/modules/astro-content/#collectionentry) \`id\` is a slug. If you need access to the filename (previously available as the \`id\`), use the \`filePath\` property. Replace instances of \`slug\` with \`id\`:

```
---

  return posts.map((post) => ({
    params: { slug: post.slug },
    params: { slug: post.id },
    props: post,
  }));
}
---
```

content rendered using \`entry.render()\` Collection entries no longer have a \`render()\` method. Instead, import the \`render()\` function from \`astro:content\` and use \`render(entry)\`:

```
---

const post = await getEntry('pages', 'homepage');

const { Content, headings } = await post.render();
const { Content, headings } = await render(post);
---
<Content />
```

See [the Astro v5 upgrade guide](/en/guides/upgrade-to/v5/#legacy-v20-content-collections-api) for previous guidance about backwards compatibility of legacy collections in Astro v5 and full step-by-step instructions for upgrading legacy collections to the new Content Layer API.

### Removed: `<ViewTransitions />` component

In Astro 5.0, the `<ViewTransitions />` component was renamed to `<ClientRouter />` to clarify the role of the component. The new name makes it more clear that the features you get from Astro's `<ClientRouter />` routing component are slightly different from the native CSS-based MPA router. However, a deprecated version of the `<ViewTransitions />` component still existed and may have functioned in Astro 5.x.

Astro 6.0 removes the `<ViewTransitions />` component entirely and it can no longer be used in your project. Update to the `<ClientRouter />` component to continue to use these features.

#### What should I do?

Replace all occurrences of the `ViewTransitions` import and component with `ClientRouter`:

```

<html>
  <head>
    ...
    <ViewTransitions />
    <ClientRouter />
  </head>
</html>
```

Read more about [view transitions and client-side routing in Astro](/en/guides/view-transitions/).

### Removed: `emitESMImage()`

In Astro 5.6.2, the `emitESMImage()` function was deprecated in favor of `emitImageMetadata()`, which removes two deprecated arguments that were not meant to be exposed for public use: `_watchMode` and `experimentalSvgEnabled`.

Astro 6.0 removes `emitESMImage()` entirely. Update to `emitImageMetadata()` to keep your current behavior.

#### What should I do?

Replace all occurrences of the `emitESMImage()` with `emitImageMetadata()` and remove unused arguments:

```

const imageId = '/images/photo.jpg';
const result = await emitESMImage(imageId, false, false);
const result = await emitImageMetadata(imageId);
```

Read more about [`emitImageMetadata()`](/en/reference/modules/astro-assets/#emitimagemetadata).

### Removed: `Astro.glob()`

In Astro 5.0, `Astro.glob()` was deprecated in favor of using `getCollection()` to query your collections, and `import.meta.glob()` to query other source files in your project.

Astro 6.0 removes `Astro.glob()` entirely. Update to `import.meta.glob()` to keep your current behavior.

#### What should I do?

Replace all use of `Astro.glob()` with `import.meta.glob()`. Note that `import.meta.glob()` no longer returns a `Promise`, so you may have to update your code accordingly. You should not require any updates to your [glob patterns](/en/guides/imports/#glob-patterns).

```
---
const posts = await Astro.glob('./posts/*.md');
const posts = Object.values(import.meta.glob('./posts/*.md', { eager: true }));
---

{posts.map((post) => <li><a href={post.url}>{post.frontmatter.title}</a></li>)}
```

Where appropriate, consider using [content collections](/en/guides/content-collections/) to organize your content, which has its own newer, more performant querying functions.

You may also wish to consider using glob packages from NPM, such as [`fast-glob`](https://www.npmjs.com/package/fast-glob).

Learn more about [importing files with `import.meta.glob`](/en/guides/imports/#importmetaglob).

### Removed: exposed `astro:actions` internals

In Astro 5.x, some internals were exported from `astro:actions` that were not meant to be exposed for public use.

Astro 6.0 removes the following functions, classes and types as exports from the `astro:actions` virtual module. These can no longer be imported in your project files:

-   `ACTION_ERROR_CODES`
-   `ActionInputError`
-   `appendForwardSlash`
-   `astroCalledServerError`
-   `callSafely`
-   `deserializeActionResult`
-   `formDataToObject`
-   `getActionQueryString`
-   `serializeActionResult`
-   `type Actions`
-   `type ActionAccept`
-   `type AstroActionContext`
-   `type SerializedActionResult`

#### What should I do?

Replace all imports of `serializeActionResult()` and `deserializeActionResult()` with `getActionContext()`. These two methods are now available through `getActionContext()`:

```

  // ...
});
```

Remove any occurrences of the other removed exports:

Learn more about all utilities available in the [Actions API Reference](/en/reference/modules/astro-actions/).

### Removed: Percent-Encoding in routes

In Astro 5.x, it was possible to include a percent-encoded percent sign (`%25`) in filenames.

Astro 6.0 removes support for the characters `%25` in filenames for security reasons. This restriction prevents encoding-based security bypasses where `%25` decodes to `%`, potentially leading to ambiguous or invalid encoding sequences.

#### What should I do?

If you have route files with `%25` in the filename, rename them to use a different character:

```
src/pages/test%25file.astro
src/pages/test-file.astro
```

### Removed: `astro:ssr-manifest` virtual module (Integration API)

In Astro 5.x, the deprecated `astro:ssr-manifest` virtual module could still be used to access configuration values.

Astro 6.0 removes the `astro:ssr-manifest` virtual module entirely. It is no longer used by integrations or internally by Astro. The manifest is now passed directly through integration hooks and adapter APIs rather than through a virtual module. For build-specific manifest data, use the `astro:build:ssr` integration hook, which receives the manifest as a parameter.

#### What should I do?

If your integration or code imports from `astro:ssr-manifest`, use `astro:config/server` instead to access configuration values:

```

// Use srcDir, outDir, root, etc. for configuration values
```

Learn more about [the `astro:config` virtual module](/en/reference/modules/astro-config/).

### Removed: `RouteData.generate()` (Adapter API)

In Astro 5.x, routes could be generated using the `generate()` method on `RouteData`.

Astro 6.0 removes `RouteData.generate()` because route generation is now handled internally by Astro.

#### What should I do?

Remove any calls to `route.generate()` in your code. This method is no longer needed:

```
const generated = route.generate(params);
```

Learn more about [the Adapter API](/en/reference/adapter-reference/).

### Removed: `routes` on `astro:build:done` hook (Integration API)

In Astro 5.0, accessing `routes` on the `astro:build:done` hook was deprecated.

Astro 6.0 removes the `routes` array passed to this hook entirely. Instead, the `astro:routes:resolved` hook should be used.

#### What should I do?

Remove any instance of `routes` passed to `astro:build:done` and replace it with the new `astro:routes:resolved` hook. Access `distURL` on the newly exposed `assets` map:

```
const integration = () => {
    let routes
    return {
        name: 'my-integration',
        hooks: {
            'astro:routes:resolved': (params) => {
                routes = params.routes
            },
            'astro:build:done': ({
                routes
                assets
            }) => {
                for (const route of routes) {
                    const distURL = assets.get(route.pattern)
                    if (distURL) {
                        Object.assign(route, { distURL })
                    }
                }
                console.log(routes)
            }
        }
    }
}
```

Learn more about [the Integration API `astro:routes:resolved` hook](/en/reference/integrations-reference/#astroroutesresolved) for building integrations.

### Removed: `entryPoints` on `astro:build:ssr` hook (Integration API)

In Astro 5.0, [`functionPerRoute` was deprecated](/en/guides/upgrade-to/v5/#deprecated-functionperroute-adapter-api). That meant that `entryPoints` on the `astro:build:ssr` hook was always empty.

Astro 6.0 removes the `entryPoints` map passed to this hook entirely.

#### What should I do?

Remove any instance of `entryPoints` passed to `astro:build:ssr`:

```
const integration = () => {
    return {
        name: 'my-integration',
        hooks: {
            'astro:build:ssr': (params) => {
                someLogic(params.entryPoints)
            },
        }
    }
}
```

### Removed: old `app.render()` signature (Adapter API)

In Astro 4.0, the `app.render()` signature that allowed passing `routeData` and `locals` as optional arguments was deprecated in favor of a single optional `renderOptions` argument.

Astro 6.0 removes this signature entirely. Attempting to pass these separate arguments will now cause an error in your project.

#### What should I do?

Review your `app.render()` calls and pass `routeData` and `locals` as properties of an object instead of as multiple independent arguments:

```
app.render(request, routeData, locals)
app.render(request, { routeData, locals })
```

Learn more about the [Adapter API](/en/reference/adapter-reference/).

### Removed: `app.setManifestData()` (Adapter API)

In Astro 5.0, the `app.setManifestData()` method was available on `App` and `NodeApp`, but is no longer used nor needed.

Astro 6.0 removes this method entirely.

#### What should I do?

Remove any call to `app.setManifestData()`. If you need to update the manifest, create a new `App` instance.

Learn more about the [Adapter API](/en/reference/adapter-reference/).

### Removed: `handleForms` prop for the `<ClientRouter />` component

In Astro 4.0, the `handleForms` prop of the `<ClientRouter />` component was deprecated, as it was no longer necessary to opt in to handling `submit` events for `form` elements. This functionality has been built in by default and the property, if still included in your project, silently had no impact on form submission.

Astro 6.0 removes this prop entirely and it now must be removed to avoid errors in your project.

#### What should I do?

Remove the `handleForms` property from your `<ClientRouter />` component if it exists. It has provided no additional functionality, and so removing it should not change any behavior in your project:

```
---

---
<html>
  <head>
    <ClientRouter handleForms />
  </head>
  <body>
    <!-- stuff here -->
  </body>
</html>
```

Learn more about [transitions with forms](/en/guides/view-transitions/#transitions-with-forms).

### Removed: `prefetch()` `with` option

In Astro 4.8.4, the `with` option of the programmatic `prefetch()` function was deprecated in favor of a more sensible default behavior that no longer required specifying the priority of prefetching for each page.

Astro 6.0 removes this option entirely and it is no longer possible to configure the priority of prefetching by passing the `with` option. Attempting to do so will now cause errors.

By default, Astro's prefetching now uses an automatic approach that will always try to use `<link rel="prefetch>` if supported, or will fall back to `fetch()`.

#### What should I do?

Review your `prefetch()` calls and remove the `with` option if it still exists:

```
prefetch('/about', { with: 'fetch' });
prefetch('/about');
```

Learn more about [prefetching](/en/guides/prefetch/).

### Removed: `rewrite()` from Actions context

In Astro 5.5.6, the `ActionAPIContext.rewrite()` method was deprecated because custom endpoints should be used instead of rewrites.

Astro 6.0 removes the `rewrite()` method from `ActionAPIContext` entirely and it may no longer be used.

#### What should I do?

Review your Actions handlers and remove any call to `rewrite()`:

```

  }
</style>
<style>
  body {
    background: yellow;
    background: red;
  }
</style>
<script>
    console.log("hello")
    console.log("world")
</script>
<script>
    console.log("world!")
    console.log("hello!")
</script>
```

Read more about [using `script`](/en/guides/client-side-scripts/) and [`style`](/en/guides/styling/) tags.

### Changed: how responsive image styles are emitted

In Astro 5.x, images were computed at runtime and the `fit` and `pos` responsive image styles were injected in a `style` attribute. This did not allow compatibility with Astro's Content Security Policy (CSP) for many reasons.

Astro 6 generates image styles inside a virtual module at build time based on project configuration, resulting in a hash class and `data-*` attributes to apply responsive styling to your images.

#### What should I do?

Visually inspect your images to ensure that they are rendering as expected. This is an implementation detail that should not affect the expected use of responsive images.

However, if you were relying on the inline styles previously generated for your images:

```
<img style="--fit: <value>; --pos: <value>" >
```

then you will need to update your project code to account for the new `data-*` attributes instead:

```
<img class="__a_HaSh350" data-astro-fit="value" data-astro-pos="value" >
```

## Breaking Changes

The following changes are considered breaking changes in Astro v6.0. Breaking changes may or may not provide temporary backwards compatibility. If you were using these features, you may have to update your code as recommended in each entry.

### Changed: endpoints with a file extension cannot be accessed with a trailing slash

In Astro v5.0, custom endpoints whose URL ended in a file extension (e.g. `/src/pages/sitemap.xml.ts` ) could be accessed with a trailing slash (`/sitemap.xml/`) or without (`/sitemap.xml`), regardless of the value configured for `build.trailingSlash`.

In Astro v6.0, these endpoints can only be accessed without a trailing slash. This is true regardless of your `build.trailingSlash` configuration.

#### What should I do?

Review your links to your custom endpoints that include a file extension in the URL and remove any trailing slashes:

```
<a href="/sitemap.xml/">Sitemap</a>
<a href="/sitemap.xml">Sitemap</a>
```

Learn more about [custom endpoints](/en/guides/endpoints/).

### Changed: `import.meta.env` values are always inlined

In Astro 5.13, the `experimental.staticImportMetaEnv` flag was introduced to update the behavior when accessing `import.meta.env` directly to align with [Vite's handling of environment variables](https://vite.dev/guide/env-and-mode.html#env-variables) and ensures that `import.meta.env` values are always inlined.

In Astro 5.x, non-public environment variables were replaced by a reference to `process.env`. Additionally, Astro could also convert the value type of your environment variables used through `import.meta.env`, which could prevent access to some values such as the strings `"true"` (which was converted to a boolean value), and `"1"` (which was converted to a number).

Astro 6 removes this experimental flag and makes this the new default behavior in Astro: `import.meta.env` values are always inlined and never coerced.

#### What should I do?

If you were previously using this experimental feature, you must [remove this experimental flag from your configuration](#experimental-flags) as it no longer exists.

If you were relying on coercion, you may need to update your project code to apply it manually:

```
const enabled: boolean = import.meta.env.ENABLED;
const enabled: boolean = import.meta.env.ENABLED === "true";
```

If you were relying on the transformation into `process.env`, you may need to update your project code to apply it manually:

```
const enabled: boolean = import.meta.env.DB_PASSWORD;
const enabled: boolean = process.env.DB_PASSWORD;
```

You may also need to update types:

```
interface ImportMetaEnv {
  readonly PUBLIC_POKEAPI: string;
  readonly DB_PASSWORD: string;
  readonly ENABLED: boolean;
  readonly ENABLED: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

namespace NodeJS {
  interface ProcessEnv {
    DB_PASSWORD: string;
  }
}
```

If you need more control over environment variables in Astro, we recommend you use `astro:env`.

Learn more about [environment variables](/en/guides/environment-variables/) in Astro, including `astro:env`.

### Changed: Cropping by default in default image service

In Astro 5.0, the default image service would only apply cropping when the `fit` option was provided.

Astro 6.0 applies cropping by default without requiring setting the `fit` option.

#### What should I do?

No changes are needed to your existing cropped images as the `fit` property is still valid. However, if you were previously setting `fit` to `contain` (its default value) in order to crop your images, you may now remove this option and still achieve the same cropping behavior by specifying `width` and `height` alone:

```
---

---
<Image src={myImage} width={400} height={300} fit="contain" />
<Image src={myImage} width={400} height={300} />
```

### Changed: Never upscale images in default image service

In Astro 5.x, the default image service would upscale images when the requested dimensions were larger than the source image.

Astro 6.0 removes this behavior: the default image service never upscales images.

#### What should I do?

Review your images and update dimensions as needed. If you do need to upscale images, you may consider upscaling the images manually or using a custom image service that supports upscaling.

### Changed: SVG rasterization

In Astro v5.x, Astro's default Sharp image service was unable to convert SVG files to raster files (e.g. PNG, WebP). This meant that the `<Image />` component would ignore any value set for `format` when optimizing and transforming SVG files.

Astro 6.0 now supports SVG rasterization. This is subject to [many limitations](https://github.com/lovell/sharp/issues?q=is%3Aissue%20state%3Aopen%20svg), for instance, SVGs with embedded fonts might not be converted properly. However, when the `format` property is set, the image service will now attempt to convert SVG images.

#### What should I do?

If you were previously relying on the fact that the image service would automatically skip converting SVGs, you must now check the format of your images beforehand to avoid converting SVGs to raster images:

```
<Image src={imageThatMightBeAnSvg} format="avif" alt="example" />

<Image
	src={imageThatMightBeAnSvg}
	format={imageThatMightBeAnSvg.format === "svg" ? "svg" : "avif"}
	alt="example"
/>
```

Learn more about [the `format` image property](/en/reference/modules/astro-assets/#format).

### Changed: `getImage()` throws when called on the client

In Astro 5.x, calling `getImage()` from `astro:assets` on the client would silently fail or produce incorrect results.

Astro 6.0 throws a runtime error when `getImage()` is called on the client.

#### What should I do?

Call `getImage()` on the server and pass the resulting `src` to the client instead:

```
---

const optimizedBackground = await getImage({ src: myBackground, format: "avif" });
---

<div id="background" data-src={optimizedBackground.src}></div>

<script>
  const src = document.getElementById("background").dataset.src;
  // use src client-side as needed
</script>
```

See [generating images with `getImage()`](/en/guides/images/#generating-images-with-getimage) for a full example.

### Changed: Markdown heading ID generation

In Astro 5.x, an additional default processing step to Markdown stripped trailing hyphens from the end of IDs for section headings ending in special characters. This provided a cleaner `id` value, but could lead to incompatibilities rendering your Markdown across platforms.

In Astro 5.5, the `experimental.headingIdCompat` flag was introduced to allow you to make the IDs generated by Astro for Markdown headings compatible with common platforms like GitHub and npm, using the popular [`github-slugger`](https://github.com/Flet/github-slugger) package.

Astro 6.0 removes this experimental flag and makes this the new default behavior in Astro: trailing hyphens from the end of IDs for headings ending in special characters are no longer removed.

#### What should I do?

If you have manual links to headings, you may need to update the anchor link value with a new trailing hyphen. For example, the following Markdown heading:

```
## `<Picture />`
```

will now generate the following HTML with a trailing hyphen in the heading `id`:

```
<h2 id="picture-"><code>&lt;Picture /&gt;</code></h2>
```

and must now be linked to as:

```
See [the Picture component](/en/guides/images/#picture-) for more details.
```

If you were previously using the experimental feature to enforce trailing hyphens, you must [remove this experimental flag from your configuration](#experimental-flags) as it no longer exists.

If you were previously using the `rehypeHeadingIds` plugin directly to enforce compatibility, remove the `headingIdCompat` option as it no longer exists:

If you want to keep the old ID generation for backward compatibility reasons, you can create a custom rehype plugin that will generate headings IDs like Astro 5.x. This will allow you to continue to use your existing anchor links without adding trailing hyphens.

Create a custom rehype plugin to strip trailing hyphens

1.  Install required dependencies:
    
    \`\`\`sh npm i github-slugger hast-util-heading-rank unist-util-visit hast-util-to-string \`\`\` \`\`\`sh pnpm add github-slugger hast-util-heading-rank unist-util-visit hast-util-to-string \`\`\` \`\`\`sh yarn add github-slugger hast-util-heading-rank unist-util-visit hast-util-to-string \`\`\`
2.  Create a custom rehype plugin that will generate headings IDs like Astro v5:
    
    ```
    import GithubSlugger from 'github-slugger';
    import { headingRank } from 'hast-util-heading-rank';
    import { visit } from 'unist-util-visit';
    import { toString } from 'hast-util-to-string';
    
    const slugs = new GithubSlugger();
    
    export function rehypeSlug() {
      /**
       * @param {import('hast').Root} tree
       */
      return (tree) => {
        slugs.reset();
        visit(tree, 'element', (node) => {
          if (headingRank(node) && !node.properties.id) {
            let slug = slugs.slug(toString(node));
            // Strip trailing hyphens like in Astro v5 and below:
            if (slug.endsWith('-')) slug = slug.slice(0, -1);
            node.properties.id = slug;
          }
        });
      };
    }
    ```
    
3.  Add the custom plugin to your Markdown configuration in `astro.config.mjs`:
    
    ```
    import { defineConfig } from 'astro/config';
    import { rehypeSlug } from './plugins/rehype-slug';
    
    export default defineConfig({
      markdown: {
        rehypePlugins: [rehypeSlug],
      },
    });
    ```
    

Learn more about [Heading IDs](/en/guides/markdown-content/#heading-ids).

### Changed: `getStaticPaths()` cannot return `params` of type number

In Astro 5.x, `getStaticPaths()` could return `params` of type number, which would always be stringified by Astro. However, that could be confusing because it conflicted with `Astro.params` types.

Astro 6.0 removes this behavior: `getStaticPaths()` must now return string or undefined `params` values.

#### What should I do?

Review your dynamic routes using `getStaticPaths()` and convert any number params to strings:

```
---
```

Learn more about [testing Astro components](/en/guides/testing/).

### Changed: Rollup output file name config path (Vite config)

In Astro 5.x, custom Rollup output file name options for client assets could be configured at `vite.build.rollupOptions.output`.

Astro 6.0 scopes client build output configuration to Vite's client environment. If you customize `entryFileNames`, `chunkFileNames`, or `assetFileNames` for client assets, use `vite.environments.client.build.rollupOptions.output`.

#### What should I do?

Move your config from `vite.build.rollupOptions.output` to `vite.environments.client.build.rollupOptions.output`:

### Changed: Integration hooks and HMR access patterns (Integration API)

In Astro 5.x, Astro relied on certain patterns for integration hooks and HMR access that were incompatible with or could be improved by integrating Vite's Environment API.

Astro 6.0 uses Vite's new Environment API for build configuration and dev server interactions. This primarily enables dev mode in runtimes like workerd, but means that some integration hooks and HMR access patterns have changed.

#### What should I do?

**For integrations using `astro:build:setup`:**

The hook is now called once with all environments configured (`ssr`, `client`, `prerender`), instead of being called separately for each build target. Remove the `target` parameter and use `vite.environments` to configure specific environments:

```
{
  hooks: {
    'astro:build:setup': ({ target, vite }) => {
      if (target === 'client') {
        vite.build.minify = false;
      }
    }
    'astro:build:setup': ({ vite }) => {
      vite.environments.client.build.minify = false;
    }
  }
}
```

**For dev toolbar and integration code accessing HMR:**

Replace `server.hot.send()` with `server.environments.client.hot.send()`:

```
server.hot.send(event)
server.environments.client.hot.send(event)
```

Learn more about the [Vite Environment API](https://vite.dev/guide/api-environment) and Astro [integration hooks](/en/reference/integrations-reference/#astrobuildsetup).

### Changed: `SSRManifest` interface structure (Adapter API)

In Astro 5.x, path properties of the `SSRManifest` interface like `srcDir`, `outDir`, `cacheDir`, `publicDir`, `buildClientDir`, and `buildServerDir` were URL strings.

Astro 6.0 changes the form of these path properties to `URL` objects instead of URL strings. With this change, several new properties are now available on the manifest, and others have been updated or removed.

#### What should I do?

If you were treating these path properties as strings, you will now need to handle the `URL` object. For example, you will now need to access the `href` property of the `URL` object:

```
// To retrieve the same format (e.g., "file:///path/to/src"), make the following change:
const srcPath = manifest.srcDir;
const srcPath = manifest.srcDir.href;
```

If you were accessing the `hrefRoot` property, you will need to remove it, as it is no longer available on the manifest.

Update any use of `serverIslandMappings` and `sessionDriver`. These are now async methods:

```
const mappings = manifest.serverIslandMappings;
const driver = manifest.sessionDriver;
const mappings = await manifest.serverIslandMappings?.();
const driver = await manifest.sessionDriver?.();
```

Learn more about [the Adapter API](/en/reference/adapter-reference/).

### Changed: schema types are inferred instead of generated (Content Loader API)

In Astro 5.x, the types for content collections were generated using `zod-to-ts` when provided by a content loader and not defined by a user-provided schema.

Astro 6.0 removes this behavior: types are no longer generated using `zod-to-ts`. Instead, types are inferred.

#### What should I do?

If you are providing a `schema` in a content loader, you must use the [TypeScript' `satisfies` operator](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html#the-satisfies-operator):

```
import type { Loader } from 'astro/loaders'

function myLoader(): Loader {
function myLoader() {
  return {
    name: 'my-loader',
    load: async (context) => {
      // ...
    },
    schema: z.object({/* ... */})
  }
  } satisfies Loader
}
```

Learn more about [defining loader schema types](/en/reference/content-loader-reference/#the-loader-object).

## Known Issues

Please check [Astro's issues on GitHub](https://github.com/withastro/astro/issues/) for any reported issues, or to file an issue yourself.

## [Upgrade to Astro v7](https://docharvest.github.io/docs/astro/guides/upgrade-to/v7/)

Contents

astro

Upgrade to Astro v7

Astro

Upgrade to Astro v7

````
export default defineConfig({
  // specify a different file for advanced routing configuration:
  fetchFile: './src/router.ts',
  // or disable advanced routing entirely:
  // fetchFile: null,
});
```
````

-   **Rename your file** to something else (e.g. `src/fetcher.ts`, `src/main.ts`), and update any imports that reference it.

### New default Markdown processor: Sätteri

Astro now renders your `.md` and `.mdx` files with [Sätteri](https://satteri.bruits.org/), its native Markdown pipeline, instead of the remark/rehype pipeline. As a result, `@astrojs/markdown-remark` is no longer installed by default.

#### What should I do?

If you don't use remark or rehype plugins, you don't need to do anything. Your Markdown and MDX will now be rendered by Sätteri, which applies GitHub-Flavored Markdown and SmartyPants just like before.

If you depend on remark and rehype plugins, you can port them to [Sätteri MDAST or HAST plugins](https://satteri.bruits.org/docs/plugins/). If you depend on recma plugins, or if you are not yet ready or able to port your remark and rehype plugins, you can [stay on the `unified()` pipeline](/en/guides/markdown-content/#switching-to-the-unified-processor).

To keep using unified plugins:

1.  Install `@astrojs/markdown-remark`:
    
    \`\`\`shell npm install @astrojs/markdown-remark \`\`\` \`\`\`shell pnpm add @astrojs/markdown-remark \`\`\` \`\`\`shell yarn add @astrojs/markdown-remark \`\`\`
2.  Set [`unified()` as your Markdown processor](/en/guides/markdown-content/#switching-to-the-unified-processor):
    
    ```
    import { defineConfig } from 'astro/config';
    import { unified } from '@astrojs/markdown-remark';
    
    export default defineConfig({
      markdown: {
        processor: unified(),
      },
    });
    ```
    

The deprecated `markdown.remarkPlugins`, `markdown.rehypePlugins`, and `markdown.remarkRehype` options still work, but now also require `@astrojs/markdown-remark` to be installed.

### New default whitespace handling: `compressHTML: 'jsx'`

In Astro v6.x, whitespace handling used HTML-aware compression by default. This means that Astro would preserve a single space between inline elements, [following HTML rules](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Text/Whitespace#how_does_html_process_whitespace).

In Astro v7.0, the default value of [`compressHTML`](/en/reference/configuration-reference/#compresshtml) has changed from `true` to `'jsx'`. Now, Astro strips whitespace from your HTML using JSX rules by default, the same way frameworks like React do.

The following example would render as `helloworld` in Astro v7.0, instead of `hello world` in Astro v6.x:

```
<span>hello</span>
<em>world</em>
```

#### What should I do?

Visually inspect your website to ensure that the spaces between elements are rendered as expected. You may not need to take any further action.

If you notice that some spaces are missing, identify the components and pages where you are using [inline elements](https://developer.mozilla.org/en-US/docs/Glossary/Inline-level_content). Then, update them to add an explicit space between these elements using `{" "}`:

```
<span>hello</span>
<em>world</em>
<span>hello</span> <em>world</em>
```

If you prefer to keep the previous behavior, set `compressHTML` to `true`. You can also use `compressHTML: false` to preserve all whitespace.

## Deprecated

The following deprecated features are no longer supported and are no longer documented. Please update your project accordingly.

Some deprecated features may temporarily continue to function until they are completely removed. Others may silently have no effect, or throw an error prompting you to update your code.

### Deprecated: `getContainerRenderer()` from integration package roots

In Astro 6.x, the [`getContainerRenderer()`](/en/reference/container-reference/#adding-a-renderer-through-the-container-api) helper used with the Container API was imported from an official integration's package root (e.g. `@astrojs/react`). This could cause bundlers to pull in unrelated, build-time-only exports from the package root when only the Container API was needed.

Astro 7.0 deprecates importing `getContainerRenderer()` from an integration's package root in favor of a dedicated `container-renderer` entrypoint.

#### What should I do?

Update your Container API imports to use the new `container-renderer` entrypoint for each official integration:

```
- import { getContainerRenderer } from '@astrojs/react';
+ import { getContainerRenderer } from '@astrojs/react/container-renderer';
```

This entrypoint is available for `@astrojs/react`, `@astrojs/preact`, `@astrojs/solid-js`, `@astrojs/svelte`, `@astrojs/vue`, and `@astrojs/mdx`.

## Removed

The following features have now been entirely removed from the code base and can no longer be used. Some of these features may have continued to work in your project even after deprecation. Others may have silently had no effect.

Projects now containing these removed features will be unable to build, and there will no longer be any supporting documentation prompting you to remove these features.

### Removed: `@astrojs/db`

The `@astrojs/db` package has been removed in Astro v7.0 and is no longer maintained.

#### What should I do?

Remove `@astrojs/db` from your project's dependencies and replace it with one of the following alternatives:

-   **Node.js built-in SQLite**: Node.js now includes a built-in [`node:sqlite`](https://nodejs.org/api/sqlite.html) module (available since Node.js v22.5.0). This is a good option if you are using the Node.js adapter and were using `@astrojs/db` for local SQLite storage.
    
-   **[Drizzle ORM](https://orm.drizzle.team/)**: If you were using `@astrojs/db` for its Drizzle-based schema and query API, you can use Drizzle directly with any supported database.
    
-   **Other database libraries**: Use any database library that suits your deployment platform (e.g. [Turso](https://turso.tech/), [PlanetScale](https://planetscale.com/), [Neon](https://neon.tech/)).
    

### Removed: exposed `astro:transitions` internals

In Astro 6.x, some helpers available in `astro:transitions` and `astro:transitions/client` were deprecated.

In Astro 7.0, the following APIs can no longer be used in your project:

-   `TRANSITION_BEFORE_PREPARATION`
-   `TRANSITION_AFTER_PREPARATION`
-   `TRANSITION_BEFORE_SWAP`
-   `TRANSITION_AFTER_SWAP`
-   `TRANSITION_PAGE_LOAD`
-   `isTransitionBeforePreparationEvent()`
-   `isTransitionBeforeSwapEvent()`
-   `createAnimationScope()`

#### What should I do?

Remove any occurrence of `createAnimationScope()`:

```
-import { createAnimationScope } from 'astro:transitions';
```

Replace any occurrence of the other APIs using the [lifecycle event names](/en/reference/modules/astro-transitions/#lifecycle-events) directly:

```
-import {
-	TRANSITION_AFTER_SWAP,
-	isTransitionBeforePreparationEvent,
-} from 'astro:transitions/client';

-console.log(isTransitionBeforePreparationEvent(event));
+console.log(event.type === 'astro:before-preparation');

-console.log(TRANSITION_AFTER_SWAP);
+console.log('astro:after-swap');
```

Learn more about all utilities available in the [View Transitions Router API Reference](/en/reference/modules/astro-transitions/).

## [View transitions](https://docharvest.github.io/docs/astro/guides/view-transitions/)



## [Install Astro](https://docharvest.github.io/docs/astro/install-and-setup/)



## [Astro recipes](https://docharvest.github.io/docs/astro/recipes/)

Contents

astro

Astro recipes

Astro

Astro recipes

See guided examples of adding features to your Astro project.

## Official Recipes

Astro's official recipes are short, focused how-to guides that walk a reader through completing a working example of a specific task. Recipes are a great way to add new features or behavior to your Astro project by following step-by-step instructions!

## Community Resources

Find more recipes written and submitted by the community at [Astro Tips](https://astro-tips.dev).

## [Installing a Vite or Rollup plugin](https://docharvest.github.io/docs/astro/recipes/add-yaml-support/)

Contents

astro

Installing a Vite or Rollup plugin

Astro

Installing a Vite or Rollup plugin

Astro builds on top of Vite, and supports both Vite and Rollup plugins. This recipe uses a Rollup plugin to add the ability to import a YAML (`.yml`) file in Astro.

## Recipe

1\. Install \`@rollup/plugin-yaml\`:

```
<PackageManagerTabs>
    <Fragment slot="npm">
    ```shell
    npm install @rollup/plugin-yaml --save-dev
    ```
    </Fragment>
    <Fragment slot="pnpm">
    ```shell
    pnpm add @rollup/plugin-yaml --save-dev
    ```
    </Fragment>
    <Fragment slot="yarn">
    ```shell
    yarn add @rollup/plugin-yaml --dev
    ```
    </Fragment>
</PackageManagerTabs>
```

2.  Import the plugin in your `astro.config.mjs` and add it to the Vite plugins array:
    
    ```
    import { defineConfig } from 'astro/config';
    import yaml from '@rollup/plugin-yaml';
    
    export default defineConfig({
      vite: {
        plugins: [yaml()]
      }
    });
    ```
    
3.  Finally, you can import YAML data using an `import` statement:
    
    ```
    import yml from './data.yml';
    ```
    
    :::note While you can now import YAML data in your Astro project, your editor will not provide types for the imported data. To add types, create or find an existing `*.d.ts` file in the `src` directory of your project and add the following:
    
    ```
    // Specify the file extension you want to import
    declare module "*.yml" {
      const value: any; // Add type definitions here if desired
      export default value;
    }
    ```
    
    This will allow your editor to provide type hints for your YAML data. :::

## [Analyze bundle size](https://docharvest.github.io/docs/astro/recipes/analyze-bundle-size/)

Contents

astro

Analyze bundle size

Astro

Analyze bundle size

Understanding what is a part of an Astro bundle is important for improving site performance. Visualizing the bundle can give clues as to where changes can be made in your project to reduce the bundle size.

## Recipe

The [`rollup-plugin-visualizer` library](https://github.com/btd/rollup-plugin-visualizer) allows you to visualize and analyze your Rollup bundle to see which modules are taking up space.

1.  Install `rollup-plugin-visualizer`:
    
    \`\`\`shell npm install rollup-plugin-visualizer --save-dev \`\`\` \`\`\`shell pnpm add rollup-plugin-visualizer --save-dev \`\`\` \`\`\`shell yarn add rollup-plugin-visualizer --save-dev \`\`\`
2.  Add the plugin to the `astro.config.mjs` file:
    
    ```
    // @ts-check
    import { defineConfig } from 'astro/config';
    import { visualizer } from "rollup-plugin-visualizer";
    
    export default defineConfig({
    vite: {
        plugins: [visualizer({
            emitFile: true,
            filename: "stats.html",
        })]
    }
    });
    ```
    
3.  Run the build command:
    
    \`\`\`shell npm run build \`\`\` \`\`\`shell pnpm build \`\`\` \`\`\`shell yarn build \`\`\`
4.  Find the `stats.html` file(s) for your project.
    
    ```
     This will be at the root of your `dist/` directory for entirely static sites and will allow you to see what is included in the bundle.
     
     If your Astro project uses on-demand rendering, you will have two `stats.html` files. One will be for the client, and the other for the server, and each will be located at the root of the `dist/client` and `dist/server/` directories.
     
     See [the Rollup Plugin Visualizer documentation](https://github.com/btd/rollup-plugin-visualizer#how-to-use-generated-files) for guidance on how to interpret these files, or configure specific options.
    ```
    

:::note Given Astro's unique approach to hydration, the build isn't necessarily representative of the bundle that the client will receive.

The Rollup visualizer shows all dependencies that are used across the site, but it does not break down the bundle size on a per-page basis. :::

## [Build a custom image component](https://docharvest.github.io/docs/astro/recipes/build-custom-img-component/)

Contents

astro

Build a custom image component

Astro

Build a custom image component

Astro provides two built-in components that you can use to display and optimize your images. The `<Picture>` component allows you to display responsive images and work with different formats and sizes. The `<Image>` component will optimize your images and allow you to pass in different formats and quality properties.

When you need options that the `<Picture>` and `<Image>` components do not currently support, you can use the `getImage()` function to create a custom component.

In this recipe, you will use the [`getImage()` function](/en/guides/images/#generating-images-with-getimage) to create your own custom image component that displays different source images based on media queries.

## Recipe

1\. Create a new Astro component and import the \`getImage()\` function

````
```astro title="src/components/MyCustomImageComponent.astro" 
---
 import { getImage } from "astro:assets";
---

```
````

2.  Create a new component for your custom image. `MyCustomComponent.astro` will receive three `props` from `Astro.props`. The `mobileImgUrl` and `desktopImgUrl` props are used for creating your image at different viewport sizes. The `alt` prop is used for the image's alt text. These props will be passed wherever you render your custom image components. Add the following imports and define the props that you will use in your component. You can also use TypeScript to type the props.
    
    ```
    ---
    import type { ImageMetadata } from "astro";
    import { getImage } from "astro:assets";
    
    interface Props {
        mobileImgUrl: string | ImageMetadata;
        desktopImgUrl: string | ImageMetadata;
        alt: string;
    }
    
    const { mobileImgUrl, desktopImgUrl, alt } = Astro.props;
    ---
    ```
    
3.  Define each of your responsive images by calling the `getImage()` function with your desired properties.
    
    ```
    ---
    import type { ImageMetadata } from "astro";
    import { getImage } from "astro:assets";
    
    interface Props {
        mobileImgUrl: string | ImageMetadata;
        desktopImgUrl: string | ImageMetadata;
        alt: string;
    }
    
    const { mobileImgUrl, desktopImgUrl, alt } = Astro.props;
    
    const mobileImg = await getImage({
        src: mobileImgUrl,
        format: "webp",
        width: 200,
        height: 200,
    });
    
    const desktopImg = await getImage({
        src: desktopImgUrl,
        format: "webp",
        width: 800,
        height: 200,
    });
    ---
    ```
    
4.  Create a `<picture>` element that generates a `srcset` with your different images based on your desired media queries.
    
    ```
    ---
    import type { ImageMetadata } from "astro";
    import { getImage } from "astro:assets";
    
    interface Props {
        mobileImgUrl: string | ImageMetadata;
        desktopImgUrl: string | ImageMetadata;
        alt: string;
    }
    
    const { mobileImgUrl, desktopImgUrl, alt } = Astro.props;
    
    const mobileImg = await getImage({
        src: mobileImgUrl,
        format: "webp",
        width: 200,
        height: 200,
    });
    
    const desktopImg = await getImage({
        src: desktopImgUrl,
        format: "webp",
        width: 800,
        height: 200,
    });
    ---
    
    <picture>
        <source media="(max-width: 799px)" srcset={mobileImg.src} />
        <source media="(min-width: 800px)" srcset={desktopImg.src} />
        <img src={desktopImg.src} alt={alt} />
    </picture>
    ```
    
5.  Import and use `<MyCustomImageComponent />` in any `.astro` file. Be sure to pass the necessary props for generating two different images at the different viewport sizes:
    
    ```
    ---
    import MyCustomImageComponent from "../components/MyCustomImageComponent.astro";
    import mobileImage from "../images/mobile-profile-image.jpg";
    import desktopImage from "../images/desktop-profile-image.jpg";
    ---
    
    <MyCustomImageComponent
        mobileImgUrl={mobileImage}
        desktopImgUrl={desktopImage}
        alt="user profile picture"
    />
    ```

## [Build HTML forms in Astro pages](https://docharvest.github.io/docs/astro/recipes/build-forms/)

Contents

astro

Build HTML forms in Astro pages

Astro

Build HTML forms in Astro pages

Astro pages that are rendered on demand can both display and handle forms. In this recipe, you'll use a standard HTML form to submit data to the server. Your frontmatter script will handle the data on the server, sending no JavaScript to the client.

:::tip\[Build forms with Astro Actions\] In v4.15, Astro added actions which provide several benefits over basic HTML forms including validating your form data and updating your UI based on the form submission. To use this method for building forms instead, see our [actions guide](/en/guides/actions/) to learn more about these features. :::

## Prerequisites

-   An Astro project with a [server adapter](/en/guides/on-demand-rendering/#server-adapters) installed.

## Recipe

1\. Create or identify a \`.astro\` page which will contain your form and your handling code. For example, you could add a registration page:

````
```astro title="src/pages/register.astro"
---
---
<h1>Register</h1>
```
````

2.  Add a `<form>` tag with some inputs to the page. Each input should have a `name` attribute that describes the value of that input.
    
    Be sure to include a `<button>` or `<input type="submit">` element to submit the form.
    
    ```
    ---
    ---
    <h1>Register</h1>
    <form>
      <label>
        Username:
        <input type="text" name="username" />
      </label>
      <label>
        Email:
        <input type="email" name="email" />
      </label>
      <label>
        Password:
        <input type="password" name="password" />
      </label>
      <button>Submit</button>
    </form>
    ```
    
3.  Use [validation attributes](https://developer.mozilla.org/en-US/docs/Learn/Forms/Form_validation#using_built-in_form_validation) to provide basic client-side validation that works even if JavaScript is disabled.
    
    In this example,
    
    -   `required` prevents form submission until the field is filled.
    -   `minlength` sets a minimum required length for the input text.
    -   `type="email"` also introduces validation that will only accept a valid email format.
    
    ```
    ---
    ---
    <h1>Register</h1>
    <form>
      <label>
        Username:
        <input type="text" name="username" required />
      </label>
      <label>
        Email:
        <input type="email" name="email" required />
      </label>
      <label>
        Password:
        <input type="password" name="password" required minlength="6" />
      </label>
      <button>Submit</button>
    </form>
    ```
    
    :::tip You can add custom validation logic that refers to multiple fields using a `<script>` tag and the [Constraint Validation API](https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation#complex_constraints_using_the_constraint_validation_api).
    
    To write complex validation logic more easily, you can build your form using a [frontend framework](/en/guides/framework-components/) and choose a form library like [React Hook Form](https://react-hook-form.com/) or [Felte](https://felte.dev/). :::
    
4.  The form submission will cause the browser to request the page again. Change the form's data transfer `method` to `POST` to send the form data as part of the `Request` body, rather than as URL parameters.
    
    ```
    ---
    ---
    <h1>Register</h1>
    <form method="POST">
      <label>
        Username:
        <input type="text" name="username" required />
      </label>
      <label>
        Email:
        <input type="email" name="email" required />
      </label>
      <label>
        Password:
        <input type="password" name="password" required minlength="6" />
      </label>
      <button>Submit</button>
    </form>
    ```
    
5.  Check for the `POST` method in the frontmatter and access the form data using `Astro.request.formData()`. Wrap this in a `try ... catch` block to handle cases when the `POST` request wasn't sent by a form and the `formData` is invalid.
    
    ```
    ---
    export const prerender = false; // Not needed in 'server' mode
    
    if (Astro.request.method === "POST") {
      try {
        const data = await Astro.request.formData();
        const name = data.get("username");
        const email = data.get("email");
        const password = data.get("password");
        // Do something with the data
      } catch (error) {
        if (error instanceof Error) {
          console.error(error.message);
        }
      }
    }
    ---
    <h1>Register</h1>
    <form method="POST">
      <label>
        Username:
        <input type="text" name="username" required />
      </label>
      <label>
        Email:
        <input type="email" name="email" required />
      </label>
      <label>
        Password:
        <input type="password" name="password" required minlength="6" />
      </label>
      <button>Submit</button>
    </form>
    ```
    
6.  Validate the form data on the server. This should include the same validation done on the client to prevent malicious submissions to your endpoint and to support the rare legacy browser that doesn't have form validation.
    
    It can also include validation that can't be done on the client. For example, this example checks if the email is already in the database.
    
    Error messages can be sent back to the client by storing them in an `errors` object and accessing it in the template.
    
    ```
    ---
    export const prerender = false; // Not needed in 'server' mode
    
    import { isRegistered, registerUser } from "../../data/users"
    import { isValidEmail } from "../../utils/isValidEmail";
    
    const errors = { username: "", email: "", password: "" };
    if (Astro.request.method === "POST") {
      try {
        const data = await Astro.request.formData();
        const name = data.get("username");
        const email = data.get("email");
        const password = data.get("password");
        if (typeof name !== "string" || name.length < 1) {
          errors.username += "Please enter a username. ";
        }
        if (typeof email !== "string" || !isValidEmail(email)) {
          errors.email += "Email is not valid. ";
        } else if (await isRegistered(email)) {
          errors.email += "Email is already registered. ";
        }
        if (typeof password !== "string" || password.length < 6) {
          errors.password += "Password must be at least 6 characters. ";
        }
        const hasErrors = Object.values(errors).some(msg => msg)
        if (!hasErrors) {
          await registerUser({name, email, password});
          return Astro.redirect("/login");
        }
      } catch (error) {
        if (error instanceof Error) {
          console.error(error.message);
        }
      }
    }
    ---
    <h1>Register</h1>
    <form method="POST">
      <label>
        Username:
        <input type="text" name="username" />
      </label>
      {errors.username && <p>{errors.username}</p>}
      <label>
        Email:
        <input type="email" name="email" required />
      </label>
      {errors.email && <p>{errors.email}</p>}
      <label>
        Password:
        <input type="password" name="password" required minlength="6" />
      </label>
      {errors.password && <p>{errors.password}</p>}
      <button>Register</button>
    </form>
    ```

## [Build forms with API routes](https://docharvest.github.io/docs/astro/recipes/build-forms-api/)



## [Use Bun with Astro](https://docharvest.github.io/docs/astro/recipes/bun/)

Contents

astro

Use Bun with Astro

Astro

Use Bun with Astro

[Bun](https://bun.sh/) is an all-in-one JavaScript runtime & toolkit. See [Bun's documentation](https://bun.sh/docs) for more information.

:::caution Using Bun with Astro may reveal rough edges. Some integrations may not work as expected. Consult [Bun's official documentation for working with Astro](https://bun.sh/guides/ecosystem/astro) for details.

If you have any problems using Bun, please [open an Issue on GitHub with Bun directly](https://github.com/oven-sh/bun/issues/new/choose). :::

## Prerequisites

-   Bun installed locally on your machine. See the [installation instructions](https://bun.sh/docs/installation) in Bun's official documentation.

## Create a new Astro project with Bun

Create a new Astro project with Bun using the following `create-astro` command:

```
bun create astro my-astro-project-using-bun
```

## Install dependencies

If you skipped the “Install dependencies?” step during the CLI wizard, then be sure to install your dependencies before continuing.

```
bun install
```

## Add Types

Bun publishes the [`@types/bun`](https://www.npmjs.com/package/@types/bun) package, containing the runtime types for Bun.

Install `@types/bun` using the following command:

```
bun add -d @types/bun
```

## CLI installation flags

### Using integrations

You can also use any of the official Astro integrations with the `astro add` command:

```
bun astro add react
```

### Use a theme or starter template

You can start a new Astro project based on an [official example](https://github.com/withastro/astro/tree/main/examples) or the main branch of any GitHub repository by passing a `--template` argument to the `create astro` command.

Run the following command in your terminal, substituting the official Astro starter template name, or the GitHub username and repository of the theme you want to use:

```
# create a new project with an official example
bun create astro@latest --template <example-name>
# create a new project based on a GitHub repository’s main branch
bun create astro@latest --template <github-username>/<github-repo>
```

## Develop and build

To run the development server, use following command:

```
bun run dev
```

### Build and preview your site

To build your site, use the following command:

```
bun run build
```

When the build is finished, run the appropriate preview command (e.g. `bun run preview`) in your terminal and you can view the built version of your site locally in the same browser preview window.

## Testing

Bun ships with a fast, built-in, Jest-compatible test runner through the [`bun test` command](https://bun.sh/docs/cli/test). You can also use any other [testing tools for Astro](/en/guides/testing/).

## Official Resources

-   [Build an app with Astro and Bun](https://bun.sh/guides/ecosystem/astro)

## Community Resources

Using Bun with Astro? Add your blog post or video to this page!

-   [Using Bun with Astro and Cloudflare Pages](https://handerson.hashnode.dev/using-bun-with-astro-and-cloudflare-pages) - blog post

## [Call endpoints from the server](https://docharvest.github.io/docs/astro/recipes/call-endpoints/)

Contents

astro

Call endpoints from the server

Astro

Call endpoints from the server

Endpoints can be used to serve many kinds of data. This recipe calls a server endpoint from a page's component script to display a greeting, without requiring an additional fetch request.

## Prerequisites

-   A project with [SSR](/en/guides/on-demand-rendering/) (output: 'server') enabled

## Recipe

1\. Create an endpoint in a new file \`src/pages/api/hello.ts\` that returns some data:

````
```ts title="src/pages/api/hello.ts"
import type { APIRoute } from 'astro'

export const GET: APIRoute = () => {
  return new Response(
    JSON.stringify({
      greeting: 'Hello',
    }),
  )
}
```
````

2.  On any Astro page, import the `GET()` method from the endpoint. Call it with the [`Astro` global](/en/reference/api-reference/) to provide the request context, and use the response on the page:
    
    ```
    ---
    import { GET } from './api/hello.ts'
    
    let response = await GET(Astro)
    const data = await response.json()
    ---
    
    <h1>{data.greeting} world!</h1>
    ```

## [Verify a Captcha](https://docharvest.github.io/docs/astro/recipes/captcha/)

Contents

astro

Verify a Captcha

Astro

Verify a Captcha

[Server endpoints](/en/guides/endpoints/#server-endpoints-api-routes) can be used as REST API endpoints to run functions such as authentications, database access, and verifications without exposing sensitive data to the client.

In this recipe, an API route is used to verify Google reCAPTCHA v3 without exposing the secret to clients.

## Prerequisites

-   A project with [SSR](/en/guides/on-demand-rendering/) (`output: 'server'`) enabled

## Recipe

1\. Create a \`POST\` endpoint that accepts recaptcha data, then verifies it with reCAPTCHA's API. Here, you can safely define secret values or read environment variables.

````
```js title="src/pages/recaptcha.js"
export async function POST({ request }) {
  const data = await request.json();

  const recaptchaURL = 'https://www.google.com/recaptcha/api/siteverify';
  const requestHeaders = {
    'Content-Type': 'application/x-www-form-urlencoded'
  };
  const requestBody = new URLSearchParams({
    secret: "YOUR_SITE_SECRET_KEY",   // This can be an environment variable
    response: data.recaptcha          // The token passed in from the client
  });

  const response = await fetch(recaptchaURL, {
    method: "POST",
    headers: requestHeaders,
    body: requestBody.toString()
  });

  const responseData = await response.json();

  return new Response(JSON.stringify(responseData), { status: 200 });
}
```
````

2.  Access your endpoint using `fetch` from a client script:
    
    ```
    <html>
      <head>
        <script is:inline src="https://www.google.com/recaptcha/api.js"></script>
      </head>
    
      <body>
        <button class="g-recaptcha" 
          data-sitekey="PUBLIC_SITE_KEY" 
          data-callback="onSubmit" 
          data-action="submit"> Click me to verify the captcha challenge! </button>
    
        <script is:inline>
          function onSubmit(token) {
            fetch("/recaptcha", {
              method: "POST",
              body: JSON.stringify({ recaptcha: token })
            })
            .then((response) => response.json())
            .then((gResponse) => {
              if (gResponse.success) {
                // Captcha verification was a success
              } else {
                // Captcha verification failed
              }
            })
          }
        </script>
      </body>
    </html>
    ```

## [Customize file names in the build output](https://docharvest.github.io/docs/astro/recipes/customizing-output-filenames/)

Contents

astro

Customize file names in the build output

Astro

Customize file names in the build output

By default, the `astro build` command outputs your built assets from [your project source](/en/basics/project-structure/#src), like JavaScript and CSS files located in the `src/` directory, into an `_astro` directory with hashed filenames (e.g. `_astro/index.DRf8L97S.js`) which are excellent for long-term caching.

Although it is normally not necessary, you can customise the output file names when needed. For example, this can be helpful if you have scripts with names that might trigger ad blockers (e.g. `ads.js`), or if you want to organize your assets with a particular naming convention. By customizing Rollup output options, you can gain more control over your project's build structure, allowing you to meet specific organizational or deployment requirements.

## Recipe

This recipe configures `vite.environments.client.build.rollupOptions` to output built assets with the following structure and naming pattern:

-   JavaScript entry files (e.g. scripts directly associated with your pages or layouts): `dist/js/[name]-[hash].js`
-   JavaScript code-split chunks (e.g. dynamically imported components or shared modules): `dist/js/chunks/[name]-[hash].js`
-   Other assets (e.g. CSS, images, fonts): `dist/static/[name]-[hash][extname]` (e.g. `dist/static/styles-a1b2c3d4.css`, `dist/static/logo-e5f6g7h8.svg`)

1.  Add Vite Rollup Output Options.
    
    Modify your `astro.config.mjs` to include the following `vite.environments.client.build.rollupOptions.output` configuration. This is where you can define the custom naming patterns for your assets using Rollup's [`entryFileNames`](https://rollupjs.org/configuration-options/#output-entryfilenames), [`chunkFileNames`](https://rollupjs.org/configuration-options/#output-chunkfilenames), and [`assetFileNames`](https://rollupjs.org/configuration-options/#output-assetfilenames):
    
    ```
    import { defineConfig } from 'astro/config';
    
    export default defineConfig({
      // ...
      vite: {
        environments: {
          client: {
            build: {
              rollupOptions: {
                output: {
                  // path names relative to `outDir`
                  entryFileNames: 'js/[name]-[hash].js',
                  chunkFileNames: 'js/chunks/[name]-[hash].js',
                  assetFileNames: 'static/[name]-[hash][extname]',
                },
              },
            },
          },
        },
      },
    });
    ```
    
    This example uses the following file name placeholders:
    
    -   `[name]`: The original name of the file (without the extension and path).
    -   `[hash]`: A content-based hash generated for the file, crucial for cache busting. You can also specify a length, e.g. `[hash:8]`. This ensures that when you update an asset, the filename changes, forcing browsers to download the new version instead of serving a stale cached version.
    -   `[extname]`: The original file extension, including the leading dot (e.g. `.js`, `.css`, `.svg`).
    
    For a full list of available placeholders and advanced patterns for these options, refer to the \[Rollup configuration documentation\](https://rollupjs.org/configuration-options/).
2.  Build your project.
    
    Since these filename customizations apply to the production build output only, you will need to run your project's build command:
    
    \`\`\`shell npm run build \`\`\` \`\`\`shell pnpm build \`\`\` \`\`\`shell yarn build \`\`\`
3.  After the build completes, inspect your [output directory](/en/reference/configuration-reference/#outdir) (`dist/` by default).
    
    Verify that the build assets from your project `src` are named and organized according to the new patterns. (Files from [your `public/` directory](/en/basics/project-structure/#public) are copied directly to the output directory and are not affected by these Rollup naming options.)
    
    Depending on your project's specific contents, your build folder will now look something like this:
    
    \- dist/ - js/ - index-a1b2c3d4.js - chunks/ - common-e5f6g7h8.js - img/ - logo-i9j0k1l2.png - fonts/ - myfont-q2w3e4r5.woff2 - static\_assets/ - styles-m3n4o5p6.css - index.html - about/ - index.html - ... (other HTML files and public assets)

## [Build your Astro site with Docker](https://docharvest.github.io/docs/astro/recipes/docker/)



## [Dynamically import images](https://docharvest.github.io/docs/astro/recipes/dynamically-importing-images/)

Contents

astro

Dynamically import images

Astro

Dynamically import images

Local [images](/en/guides/images/) must be imported into `.astro` files in order to display them. There will be times where you will want or need to dynamically import the image paths of your images instead of explicitly importing each individual image.

In this recipe, you will learn how to dynamically import your images using Vite's `import.meta.glob` function. You will build a card component that displays the name, age, and photo of a person.

## Recipe

1\. Create a new \`assets\` folder under the \`src\` directory and add your images inside that new folder.

```
<FileTree>
- src/
  - assets/
    - avatar-1.jpg
    - avatar-2.png
    - avatar-3.jpeg
</FileTree>

:::note
`assets` is a popular folder name convention for placing images but you are free to name the folder whatever you like.
::: 
```

2.  Create a new Astro component for your card and import the `<Image />` component.
    
    ```
    ---
    import { Image } from 'astro:assets';
    ---
    ```
    
3.  Specify the `props` that your component will receive in order to display the necessary information on each card. You can optionally define their types, if you are using TypeScript in your project.
    
    ```
    ---
    import { Image } from 'astro:assets';
    
    interface Props {
       imagePath: string;
       altText: string;
       name: string;
       age: number;
    }
    
    const { imagePath, altText, name, age } = Astro.props;
    ---
    ```
    
4.  Create a new `images` variable and use the `import.meta.glob` function which returns an object of all of the image paths inside the `assets` folder. You will also need to import `ImageMetadata` type to help define the type of the `images` variable.
    
    ```
    ---
    import type { ImageMetadata } from 'astro';
    import { Image } from 'astro:assets';
    
    interface Props {
       imagePath: string;
       altText: string;
       name: string;
       age: number;
    }
    
    const { imagePath, altText, name, age } = Astro.props;
    const images = import.meta.glob<{ default: ImageMetadata }>('/src/assets/*.{jpeg,jpg,png,gif}')
    ---
    ```
    
5.  Use the props to create the markup for your card component.
    
    ```
    ---
    import type { ImageMetadata } from 'astro';
    import { Image } from 'astro:assets';
    
    interface Props {
       imagePath: string;
       altText: string;
       name: string;
       age: number;
    }
    
    const { imagePath, altText, name, age } = Astro.props;
    const images = import.meta.glob<{ default: ImageMetadata }>('/src/assets/*.{jpeg,jpg,png,gif}');
    ---
    <div class="card">
        <h2>{name}</h2>
        <p>Age: {age}</p>
        <Image src={} alt={altText} />
    </div>
    ```
    
6.  Inside the `src` attribute, pass in the `images` object and use bracket notation for the image path. Then make sure to invoke the glob function.
    
    Since you are accessing the `images` object which has an unknown type, you should also `throw` an error in case an invalid file path is passed as a prop.
    
    ```
    
    ---
    import type { ImageMetadata } from 'astro';
    import { Image } from 'astro:assets';
    
    interface Props {
       imagePath: string;
       altText: string;
       name: string;
       age: number;
    }
    
    const { imagePath, altText, name, age } = Astro.props;
    const images = import.meta.glob<{ default: ImageMetadata }>('/src/assets/*.{jpeg,jpg,png,gif}');
    if (!images[imagePath]) throw new Error(`"${imagePath}" does not exist in glob: "src/assets/*.{jpeg,jpg,png,gif}"`);
    ---
    <div class="card">
        <h2>{name}</h2>
        <p>Age: {age}</p>
        <Image src={images[imagePath]()} alt={altText} />
    </div>
    ```
    
    :::note `images` is an object that contains all of the image paths inside the `assets` folder.
    
    ```
    const images = {
      './assets/avatar-1.jpg': () => import('./assets/avatar-1.jpg'),
      './assets/avatar-2.png': () => import('./assets/avatar-2.png'),
      './assets/avatar-3.jpeg': () => import('./assets/avatar-3.jpeg')
    }
    ```
    
    The `imagePath` prop is a string that contains the path to the image that you want to display. The `import.meta.glob()` is doing the work of finding the image path that matches the `imagePath` prop and handling the import for you. :::
    
7.  Import and use the card component inside an Astro page, passing in the values for the `props`.
    
    ```
    ---
    import MyCustomCardComponent from '../components/MyCustomCardComponent.astro';
    ---
    <MyCustomCardComponent 
        imagePath="/src/assets/avatar-1.jpg"
        altText="A headshot of Priya against a brick wall background."
        name="Priya"
        age={25}
    />
    ```

## [Add icons to external links](https://docharvest.github.io/docs/astro/recipes/external-links/)

Contents

astro

Add icons to external links

Astro

Add icons to external links

Using a rehype plugin, you can identify and modify links in your Markdown files that point to external sites. This example adds icons to the end of each external link, so that visitors will know they are leaving your site.

## Prerequisites

-   An Astro project using Markdown for content pages.

## Recipe

1\. Install both the \[\`rehype-external-links\`\](https://www.npmjs.com/package/rehype-external-links) plugin and \[\`@astrojs/markdown-remark\`\](https://www.npmjs.com/package/@astrojs/markdown-remark).

```
<PackageManagerTabs>
    <Fragment slot="npm">
    ```shell
    npm install rehype-external-links @astrojs/markdown-remark
    ```
    </Fragment>
    <Fragment slot="pnpm">
    ```shell
    pnpm add rehype-external-links @astrojs/markdown-remark
    ```
    </Fragment>
    <Fragment slot="yarn">
    ```shell
    yarn add rehype-external-links @astrojs/markdown-remark
    ```
    </Fragment>
  </PackageManagerTabs>
```

2.  Configure the plugin in your `astro.config.mjs` file.
    
    Import `unified()` and define it as the Markdown processor to [support remark plugins](/en/guides/markdown-content/#using-remark-and-rehype-plugins). Then, pass to `rehypePlugins` an array containing your imported `rehypeExternalLinks` plugin and an options object with a `content` property. Set this property's `type` to `text` if you want to add plain text to the end of the link. To add HTML to the end of the link instead, set the property `type` to `raw`.
    
    ```
    import { unified } from '@astrojs/markdown-remark';
    import { defineConfig } from 'astro/config';
    import rehypeExternalLinks from 'rehype-external-links';
    
    export default defineConfig({
      // ...
      markdown: {
        processor: unified({
          rehypePlugins: [
            [
              rehypeExternalLinks,
              {
                content: { type: 'text', value: ' 🔗' }
              }
            ],
          ]
        }),
      },
    });
    ```
    
    :::note The value of the `content` property is [not represented in the accessibility tree](https://developer.mozilla.org/en-US/docs/Web/CSS/content#accessibility_concerns). As such, it's best to make clear that the link is external in the surrounding content, rather than relying on the icon alone. :::

## [Add i18n features](https://docharvest.github.io/docs/astro/recipes/i18n/)

Contents

astro

Add i18n features

Astro

Add i18n features

In this recipe, you will learn how to use content collections and dynamic routing to build your own internationalization (i18n) solution and serve your content in different languages.

:::tip In v4.0, Astro added built-in support for i18n routing that allows you to configure default and supported languages and includes valuable helper functions to assist you in serving an international audience. If you want to use this instead, see our [internationalization guide](/en/guides/internationalization/) to learn about these features. ::: This example serves each language at its own subpath, e.g. `example.com/en/blog` for English and `example.com/fr/blog` for French.

If you prefer the default language to not be visible in the URL unlike other languages, there are [instructions to hide the default language](/en/recipes/i18n/#hide-default-language-in-the-url) below.

See the [resources section](#resources) for external links to related topics such as right-to-left (RTL) styling and choosing language tags.

## Recipe

### Set up pages for each language

1\. Create a directory for each language you want to support. For example, \`en/\` and \`fr/\` if you are supporting English and French:

```
<FileTree>
- src/
  - pages/
    - **en/**
      - about.astro
      - index.astro
    - **fr/**
      - about.astro
      - index.astro
    - index.astro
</FileTree>
```

2.  Set up `src/pages/index.astro` to redirect to your default language.
    
    \`\`\`astro --- // src/pages/index.astro ---  \`\`\`
    
    ```
     This approach uses a [meta refresh](https://en.wikipedia.org/wiki/Meta_refresh) and will work however you deploy your site. Some static hosts also let you configure server redirects with a custom configuration file. See your deploy platform’s documentation for more details.
    ```
    
    If you are using an SSR adapter, you can use \[\`Astro.redirect\`\](/en/guides/routing/#dynamic-redirects) to redirect to the default language on the server.
    
    ```
     ```astro
     ---
     // src/pages/index.astro
     return Astro.redirect('/en/');
     ---
     ```
    ```
    

### Use collections for translated content

1\. Create a folder in \`src/content/\` for each type of content you want to include and add subdirectories for each supported language. For example, to support English and French blog posts:

```
<FileTree>
- src/
  - content/
      - blog/
        - **en/** Blog posts in English
            - post-1.md
            - post-2.md
        - **fr/** Blog posts in French
          - post-1.md
          - post-2.md
</FileTree>
```

2.  Create a `src/content.config.ts` file and export a collection for each type of content.
    
    ```
    //src/content.config.ts
    import { defineCollection } from 'astro:content';
    import { z } from 'astro/zod';
    
    const blogCollection = defineCollection({
      schema: z.object({
        title: z.string(),
        author: z.string(),
        date: z.date()
      })
    });
    
    export const collections = {
      'blog': blogCollection
    };
    ```
    
    Read more about [Content Collections](/en/guides/content-collections/).
    
3.  Use [dynamic routes](/en/guides/routing/#dynamic-routes) to fetch and render content based on a `lang` and a `slug` parameter.
    
    In static rendering mode, use \`getStaticPaths\` to map each content entry to a page:
    
    ```
     ```astro
     //src/pages/[lang]/blog/[...slug].astro
     ---
     import { getCollection, render } from 'astro:content';
     
     export async function getStaticPaths() {
       const pages = await getCollection('blog');
    
       const paths = pages.map(page => {
         const [lang, ...slug] = page.id.split('/');
         return { params: { lang, slug: slug.join('/') || undefined }, props: page };
       });
    
       return paths;
     }
    
     const { lang, slug } = Astro.params;
     const page = Astro.props;
     const formattedDate = page.data.date.toLocaleString(lang);
     const { Content } = await render(page);
     ---
     <h1>{page.data.title}</h1>
     <p>by {page.data.author} • {formattedDate}</p>
     <Content/>
     ```
    ```
    
    In \[SSR mode\](/en/guides/on-demand-rendering/), fetch the requested entry directly:
    
    ```
     ```astro
     //src/pages/[lang]/blog/[...slug].astro
     ---
     import { getEntry, render } from 'astro:content';
    
     const { lang, slug } = Astro.params;
     const page = await getEntry('blog', `${lang}/${slug}`);
    
     if (!page) {
       return Astro.redirect('/404');
     }
    
     const formattedDate = page.data.date.toLocaleString(lang);
     const { Content, headings } = await render(page);
     ---
     <h1>{page.data.title}</h1>
     <p>by {page.data.author} • {formattedDate}</p>
     <Content/>
     ```
    ```
    
    Read more about [dynamic routing](/en/guides/routing/#dynamic-routes).
    
    :::tip\[Date formatting\] The example above uses the built-in [`toLocaleString()` date-formatting method](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toLocaleString) to create a human-readable string from the frontmatter date. This ensures the date and time are formatted to match the user’s language. :::
    

### Translate UI strings

Create dictionaries of terms to translate the labels for UI elements around your site. This allows your visitors to experience your site fully in their language.

1\. Create a \`src/i18n/ui.ts\` file to store your translation strings:

````
```ts
// src/i18n/ui.ts
export const languages = {
  en: 'English',
  fr: 'Français',
};

export const defaultLang = 'en';

export const ui = {
  en: {
    'nav.home': 'Home',
    'nav.about': 'About',
    'nav.twitter': 'Twitter',
  },
  fr: {
    'nav.home': 'Accueil',
    'nav.about': 'À propos',
  },
} as const;
```
````

2.  Create two helper functions: one to detect the page language based on the current URL, and one to get translations strings for different parts of the UI in `src/i18n/utils.ts`:
    
    ```
    // src/i18n/utils.ts
    import { ui, defaultLang } from './ui';
    
    export function getLangFromUrl(url: URL) {
      const [, lang] = url.pathname.split('/');
      if (lang in ui) return lang as keyof typeof ui;
      return defaultLang;
    }
    
    export function useTranslations(lang: keyof typeof ui) {
      return function t(key: keyof typeof ui[typeof defaultLang]) {
        return ui[lang][key] || ui[defaultLang][key];
      }
    }
    ```
    
    :::note\[Did you notice?\] In step 1, the `nav.twitter` string was not translated to French. You may not want every term translated, such as proper names or common industry terms. The `useTranslations` helper will return the default language’s value if a key is not translated. In this example, French users will also see “Twitter” in the nav bar. :::
    
3.  Import the helpers where needed and use them to choose the UI string that corresponds to the current language. For example, a nav component might look like:
    
    ```
    ---
    // src/components/Nav.astro
    import { getLangFromUrl, useTranslations } from '../i18n/utils';
    
    const lang = getLangFromUrl(Astro.url);
    const t = useTranslations(lang);
    ---
    <ul>
        <li>
            <a href={`/${lang}/home/`}>
              {t('nav.home')}
            </a>
        </li>
        <li>
            <a href={`/${lang}/about/`}>
              {t('nav.about')}
            </a>
        </li>
        <li>
            <a href="https://twitter.com/astrodotbuild">
              {t('nav.twitter')}
            </a>
        </li>
    </ul>
    ```
    
4.  Each page must have a `lang` attribute on the `<html>` element that matches the language on the page. In this example, a [reusable layout](/en/basics/layouts/) extracts the language from the current route:
    
    ```
    ---
    // src/layouts/Base.astro
    
    import { getLangFromUrl } from '../i18n/utils';
    
    const lang = getLangFromUrl(Astro.url);
    ---
    <html lang={lang}>
        <head>
            <meta charset="utf-8" />
            <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
            <meta name="viewport" content="width=device-width" />
            <title>Astro</title>
        </head>
        <body>
            <slot />
        </body>
    </html>
    ```
    
    You can then use this base layout to ensure that pages use the correct `lang` attribute automatically.
    
    ```
    ---
    // src/pages/en/about.astro
    import Base from '../../layouts/Base.astro';
    ---
    <Base>
        <h1>About me</h1>
        ...
    </Base>
    ```
    

### Let users switch between languages

Create links to the different languages you support so users can choose the language they want to read your site in.

1\. Create a component to show a link for each language:

````
```astro
---
// src/components/LanguagePicker.astro
import { languages } from '../i18n/ui';
---
<ul>
  {Object.entries(languages).map(([lang, label]) => (
    <li>
      <a href={`/${lang}/`}>{label}</a>
    </li>
  ))}
</ul>
```
````

2.  Add `<LanguagePicker />` to your site so it is shown on every page. The example below adds it to the site footer in a base layout:
    
    ```
    ---
    // src/layouts/Base.astro
    import LanguagePicker from '../components/LanguagePicker.astro';
    import { getLangFromUrl } from '../i18n/utils';
    
    const lang = getLangFromUrl(Astro.url);
    ---
    <html lang={lang}>
        <head>
            <meta charset="utf-8" />
            <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
            <meta name="viewport" content="width=device-width" />
            <title>Astro</title>
        </head>
        <body>
            <slot />
            <footer>
              <LanguagePicker />
            </footer>
        </body>
    </html>
    ```
    

### Hide default language in the URL

1\. Create a directory for each language except the default language. For example, store your default language pages directly in \`pages/\`, and your translated pages in \`fr/\`:

```
<FileTree>
- src/
  - pages/
    - about.astro
    - index.astro
    - **fr/**
      - about.astro
      - index.astro
</FileTree>
```

2.  Add another line to the `src/i18n/ui.ts` file to toggle the feature:
    
    ```
    // src/i18n/ui.ts
    export const showDefaultLang = false;
    ```
    
3.  Add a helper function to `src/i18n/utils.ts`, to translate paths based on the current language:
    
    ```
    // src/i18n/utils.ts
    import { ui, defaultLang, showDefaultLang } from './ui';
    
    export function useTranslatedPath(lang: keyof typeof ui) {
      return function translatePath(path: string, l: string = lang) {
        return !showDefaultLang && l === defaultLang ? path : `/${l}${path}`
      }
    }
    ```
    
4.  Import the helper where needed. For example, a `nav` component might look like:
    
    ```
    ---
    // src/components/Nav.astro
    import { getLangFromUrl, useTranslations, useTranslatedPath } from '../i18n/utils';
    
    const lang = getLangFromUrl(Astro.url);
    const t = useTranslations(lang);
    const translatePath = useTranslatedPath(lang);
    ---
    <ul>
        <li>
            <a href={translatePath('/home/')}>
              {t('nav.home')}
            </a>
        </li>
        <li>
            <a href={translatePath('/about/')}>
              {t('nav.about')}
            </a>
        </li>
        <li>
            <a href="https://twitter.com/astrodotbuild">
              {t('nav.twitter')}
            </a>
        </li>
    </ul>
    ```
    
5.  The helper function can also be used to translate paths for a specific language. For example, when users switch between languages:
    
    ```
    ---
    // src/components/LanguagePicker.astro
    import { languages } from '../i18n/ui';
    import { getLangFromUrl, useTranslatedPath } from '../i18n/utils';
    
    const lang = getLangFromUrl(Astro.url);
    const translatePath = useTranslatedPath(lang);
    ---
    <ul>
      {Object.entries(languages).map(([lang, label]) => (
        <li>
          <a href={translatePath('/', lang)}>{label}</a>
        </li>
      ))}
    </ul>
    ```
    

### Translate Routes

Translate the routes of your pages for each language.

1\. Add route mappings to \`src/i18n/ui.ts\`:

````
```ts
// src/i18n/ui.ts
export const routes = {
  de: {
    'services': 'leistungen',
  },
  fr: {
    'services': 'prestations-de-service',
  },
}
```
````

2.  Update the `useTranslatedPath` helper function in `src/i18n/utils.ts` to add router translation logic.
    
    ```
    // src/i18n/utils.ts
    import { ui, defaultLang, showDefaultLang, routes } from './ui';
    
    export function useTranslatedPath(lang: keyof typeof ui) {
      return function translatePath(path: string, l: string = lang) {
        const pathName = path.replaceAll('/', '')
        const hasTranslation = defaultLang !== l && routes[l] !== undefined && routes[l][pathName] !== undefined
        const translatedPath = hasTranslation ? '/' + routes[l][pathName] : path
    
        return !showDefaultLang && l === defaultLang ? translatedPath : `/${l}${translatedPath}`
      }
    }
    ```
    
3.  Create a helper function to get the route, if it exists based on the current URL, in `src/i18n/utils.ts`:
    
    ```
    // src/i18n/utils.ts
    import { ui, defaultLang, showDefaultLang, routes } from './ui';
    
    export function getRouteFromUrl(url: URL): string | undefined {
      const pathname = new URL(url).pathname;
      const parts = pathname?.split('/');
      const path = parts.pop() || parts.pop();
    
      if (path === undefined) {
        return undefined;
      }
      
      const currentLang = getLangFromUrl(url);
    
      if (defaultLang === currentLang) {
        const route = Object.values(routes)[0];
        return route[path] !== undefined ? route[path] : undefined;
      }
      
      const getKeyByValue = (obj: Record<string, string>, value: string): string | undefined  => {
          return Object.keys(obj).find((key) => obj[key] === value);
      }
    
      const reversedKey = getKeyByValue(routes[currentLang], path);
    
      if (reversedKey !== undefined) {
        return reversedKey;
      }
    
      return undefined;
    }
    ```
    
4.  The helper function can be used to get a translated route. For example, when no translated route is defined, the user will be redirected to the home page:
    
    ```
    ---
    // src/components/LanguagePicker.astro
    import { languages } from '../i18n/ui';
    import { getRouteFromUrl, useTranslatedPath } from '../i18n/utils';
    
    const route = getRouteFromUrl(Astro.url);
    ---
    <ul>
      {Object.entries(languages).map(([lang, label]) => {
        const translatePath = useTranslatedPath(lang);
        return (
          <li>
            <a href={translatePath(`/${route ? route : ''}`)}>{label}</a>
          </li>
        )
      })}
    </ul>
    ```
    

## Resources

-   [Choosing a Language Tag](https://www.w3.org/International/questions/qa-choosing-language-tags)
-   [Right-to-left (RTL) Styling 101](https://rtlstyling.com/)

## Community libraries

Find [community-built i18n utilities](https://astro.build/integrations/?search=i18n) that you can add to your Astro project in our integrations directory.

## [Create a dev toolbar app](https://docharvest.github.io/docs/astro/recipes/making-toolbar-apps/)

Contents

astro

Create a dev toolbar app

Astro

Create a dev toolbar app

Astro includes a [development toolbar](/en/guides/dev-toolbar/) that you can use to inspect your site, check for accessibility and performance issues, and more. This toolbar can be extended with custom apps.

## Build a motivational dev toolbar app

In this recipe, you'll learn how to create a dev toolbar app that helps you stay motivated while working on your site. This app will display a motivational message every time you toggle it on.

:::tip Just want to get started quickly? Jump start your app by creating a new Astro project with the `toolbar-app` template.

\`\`\`shell npm create astro@latest -- --template toolbar-app \`\`\` \`\`\`shell pnpm create astro -- --template toolbar-app \`\`\` \`\`\`shell yarn create astro -- --template toolbar-app \`\`\`

Or, keep reading to learn how to build an app from scratch. :::

### Creating the Astro integration

Dev toolbar apps can only be added by [Astro Integrations](/en/guides/integrations/) using [the `astro:config:setup` hook](/en/reference/integrations-reference/#astroconfigsetup). You will need to create both a toolbar app and the integration that will add it to the toolbar of your existing Astro project.

1.  In the root of your existing Astro project, create a new folder named `my-toolbar-app/` for your app and integration files. Create two new files in this folder: `app.ts` and `my-integration.ts`.
    
    \- \*\*my-toolbar-app/\*\* - \*\*app.ts\*\* - \*\*my-integration.ts\*\* - src/ - pages/ - ... - astro.config.mjs - package.json - tsconfig.json
2.  In `my-integration.ts`, add the following code to provide both the name of your integration and the [`addDevToolbarApp()` function](/en/reference/dev-toolbar-app-reference/#toolbar-app-integration-setup) needed to add your dev toolbar app with the `astro:config:setup` hook:
    
    ```
    import { fileURLToPath } from 'node:url';
    import type { AstroIntegration } from 'astro';
    
    export default {
      name: 'my-astro-integration',
      hooks: {
        'astro:config:setup': ({ addDevToolbarApp }) => {  
          addDevToolbarApp({
            id: "my-toolbar-app",
            name: "My Toolbar App",
            icon: "🚀",
            entrypoint: fileURLToPath(new URL('./app.ts', import.meta.url))
          });
        },
      },
    } satisfies AstroIntegration;
    ```
    
    :::note\[Using relative paths to the entrypoint\] The `entrypoint` is the path to your dev toolbar app file **relative to the root of your existing Astro project**, not to the integration folder (`my-toolbar-app`) itself.
    
    To use relative paths for entrypoints, get the path to the current file using `import.meta.url` and resolve the path to the entrypoint from there. :::
    
3.  To use this integration in your project, add it to the `integrations` array in your `astro.config.mjs` file.
    
    ```
    import { defineConfig } from 'astro/config';
    import myIntegration from './my-toolbar-app/my-integration.ts';
    
    export default defineConfig({
      integrations: [myIntegration],
    })
    ```
    
4.  If not already running, start the dev server. If your integration has been successfully added to your project, you should see a new "undefined" app in the dev toolbar.
    
    But, you will also see an error message that your dev toolbar app has failed to load. This is because you have not yet built the app itself. You will do that in the next section.
    

See the [Astro Integration API documentation](/en/reference/integrations-reference/) for more about building Astro integrations.

### Creating the app

Dev toolbar apps are defined using the `defineToolbarApp()` function from the `astro/toolbar` module. This function takes an object with an `init()` function that will be called when the dev toolbar app is loaded.

This `init()` function contains your app logic to render elements to the screen, send and receive client-side events from the dev toolbar, and communicate with the server.

To display motivational messages on the screen, you will use the `canvas` property to access a standard [ShadowRoot](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot). Elements can be created and added to the ShadowRoot using the standard DOM APIs.

1.  Copy the following code into `my-toolbar-app/app.ts`. This provides a list of motivational messages, and the logic to create a new `<h1>` element with a random message:
    
    ```
    import { defineToolbarApp } from "astro/toolbar";
    
    const motivationalMessages = [
      "You're doing great!",
      "Keep up the good work!",
      "You're awesome!",
      "You're a star!",
    ];
    
    export default defineToolbarApp({
        init(canvas) {
          const h1 = document.createElement('h1');
          h1.textContent = motivationalMessages[Math.floor(Math.random() * motivationalMessages.length)];
    
          canvas.append(h1);
        },
    });
    ```
    
2.  Start the dev server if it is not already running and toggle the app on in the dev toolbar. If your app is working successfully, you will see a motivational message displayed in the top-left corner of the screen. (And, it's true!)
    
    However, this message will not change when the app is toggled on and off, as the `init()` function is only called once when the app is loaded.
    
3.  To add client-side interactivity to your app, add the `app` argument and use `onAppToggled()` to select a new random message each time your toolbar app is toggled on:
    
    ```
    import { defineToolbarApp } from "astro/toolbar";
    
    const motivationalMessages = [
      "You're doing great!",
      "Keep up the good work!",
      "You're awesome!",
      "You're a star!",
    ];
    
    export default defineToolbarApp({
        init(canvas, app) {
          const h1 = document.createElement('h1');
          h1.textContent = motivationalMessages[Math.floor(Math.random() * motivationalMessages.length)];
          
          canvas.append(h1);
    
          // Display a random message when the app is toggled
          app.onToggled(({ state }) => {
            const newMessage = motivationalMessages[Math.floor(Math.random() * motivationalMessages.length)];
            h1.textContent = newMessage;
          });
        },
    });
    ```
    
4.  In your browser preview, toggle your app on and off several times. With this change, a new random message will be selected every time you toggle the app on, providing you with an infinite source of motivation!
    

See the [Astro Dev Toolbar API documentation](/en/reference/dev-toolbar-app-reference/) for more about building dev toolbar apps.

## Building apps with a UI framework

UI frameworks like React, Vue, or Svelte can also be used to create dev toolbar apps. These frameworks provide a more declarative way to create UIs and can make your code more maintainable and easier to read.

The same motivational dev toolbar app built into your existing Astro project earlier on this page with JavaScript can be built using a UI framework (e.g. Preact) instead. Depending on your chosen framework, you may or may not require a build step.

:::note However you choose to build your dev toolbar app, using JavaScript or a UI framework, you will still need to [create the integration](#creating-the-astro-integration) that adds your app to the dev toolbar. :::

### Without a build step

If your framework supports it, you can create a dev toolbar app without a build step. For example, you can use Preact's `h` function to create elements and render them directly to the ShadowRoot:

```

const motivationalMessages = [
  "You're doing great!",
  "Keep up the good work!",
  "You're awesome!",
  "You're a star!",
];

      render(h('h1', null, message), canvas);
    },
});
```

Alternatively, the [`htm` package](https://github.com/developit/htm) is a good choice for creating dev toolbar apps without a build step, offering native integration for React and Preact and support for other frameworks:

```

const motivationalMessages = [
  "You're doing great!",
  "Keep up the good work!",
  "You're awesome!",
  "You're a star!",
];

      render(html`<h1>${message}</h1>`, canvas);
    },
});
```

In both cases, you can now start your project and see the motivational message displayed in the top-left corner of the screen when you toggle the app on.

### With a build step

Astro does not preprocess JSX code in dev toolbar apps, so a build step is required in order to use JSX components in your dev toolbar app.

The following steps will use TypeScript to do this, but any other tools that compile JSX code will also work (e.g. Babel, Rollup, ESBuild).

1\. Install TypeScript inside your project:

```
<PackageManagerTabs>
  <Fragment slot="npm">
    ```shell
    npm install --save-dev typescript
    ```
  </Fragment>
  <Fragment slot="pnpm">
    ```shell
    pnpm install --save-dev typescript
    ```
  </Fragment>
  <Fragment slot="yarn">
    ```shell
    yarn add --dev typescript
    ```
  </Fragment>
</PackageManagerTabs>
```

2.  Create a `tsconfig.json` file in the root of your toolbar app's folder with the appropriate settings to build and for the framework you're using ([React](https://react-typescript-cheatsheet.netlify.app/docs/basic/setup), [Preact](https://preactjs.com/guide/v10/typescript), [Solid](https://www.solidjs.com/guides/typescript)). For example, for Preact:
    
    ```
    {
      "compilerOptions": {
        "skipLibCheck": true,
        "module": "NodeNext",
        "jsx": "react-jsx",
        "jsxImportSource": "preact",
      }
    }
    ```
    
3.  Adjust the `entrypoint` in your integration to point to the compiled file, remembering that this file is relative to the root of your Astro project:
    
    ```
    addDevToolbarApp({
      id: "my-toolbar-app",
      name: "My Toolbar App",
      icon: "🚀",
      entrypoint: join(__dirname, "./app.js"),
    });
    ```
    
4.  Run `tsc` to build your toolbar app, or `tsc --watch` to automatically rebuild your app when you make changes.
    
    With these changes, you can now rename your `app.ts` file to `app.tsx` (or `.jsx`) and use JSX syntax to create your dev toolbar app:
    
    ```
    import { defineToolbarApp } from "astro/toolbar";
    import { render } from "preact";
    
    const motivationalMessages = [
      "You're doing great!",
      "Keep up the good work!",
      "You're awesome!",
      "You're a star!",
    ];
    
    export default defineToolbarApp({
        init(canvas) {
          const message = motivationalMessages[Math.floor(Math.random() * motivationalMessages.length)];
          render(<h1>{message}</h1>, canvas);
        },
    });
    ```
    

You should now have all the tools you need to create a dev toolbar app using a UI framework of your choice!

## [Add last modified time](https://docharvest.github.io/docs/astro/recipes/modified-time/)

Contents

astro

Add last modified time

Astro

Add last modified time

Learn how to build a [remark plugin](https://github.com/remarkjs/remark) that adds the last modified time as a [custom frontmatter property](/en/guides/markdown-content/#modifying-frontmatter-programmatically) of your Markdown and MDX files. Use this property to display the modified time in your pages.

:::note\[Uses Git history\] This recipe calculates time based on your repository’s Git history and may not be accurate on some deployment platforms. Your host may be performing **shallow clones** which do not retrieve the full git history. :::

## Recipe

1\. Install \[\`Day.js\`\](https://www.npmjs.com/package/dayjs) to modify and format times, and \[\`@astrojs/markdown-remark\`\](https://www.npmjs.com/package/@astrojs/markdown-remark) to use \[the \`unified()\` processor\](/en/guides/markdown-content/#using-remark-and-rehype-plugins): \`\`\`shell npm install dayjs @astrojs/markdown-remark \`\`\` \`\`\`shell pnpm add dayjs @astrojs/markdown-remark \`\`\` \`\`\`shell yarn add dayjs @astrojs/markdown-remark \`\`\`

2.  Create a Remark Plugin
    
    This plugin uses `execSync` to run a Git command that returns the timestamp of the latest commit in ISO 8601 format. The timestamp is then added to the frontmatter of the file.
    
    ```
    import { execSync } from "node:child_process";
    
    export function remarkModifiedTime() {
      return function (tree, file) {
        const filepath = file.history[0];
        const result = execSync(`git log -1 --pretty="format:%cI" "${filepath}"`);
        file.data.astro.frontmatter.lastModified = result.toString();
      };
    }
    ```
    
    ```
     <details>
     <summary>Using the file system instead of Git</summary>
    
      Although using Git is the recommended way to get the last modified timestamp from a file, it is possible to use the file system modified time.
    ```
    
    This plugin uses `statSync` to get the `mtime` (modified time) of the file in ISO 8601 format. The timestamp is then added to the frontmatter of the file.
    
    ```
    import { statSync } from "fs";
    
    export function remarkModifiedTime() {
      return function (tree, file) {
        const filepath = file.history[0];
        const result = statSync(filepath);
        file.data.astro.frontmatter.lastModified = result.mtime.toISOString();
      };
    }
    ```
    
    ```
     </details>
    ```
    
3.  Add the plugin to your config
    
    ```
    import { unified } from '@astrojs/markdown-remark';
    import { defineConfig } from 'astro/config';
    import { remarkModifiedTime } from './remark-modified-time.mjs';
    
    export default defineConfig({
      markdown: {
        processor: unified({
          remarkPlugins: [remarkModifiedTime],
        }),
      },
    });
    ```
    
    Now all Markdown documents will have a `lastModified` property in their frontmatter.
    
4.  Display Last Modified Time
    
    If your content is stored in a [content collection](/en/guides/content-collections/), access the `remarkPluginFrontmatter` from the `render(entry)` function. Then render `lastModified` in your template wherever you would like it to appear.
    
    ```
    ---
    import { getCollection, render } from 'astro:content';
    import dayjs from "dayjs";
    import utc from "dayjs/plugin/utc";
    
    dayjs.extend(utc);
    
    export async function getStaticPaths() {
      const blog = await getCollection('blog');
      return blog.map(entry => ({
        params: { slug: entry.id },
        props: { entry },
      }));
    }
    
    const { entry } = Astro.props;
    const { Content, remarkPluginFrontmatter } = await render(entry);
    
    const lastModified = dayjs(remarkPluginFrontmatter.lastModified)
      .utc()
      .format("HH:mm:ss DD MMMM YYYY UTC");
    ---
    
    <html>
      <head>...</head>
      <body>
        ...
        <p>Last Modified: {lastModified}</p>
        ...
      </body>
    </html>
    ```
    
    If you're using a [Markdown layout](/en/basics/layouts/#markdown-layouts), use the `lastModified` frontmatter property from `Astro.props` in your layout template.
    
    ```
    ---
    import dayjs from "dayjs";
    import utc from "dayjs/plugin/utc";
    
    dayjs.extend(utc);
    
    const lastModified = dayjs()
      .utc(Astro.props.frontmatter.lastModified)
      .format("HH:mm:ss DD MMMM YYYY UTC");
    ---
    
    <html>
      <head>...</head>
      <body>
        <p>{lastModified}</p>
        <slot />
      </body>
    </html>
    ```

## [Add reading time](https://docharvest.github.io/docs/astro/recipes/reading-time/)

Contents

astro

Add reading time

Astro

Add reading time

Create a [remark plugin](https://github.com/remarkjs/remark) which adds a reading time property to the frontmatter of your Markdown or MDX files. Use this property to display the reading time for each page.

## Recipe

1\. Install the following packages: - \[\`reading-time\`\](https://www.npmjs.com/package/reading-time) to calculate minutes read - \[\`mdast-util-to-string\`\](https://www.npmjs.com/package/mdast-util-to-string) to extract all text from your markdown - \[\`@astrojs/markdown-remark\`\](https://www.npmjs.com/package/@astrojs/markdown-remark) to use \[the \`unified()\` processor\](/en/guides/markdown-content/#using-remark-and-rehype-plugins):

```
<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
npm install reading-time mdast-util-to-string @astrojs/markdown-remark
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
pnpm add reading-time mdast-util-to-string @astrojs/markdown-remark
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
yarn add reading-time mdast-util-to-string @astrojs/markdown-remark
  ```
  </Fragment>
</PackageManagerTabs>
```

2.  Create a remark plugin.
    
    This plugin uses the `mdast-util-to-string` package to get the Markdown file's text. This text is then passed to the `reading-time` package to calculate the reading time in minutes.
    
    ```
    import getReadingTime from 'reading-time';
    import { toString } from 'mdast-util-to-string';
    
    export function remarkReadingTime() {
      return function (tree, { data }) {
        const textOnPage = toString(tree);
        const readingTime = getReadingTime(textOnPage);
        // readingTime.text will give us minutes read as a friendly string,
        // i.e. "3 min read"
        data.astro.frontmatter.minutesRead = readingTime.text;
      };
    }
    ```
    
3.  Add the plugin to your config:
    
    ```
    import { unified } from '@astrojs/markdown-remark';
    import { defineConfig } from 'astro/config';
    import { remarkReadingTime } from './remark-reading-time.mjs';
    
    export default defineConfig({
      markdown: {
        processor: unified({
          remarkPlugins: [remarkReadingTime],
        }),
      },
    });
    ```
    
    Now all Markdown documents will have a calculated `minutesRead` property in their frontmatter.
    
4.  Display Reading Time
    
    If your blog posts are stored in a [content collection](/en/guides/content-collections/), access the `remarkPluginFrontmatter` from the `render(entry)` function. Then, render `minutesRead` in your template wherever you would like it to appear.
    
    ```
    ---
    import { getCollection, render } from 'astro:content';
    
    export async function getStaticPaths() {
      const blog = await getCollection('blog');
      return blog.map(entry => ({
        params: { slug: entry.id },
        props: { entry },
      }));
    }
    
    const { entry } = Astro.props;
    const { Content, remarkPluginFrontmatter } = await render(entry);
    ---
    
    <html>
      <head>...</head>
      <body>
        ...
        <p>{remarkPluginFrontmatter.minutesRead}</p>
        ...
      </body>
    </html>
    ```
    
    If you're using a [Markdown layout](/en/basics/layouts/#markdown-layouts), use the `minutesRead` frontmatter property from `Astro.props` in your layout template.
    
    ```
    ---
    const { minutesRead } = Astro.props.frontmatter;
    ---
    
    <html>
      <head>...</head>
      <body>
        <p>{minutesRead}</p>
        <slot />
      </body>
    </html>
    ```

## [Add an RSS feed](https://docharvest.github.io/docs/astro/recipes/rss/)

Contents

astro

Add an RSS feed

Astro

Add an RSS feed

Astro supports fast, automatic RSS feed generation for blogs and other content websites. RSS feeds provide an easy way for users to subscribe to your content.

## Setting up `@astrojs/rss`

The package [`@astrojs/rss`](https://github.com/withastro/astro/tree/main/packages/astro-rss) provides helpers for generating RSS feeds using [API endpoints](/en/guides/endpoints/#static-file-endpoints). This unlocks both static builds _and_ on-demand generation when using an [SSR adapter](/en/guides/on-demand-rendering/).

1\. Install \`@astrojs/rss\` using your preferred package manager:

```
<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install @astrojs/rss
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm add @astrojs/rss
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn add @astrojs/rss
  ```
  </Fragment>
</PackageManagerTabs>

:::tip
Ensure you've [configured a `site`](/en/reference/configuration-reference/#site) in your project's `astro.config`. This will be used to generate links to your RSS articles.
:::
```

2.  Create a file in `src/pages/` with a name of your choice and the extension `.xml.js` to be used as the output URL for your feed. Some common RSS feed URL names are `feed.xml` or `rss.xml`.
    
    The example file below `src/pages/rss.xml.js` will create an RSS feed at `site/rss.xml`.
    
3.  Import the `rss()` helper from the `@astrojs/rss` package into your `.xml.js` file and export a function that returns it using the following parameters:
    
    ```
    import rss from '@astrojs/rss';
    
    export function GET(context) {
      return rss({
        // `<title>` field in output xml
        title: 'Buzz’s Blog',
        // `<description>` field in output xml
        description: 'A humble Astronaut’s guide to the stars',
        // Pull in your project "site" from the endpoint context
        // https://docs.astro.build/en/reference/api-reference/#site
        site: context.site,
        // Array of `<item>`s in output xml
        // See "Generating items" section for examples using content collections and glob imports
        items: [],
        // (optional) inject custom xml
        customData: `<language>en-us</language>`,
      });
    }
    ```
    

See the [`@astrojs/rss` README](https://github.com/withastro/astro/tree/main/packages/astro-rss) for the full configuration reference.

## Generating `items`

The `items` field accepts a list of RSS feed objects, which can be generated from content collections entries using `getCollection()` or from your page files using `pagesGlobToRssItems()`.

The RSS feed standard format includes metadata for each published item, including values such as:

-   `title`: The title of the entry. Optional only if a `description` is set. Otherwise, required.
-   `description`: A short excerpt from or describing the entry. Optional only if a `title` is set. Otherwise, required.
-   `link`: A URL to the original source of the entry. (optional)
-   `pubDate`: The date of publication of the entry. (optional)
-   `content`: The full content of your post. (optional)

See the [`items` configuration reference](https://github.com/withastro/astro/tree/main/packages/astro-rss#items) for a complete list of options.

### Using content collections

To create an RSS feed of pages managed in [content collections](/en/guides/content-collections/), use the `getCollection()` function to retrieve the data required for your `items` array. You will need to specify the values for each desired property (e.g. `title`, `description`) from the returned data.

```

  return rss({
    title: 'Buzz’s Blog',
    description: 'A humble Astronaut’s guide to the stars',
    site: context.site,
    items: blog.map((post) => ({
      title: post.data.title,
      pubDate: post.data.pubDate,
      description: post.data.description,
      // Compute RSS link from post `id`
      // This example assumes all posts are rendered as `/blog/[id]` routes
      link: `/blog/${post.id}/`,
    })),
  });
}
```

Optional: replace your existing blog collection schema to enforce the expected RSS properties.

To ensure that every blog entry produces a valid RSS feed item, you can optionally import and apply `rssSchema` instead of defining each individual property of your schema.

```

const blog = defineCollection({
  schema: rssSchema,
});
```

### Using glob imports

To create an RSS feed from documents in `src/pages/`, use the `pagesGlobToRssItems()` helper. This accepts an [`import.meta.glob`](https://vite.dev/guide/features.html#glob-import) result and outputs an array of valid RSS feed items (see [more about writing glob patterns](/en/guides/imports/#glob-patterns) for specifying which pages to include).

:::caution This function assumes, but does not verify, that all necessary feed properties are present in each document's frontmatter. If you encounter errors, verify each page frontmatter manually. :::

```

}
```

:::note\[Using an older version?\] In versions of `@astrojs/rss` before v2.1.0, pass your glob result straight to `items` without the `pagesGlobToRssItems()` wrapper:

```
items: import.meta.glob('./blog/*.{md,mdx}'),
```

This method is deprecated for all versions of Astro since v2.1.0, and cannot be used on modern projects. :::

### Including full post content

Set the `content` key on `rss.items` to provide the full content of a post as HTML. This allows `@astrojs/rss` to make the full Markdown text of your post available to RSS feed readers. Images and links with full URL paths are also supported. However, images and internal links to other pages using relative paths are not.

When rendering full post content, you will have to consider images, relative links, styles, scripts, and other elements beyond standard Markdown text that you may have in your posts. You may need to include additional logic in your `src/pages/rss.xml.js` endpoint to account for these, or to remove elements that are unnecessary for an RSS feed (e.g. those that are used only for styling or interaction on your website).

You can see [one specific community implementation](https://github.com/delucis/astro-blog-full-text-rss/blob/latest/src/pages/rss.xml.ts) that addresses some of these concerns for an example of how to proceed.

:::tip A package like [`sanitize-html`](https://www.npmjs.com/package/sanitize-html) will make sure that your content is properly sanitized, escaped, and encoded. In the process, such a package might also remove some harmless elements and attributes, so make sure to verify the output and configure the package according to your needs. :::

When using content collections, render the post `body` using a standard Markdown parser like [`markdown-it`](https://github.com/markdown-it/markdown-it) and sanitize the result, including any extra tags (e.g. `<img>`) needed to render your content:

```

const parser = new MarkdownIt();

  return rss({
    title: 'Buzz’s Blog',
    description: 'A humble Astronaut’s guide to the stars',
    site: context.site,
    items: blog.map((post) => ({
      link: `/blog/${post.id}/`,
      // Note: this will not process components or JSX expressions in MDX files.
      content: sanitizeHtml(parser.render(post.body), {
        allowedTags: sanitizeHtml.defaults.allowedTags.concat(['img'])
      }),
      ...post.data,
    })),
  });
}
```

When using glob imports with Markdown, you may use the `compiledContent()` helper to retrieve the rendered HTML for sanitization. Note: this feature is **not** supported for MDX files.

```

  const posts = Object.values(postImportResult);
  return rss({
    title: 'Buzz’s Blog',
    description: 'A humble Astronaut’s guide to the stars',
    site: context.site,
    items: await Promise.all(posts.map(async (post) => ({
      link: post.url,
      content: sanitizeHtml((await post.compiledContent())),
      ...post.frontmatter,
    }))),
  });
}
```

## Removing trailing slashes

Astro's RSS feed produces links with a trailing slash by default, no matter what value you have configured for `trailingSlash`. This means that your RSS links may not match your post URLs exactly.

If you have set `trailingSlash: "never"` on your `astro.config.mjs`, set `trailingSlash: false` in the `rss()` helper so that your feed matches your project configuration.

```

  return rss({
    title: 'Buzz’s Blog',
    description: 'A humble Astronaut’s guide to the stars',
    site: context.site,
    trailingSlash: false,
    items: posts.map((post) => ({
      link: post.url,
      ...post.frontmatter,
    })),
  });
}
```

## Adding a stylesheet

Style your RSS feed for a more pleasant user experience when viewing the file in your browser.

Use the `rss` function's `stylesheet` option to specify an absolute path to your stylesheet.

```
rss({
  // ex. use your stylesheet from "public/rss/styles.xsl"
  stylesheet: '/rss/styles.xsl',
  // ...
});
```

:::tip If you'd prefer not to create your own stylesheet, you may use a premade stylesheet such as the [Pretty Feed v3 default stylesheet](https://github.com/genmon/aboutfeeds/blob/main/tools/pretty-feed-v3.xsl). Download the stylesheet from GitHub and save into your project's `public/` directory. :::

## Enabling RSS feed auto-discovery

[RSS autodiscovery](https://www.rssboard.org/rss-autodiscovery) allows browsers and other software to automatically find a site's RSS feed from the main URL.

To enable, add a `<link>` tag with the following attributes to your site's `head` element:

```
<link
    rel="alternate"
    type="application/rss+xml"
    title="Your Site's Title"
    href={new URL("rss.xml", Astro.site)}
/>
```

With this tag, readers of your blog can enter your site's base URL into their RSS reader to subscribe to your posts without needing the specific URL of your RSS feed.

## Next Steps

After visiting your feed in the browser at `your-domain.com/rss.xml` and confirming that you can see data for each of your posts, you can now [promote your feed on your website](https://medium.com/samsung-internet-dev/add-rss-feeds-to-your-website-to-keep-your-core-readers-engaged-3179dca9c91e#:~:text=com/~deno%2Drss-,Advertising%20your%20RSS%20feed,-Now%20you%20have). Adding the standard RSS icon to your site lets your readers know that they can subscribe to your posts in their own feed reader.

## Resources

-   [RSS Feeds](https://aboutfeeds.com/)

## [Share state between Astro components](https://docharvest.github.io/docs/astro/recipes/sharing-state/)

Contents

astro

Share state between Astro components

Astro

Share state between Astro components

:::tip Using framework components? See [how to share state between Islands](/en/recipes/sharing-state-islands/)! :::

When building an Astro website, you may need to share state across components. Astro recommends the use of [Nano Stores](https://github.com/nanostores/nanostores) for shared client storage.

## Recipe

1\. Install Nano Stores:

```
<PackageManagerTabs>
  <Fragment slot="npm">
  ```shell
  npm install nanostores
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```shell
  pnpm add nanostores
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```shell
  yarn add nanostores
  ```
  </Fragment>
</PackageManagerTabs>
```

2.  Create a store. In this example, the store tracks whether a dialog is open or not:
    
    ```
    import { atom } from 'nanostores';
    
    export const isOpen = atom(false);
    ```
    
3.  Import and use the store in a `<script>` tag in the components that will share state.
    
    The following `Button` and `Dialog` components each use the shared `isOpen` state to control whether a particular `<div>` is hidden or displayed:
    
    ```
    <button id="openDialog">Open</button>
    
    <script>
      import { isOpen } from '../store.js';
      
      // Set the store to true when the button is clicked
      function openDialog() {
        isOpen.set(true);
      }
    
      // Add an event listener to the button
      document.getElementById('openDialog').addEventListener('click', openDialog);
    </script>
    ```
    
    ```
    <div id="dialog" style="display: none">Hello world!</div>
    
    <script>
      import { isOpen } from '../store.js';
    
      // Listen to changes in the store, and show/hide the dialog accordingly    
      isOpen.subscribe(open => {
        if (open) {
          document.getElementById('dialog').style.display = 'block';
        } else {
          document.getElementById('dialog').style.display = 'none';
        }
      })
    </script>
    ```
    

## Resources

-   [Nano Stores on NPM](https://www.npmjs.com/package/nanostores)
-   [Nano Stores documentation for Vanilla JS](https://github.com/nanostores/nanostores#vanilla-js)

## [Share state between islands](https://docharvest.github.io/docs/astro/recipes/sharing-state-islands/)



## [Using streaming to improve page performance](https://docharvest.github.io/docs/astro/recipes/streaming-improve-page-performance/)

Contents

astro

Using streaming to improve page performance

Astro

Using streaming to improve page performance

Astro's SSR uses HTML streaming to send each component to the browser when available for faster page loading. To improve your page's performance even further, you can build your components strategically to optimize their loading by avoiding blocking data fetches.

The following refactoring example demonstrates how to improve page performance by moving fetch calls to other components, moving them out of a component where they block page rendering.

The following page `await`s some data in its frontmatter. Astro will wait for all of the `fetch` calls to resolve before sending any HTML to the browser.

```
---
const personResponse = await fetch('https://randomuser.me/api/');
const personData = await personResponse.json();
const randomPerson = personData.results[0];
const factResponse = await fetch('https://catfact.ninja/fact');
const factData = await factResponse.json();
---
<html>
  <head>
    <title>A name and a fact</title>
  </head>
  <body>
    <h2>A name</h2>
    <p>{randomPerson.name.first}</p>
    <h2>A fact</h2>
    <p>{factData.fact}</p>
  </body>
</html>
```

Moving the `await` calls into smaller components allows you to take advantage of Astro's streaming. Using the following components to perform the data fetches, Astro can render some HTML first, such as the title, and then the paragraphs when the data is ready.

```
---
const personResponse = await fetch('https://randomuser.me/api/');
const personData = await personResponse.json();
const randomPerson = personData.results[0];
---
<p>{randomPerson.name.first}</p>
```

```
---
const factResponse = await fetch('https://catfact.ninja/fact');
const factData = await factResponse.json();
---
<p>{factData.fact}</p>
```

The Astro page below using these components can render parts of the page sooner. The `<head>`, `<body>`, and `<h2>` tags are no longer blocked by data fetches. The server will then fetch data for `RandomName` and `RandomFact` in parallel and stream the resulting HTML to the browser.

```
---

---
<html>
  <head>
    <title>A name and a fact</title>
  </head>
  <body>
    <h2>A name</h2>
    <RandomName />
    <h2>A fact</h2>
    <RandomFact />
  </body>
</html>
```

#### Including Promises directly

You can also include promises directly in the template. Instead of blocking the entire component, it will resolve the promise in parallel and only block the markup that comes after it.

```
---
const personPromise = fetch('https://randomuser.me/api/')
  .then(response => response.json())
  .then(personData => personData.results[0].name.first);
const factPromise = fetch('https://catfact.ninja/fact')
  .then(response => response.json())
  .then(factData => factData.fact);
---
<html>
  <head>
    <title>A name and a fact</title>
  </head>
  <body>
    <h2>A name</h2>
    <p>{personPromise}</p>
    <h2>A fact</h2>
    <p>{factPromise}</p>
  </body>
</html>
```

In this example, `A name` will render while `personPromise` and `factPromise` are loading. Once `personPromise` has resolved, `A fact` will appear and `factPromise` will render when it's finished loading.

## [Style rendered Markdown with Tailwind Typography](https://docharvest.github.io/docs/astro/recipes/tailwind-rendered-markdown/)



## [Astro Adapter API](https://docharvest.github.io/docs/astro/reference/adapter-reference/)

Contents

astro

Astro Adapter API

Astro

Astro Adapter API

Astro is designed to make it easy to deploy to any cloud provider for on-demand rendering, also known as server-side rendering (SSR). This ability is provided by **adapters**, which are [integrations](/en/reference/integrations-reference/). See the [on-demand rendering guide](/en/guides/on-demand-rendering/) to learn how to use an existing adapter.

## What is an adapter?

An adapter is a special kind of [integration](/en/reference/integrations-reference/) that provides an entrypoint for server rendering at request time. An adapter has access to the full Integration API and does two things:

-   Implements host-specific APIs for handling requests.
-   Configures the build according to host conventions.

## Building an adapter

Create an integration and call the `setAdapter()` function in the [`astro:config:done`](/en/reference/integrations-reference/#astroconfigdone) hook. This allows you to define a server entrypoint and the features supported by your adapter.

The following example creates an adapter with a server entrypoint and stable support for Astro static output:

```

      },
    },
  };
}
```

The `setAdapter()` function accepts an object containing the following properties:

### `name`

**Type:** `string`

Defines a unique name for your adapter. This will be used for logging.

### `entrypointResolution`

**Type:** `"explicit" | "auto"`  
**Default**: `"explicit"`  

:::caution\[Deprecated\] `entrypointResolution: "explicit"` is deprecated. `entrypointResolution: "auto"` will become the default, and only, behavior in a future major version.

See [how to migrate](/en/guides/upgrade-to/v6/#deprecated-createexports-and-start-adapter-api). :::

Specifies the method Astro will use to resolve the server entrypoint: `"auto"` (recommended) or `"explicit"` (default, but deprecated):

-   **`"auto"` (recommended):** You are responsible for providing a valid module as an entrypoint using either [`serverEntrypoint`](/en/reference/adapter-reference/#serverentrypoint) or, if you need further customization at the Vite level using [`vite.build.rollupOptions.input`](https://rollupjs.org/configuration-options/#input).
-   **`"explicit"` (deprecated)**: You must provide the exports required by the host in the server entrypoint using a `createExports()` function before passing them to `setAdapter()` as an [`exports`](#exports) list. This supports adapters built using the Astro 5 version of the Adapter API. By default, all adapters will receive this value to allow backwards compatibility. **However, no new adapters should be created with this value.** Existing adapters should override this default value with `"auto"` as soon as they are able to migrate to the new v6 API.

The following example defines the `entrypointResolution` and `serverEntrypoint` to tell Astro that a custom entrypoint is provided:

```

      },
    },
  };
}
```

The following example defines the `entrypointResolution` and Rollup options to tell Astro that a custom entrypoint is provided:

```

      },
    },
  };
}
```

Learn more about how to [build a server entrypoint](#building-a-server-entrypoint).

### `serverEntrypoint`

**Type:** `string | URL`

Defines the entrypoint for on-demand rendering.

### `supportedAstroFeatures`

**Type:** `AstroAdapterFeatureMap`  

A map of Astro's built-in features supported by the adapter. This allows Astro to determine which features an adapter supports, so appropriate error messages can be provided.

Discover the [available Astro features](#astro-features) that an adapter can configure.

### `adapterFeatures`

**Type:** `AstroAdapterFeatures`  

An object that specifies which [adapter features that change the build output](#adapter-features) are supported by the adapter.

### `client`

**Type:** `{ internalFetchHeaders?: Record<string, string> | () => Record<string, string>; assetQueryParams?: URLSearchParams; }`  

A configuration object for Astro's client-side code.

#### `client.internalFetchHeaders`

**Type:** `Record<string, string> | () => Record<string, string>`

Defines the headers to inject into Astro's internal fetch calls (e.g. Actions, View Transitions, Server Islands, Prefetch). This can be an object of headers or a function that returns headers.

The following example retrieves a `DEPLOY_ID` from the environment variables and, if provided, returns an object with the header name as key and the deploy id as value:

```

              return deployId ? { 'Your-Header-ID': deployId } : {};
            },
          },
        });
      },
    },
  };
}
```

#### `client.assetQueryParams`

**Type:** `URLSearchParams`

Defines the query parameters to append to all asset URLs (e.g. images, stylesheets, scripts). This is useful for adapters that need to track deployment versions or other metadata.

The following example retrieves a `DEPLOY_ID` from the environment variables and, if provided, returns an object with a custom search parameter name as key and the deploy id as value:

```

      },
    },
  };
}
```

### `previewEntrypoint`

**Type:** `string | URL`  

Defines the path or ID of a module in the adapter's package that is responsible for starting up the built server when `astro preview` is run.

```

      },
    },
  };
}
```

Learn more about how to [build a preview entrypoint](#building-a-preview-entrypoint).

### `args`

**Type:** `any`

:::caution\[Deprecated\] This property is deprecated and will be removed in a future major version. Learn how to [update your adapter with `entrypointResolution: "auto"`](/en/guides/upgrade-to/v6/#deprecated-createexports-and-start-adapter-api). :::

A JSON-serializable value that will be passed to the adapter's server entrypoint at runtime. This is useful to pass an object containing build-time configuration (e.g. paths, secrets) to your server runtime code.

The following example defines an `args` object with a property that identifies where assets generated by Astro are located:

```

      },
    },
  };
}
```

### `exports`

**Type:** `string[]`

:::caution\[Deprecated\] This property is deprecated and will be removed in a future major version. Learn how to [update your adapter with `entrypointResolution: "auto"`](/en/guides/upgrade-to/v6/#deprecated-createexports-and-start-adapter-api). :::

Defines an array of named exports to use in conjunction with the `createExports()` function of your server entrypoint.

The following example assumes that `createExports()` provides an export named `handler`:

```

      },
    },
  };
}
```

## Custom prerenderer

Adapters can provide a custom prerenderer to control how pages are prerendered by using the [`setPrerenderer()`](/en/reference/integrations-reference/#setprerenderer-option) function in the `astro:build:start` hook.

The following example shows how an adapter can set a custom prerenderer:

```

          },
          async render(request, { routeData }) {
            // request: Request, options: { routeData: RouteData }
            // Custom rendering logic, e.g. make HTTP requests to a preview server
            const response = await fetch(`http://localhost:4321${new URL(request.url).pathname}`);
            return response;
          },
          async teardown() {
            // Stop the preview server
          }
        }));
      },
      'astro:config:done': ({ setAdapter }) => {
        setAdapter({
          name: '@example/my-adapter',
          entrypointResolution: 'auto',
          serverEntrypoint: '@example/my-adapter/server.js',
        });
      },
    },
  };
}
```

The factory function receives the default prerenderer, allowing you to wrap or extend its behavior. This is useful when you only need to customize specific aspects of prerendering.

## Building a server entrypoint

You will need to create a file that executes during server-side requests to enable on-demand rendering with your particular host. Astro's adapter API attempts to work with any type of host and gives a flexible way to conform to the host APIs.

You can import and use [`createApp()`](/en/reference/modules/astro-app/#createapp) to access methods that allow you to work with standard [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) and [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) objects.

This file should conform to what the host expects. For example, some serverless hosts expect you to export an `handler()` function:

```

const app = createApp();

const RESOLVED_VIRTUAL_MODULE_ID = '\0' + VIRTUAL_MODULE_ID;

function createConfigPlugin(config) {
  return {
    name: VIRTUAL_MODULE_ID,
		resolveId: {
			filter: {
				id: new RegExp(`^${VIRTUAL_MODULE_ID}$`),
			},
			handler() {
				return RESOLVED_VIRTUAL_MODULE_ID;
			},
		},
		load: {
			filter: {
				id: new RegExp(`^${RESOLVED_VIRTUAL_MODULE_ID}$`),
			},
			handler() {
				return `
          export const assets = ${JSON.stringify(config.build.assets)};
        `;
			},
		},
	};
}

  return {
    name: '@example/my-adapter',
    hooks: {
      'astro:config:setup': ({ config, updateConfig }) => {
        _config = config;

        updateConfig({
          vite: {
            plugins: [createConfigPlugin(_config)]
          }
        })
      },
      'astro:config:done': ({ config, setAdapter }) => {
        _config = config;
        setAdapter({
          name: '@example/my-adapter',
          entrypointResolution: 'auto',
          serverEntrypoint: '@example/my-adapter/server.js',
        });
      },
    },
  };
}
```

You can create internal types if needed:

```
declare module 'virtual:@example/my-adapter:config' {
  export const assets: string;
}
```

You can then import the virtual module:

```

const app = createApp();

  const port = config.port ?? 4321;
  const server = createServer(host, port);

  return server;
};
```

## Astro features

Astro features are a way for an adapter to tell Astro whether they are able to support a feature, and also the adapter’s level of support.

When using these properties, Astro will:

-   run specific validation;
-   emit contextual information to the logs;

These operations are run based on the features supported or not supported, their level of support, the [desired amount of logging](#adaptersupportwithmessagesuppress), and the user's own configuration.

The following configuration tells Astro that this adapter has experimental support for the Sharp-powered built-in image service:

```

      },
    },
  };
}
```

If the Sharp image service is used, Astro will log a warning and error to the terminal based on your adapter's support:

```
[@example/my-adapter] The feature is experimental and subject to issues or changes.

[@example/my-adapter] The currently selected adapter `@example/my-adapter` is not compatible with the service "Sharp". Your project will NOT be able to build.
```

A message can additionally be provided to give more context to the user:

```

      },
    },
  };
}
```

This object contains the following configurable features:

### `staticOutput`

**Type:** [`AdapterSupport`](#adaptersupport)

Defines whether the adapter is able to serve static pages.

### `hybridOutput`

**Type:** [`AdapterSupport`](#adaptersupport)

Defines whether the adapter is able to serve sites that include a mix of static and on-demand rendered pages.

### `serverOutput`

**Type:** [`AdapterSupport`](#adaptersupport)

Defines whether the adapter is able to serve on-demand rendered pages.

### `i18nDomains`

**Type:** [`AdapterSupport`](#adaptersupport)  

Defines whether the adapter is able to support i18n domains.

### `envGetSecret`

**Type:** [`AdapterSupport`](#adaptersupport)  

Defines whether the adapter is able to support `getSecret()` exported from [`astro:env/server`](/en/reference/modules/astro-env/). When enabled, this feature allows your adapter to retrieve secrets configured by users in `env.schema`.

The following example enables the feature by passing [a valid `AdapterSupportsKind` value](#adaptersupportskind) to the adapter:

```

      },
    },
  };
}
```

The `astro/env/setup` module allows you to provide an implementation for `getSecret()`. In [your server entrypoint](#building-a-server-entrypoint), call `setGetEnv()` as soon as possible:

```

    return await app.render(request);
  }
}
```

### `sharpImageService`

**Type:** [`AdapterSupport`](#adaptersupport)  

Defines whether the adapter supports image transformation using the built-in Sharp image service.

## Adapter features

A set of features that changes the output of the emitted files. When an adapter opts in to these features, they will get additional information inside specific hooks and must implement the proper logic to handle the different output.

### `middlewareMode`

**Type:** [`MiddlewareMode`](#middlewaremode-1)  
**Default:** `"classic"`  

Determines at which stage of the page lifecycle the middleware is executed, and how the middleware code is emitted in the build output.

The `classic` mode matches the default behavior of Astro. On prerendered pages, middleware is run at build time, and when the page is requested, the middleware is not run again. On dynamic pages, middleware is run at request time only. The middleware code is part of your server bundle.

In `edge` mode, the middleware code can be deployed independently from the server bundle, for example, as an edge function.

```

      },
    },
  };
}
```

Then, consume the hook [`astro:build:ssr`](/en/reference/integrations-reference/#astrobuildssr), which will give you a `middlewareEntryPoint`, an `URL` to the physical file on the file system.

```

      },

      'astro:build:ssr': ({ middlewareEntryPoint }) => {
        // remember to check if this property exits, it will be `undefined` if the adapter doesn't opt in to the feature
        if (middlewareEntryPoint) {
          createEdgeMiddleware(middlewareEntryPoint)
        }
      }  
    },
  };
}

function createEdgeMiddleware(middlewareEntryPoint) {
  // emit a new physical file using your bundler
}
```

### `buildOutput`

**Type:** `"static" | "server"`  
**Default:** `"server"`  

Allows you to force a specific output shape for the build. This can be useful for adapters that only work with a specific output type. For example, your adapter might expect a static website so it can create host-specific files. Defaults to `server` if not specified.

```

      },
    },
  };
}
```

### `staticHeaders`

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

Whether or not the adapter provides support for setting response headers for static pages. When this feature is enabled, Astro will return a map of the `Headers` emitted by the static pages. This map is available as `routeToHeaders` in the [`astro:build:generated` hook](/en/reference/integrations-reference/#astrobuildgenerated) and can be used to generate platform-specific output that controls HTTP headers, for example, to create a `_headers` file for platforms that support it.

```

      },
      'astro:build:generated': ({ routeToHeaders }) => {
        // use `routeToHeaders` to generate a configuration file
        // for your virtual host of choice
      },
    },
  };
}
```

The value of the headers might change based on the features enabled/used by the application. For example, if [CSP is enabled](/en/reference/configuration-reference/#securitycsp), the `<meta http-equiv="content-security-policy">` element is not added to the static page. Instead, its `content` is available in the `routeToHeaders` map.

### `preserveBuildClientDir`

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

When `true`, static builds will preserve the `client/server` directory structure instead of outputting directly to `outDir`. This ensures static builds use `build.client` for assets, maintaining consistency with server builds.

This is useful for adapters that require a specific directory structure regardless of the build output type, such as deploying to platforms with specific file organization requirements.

```

      },
    },
  };
}
```

### `preserveBuildServerDir`

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

When `true`, static builds will preserve the `client/server` directory structure for server output instead of outputting directly to `outDir`. This ensures static builds use `build.server` for server files, maintaining consistency with server builds.

This is useful for adapters that require a consistent `dist/client/` and `dist/server/` layout regardless of the build output type, such as when a static site may still contain server islands or image endpoints that need a server entry.

```

      },
    },
  };
}
```

## Adapter types reference

The following types can be imported from the `astro` module:

### `AdapterSupport`

**Type:** `[AdapterSupportsKind](#adaptersupport) | [AdapterSupportWithMessage](#adaptersupportwithmessage)`  

A union of valid formats to describe the support level for a feature.

### `AdapterSupportsKind`

**Type:** `"deprecated" | "experimental" | "limited" | "stable" | "unsupported"`

Defines the level of support for a feature by your adapter:

-   Use `"deprecated"` when your adapter deprecates support for a feature before removing it completely in a future version.
-   Use `"experimental"` when your adapter adds support for a feature, but issues or breaking changes are expected.
-   Use `"limited"` when your adapter only supports a subset of the full feature.
-   Use `"stable"` when the feature is fully supported by your adapter.
-   Use `"unsupported"` to warn users that they may encounter build issues in their project, as this feature is not supported by your adapter.

### `AdapterSupportWithMessage`

An object that allows you to define a support level for a feature and a message to be logged in the user console. This object contains the following properties:

#### `AdapterSupportWithMessage.support`

**Type:** `Exclude<[AdapterSupportsKind](#adaptersupportskind), "stable">`

Defines the level of support for a feature by your adapter.

#### `AdapterSupportWithMessage.message`

**Type:** `string`

Defines a custom message to log regarding the support of a feature by your adapter.

#### `AdapterSupportWithMessage.suppress`

**Type:** `"default" | "all"`  

An option to prevent showing some or all logged messages about an adapter's support for a feature.

If Astro's default log message is redundant, or confusing to the user in combination with your [custom `message`](#adaptersupportwithmessagemessage), you can use `suppress: "default"` to suppress the default message and only log your message:

```

      },
    },
  };
}
```

You can also use `suppress: "all"` to suppress all messages about support for the feature. This is useful when these messages are unhelpful to users in a specific context, such as when they have a configuration setting that means they are not using that feature. For example, you can choose to prevent logging any messages about Sharp support from your adapter:

```

      },
    },
  };
}
```

### `MiddlewareMode`

**Type:** `"classic" | "edge"`  

A union of valid formats to describe the mode in which middleware is run.

### `CreatePreviewServer`

**Type:** `(params: [PreviewServerParams](#previewserverparams)) => [PreviewServer](#previewserver) | Promise<[PreviewServer](#previewserver)>`

Describes the function an adapter should export to start a preview server when [`astro preview`](/en/reference/cli-reference/#astro-preview) is run.

### `PreviewServer`

**Type:** `{ host?: string; port: number; closed(): Promise<void>; stop(): Promise<void>; }`

Describes an instance of a preview server for the adapter.

#### `PreviewServer.host`

**Type:** `string | undefined`

Defines the host the preview server is listening on.

#### `PreviewServer.port`

**Type:** `number`

Defines the port the preview server is listening on.

#### `PreviewServer.closed()`

**Type:** `() => Promise<void>`

Defines a function that resolves when the preview server has closed.

#### `PreviewServer.stop()`

**Type:** `() => Promise<void>`

Defines a function to stop the preview server and perform any necessary cleanup.

### `PreviewServerParams`

**Type:** `object`

Describes the configuration for the preview server.

#### `PreviewServerParams.outDir`

**Type:** `URL`

The [configured output directory](/en/reference/configuration-reference/#outdir) for the build.

#### `PreviewServerParams.client`

**Type:** `URL`

The [configured client assets directory](/en/reference/configuration-reference/#buildclient) for the build.

#### `PreviewServerParams.server`

**Type:** `URL`  

The [configured directory for server JavaScript](/en/reference/configuration-reference/#buildserver) when building to SSR.

#### `PreviewServerParams.serverEntrypoint`

**Type:** `URL`

The built server entry module generated by Astro.

#### `PreviewServerParams.host`

**Type:** `string | undefined`

Specifies the [configured host](/en/reference/configuration-reference/#serverhost) on which the server preview should listen.

#### `PreviewServerParams.port`

**Type:** `number`

Defines the [configured port](/en/reference/configuration-reference/#serverport) on which the server preview should listen.

#### `PreviewServerParams.base`

**Type:** `string`

Specifies the [configured base path](/en/reference/configuration-reference/#base) to deploy to.

#### `PreviewServerParams.logger`

**Type:** [`AstroIntegrationLogger`](/en/reference/integrations-reference/#astrointegrationlogger)

Defines an instance of the Astro logger that can be used to write logs when the preview server is running.

#### `PreviewServerParams.headers`

**Type:** `OutgoingHttpHeaders | undefined`

Describes the [configured HTTP response headers](/en/reference/configuration-reference/#serverheaders).

#### `PreviewServerParams.allowedHosts`

**Type:** `string[] | true | undefined`  

Describes the [configured allowed hosts](/en/reference/configuration-reference/#serverallowedhosts) that the preview server should respond to.

#### `PreviewServerParams.root`

**Type:** `URL`

Specifies the [configured root directory](/en/reference/configuration-reference/#root) of the project.

## Allow installation via `astro add`

[The `astro add` command](/en/reference/cli-reference/#astro-add) allows users to easily add integrations and adapters to their project. To allow your adapter to be installed with this command, **add `astro-adapter` to the `keywords` field in your `package.json`**:

```
{
  "name": "example",
  "keywords": ["astro-adapter"],
}
```

Once you [publish your adapter to npm](https://docs.npmjs.com/cli/v8/commands/npm-publish), running `astro add example` will install your package with any peer dependencies specified in your `package.json` and instruct users to update their project config manually.

## [Astro render context](https://docharvest.github.io/docs/astro/reference/api-reference/)



## [Template expressions reference](https://docharvest.github.io/docs/astro/reference/astro-syntax/)

Contents

astro

Template expressions reference

Astro

Template expressions reference

Astro component syntax is a superset of HTML. The syntax was designed to feel familiar to anyone with experience writing HTML or JSX, and adds support for including components and JavaScript expressions.

## JSX-like Expressions

You can define local JavaScript variables inside of the frontmatter component script between the two code fences (`---`) of an Astro component. You can then inject these variables into the component's HTML template using JSX-like expressions!

:::note\[Dynamic vs reactive\] Using this approach, you can include **dynamic** values that are calculated in the frontmatter. But once included, these values are not **reactive** and will never change. Astro components are templates that only run once, during the rendering step.

See below for more examples of [differences between Astro and JSX](#differences-between-astro-and-jsx). :::

### Variables

Local variables can be added into the HTML using the curly braces syntax:

```
---
const name = "Astro";
---
<div>
  <h1>Hello {name}!</h1>  <!-- Outputs <h1>Hello Astro!</h1> -->
</div>
```

### Dynamic Attributes

Local variables can be used in curly braces to pass attribute values to both HTML elements and components:

```
---
const name = "Astro";
---
<h1 class={name}>Attribute expressions are supported</h1>

<MyComponent templateLiteralNameAttribute={`MyNameIs${name}`} />
```

:::caution HTML attributes will be converted to strings, so it is not possible to pass functions and objects to HTML elements. For example, you can't assign an event handler to an HTML element in an Astro component:

```
---
function handleClick () {
    console.log("button clicked!");
}
---
<!-- ❌ This doesn't work! ❌ -->
<button onClick={handleClick}>Nothing will happen when you click me!</button>
```

Instead, use a client-side script to add the event handler, like you would in vanilla JavaScript:

```
---
---
<button id="button">Click Me</button>
<script>
  function handleClick () {
    console.log("button clicked!");
  }
  document.getElementById("button").addEventListener("click", handleClick);
</script>
```

:::

### Dynamic HTML

Local variables can be used in JSX-like functions to produce dynamically-generated HTML elements:

```
---
const items = ["Dog", "Cat", "Platypus"];
---
<ul>
  {items.map((item) => (
    <li>{item}</li>
  ))}
</ul>
```

Astro can conditionally display HTML using JSX logical operators and ternary expressions.

```
---
const visible = true;
---
{visible && <p>Show me!</p>}

{visible ? <p>Show me!</p> : <p>Else show me!</p>}
```

### Dynamic Tags

You can also use dynamic tags by assigning an HTML tag name to a variable or with a component import reassignment:

```
---

const Element = 'div'
const Component = MyComponent;
---
<Element>Hello!</Element> <!-- renders as <div>Hello!</div> -->
<Component /> <!-- renders as <MyComponent /> -->
```

When using dynamic tags:

-   **Variable names must be capitalized.** For example, use `Element`, not `element`. Otherwise, Astro will try to render your variable name as a literal HTML tag.
    
-   **Hydration directives are not supported.** When using [`client:*` hydration directives](/en/guides/framework-components/#hydrating-interactive-components), Astro needs to know which components to bundle for production, and the dynamic tag pattern prevents this from working.
    
-   **The [define:vars directive](/en/reference/directives-reference/#definevars) is not supported.** If you cannot wrap the children with an extra element (e.g `<div>`), then you can manually add a ``style={`--myVar:${value}`}`` to your Element.
    

### Fragments

Astro supports `<> </>` notation and also provides a built-in `<Fragment />` component. This component can be useful to avoid wrapper elements when adding [`set:*` directives](/en/reference/directives-reference/#sethtml) to inject an HTML string.

The following example renders paragraph text using the `<Fragment />` component:

```
---
const htmlString = '<p>Raw HTML content</p>';
---
<Fragment set:html={htmlString} />
```

### Differences between Astro and JSX

Astro component syntax is a superset of HTML. It was designed to feel familiar to anyone with HTML or JSX experience, but there are a couple of key differences between `.astro` files and JSX.

#### Attributes

In Astro, you use the standard `kebab-case` format for all HTML attributes instead of the `camelCase` used in JSX. This even works for `class`, which is not supported by React.

```
<div className="box" dataValue="3" />
<div class="box" data-value="3" />
```

#### Multiple Elements

An Astro component template can render multiple elements with no need to wrap everything in a single `<div>` or `<>`, unlike JavaScript or JSX.

```
---
// Template with multiple elements
---
<p>No need to wrap elements in a single containing element.</p>
<p>Astro supports multiple root elements in a template.</p>
```

#### Comments

In Astro, you can use standard HTML comments or JavaScript-style comments.

```
---
---
<!-- HTML comment syntax is valid in .astro files -->
{/* JS comment syntax is also valid */}
```

:::caution HTML-style comments will be included in browser DOM, while JS ones will be skipped. To leave TODO messages or other development-only explanations, you may wish to use JavaScript-style comments instead. :::

## Component utilities

### `Astro.slots`

`Astro.slots` contains utility functions for modifying an Astro component's slotted children.

#### `Astro.slots.has()`

**Type:** `(slotName: string) => boolean`

You can check whether content for a specific slot name exists with `Astro.slots.has()`. This can be useful when you want to wrap slot contents but only want to render the wrapper elements when the slot is being used.

```
---
---
<slot />

{Astro.slots.has('more') && (
  <aside>
    <h2>More</h2>
    <slot name="more" />
  </aside>
)}
```

#### `Astro.slots.render()`

**Type:** `(slotName: string, args?: any[]) => Promise<string>`

You can asynchronously render the contents of a slot to a string of HTML using `Astro.slots.render()`.

```
---
const html = await Astro.slots.render('default');
---
<Fragment set:html={html} />
```

:::note This is for advanced use cases! In most circumstances, it is simpler to render slot contents with [the `<slot />` element](/en/basics/astro-components/#slots). :::

`Astro.slots.render()` optionally accepts a second argument: an array of parameters that will be forwarded to any function children. This can be useful for custom utility components.

For example, this `<Shout />` component converts its `message` prop to uppercase and passes it to the default slot:

```
---
const message = Astro.props.message.toUpperCase();
let html = '';
if (Astro.slots.has('default')) {
  html = await Astro.slots.render('default', [message]);
}
---
<Fragment set:html={html} />
```

A callback function passed as `<Shout />`’s child will receive the all-caps `message` parameter:

```
---

---
<Shout message="slots!">
  {(message) => <div>{message}</div>}
</Shout>

<!-- renders as <div>SLOTS!</div> -->
```

Callback functions can be passed to named slots inside a wrapping HTML element tag with a `slot` attribute. This element is only used to transfer the callback to a named slot and will not be rendered onto the page.

```
<Shout message="slots!">
  <fragment slot="message">
    {(message) => <div>{message}</div>}
  </fragment>
</Shout>
```

Use a standard HTML element for the wrapping tag or any lowercase tag (e.g. `<fragment>` instead of `<Fragment />`) that will not be interpreted as a component. Do not use the HTML `<slot>` element as this will be interpreted as an Astro slot.

### `Astro.self`

`Astro.self` allows Astro components to be recursively called. This behavior lets you render an Astro component from within itself by using `<Astro.self>` in the component template. This can help iterate over large data stores and nested data structures.

```
---
// NestedList.astro
const { items } = Astro.props;
---
<ul class="nested-list">
  {items.map((item) => (
    <li>
      <!-- If there is a nested data-structure we render `<Astro.self>` -->
      <!-- and can pass props through with the recursive call -->
      {Array.isArray(item) ? (
        <Astro.self items={item} />
      ) : (
        item
      )}
    </li>
  ))}
</ul>
```

This component could then be used like this:

```
---

---
<NestedList items={['A', ['B', 'C'], 'D']} />
```

And would render HTML like this:

```
<ul class="nested-list">
  <li>A</li>
  <li>
    <ul class="nested-list">
      <li>B</li>
      <li>C</li>
    </ul>
  </li>
  <li>D</li>
</ul>
```

## [Astro Cache Provider API](https://docharvest.github.io/docs/astro/reference/cache-provider-reference/)

Contents

astro

Astro Cache Provider API

Astro

Astro Cache Provider API

Astro Cache Provider API allows you to configure and manage [route caching](/en/guides/caching/) behavior. This API includes built-in support for an in-memory cache provider and the ability to create custom providers for various caching strategies and runtimes.

## What is a cache provider?

Cache behavior is determined by the configured **cache provider**. Providers fall into two categories:

### CDN providers

CDN providers translate cache directives into response headers (e.g. `CDN-Cache-Control`, `Cache-Tag`) and rely on a CDN or reverse proxy to handle caching. These internal headers are stripped before the response reaches the client.

A CDN provider implements `setHeaders()` to produce the appropriate headers.

### Runtime providers

Runtime providers implement `onRequest()` to intercept requests and cache responses in-process. They add an `X-Astro-Cache` response header for observability:

-   **`HIT`**: response served from cache
-   **`MISS`**: response rendered fresh and stored in cache
-   **`STALE`**: stale response served while revalidating in the background

## Built-in memory cache provider

Astro includes a built-in in-memory LRU runtime cache provider suitable for single-instance deployments. Import `memoryCache()` from `astro/config`:

### `memoryCache()` options

**Type:** `{ max?: number; query?: object }`  
**Default:** `{ max: 1000 }`

Configures the in-memory cache provider.

#### `max`

**Type:** `number`  
**Default:** `1000`

Defines the maximum number of entries to keep in cache. When the cache exceeds this limit, the least recently used entry is evicted.

#### `query`

**Type:** `{ sort?: boolean; include?: string[]; exclude?: string[]; }`  

Controls how query parameters are handled in cache keys.

##### `query.sort`

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

Determines whether query parameters should be sorted alphabetically. This is useful when parameter order is significant and to ensure that their order does not affect the cache key.

Set to `false` to disable sorting and cache URLs with different query parameter orders separately.

##### `query.exclude`

**Type:** `string[]`  
**Default:** `['utm_*', 'fbclid', 'gclid', 'gbraid', 'wbraid', 'dclid', 'msclkid', 'twclid', 'li_fat_id', 'mc_cid', 'mc_eid', '_ga', '_gl', '_hsenc', '_hsmi', '_ke', 'oly_anon_id', 'oly_enc_id', 'rb_clickid', 's_cid', 'vero_id', 'wickedid', 'yclid', '__s', 'ref']`

Lists the query parameters to exclude from the cache key. This supports glob wildcards (e.g. `"utm_*"`) and, by default, excludes common tracking and analytics parameters.

Set to `[]` to include all query parameters in the cache key:

```
memoryCache({
  query: { exclude: [] },
});
```

An error is thrown if used together with [`include`](#queryinclude).

##### `query.include`

**Type:** `string[]`

Lists the query parameter names to include in the cache key. When set, all other parameters are ignored, including default tracking parameter exclusions.

The following example only uses `page` and `sort` parameters in the cache key, ignoring all others:

```
memoryCache({
  query: { include: ['page', 'sort'] },
});
```

An error is thrown if used together with [`exclude`](#queryexclude).

### Cache key behavior

The memory provider automatically normalizes cache keys for better hit rates:

-   **Query parameter sorting**: Parameters are sorted alphabetically, so `/page?b=2&a=1` and `/page?a=1&b=2` resolve to the same cache entry.
-   **Tracking parameter exclusion**: Common analytics and tracking parameters (e.g. `utm_source`, `fbclid`, `gclid`) are excluded from the cache key by default. This prevents cache fragmentation from marketing links without affecting your page content.
-   **Vary header support**: When a response includes a [`Vary`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Vary) header, the memory provider uses the specified request header values to create separate cache entries for each variant. For example, a response with `Vary: Accept-Language` will cache different versions for different languages.

:::note The `Cookie` header is always ignored for Vary-based cache keying because it has extremely high cardinality (every user typically has different cookies), making it effectively uncacheable. :::

## Writing a custom cache provider

A cache provider has two parts:

1.  **The runtime module** — A file that **default-exports** a `CacheProviderFactory` function. This module is bundled into your SSR output, so it must be runtime-agnostic: avoid Node.js built-in modules (e.g. `node:fs`, `node:path`) unless your target runtime supports them.
    
2.  **The config helper** — A function exported for users to call in `astro.config.mjs`. It returns a [`CacheProviderConfig` object](#cacheproviderconfig) that tells Astro where to find the runtime module and what options to pass it. This is the same pattern used by the built-in [`memoryCache()` provider](#built-in-memory-cache-provider).
    

The following example shows a config helper that accepts typed options and points to a runtime module:

```

interface MyProviderOptions {
  apiKey: string;
  region?: string;
}

}
```

The config helper is then called in the Astro config:

The runtime module default-exports a factory that receives the serialized `config` and returns a [`CacheProvider`](#cacheprovider):

```

const factory: CacheProviderFactory = (config) => {
  return {
    name: 'my-cache-provider',

    // CDN-style: translate cache options into response headers
    setHeaders(options) {
      const headers = new Headers();
      if (options.maxAge !== undefined) {
        let value = `max-age=${options.maxAge}`;
        if (options.swr !== undefined) {
          value += `, stale-while-revalidate=${options.swr}`;
        }
        headers.set('CDN-Cache-Control', value);
      }
      if (options.tags?.length) {
        headers.set('Cache-Tag', options.tags.join(','));
      }
      return headers;
    },

    // Runtime-style: intercept requests (optional)
    async onRequest(context, next) {
      // Check cache, call next(), store response...
      return next();
    },

    // Handle invalidation requests
    async invalidate(options) {
      // Purge by tags or path...
    },
  };
};
```

When writing a CDN provider, Astro provides [shared utilities](#cache-provider-utilities) for building cache-control headers and path-based invalidation tags.

## Cache provider utilities

Astro exports shared helpers for CDN provider authors from `astro/cache/provider-utils`. These are the same helpers used by the first-party Netlify, Vercel, and Cloudflare providers.

### `buildCacheControlDirectives()`

**Type:** `(options: [CacheOptions](#cacheoptions), extraDirectives?: string[]) => string | undefined`

Builds a cache-control directive string (e.g. `"public, max-age=300, stale-while-revalidate=60"`) from `CacheOptions`, without a header name so each provider can apply its own (such as `Netlify-CDN-Cache-Control` or `Cloudflare-CDN-Cache-Control`). Pass `extraDirectives` to prepend platform directives such as `public` or `durable`. Returns `undefined` when there are no caching directives.

### `pathTag()`

**Type:** `(path: string) => string`

Generates a cache tag for a given path (`astro-path:{path}`). Used to support [`invalidate({ path })`](/en/reference/api-reference/#cacheinvalidate) on platforms that only offer tag-based purging.

### `setConditionalHeaders()`

**Type:** `(headers: Headers, options: [CacheOptions](#cacheoptions)) => void`

Sets `Last-Modified` and `ETag` headers on a `Headers` object from the corresponding `CacheOptions` values.

### `collectInvalidationTags()`

**Type:** `(options: [InvalidateOptions](#invalidateoptions)) => string[]`

Collects all tags needed to invalidate the given options, including the path tag when `options.path` is set. Used by providers that implement path invalidation via tags rather than native path purge.

### `normalizeTags()`

**Type:** `(tags: string | string[] | undefined) => string[]`

Normalizes a tag value to a flat string array.

## Cache provider types reference

The following types can be imported from the `astro` module:

### `CacheOptions`

Describes the options passed to a cache provider.

Learn how to [use cache options](/en/guides/caching/#setting-cache-options) to control caching behavior.

#### `CacheOptions.maxAge`

**Type:** `number`

Defines the time in seconds the response is considered fresh.

#### `CacheOptions.swr`

**Type:** `number`

Specifies the stale-while-revalidate window in seconds. Stale content is served while a fresh response is generated in the background.

#### `CacheOptions.tags`

**Type:** `string[]`

A list of cache tags for targeted invalidation. Tags accumulate across multiple [`cache.set()`](/en/reference/api-reference/#cacheset) calls.

#### `CacheOptions.lastModified`

**Type:** `Date`

Indicates the most recent modification date. When multiple calls to [`cache.set()`](/en/reference/api-reference/#cacheset) provide `lastModified`, the most recent call takes precedence.

#### `CacheOptions.etag`

**Type:** `string`

Specifies the entity tag for conditional requests.

### `CacheProvider`

Describes a provider used for caching. This requires the `name` and `invalidate()` properties and accepts optional properties.

#### `CacheProvider.name`

**Type:** `string`

A unique name for the provider, used in logs and for identification.

#### `CacheProvider.setHeaders()`

**Type:** `(options: [CacheOptions](#cacheoptions), request: Request) => Headers`

Translates cache options into response headers. This is called after the response is rendered but before it is sent to the client. These headers are stripped from the final response.

The incoming `request` is passed as a second argument so a provider can read the URL or request headers. This can be useful to auto-tag responses with their pathname for path-based invalidation.

#### `CacheProvider.onRequest()`

**Type:** `(context: { request: Request; url: URL; waitUntil?: (promise: Promise<unknown>) => void }, next: [MiddlewareNext](/en/reference/modules/astro-middleware/#middlewarenext)) => Promise<Response>`

Intercepts requests to implement runtime caching. The `context` includes a `waitUntil()` function (when available in the runtime) for background work such as stale-while-revalidate.

#### `CacheProvider.invalidate()`

**Type:** `(options: [InvalidateOptions](#invalidateoptions)) => Promise<void>`

Handles purge requests by tag or path.

### `CacheProviderConfig`

**Type:** `{ entrypoint: string | URL; config?: Record<string, any> }`

The configuration object passed to `cache.provider`. Use a helper function (e.g. `memoryCache()`) for type-safe configuration.

### `CacheProviderFactory`

**Type:** `(config: Record<string, any> | undefined) => [CacheProvider](#cacheprovider)`

The factory function type. Receives the provider's serializable config object from the Astro config.

### `InvalidateOptions`

Describes the options passed to the provider's `invalidate()` method.

#### `InvalidateOptions.path`

**Type:** `string`

Exact path to invalidate. No glob or wildcard support.

#### `InvalidateOptions.tags`

**Type:** `string | string[]`

Tag or tags to invalidate. All entries with matching tags are purged.

## [CLI Commands](https://docharvest.github.io/docs/astro/reference/cli-reference/)



## [Configuration Reference](https://docharvest.github.io/docs/astro/reference/configuration-reference/)

Contents

astro

Configuration Reference

Astro

Configuration Reference

```
style-src 'self' 'sha256-somehash';
"
```

\`\`\`

You can further customize the `<meta>` element by enabling this feature with a configuration object that includes additional options.

##### security.csp.algorithm

**Type:** `"SHA-256" | "SHA-384" | "SHA-512"`  
**Default:** `'SHA-256'`  

The [hash function](https://developer.mozilla.org/en-US/docs/Glossary/Hash_function) to use when generating the hashes of the styles and scripts emitted by Astro.

##### security.csp.directives

**Type:** `Array<string>`  
**Default:** `[]`  

A list of [CSP directives](https://content-security-policy.com/#directive) (beyond `script-src` and `style-src` which are included by default) that defines valid sources for specific content types. These directives are added to all pages.

After the build, the `<meta>` element will add your directives into the `content` value alongside Astro's default directives:

```
<meta
  http-equiv="content-security-policy"
  content="
    default-src 'self';
    img-src 'self' 'https://images.cdn.example.com';
    script-src 'self' 'sha256-somehash';
    style-src 'self' 'sha256-somehash';
  "
>
```

##### security.csp.styleDirective

**Type:** `CspStyleDirective`  
**Default:** `undefined`  

A configuration object that allows you to override the default sources for the `style-src` directive with the [`resources`](#securitycspstyledirectiveresources) property, or to provide additional [hashes](#securitycspstyledirectivehashes) to be rendered.

###### security.csp.styleDirective.hashes

**Type:** `Array<CspHash>`  
**Default:** `[]`  

A list of additional hashes to be rendered.

You must provide hashes that start with `sha384-`, `sha512-` or `sha256-`. Other values will cause a validation error. These hashes are added to all pages.

After the build, the `<meta>` element will include your additional hashes in the `style-src` directives:

```
<meta
  http-equiv="content-security-policy"
  content="
    style-src 'self' 'sha384-styleHash' 'sha512-styleHash' 'sha256-styleHash' 'sha256-generatedByAstro';
  "
>
```

###### security.csp.styleDirective.resources

**Type:** `Array<string>`  
**Default:** `[]`  

A list of valid sources for `style-src` directives to override Astro's default sources. This will not include `'self'` by default, and must be included in this list if you wish to keep it. These resources are added to all pages.

After the build, the `<meta>` element will instead apply your sources to the `style-src` directives:

```
<head>
  <meta
    http-equiv="content-security-policy"
    content="
     style-src 'self' https://styles.cdn.example.com 'sha256-somehash';
    "
  >
</head>
```

When resources are inserted multiple times or from multiple sources (e.g. defined in your `csp` config and added using [the CSP runtime API](/en/reference/api-reference/#csp)), Astro will merge and deduplicate all resources to create your `<meta>` element.

##### security.csp.scriptDirective

**Type:** `CspScriptDirective`  
**Default:** `undefined`  

A configuration object that allows you to override the default sources for the `script-src` directive with the [`resources`](#securitycspscriptdirectiveresources) property, or to provide additional [hashes](#securitycspscriptdirectivehashes) to be rendered.

###### security.csp.scriptDirective.hashes

**Type:** `Array<CspHash>`  
**Default:** `[]`  

A list of additional hashes to be rendered.

You must provide hashes that start with `sha384-`, `sha512-` or `sha256-`. Other values will cause a validation error. These hashes are added to all pages.

After the build, the `<meta>` element will include your additional hashes in the `script-src` directives:

```
<meta
  http-equiv="content-security-policy"
  content="
    script-src 'self' 'sha384-scriptHash' 'sha512-scriptHash' 'sha256-scriptHash' 'sha256-generatedByAstro';
  "
>
```

###### security.csp.scriptDirective.resources

**Type:** `Array<string>`  
**Default:** `[]`  

A list of valid sources for the `script-src` directives to override Astro's default sources. This will not include `'self'` by default, and must be included in this list if you wish to keep it. These resources are added to all pages.

After the build, the `<meta>` element will instead apply your sources to the `script-src` directives:

```
<head>
  <meta
    http-equiv="content-security-policy"
    content="
     script-src 'self' https://cdn.example.com 'sha256-somehash';
    "
  >
</head>
```

When resources are inserted multiple times or from multiple sources (e.g. defined in your `csp` config and added using [the CSP runtime API](/en/reference/api-reference/#csp)), Astro will merge and deduplicate all resources to create your `<meta>` element.

###### security.csp.scriptDirective.strictDynamic

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

Enables [the `strict-dynamic` keyword](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP#the_strict-dynamic_keyword) to support the dynamic injection of scripts.

## Build Options

### build.format

**Type:** `('file' | 'directory' | 'preserve')`  
**Default:** `'directory'`

Control the output file format of each page. This value may be set by an adapter for you.

-   `'file'`: Astro will generate an HTML file named for each page route. (e.g. `src/pages/about.astro` and `src/pages/about/index.astro` both build the file `/about.html`)
-   `'directory'`: Astro will generate a directory with a nested `index.html` file for each page. (e.g. `src/pages/about.astro` and `src/pages/about/index.astro` both build the file `/about/index.html`)
-   `'preserve'`: Astro will generate HTML files exactly as they appear in your source folder. (e.g. `src/pages/about.astro` builds `/about.html` and `src/pages/about/index.astro` builds the file `/about/index.html`)

```
{
  build: {
    // Example: Generate `page.html` instead of `page/index.html` during build.
    format: 'file'
  }
}
```

#### Effect on Astro.url

Setting `build.format` controls what `Astro.url` is set to during the build. When it is:

-   `directory` - The `Astro.url.pathname` will include a trailing slash to mimic folder behavior. (e.g. `/foo/`)
-   `file` - The `Astro.url.pathname` will include `.html`. (e.g. `/foo.html`)

This means that when you create relative URLs using `new URL('./relative', Astro.url)`, you will get consistent behavior between dev and build.

To prevent inconsistencies with trailing slash behaviour in dev, you can restrict the [`trailingSlash` option](#trailingslash) to `'always'` or `'never'` depending on your build format:

-   `directory` - Set `trailingSlash: 'always'`
-   `file` - Set `trailingSlash: 'never'`

### build.client

**Type:** `string`  
**Default:** `'./client'`

Controls the output directory of your client-side CSS and JavaScript when building a website with server-rendered pages. `outDir` controls where the code is built to.

This value is relative to the `outDir`.

```
{
  output: 'server',
  build: {
    client: './client'
  }
}
```

### build.server

**Type:** `string`  
**Default:** `'./server'`

Controls the output directory of server JavaScript when building to SSR.

This value is relative to the `outDir`.

```
{
  build: {
    server: './server'
  }
}
```

### build.assets

**Type:** `string`  
**Default:** `'_astro'`  

Specifies the directory in the build output where Astro-generated assets (bundled JS and CSS for example) should live.

```
{
  build: {
    assets: '_custom'
  }
}
```

**See Also:**

-   outDir

### build.assetsPrefix

**Type:** `string | Record<string, string>`  
**Default:** `undefined`  

Specifies the prefix for Astro-generated asset links. This can be used if assets are served from a different domain than the current site.

This requires uploading the assets in your local `./dist/_astro` folder to a corresponding `/_astro/` folder on the remote domain. To rename the `_astro` path, specify a new directory in `build.assets`.

To fetch all assets uploaded to the same domain (e.g. `https://cdn.example.com/_astro/...`), set `assetsPrefix` to the root domain as a string (regardless of your `base` configuration):

```
{
  build: {
    assetsPrefix: 'https://cdn.example.com'
  }
}
```

**Added in:** `astro@4.5.0`

You can also pass an object to `assetsPrefix` to specify a different domain for each file type. In this case, a `fallback` property is required and will be used by default for any other files.

```
{
  build: {
    assetsPrefix: {
      'js': 'https://js.cdn.example.com',
      'mjs': 'https://js.cdn.example.com',
      'css': 'https://css.cdn.example.com',
      'fallback': 'https://cdn.example.com'
    }
  }
}
```

### build.serverEntry

**Type:** `string`  
**Default:** `'entry.mjs'`

Specifies the file name of the server entrypoint when building to SSR. This entrypoint is usually dependent on which host you are deploying to and will be set by your adapter for you.

Note that it is recommended that this file ends with `.mjs` so that the runtime detects that the file is a JavaScript module.

```
{
  build: {
    serverEntry: 'main.mjs'
  }
}
```

### build.redirects

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

Specifies whether redirects will be output to HTML during the build. This option only applies to `output: 'static'` mode; in SSR redirects are treated the same as all responses.

This option is mostly meant to be used by adapters that have special configuration files for redirects and do not need/want HTML based redirects.

```
{
  build: {
    redirects: false
  }
}
```

### build.inlineStylesheets

**Type:** `'always' | 'auto' | 'never'`  
**Default:** `auto`  

Control whether project styles are sent to the browser in a separate css file or inlined into `<style>` tags. Choose from the following options:

-   `'always'` - project styles are inlined into `<style>` tags
-   `'auto'` - only stylesheets smaller than `ViteConfig.build.assetsInlineLimit` (default: 4kb) are inlined. Otherwise, project styles are sent in external stylesheets.
-   `'never'` - project styles are sent in external stylesheets

```
{
	build: {
		inlineStylesheets: `never`,
	},
}
```

### build.concurrency

**Type:** `number`  
**Default:** `1`  

The number of pages to build in parallel.

**In most cases, you should not change the default value of `1`.**

Use this option only when other attempts to reduce the overall rendering time (e.g. batch or cache long running tasks like fetch calls or data access) are not possible or are insufficient. If the number is set too high, page rendering may slow down due to insufficient memory resources and because JS is single-threaded.

```
{
  build: {
    concurrency: 2
  }
}
```

:::caution\[Breaking changes possible\] This feature is stable and is not considered experimental. However, this feature is only intended to address difficult performance issues, and breaking changes may occur in a [minor release](/en/upgrade-astro/#semantic-versioning) to keep this option as performant as possible. Please check the [Astro CHANGELOG](https://github.com/withastro/astro/blob/refs/heads/next/packages/astro/CHANGELOG.md) for every minor release if you are using this feature. :::

## Server Options

Customize the Astro dev server, used by both `astro dev` and `astro preview`.

```
{
  server: { port: 1234, host: true}
}
```

To set different configuration based on the command run ("dev", "preview") a function can also be passed to this configuration option.

```
{
  // Example: Use the function syntax to customize based on command
  server: ({ command }) => ({ port: command === 'dev' ? 4321 : 4000 })
}
```

### server.host

**Type:** `string | boolean`  
**Default:** `false`  

Set which network IP addresses the server should listen on (i.e. non-localhost IPs).

-   `false` - do not expose on a network IP address
-   `true` - listen on all addresses, including LAN and public addresses
-   `[custom-address]` - expose on a network IP address at `[custom-address]` (ex: `192.168.0.1`)

### server.port

**Type:** `number`  
**Default:** `4321`

Set which port the server should listen on.

If the given port is already in use, Astro will automatically try the next available port.

```
{
  server: { port: 8080 }
}
```

### server.allowedHosts

**Type:** `Array<string> | true`  
**Default:** `[]`  

A list of hostnames that Astro is allowed to respond to. When the value is set to `true`, any hostname is allowed.

```
{
  server: {
  	allowedHosts: ['staging.example.com', 'qa.example.com']
  }
}
```

### server.open

**Type:** `string | boolean`  
**Default:** `false`  

Controls whether the dev server should open in your browser window on startup.

Pass a full URL string (e.g. "[http://example.com](http://example.com)") or a pathname (e.g. "/about") to specify the URL to open.

```
{
  server: { open: "/about" }
}
```

### server.headers

**Type:** `OutgoingHttpHeaders`  
**Default:** `{}`  

Set custom HTTP response headers to be sent in `astro dev` and `astro preview`.

## fetchFile

**Type:** `string | null`  
**Default:** `'fetch'`  

Customizes the file used as the fetch entrypoint inside `srcDir`. Defaults to `'fetch'`, meaning Astro looks for `src/fetch.ts` (or `.js` / `.mjs` / `.mts`).

The fetch file allows you to compose Astro's request pipeline with the Web Fetch standard or your own Hono middleware.

If you already have a `src/fetch.ts` file in use for other purposes, define a different filename or set the value to `null` to disable the entrypoint:

```
// astro.config.mjs
```

Learn more about customizing the request pipeline in the [advanced routing guide](/en/guides/routing/#advanced-routing).

## Logger Options

**Type:** `LoggerHandlerConfig`  
**Default:** `undefined`  

Configures how Astro logs messages during development and production.

By default, Astro uses a built-in logger that outputs human-friendly logs to the console. You can customize this behavior by providing [your own logger handler](/en/reference/logger-reference/#custom-loggers) or by using one of the [built-in log handlers](/en/reference/logger-reference/#built-in-loggers):

```
// astro.config.mjs
```

See [the logger API reference](/en/reference/logger-reference/) for more information.

### logger.entrypoint

**Type:** `string`  

The entrypoint of the log handler. This can be a path to a file in your project or an npm package:

### logger.config

**Type:** `Record<string, unknown> | undefined`  
**Default:** `{}`  

The configuration object for the log handler. The options depend on the configured logger.

## Session Options

Configures session storage for your Astro project. This is used to store session data in a persistent way, so that it can be accessed across different requests.

Some adapters may provide a default session driver, but you can override it with your own configuration:

Session drivers are configured at build time. This means environment variables used in the driver configuration are inlined. You must create your own driver entrypoint to [override the configuration at runtime](/en/guides/sessions/#overriding-the-configuration-at-runtime).

See [the sessions guide](/en/guides/sessions/) for more information.

### session.driver

**Type:** `SessionDriverConfig | undefined`  

The driver to use for session storage. The [Node](/en/guides/integrations-guide/node/#sessions), [Cloudflare](/en/guides/integrations-guide/cloudflare/#sessions), and [Netlify](/en/guides/integrations-guide/netlify/#sessions) adapters automatically configure a default driver for you, but you can specify your own if you would prefer or if you are using an adapter that does not provide one.

See the [code syntax highlighting guide](/en/guides/syntax-highlighting/) for usage and examples.

### markdown.syntaxHighlight

**Type:** `SyntaxHighlightConfig | SyntaxHighlightConfigType | false`  
**Default:** `{ type: 'shiki', excludeLangs: ['math'] }`

Which syntax highlighter to use for Markdown code blocks (\`\`\`), if any. This determines the CSS classes that Astro will apply to your Markdown code blocks.

-   `shiki` - use the [Shiki](https://shiki.style) highlighter (`github-dark` theme configured by default)
-   `prism` - use the [Prism](https://prismjs.com/) highlighter and [provide your own Prism stylesheet](/en/guides/syntax-highlighting/#add-a-prism-stylesheet)
-   `false` - do not apply syntax highlighting.

```
{
  markdown: {
    // Example: Switch to use prism for syntax highlighting in Markdown
    syntaxHighlight: 'prism',
  }
}
```

For more control over syntax highlighting, you can instead specify a configuration object with the properties listed below.

#### markdown.syntaxHighlight.type

**Type:** `'shiki' | 'prism'`  
**Default:** `'shiki'`  

The default CSS classes to apply to Markdown code blocks. (If no other syntax highlighting configuration is needed, you can instead set `markdown.syntaxHighlight` directly to `shiki`, `prism`, or `false`.)

#### markdown.syntaxHighlight.excludeLangs

**Type:** `Array<string>`  
**Default:** `['math']`  

An array of languages to exclude from the default syntax highlighting specified in `markdown.syntaxHighlight.type`. This can be useful when using tools that create diagrams from Markdown code blocks, such as Mermaid.js and D2.

### markdown.remarkPlugins

:::caution\[Deprecated\] Pass `remarkPlugins` to `unified({ remarkPlugins })` from `@astrojs/markdown-remark` and set it as `markdown.processor` instead. Will be removed in a future major. :::

**Type:** `RemarkPlugins`

Pass [remark plugins](https://github.com/remarkjs/remark) to customize how your Markdown is built. You can import and apply the plugin function (recommended), or pass the plugin name as a string.

```

{
  markdown: {
    remarkPlugins: [ [remarkToc, { heading: "contents"} ] ]
  }
}
```

### markdown.rehypePlugins

:::caution\[Deprecated\] Pass `rehypePlugins` to `unified({ rehypePlugins })` from `@astrojs/markdown-remark` and set it as `markdown.processor` instead. Will be removed in a future major. :::

**Type:** `RehypePlugins`

Pass [rehype plugins](https://github.com/remarkjs/remark-rehype) to customize how your Markdown's output HTML is processed. You can import and apply the plugin function (recommended), or pass the plugin name as a string.

```

{
  markdown: {
    rehypePlugins: [rehypeAccessibleEmojis]
  }
}
```

### markdown.gfm

:::caution\[Deprecated\] Pass `gfm` to your processor instead (e.g. `unified({ gfm: false })`). Will be removed in a future major. :::

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

Astro uses [GitHub-flavored Markdown](https://github.com/remarkjs/remark-gfm) by default. To disable this, set the `gfm` flag to `false`:

```
{
  markdown: {
    gfm: false,
  }
}
```

### markdown.smartypants

:::caution\[Deprecated\] Pass `smartypants` to your processor instead (e.g. `unified({ smartypants: false })`). Will be removed in a future major. :::

**Type:** `boolean | Smartypants`  
**Default:** `true`  

Whether to use the [SmartyPants formatter](https://daringfireball.net/projects/smartypants/) to transform straight quotes into smart quotes, dashes into en/em dashes, and triple dots into ellipses.

To disable this, set the `smartypants` flag to `false`.

For more control over typography, you can instead specify a configuration object with the [properties supported by `retext-smartypants`](https://github.com/retextjs/retext-smartypants?tab=readme-ov-file#fields).

### markdown.remarkRehype

:::caution\[Deprecated\] Pass `remarkRehype` to `unified({ remarkRehype })` from `@astrojs/markdown-remark` and set it as `markdown.processor` instead. Will be removed in a future major. :::

**Type:** `RemarkRehype`

Pass options to [remark-rehype](https://github.com/remarkjs/remark-rehype#api).

```
{
  markdown: {
    // Example: Translate the footnotes text to another language, here are the default English values
    remarkRehype: { footnoteLabel: "Footnotes", footnoteBackLabel: "Back to reference 1"},
  },
};
```

### markdown.processor

**Type:** `MarkdownProcessor`  

Configures the Markdown processor used to render `.md` files. Defaults to `satteri()` from `@astrojs/markdown-satteri`, Astro's native Markdown pipeline.

```
// astro.config.mjs

```

To keep the remark/rehype pipeline, install `@astrojs/markdown-remark` and pass `unified()`:

```
// astro.config.mjs

```

## i18n

**Type:** `object`  

Configures i18n routing and allows you to specify some customization options.

See our guide for more information on [internationalization in Astro](/en/guides/internationalization/)

### i18n.locales

**Type:** `Locales`  

A list of all locales supported by the website. This is a required field.

Languages can be listed either as individual codes (e.g. `['en', 'es', 'pt-br']`) or mapped to a shared `path` of codes (e.g. `{ path: "english", codes: ["en", "en-US"]}`). These codes will be used to determine the URL structure of your deployed site.

No particular language code format or syntax is enforced, but your project folders containing your content files must match exactly the `locales` items in the list. In the case of multiple `codes` pointing to a custom URL path prefix, store your content files in a folder with the same name as the `path` configured.

### i18n.defaultLocale

**Type:** `string`  

The default locale of your website/application, that is one of the specified `locales`. This is a required field.

No particular language format or syntax is enforced, but we suggest using lower-case and hyphens as needed (e.g. "es", "pt-br") for greatest compatibility.

### i18n.fallback

**Type:** `Record<string, string>`  

The fallback strategy when navigating to pages that do not exist (e.g. a translated page has not been created).

Use this object to declare a fallback `locale` route for each language you support. If no fallback is specified, then unavailable pages will return a 404.

##### Example

The following example configures your content fallback strategy to redirect unavailable pages in `/pt-br/` to their `es` version, and unavailable pages in `/fr/` to their `en` version. Unavailable `/es/` pages will return a 404.

### font.name

**Type:** `string`  

The font family name, as identified by your font provider:

```
name: "Roboto"
```

### font.cssVariable

**Type:** `string`  

A valid [ident](https://developer.mozilla.org/en-US/docs/Web/CSS/ident) of your choosing in the form of a CSS variable (i.e. starting with `--`):

```
cssVariable: "--font-roboto"
```

### font.fallbacks

**Type:** `Array<string>`  
**Default:** `["sans-serif"]`  

An array of fonts to use when your chosen font is unavailable, or loading. Fallback fonts will be chosen in the order listed. The first available font will be used:

```
fallbacks: ["CustomFont", "serif"]
```

To disable fallback fonts completely, configure an empty array:

```
fallbacks: []
```

Specify at least a [generic family name](https://developer.mozilla.org/en-US/docs/Web/CSS/font-family#generic-name) matching the intended appearance of your font. Astro will then attempt to generate [optimized fallbacks](https://developer.chrome.com/blog/font-fallbacks) using font metrics. To disable this optimization, set `optimizedFallbacks` to false.

### font.optimizedFallbacks

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

Whether or not to enable Astro's default optimization when generating fallback fonts. You may disable this default optimization to have full control over how [`fallbacks`](#fontfallbacks) are generated:

```
optimizedFallbacks: false
```

### font.weights

**Type:** `Array<(number|string)>`  
**Default:** `[400]`  

An array of [font weights](https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight). If no value is specified in your configuration, only weight `400` is included by default to prevent unnecessary downloads. You will need to include this property to access any other font weights:

```
weights: [200, "400", "bold"]
```

If the associated font is a [variable font](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_fonts/Variable_fonts_guide), you can specify a range of weights:

```
weights: ["100 900"]
```

### font.styles

**Type:** `Array<("normal"|"italic"|"oblique")>`  
**Default:** `["normal", "italic"]`  

An array of [font styles](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style):

```
styles: ["normal", "oblique"]
```

### font.subsets

**Type:** `Array<string>`  
**Default:** `["latin"]`  

Defines a list of [font subsets](https://knaap.dev/posts/font-subsetting/) to preload.

```
subsets: ["latin"]
```

### font.formats

**Type:** `Array<("woff2"|"woff"|"otf"|"ttf"|"eot")>`  
**Default:** `["woff2"]`  

An array of [font formats](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/src#font_formats):

```
formats: ["woff2", "woff"]
```

### font.options

**Type:** `Record<string, any>`  

An object to pass provider specific options. It is typed automatically based on the font family [provider](#fontprovider):

```
options: {
  experimental: {
    glyphs: ["a"]
  }
}
```

### font.display

**Type:** `"auto" | "block" | "swap" | "fallback" | "optional"`  
**Default:** `"swap"`  

Defines [how a font displays](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display) based on when it is downloaded and ready for use:

```
display: "block"
```

### font.unicodeRange

**Type:** `Array<string>`  
**Default:** `undefined`  

Determines when a font must be downloaded and used based on a specific [range of unicode characters](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/unicode-range). If a character on the page matches the configured range, the browser will download the font and all characters will be available for use on the page. To configure a subset of characters preloaded for a single font, see the [subsets](#fontsubsets) property instead.

This can be useful for localization to avoid unnecessary font downloads when a specific part of your website uses a different alphabet and will be displayed with a separate font. For example, a website that offers both English and Japanese versions can prevent the browser from downloading the Japanese font on English versions of the page that do not contain any of the Japanese characters provided in `unicodeRange`.

```
unicodeRange: ["U+26"]
```

### font.stretch

**Type:** `string`  
**Default:** `undefined`  

A [font stretch](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-stretch):

```
stretch: "condensed"
```

### font.featureSettings

**Type:** `string`  
**Default:** `undefined`  

Controls the [typographic font features](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-feature-settings) (e.g. ligatures, small caps, or swashes):

```
featureSettings: "'smcp' 2"
```

### font.variationSettings

**Type:** `string`  
**Default:** `undefined`  

Font [variation settings](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-variation-settings):

```
variationSettings: "'xhgt' 0.7"
```

## cache

**Type:** `object`  
**Default:** `undefined`  

Enables route caching for SSR responses. Provides a platform-agnostic API for caching rendered pages and API responses, with pluggable providers that adapters can configure automatically.

```
// astro.config.mjs

{
  cache: {
    provider: memoryCache(),
  },
  routeRules: {
    '/blog/[...path]': { maxAge: 300, swr: 60 },
  },
}
```

Use `Astro.cache.set()` in routes and `context.cache.set()` in middleware or API routes to control caching per-request.

### cache.provider

**Type:** `CacheProviderConfig`  

A provider that controls how responses are cached.

Use the provider's config function to get type-safe configuration:

## routeRules

**Type:** `Record<string, RouteRule>`  
**Default:** `undefined`  

Route patterns mapped to cache rules. Uses the same `[param]` and `[...rest]` syntax as [file-based routing](/en/guides/routing/#route-priority-order). Use a `[...rest]` parameter to match a group of routes:

```
// astro.config.mjs

{
  cache: { provider: memoryCache() },
  routeRules: {
    '/api/[...path]': { swr: 600 },
    '/products/[...slug]': { maxAge: 3600, tags: ['products'] },
  },
}
```

## [Astro Container API (experimental)](https://docharvest.github.io/docs/astro/reference/container-reference/)

Contents

astro

Astro Container API (experimental)

Astro

Astro Container API (experimental)

const container = await experimental\_AstroContainer.create();

````

It accepts an object with the following options:

```ts

	renderers?: AddServerRenderer[];
};

			name: never;
	  }
	| {
			renderer: SSRLoadedRendererValue;
			name: string;
	  };
````

### `streaming` option

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

Enables rendering components using [HTML streaming](/en/guides/on-demand-rendering/#html-streaming).

### `renderers` option

**Type:** `AddServerRenderer[]`  
**Default:** `[]`

A list of loaded client renderers required by the component. Use this if your `.astro` component renders any [UI framework components](/en/guides/framework-components/) or MDX using an official Astro integration (e.g. React, Vue, etc.).

Renderers can be added through the Container API automatically for static applications, or cases where the container isn't called at runtime (e.g. testing with `vitest`).

For [on-demand rendered applications](/en/guides/on-demand-rendering/), or cases where the container is called at runtime or inside other "shells" (e.g. PHP, Ruby, Java, etc.), renderers must be manually imported.

#### Adding a renderer through the Container API

For each official Astro integration, import and use the `getContainerRenderer()` helper function from its dedicated `container-renderer` entrypoint to expose its client and server rendering scripts. These entrypoints are available for `@astrojs/react`, `@astrojs/preact`, `@astrojs/solid-js`, `@astrojs/svelte`, `@astrojs/vue`, and `@astrojs/mdx`.

For renderer packages outside the `@astrojs` npm org, look in their documentation for `getContainerRenderer()` or a similar function provided.

When using `vite` (`vitest`, Astro integrations, etc.), the renderers are loaded with the function `loadRenderers()` from the virtual module `astro:container`.

:::caution Outside `vite` or for on-demand usage, you'll have to [load the renderers manually](#adding-a-renderer-manually). :::

The following example provides the necessary object to render an Astro component that renders a React component and a Svelte component:

```

const renderers = await loadRenderers([reactContainerRenderer(), svelteContainerRenderer()]);
const container = await experimental_AstroContainer.create({
    renderers
})
const result = await container.renderToString(ReactWrapper);
```

#### Adding a renderer manually

When the container is called at runtime, or inside other "shells", the `astro:container` virtual module's helper functions are not available. You must import the necessary server and client renderers manually and store them inside the container using `addServerRenderer` and `addClientRenderer`.

Server renderers are required to build your project, and must be stored in the container for every framework used. Client renderers are additionally needed to any hydrate client-side components using [`client:*` directives](/en/reference/directives-reference/#client-directives).

Only one import statement is needed per framework. Importing a renderer makes both the server and client renderers available to your container. However, **server renderers must be added to your container before client renderers**. This allows your entire container to render first, and then hydrate any interactive components.

The following example manually imports the necessary server renderers to be able to display static Vue components and `.mdx` pages. It additionally adds both server and client renderers for interactive React components.

```

const container = await experimental_AstroContainer.create();
container.addServerRenderer({ renderer: vueRenderer });
container.addServerRenderer({ renderer: mdxRenderer });

container.addServerRenderer({ renderer: reactRenderer });
container.addClientRenderer({ name: "@astrojs/react", entrypoint: "@astrojs/react/client.js" });
```

## `renderToString()`

**Type:** `(component: AstroComponentFactory; options?: [ContainerRenderOptions](#rendering-options)) => Promise<string>`

This function renders a specified component inside a container. It takes an Astro component as an argument and it returns a string that represents the HTML/content rendered by the Astro component.

```

const container = await experimental_AstroContainer.create();
const result = await container.renderToString(Card);
```

Under the hood, this function calls [`renderToResponse()`](#rendertoresponse) and `Response.text()`.

It also accepts an object as a second argument that can contain a [number of options](#rendering-options).

## `renderToResponse()`

**Type:** `(component: AstroComponentFactory; options?: [ContainerRenderOptions](#rendering-options)) => Promise<Response>`

It renders a component, and it returns a `Response` object.

```

const container = await experimental_AstroContainer.create();
const result = await container.renderToResponse(Card);
```

It also accepts an object as a second argument that can contain a [number of options](#rendering-options).

## Rendering options

Both [`renderToResponse()`](#rendertoresponse) and [`renderToString()`](#rendertostring) accept an object as their second argument:

```

	props?: Record<string, unknown>;
	request?: Request;
	params?: Record<string, string | undefined>;
	locals?: App.Locals;
	routeType?: RouteType;
	partial?: boolean;
};
```

These optional values can be passed to the rendering function in order to provide additional information necessary for an Astro component to properly render.

### `slots`

**Type**: `Record<string, any>`

An option to pass content to be rendered with [`<slots>`](/en/basics/astro-components/#slots).

If your Astro component renders one default slot, pass an object with `default` as the key:

```

const result = await container.renderToString(Card, { 
  slots: { default: "Some value" }
});
```

If your component renders named slots, use the slot names as the object keys:

```
---
---
<div>
  <slot name="header" />
  <slot name="footer" />
</div>
```

```

const result = await container.renderToString(Card, { 
  slots: {
    header: "Header content",
    footer: "Footer"
  }
});
```

You can also render components in cascade:

```
---
---
<div>
  <slot name="header" />
  <slot name="footer" />
</div>
```

```

const result = await container.renderToString(Card, { 
  slots: { 
    header: await container.renderToString(CardHeader), 
    footer:  await container.renderToString(CardFooter)
  }
});
```

### `props` option

**Type**: `Record<string, unknown>`

An option to pass [properties](/en/basics/astro-components/#component-props) for Astro components.

```

const result = await container.renderToString(Card, { 
  props: { name: "Hello, world!" }
});
```

```
---
// For TypeScript support
interface Props {
  name: string;
};

const { name } = Astro.props;
---
<div>
  {name}
</div>
```

### `request` option

**Type**: `Request`

An option to pass a `Request` with information about the path/URL the component will render.

Use this option when your component needs to read information like `Astro.url` or `Astro.request`.

You can also inject possible headers or cookies.

```

const result = await container.renderToString(Card, { 
  request: new Request("https://example.com/blog", {
    headers: {
      "x-some-secret-header": "test-value"
    }
  })
});
```

### `params` option

**Type**: `Record<string, string | undefined>`

An object to pass information about the path parameter to an Astro component responsible for [generating dynamic routes](/en/guides/routing/#dynamic-routes).

Use this option when your component needs a value for `Astro.params` in order to generate a single route dynamically.

```
---
const { locale, slug } = Astro.params;
---
<div></div>
```

```

const result = await container.renderToString(LocaleSlug, { 
  params: {
    locale: "en",
    slug: "getting-started"
  }
});
```

### `locals` options

**Type**: `App.Locals`

An option to pass information from [`Astro.locals`](/en/reference/api-reference/#locals) for rendering your component.

Use this option to when your component needs information stored during the lifecycle of a request in order to render, such as logged in status.

```
---
const { checkAuth } = Astro.locals;
const isAuthenticated = checkAuth();
---
{isAuthenticated ? <span>You're in</span> : <span>You're out</span> }
```

```

test("User is in", async () => {
  const result = await container.renderToString(Card, { 
    locals: {
      checkAuth() { return true; }
    }
  });
  
  // assert result contains "You're in"
});

test("User is out", async () => {
  const result = await container.renderToString(Card, { 
    locals: {
      checkAuth() { return false; }
    }
  });
  
  // assert result contains "You're out"
});
```

### `routeType` option

**Type**: `RouteType`

An option available when using `renderToResponse()` to specify that you are rendering an [endpoint](/en/guides/endpoints/):

```
container.renderToString(Endpoint, { routeType: "endpoint" });
```

```

const response = await container.renderToResponse(Endpoint, { 
  routeType: "endpoint"
});
const json = await response.json();
```

To test your endpoint on methods such as `POST`, `PATCH`, etc., use the `request` option to call the correct function:

```

const json = await response.json();
```

### `partial` option

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

Whether or not the Container API renders components as if they were [page partials](/en/basics/astro-pages/#page-partials). The default `true` setting renders the component in isolation without a full page shell.

To render a component as a full Astro page, including `<!DOCTYPE html>`, you can opt-out of this behavior by setting `partial` to `false`:

```

const result = await container.renderToString(Card, {
    partial: false 
});
console.log(result) // includes `<!DOCTYPE html>` at the beginning of the HTML
```

## [Astro Content Loader API](https://docharvest.github.io/docs/astro/reference/content-loader-reference/)

Contents

astro

Astro Content Loader API

Astro

Astro Content Loader API

Astro's Content Loader API allows you to load your data from any source, local or remote, and interact with Astro's content layer to manage your [content collections](/en/guides/content-collections/).

This API includes two ready-to-use loaders for content stored locally. It also provides tools for building your own custom objects that can load data from any source into content collections.

Learn more about [querying data loaded from build-time loaders](/en/guides/content-collections/#querying-build-time-collections) or [accessing live data from live loaders](/en/guides/content-collections/#accessing-live-data) with guided explanations and example usage in the content collections guide.

## Build-time loaders

Build-time loaders are objects with a [`load()` method](#loaderload) that is called at build time to fetch data and update the data store. This object can also define a schema for the entries, which can be used to validate the data and generate static types.

Astro's [`glob()`](#glob-loader) and [`file()`](#file-loader) loaders are examples of object loaders that are provided out-of-the-box for use with local content. For remote content, no prebuilt loaders are provided. You will have to build an object loader or use a [community-published loader](https://astro.build/integrations/?search=&categories%5B%5D=loaders) to retrieve remote content and interact with the data store.

For simple data fetching, you can also [define a loader as an async function](#defining-a-loader-as-a-function) that returns an array or object containing entries.

### `glob()` loader

**Type:** `(options: GlobOptions) => [Loader](#the-loader-object)`  

The `glob()` loader creates entries from directories of files from anywhere on the filesystem. The supported file types are Markdown, MDX, Markdoc, JSON, YAML, and TOML files.

This loader accepts an object with the following properties: `pattern`, `base` (optional), `generateId` (optional), and `retainBody` (optional).

```

const pages = defineCollection({
  /* Retrieve all Markdown files in your pages directory. */
  loader: glob({ pattern: "**/*.md", base: "./src/data/pages" }),
});
const blog = defineCollection({
  /* Retrieve all Markdown and MDX files in your blog directory. */
  loader: glob({ pattern: "**/*.(md|mdx)", base: "./src/data/blog" }),
});
const notes = defineCollection({
  /* Retrieve all Markdown files in your notes directory and prevent
   * the raw body of content files from being stored in the data store. */
  loader: glob({
    pattern: '**/*.md',
    base: './src/data/notes',
    retainBody: false
  }),
});
const authors = defineCollection({
  /* Retrieve all JSON files in your authors directory while retaining
   * uppercase letters in the ID. */
  loader: glob({
    pattern: '**/*.json',
    base: "./src/data/authors",
    generateId: ({ entry }) => entry.replace(/\.json$/, ''),
  }),
});
```

#### `pattern`

**Type:** `string | string[]`

The `pattern` property accepts a string or an array of strings using glob matching (e.g. wildcards, globstars). The patterns must be relative to the base directory of entry files to match.

You can learn more about the syntax to use in the [micromatch documentation](https://github.com/micromatch/micromatch#matching-features). You can also verify the validity of your pattern using an online tool like the [DigitalOcean Glob Tool](https://www.digitalocean.com/community/tools/glob).

#### `base`

**Type:** `string | URL`  
**Default:** `"."`

A relative path or [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) to the directory from which to resolve the `pattern`.

#### `generateId()`

**Type:** `(options: GenerateIdOptions) => string`

A callback function that returns a unique string per entry in a collection. It accepts an object as parameter with the following properties:

-   `entry` - the path to the entry file, relative to the base directory
-   `base` - the base directory [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL)
-   `data` - the parsed, unvalidated data of the entry

By default it uses [`github-slugger`](https://github.com/Flet/github-slugger) to generate a slug with [kebab-cased](https://developer.mozilla.org/en-US/docs/Glossary/Kebab_case) words.

#### `retainBody`

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

Whether or not to store the raw body of content files in the data store.

When `retainBody` is `false`, [`entry.body`](/en/reference/modules/astro-content/#collectionentrybody) will be `undefined` instead of containing the raw file contents.

Setting this property to `false` significantly reduces the deployed size of the data store and helps avoid hitting size limits for sites with very large collections.

For Markdown files, the rendered body will still be available in the [`entry.rendered.html` property](#dataentryrenderedhtml), and the [`entry.filePath` property](#dataentryfilepath) will still point to the original file.

For MDX collections, this will dramatically reduce the size of the collection, as there will no longer be any body retained in the store.

### `file()` loader

**Type:** `(fileName: string, options?: FileOptions) => [Loader](#the-loader-object)`  

The `file()` loader creates entries from a single file that contains an array of objects with a unique `id` field, or an object with IDs as keys and entries as values.

It supports JSON, YAML, or TOML files and you can provide a custom `parser` for data files it cannot parse by default, or to parse data asynchronously.

This loader accepts a `fileName` property and an optional options object as second argument:

```

const authors = defineCollection({
  /* Retrieve all entries from a JSON file. */
  loader: file("src/data/authors.json"),
});
const products = defineCollection({
  /* Retrieve all entries from a CSV file using a custom parser. */
  loader: file("src/data/products.csv", {
    parser: (fileContent) => { /* your parser logic */ },
  }),
});
```

#### `fileName`

**Type:** `string`

Sets the path to the file to load, relative to the root directory.

#### Options

**Type:** `FileOptions`

An optional object with the following properties:

##### `parser()`

**Type:** `(text: string) => Record<string, Record<string, unknown>> | Array<Record<string, unknown>> | Promise<Record<string, Record<string, unknown>> | Array<Record<string, unknown>>>`

A callback function to create a collection from a file’s contents. Use it when you need to process files other than JSON, YAML, or TOML that not supported by default (e.g. `.csv`) or when using [nested `.json` documents](/en/guides/content-collections/#nested-json-documents).

### Building a loader

The Content Loader API is flexible and full-featured, allowing for a variety of data fetching options. It is possible to build both simple and complex loaders. Your custom loader will depend on both the source and the shape of your data, as well as how you choose to manage the persistent data storage layer.

Most loaders will export a function that accepts configuration options and returns a [loader object](#the-loader-object) including a `name` for your loader, a `load()` method, and a `schema` defining your entries.

#### Loading collections into the data store

The [`load()`](#loaderload) function returned in the loader object defines how your content is fetched, parsed, validated and updated. It accepts a `context` object that allows you to customize your data handling in a variety of ways and interact with the data store. A typical `load()` function will:

-   Fetch your data from a source.
-   Clear the existing data store.
-   Parse and validate your data entries according to a provided schema.
-   Update the data store with new entries.

The `load()` method also provides helpers to log messages to the console, render content to HTML, watch for changes in dev mode and reload data, provide access to metadata and even the full Astro config, and more.

See the full [`LoaderContext`](#loadercontext) list of properties for all options available to the `load()` function.

#### Providing a schema

Providing a Zod [`schema`](#loaderschema) in your loader allows you to validate your fetched content entries with [`parseData()`](#loadercontextparsedata) before adding them to the data [store](#loadercontextstore). This schema will also be used as the collection's default schema when one does not exist in `src/content.config.ts` to provide type safety and editor tooling. You do not also need a schema defined in the content collection if the loader provides this property.

However, if the content collection also [defines a schema](/en/guides/content-collections/#defining-the-collection-schema), that schema will be used instead of your loader's schema. This is to allow users of your loader to extend its schema, or transform data for use in their project. If you are [publishing and distributing a loader](#distributing-your-loader) for others to use, you may wish to document this behavior and encourage users not to define a collection schema themselves, or how to do so safely if they need data returned in a different format.

If you need to dynamically generate the schema based on the configuration options or by introspecting an API, you can use [`createSchema()`](#loadercreateschema) instead.

#### Loader example

The following example shows a loader that fetches data from a provided feed URL (using a custom `loadFeedData` utility) and updates the data store with new entries each time the site is built:

```
// 1. Import the `Loader` type and any other dependencies needed

// 2. Define any options that your loader needs

  // 3. Return a loader object
  return {
    name: "feed-loader",
    load: async ({ store, parseData }) => {
      const feed = await loadFeedData(feedUrl, options.apiKey);

      store.clear();

      for (const item of feed.items) {
        const id = item.guid;
        const data = await parseData({
          id,
          data: item,
        });
        store.set({
          id,
          data,
        });
      }
    },
    // 4. Define the schema of an entry.
    schema: z.object({
      // ...
    })
  } satisfies Loader;
}
```

#### Defining your collection with your loader

Use your custom loader as the value of the `loader` property when you define your collection in `src/content.config.ts`. Configuration options can be passed to your loader as arguments:

```

const blog = defineCollection({
  loader: feedLoader({
    url: "https://api.example.com/posts",
    apiKey: "my-secret",
  }),
});
```

### Defining a loader as a function

For simple data fetches that do not need custom data store handling, validation, logging, or any other helpers provided by the [build-time loader object](#the-loader-object), you can define your loader as a function.

The function can be async and must return either an array of entries that each contain a unique `id` field, or an object where each key is a unique ID and each value is the entry.

This pattern provides a convenient shorthand to accomplish the basic tasks normally performed by the `load()` function to [load collections into the data store](#loading-collections-into-the-data-store). At build-time, the loader will automatically clear the data store and reload all the entries. No further customization options or helpers for data handling are provided.

These loaders are often simple enough that you may choose to define them inline in the `src/content.config.ts` file:

```

const countries = defineCollection({
  loader: async () => {
    const response = await fetch("https://restcountries.com/v3.1/all");
    const data = await response.json();
    // Must return an array of entries with an id property
    // or an object with IDs as keys and entries as values
    return data.map((country) => ({
      id: country.cca3,
      ...country,
    }));
  },
});
```

## Live Loaders

The Live Loader API is built to handle querying any data in real time. Live loaders can filter incoming data and verify content with type safety. Since live loaders fetch data fresh upon every request, there is no data store to update. These loaders are designed to return either data or an `Error` object to allow you to handle errors gracefully.

### Building a live loader

Most live loaders will export a function that accepts configuration options and returns a [live loader object](#the-liveloader-object) including a `name` for your loader and two methods to define how to load your collection of entries and how to load a single entry: `loadCollection()` and `loadEntry()`.

#### Loading live data

To return data about your collection, you must provide a [`loadCollection()`](#liveloaderloadcollection) function that fetches data, and returns an array of content [`entries`](#livedatacollectionentries) or an error.

To return a single live collection entry, you must provide a [`loadEntry()`](#liveloaderloadentry) function that fetches data filtered for a given `id`, and returns a single [`entry`](#livedataentry), `undefined`, or an error.

The data fetching for both of these functions is typically done using a [`try...catch` statement](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/try...catch) to [handle errors when accessing live data](#error-handling-in-live-loaders).

See the full [Live Loader API](#live-loader-api) for more about the functions and types available for building your live loader.

#### Providing a schema for live loaders

Live loaders do not include a schema property. Instead, you can provide type safety by [defining a Zod schema for your collection](/en/guides/content-collections/#using-zod-schemas-with-live-collections) in `src/live.config.ts`, or by passing generic types to the `LiveLoader` interface for the data they return.

#### Example live loader

The following example shows a live loader that defines data fetching from a CMS (using a custom `fetchFromCMS` utility) for both a collection of entries and a single entry, including type safety and error handling:

```

interface Article {
  id: string;
  title: string;
  htmlContent: string;
  author: string;
}

interface EntryFilter {
  id: string;
}

interface CollectionFilter {
  author?: string;
}

        return {
          entries: articles.map((article) => ({
            id: article.id,
            data: article,
          })),
        };
      } catch (error) {
        return {
          error: new Error('Failed to load articles', { cause: error }),
        };
      }
    },
    loadEntry: async ({ filter }) => {
      try {
        // filter will be { id: "some-id" } when called with a string
        const article = await fetchFromCMS({
          apiKey: config.apiKey,
          type: 'article',
          id: filter.id,
        });

        if (!article) {
          return {
            error: new Error('Article not found'),
          };
        }

        return {
          id: article.id,
          data: article,
          rendered: {
            html: article.htmlContent,
          },
        };
      } catch (error) {
        return {
          error: new Error('Failed to load article', { cause: error }),
        };
      }
    },
  };
}
```

#### Defining your live collection with your loader

Use your custom live loader as the value of the `loader` property when you define your collection in `src/live.config.ts`. Configuration options can be passed to your loader as arguments:

```

const blog = defineLiveCollection({
  loader: articleLoader({
    apiKey: "my-secret",
  }),
});
```

#### Error handling in live loaders

Live loaders return an [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) subclass for errors. You can create [custom error types](#creating-live-loader-error-types) and use them for more specific error handling if needed. If an error is thrown in the live loader, it will be caught and returned, wrapped in a `LiveCollectionError`.

Astro will generate some errors itself, depending on the response from the live loader:

-   If `loadEntry` returns `undefined`, Astro will return a `LiveEntryNotFoundError` to the user.
-   If a schema is defined for the collection and the data does not match the schema, Astro will return a `LiveCollectionValidationError`.
-   If the loader returns an invalid cache hint, Astro will return a `LiveCollectionCacheHintError`. The `cacheHint` field is optional, so if you do not have valid data to return, you can simply omit it.

```

    },
    // ...
  };
}
```

##### Creating live loader error types

You can create custom error types for [errors returned by your loader](#error-handling-in-live-loaders) and pass them as a generic to get proper typing:

```

    this.name = 'MyLoaderError';
  }
}

    },
    // ...
  };
}
```

When you use `getLiveCollection()` or `getLiveEntry()`, TypeScript will infer the custom error type, allowing you to handle it appropriately:

```
---

if (error) {
  if (error instanceof MyLoaderError) {
    console.error(`Loader error: ${error.message} (code: ${error.code})`);
  } else {
    console.error(`Unexpected error: ${error.message}`);
  }
  return Astro.rewrite('/500');
}
---
```

#### Defining custom filter types

Live loaders can define custom filter types for both `getLiveCollection()` and `getLiveEntry()`. This enables type-safe querying that matches your API's capabilities, making it easier for users to discover available filters and ensure they are used correctly. If you include JSDoc comments in your filter types, the user will see these in their IDE as hints when using the loader.

```

interface CollectionFilter {
  category?: string;
  /** Minimum price to filter products */
  minPrice?: number;
  /** Maximum price to filter products */
  maxPrice?: number;
}

interface EntryFilter {
  /** Alias for `sku` */
  id?: string;
  slug?: string;
  sku?: string;
}

  endpoint: string;
}): LiveLoader<Product, EntryFilter, CollectionFilter> {
  return {
    name: 'product-loader',
    loadCollection: async ({ filter }) => {
      // filter is typed as CollectionFilter
      const data = await fetchCategory({
        apiKey: config.apiKey,
        category: filter?.category ?? 'all',
        minPrice: filter?.minPrice,
        maxPrice: filter?.maxPrice,
      });

      return {
        entries: data.products.map((product) => ({
          id: product.sku,
          data: product,
        })),
      };
    },
    loadEntry: async ({ filter }) => {
      // filter is typed as EntryFilter | { id: string }
      const product = await fetchProduct({
        apiKey: config.apiKey,
        slug: filter.slug,
        sku: filter.sku || filter.id,
      });
      if (!product) {
        return {
          error: new Error('Product not found'),
        };
      }
      return {
        id: product.sku,
        data: product,
      };
    },
  };
}
```

#### Cache hints

Live loaders can provide cache hints to help with response caching. You can use this data to send HTTP cache headers or otherwise inform your caching strategy.

```

      return {
        entries: products.map((item) => ({
          id: item.id,
          data: item,
          // You can optionally provide cache hints for each entry
          cacheHint: {
            tags: [`product-${item.id}`, `category-${item.category}`],
          },
        })),
        cacheHint: {
          // All fields are optional, and are combined with each entry's cache hints
          // tags are merged from all entries
          // lastModified is the most recent lastModified of all entries and the collection
          lastModified: getLastModifiedDate(products),
          tags: ['products'],
        },
      };
    },
    loadEntry: async ({ filter }) => {
      const item = await loadStoreProduct(filter);
      return {
        id: item.id,
        data: item,
        cacheHint: {
          lastModified: new Date(item.lastModified),
          tags: [`product-${item.id}`, `category-${item.category}`],
        },
      };
    },
  };
}
```

You can then use these hints in your pages. If you have [configured a cache provider](/en/guides/caching/#configure-caching), pass cache hints directly to [`Astro.cache.set()`](/en/reference/api-reference/#cacheset):

```
---

if (error) {
  return Astro.redirect('/404');
}

// Pass cache hints to route caching
if (cacheHint) {
  Astro.cache.set(cacheHint);
}
Astro.cache.set({ maxAge: 300 });
---

<h1>{entry.data.name}</h1>
<p>{entry.data.description}</p>
```

Without a cache provider, you can use cache hints to set response headers manually for your own caching strategy:

```
---

if (error) {
  return Astro.redirect('/404');
}

if (cacheHint?.tags) {
  Astro.response.headers.set('Cache-Tag', cacheHint.tags.join(','));
}

if (cacheHint?.lastModified) {
  Astro.response.headers.set('Last-Modified', cacheHint.lastModified.toUTCString());
}
---

<h1>{entry.data.name}</h1>
<p>{entry.data.description}</p>
```

:::note Cache hints do not automatically cause the response to be cached by Astro. They provide values you can pass to [route caching](/en/guides/caching/) or use to implement your own caching strategy. :::

## Distributing your loader

Loaders can be defined in your site or as a separate npm package. If you want to share your loader with the community, you can [publish it to npm with the `withastro` and `astro-loader` keywords](/en/guides/integrations/#packagejson-data).

A loader should export a function that returns a `LiveLoader` object for live loaders or a `Loader` object for build-time loaders, allowing users to configure it with their own settings.

## Object loader API

This section shows the API for defining a [build-time object loader](#building-a-loader).

### The `Loader` object

**Type:** `Loader`

A loader function returns an object with two required properties. In addition to providing a name for the loader, this object describes how to fetch the collection data.

Optionally, you can return a third property defining a schema to validate your collection entries. Use the [TypeScript `satisfies` operator](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html#the-satisfies-operator) instead of a return type annotation to provide type safety inside your loader object and to preserve type inference when your loader is used in a collection.

#### `Loader.name`

**Type:** `string`

A unique name for the loader, used in logs and [for conditional loading](/en/reference/integrations-reference/#refreshcontent-option).

#### `Loader.load()`

**Type:** `(context: [LoaderContext](#loadercontext)) => Promise<void>`

An async function that is called at build time to load data and update the store. It is passed a [`LoaderContext`](#loadercontext) object that contains helper functions and properties for writing your loader's implementation logic, as well as the `store` database and methods for interacting with it.

#### `Loader.schema`

**Type:** `ZodSchema`

An optional [Zod schema](/en/guides/content-collections/#defining-datatypes-with-zod) that defines the shape of the entries. It is used to both validate the data and also to generate TypeScript types for the collection.

When you need to dynamically generate the schema at build time based on configuration options or by introspecting an API, use [`createSchema()`](#loadercreateschema) instead.

If present, it will be overridden by any Zod `schema` defined for the collection in the `src/content.config.ts` file.

#### `Loader.createSchema()`

**Type:** `() => Promise<{ schema: ZodSchema; types: string }>`

An optional async function that returns an object containing a [Zod schema](/en/guides/content-collections/#defining-datatypes-with-zod) and types. It is used to dynamically generate the schema at build time based on the configuration options or by introspecting an API.

When you only need to provide a static schema, provide a Zod validation object using [`schema`](#loaderschema) instead.

If present, it will be overridden by any Zod `schema` defined for the collection in the `src/content.config.ts` file.

The returned `types` contents will be written to a TypeScript file, and must export an `Entry` type or interface:

```

  return {
    name: "feed-loader",
    load: async ({ store, parseData }) => {
      const feed = await loadFeedData(feedUrl, options.apiKey);

      store.clear();

      for (const item of feed.items) {
        const id = item.guid;
        const data = await parseData({
          id,
          data: item,
        });
        store.set({
          id,
          data,
        });
      }
    },
    createSchema: async () => {
      const schema = await getSchema();
      const types = await getTypes();

      return {
      	schema,
      	types: `export type Entry = ${types}`,
      };
    },
  } satisfies Loader;
}
```

### `LoaderContext`

This object is passed to the [`load()`](#loaderload) method of the loader, and contains the following properties:

#### `LoaderContext.collection`

**Type:** `string`

The unique name of the collection. This is the key in the `collections` object in the `src/content.config.ts` file.

#### `LoaderContext.store`

**Type:** [`DataStore`](#datastore)

A database to store the actual data. Use this to update the store with new entries. See [`DataStore`](#datastore) for more information.

#### `LoaderContext.meta`

**Type:** `MetaStore`

A key-value store scoped to the collection, designed for things like sync tokens and last-modified times. This metadata is persisted between builds alongside the collection data but is only available inside the loader.

```
const lastModified = meta.get("lastModified");
// ...
meta.set("lastModified", new Date().toISOString());
```

#### `LoaderContext.logger`

**Type:** [`AstroIntegrationLogger`](/en/reference/integrations-reference/#astrointegrationlogger)

A logger that can be used to log messages to the console. Use this instead of `console.log` for more helpful logs that include loader-specific content such as the loader name or information about the loading process in the log message. See [`AstroIntegrationLogger`](/en/reference/integrations-reference/#astrointegrationlogger) for more information.

```
return {
  name: 'file-loader',
  load: async ({ config, store, logger, watcher }) => {
    const url = new URL(fileName, config.root);
    const filePath = fileURLToPath(url);
    await syncData(filePath, store);

    watcher?.on('change', async (changedPath) => {
      if (changedPath === filePath) {
        logger.info(`Reloading data from ${fileName}`);
        await syncData(filePath, store);
      }
    });
  },
};
```

#### `LoaderContext.config`

**Type:** `AstroConfig`

The full, resolved Astro configuration object with all defaults applied. See [the configuration reference](/en/reference/configuration-reference/) for more information.

```
return {
  name: 'file-loader',
  load: async ({ config, store, logger, watcher }) => {
    const url = new URL(fileName, config.root);
    const filePath = fileURLToPath(url);
    await syncData(filePath, store);

    watcher?.on('change', async (changedPath) => {
      if (changedPath === filePath) {
        logger.info(`Reloading data from ${fileName}`);
        await syncData(filePath, store);
      }
    });
  },
};
```

#### `LoaderContext.parseData()`

**Type:** `(props: ParseDataOptions<TData>) => Promise<TData>`

Validates and parses the data according to the collection schema. Pass data to this function to validate and parse it before storing it in the data store.

```

  return {
    name: "feed-loader",
    load: async ({ store, logger, parseData, meta, generateDigest }) => {
      logger.info("Loading posts");
      const feed = loadFeed(feedUrl);
      store.clear();

      for (const item of feed.items) {
        const id = item.guid;
        const data = await parseData({
          id,
          data: item,
        });
        store.set({
          id,
          data,
        });
      }
    },
  } satisfies Loader;
}
```

#### `LoaderContext.renderMarkdown()`

**Type:** `(content: string, options?: { fileURL?: URL }) => Promise<RenderedContent>`

Renders a Markdown string to HTML, returning a `RenderedContent` object.

This allows you to render Markdown content directly within your loaders using the same Markdown processing as Astro's built-in `glob()` loader and provides access to the `render()` function and `<Content />` component for [rendering body content](/en/guides/content-collections/#rendering-body-content).

Assign this object to the [rendered](#dataentryrendered) field of the [DataEntry](#dataentry) object to allow users to [render the content in a page](/en/guides/content-collections/#rendering-body-content). If the Markdown content includes frontmatter, it will be parsed and available in `metadata.frontmatter`. The frontmatter will be excluded from the HTML output.

```

      store.clear();

      for (const entry of entries) {
        store.set({
          id: entry.id,
          data: entry,
          // Assume each entry has a 'content' field with markdown content
          rendered: await renderMarkdown(entry.content),
        });
      }
    },
  } satisfies Loader;
}
```

##### `fileURL`

**Type:** `URL`

Specifies the file path to use for resolving relative image paths in Markdown content.

The following example uses the [configured root directory](/en/reference/configuration-reference/#root) to resolve image paths:

```
for (const file of files) {
  const content = await readFile(file.path, 'utf8');
  store.set({
    id: file.id,
    data: file.data,
    rendered: await renderMarkdown(content, {
      fileURL: new URL(file.path, config.root),
    }),
  });
}
```

#### `LoaderContext.generateDigest()`

**Type:** `(data: Record<string, unknown> | string) => string`

Generates a non-cryptographic content digest of an object or string. This can be used to track if the data has changed by setting [the `digest` field](#dataentrydigest) of an entry.

```

  return {
    name: "feed-loader",
    load: async ({ store, logger, parseData, meta, generateDigest }) => {
      logger.info("Loading posts");
      const feed = loadFeed(feedUrl);
      store.clear();

      for (const item of feed.items) {
        const id = item.guid;
        const data = await parseData({
          id,
          data: item,
        });

        const digest = generateDigest(data);

        store.set({
          id,
          data,
          digest,
        });
      }
    },
  } satisfies Loader;
}
```

#### `LoaderContext.watcher`

**Type:** `FSWatcher`

When running in dev mode, this is a filesystem watcher that can be used to trigger updates. See [`ViteDevServer`](https://vite.dev/guide/api-javascript.html#vitedevserver) for more information.

```
return {
  name: 'file-loader',
  load: async ({ config, store, watcher }) => {
    const url = new URL(fileName, config.root);
    const filePath = fileURLToPath(url);
    await syncData(filePath, store);

    watcher?.on('change', async (changedPath) => {
      if (changedPath === filePath) {
        logger.info(`Reloading data from ${fileName}`);
        await syncData(filePath, store);
      }
    });
  },
};
```

#### `LoaderContext.refreshContextData`

**Type:** `Record<string, unknown>`

If the loader has been triggered by an integration, this may optionally contain extra data set by that integration. It is only set when the loader is triggered by an integration. See the [`astro:server:setup`](/en/reference/integrations-reference/#refreshcontent-option) hook reference for more information.

```

        processWebhook(store, refreshContextData.webhookBody);
      }
      // ...
    },
  } satisfies Loader;
}
```

### `DataStore`

The data store is a loader's interface to the content collection data. It is a key-value (KV) store, scoped to the collection, and therefore a loader can only access the data for its own collection.

#### `DataStore.get()`

**Type:** `(key: string) => [DataEntry](#dataentry) | undefined`

Get an entry from the store by its ID. Returns `undefined` if the entry does not exist.

```
const existingEntry = store.get("my-entry");
```

The returned object is a [`DataEntry`](#dataentry) object.

#### `DataStore.set()`

**Type:** `(entry: [DataEntry](#dataentry)) => boolean`

Used after data has been [validated and parsed](#loadercontextparsedata) to add an entry to the store, returning `true` if the entry was set. This returns `false` when the [`digest`](#dataentrydigest) property determines that an entry has not changed and should not be updated.

```
    for (const item of feed.items) {
      const id = item.guid;
      const data = await parseData({
        id,
        data: item,
      });
      const digest = generateDigest(data);
      store.set({
        id,
        data,
        rendered: {
          html: data.description ?? "",
        },
        digest,
      });
    }
```

#### `DataStore.entries()`

**Type:** `() => Array<[id: string, [DataEntry](#dataentry)]>`

Get all entries in the collection as an array of key-value pairs.

#### `DataStore.keys()`

**Type:** `() => Array<string>`

Get all the keys of the entries in the collection.

#### `DataStore.values()`

**Type:** `() => Array<[DataEntry](#dataentry)>`

Get all entries in the collection as an array.

#### `DataStore.delete()`

**Type:** `(key: string) => void`

Delete an entry from the store by its ID.

#### `DataStore.clear()`

**Type:** `() => void`

Clear all entries from the collection.

#### `DataStore.has()`

**Type:** `(key: string) => boolean`

Check if an entry exists in the store by its ID.

### `DataEntry`

This is the type of the object that is stored in the data store. It has the following properties:

#### `DataEntry.id`

**Type:** `string`

An identifier for the entry, which must be unique within the collection. This is used to look up the entry in the store and is the key used with [`getEntry()`](/en/reference/modules/astro-content/#getentry) for that collection.

#### `DataEntry.data`

**Type:** `Record<string, unknown>`

The actual data for the entry. When a user accesses the collection, this will have TypeScript types generated according to the collection schema.

It is the loader's responsibility to use [`parseData()`](#loadercontextparsedata) to validate and parse the data before storing it in the data store: no validation is done when getting or setting the data.

#### `DataEntry.filePath`

**Type:** `string | undefined`

A path to the file that is the source of this entry, relative to the root of the site. This only applies to file-based loaders and is used to resolve paths such as images or other assets.

If not set, then any fields in the schema that use [the `image()` helper](/en/guides/images/#images-in-content-collections) will be treated as [public paths](/en/guides/images/#where-to-store-images) and not transformed.

#### `DataEntry.body`

**Type:** `string | undefined`

The raw body of the entry, if applicable. If the entry includes [rendered content](#dataentryrendered), then this field can be used to store the raw source. This is optional and is not used internally.

#### `DataEntry.digest`

**Type:** `string | undefined`

An optional content digest for the entry. This can be used to check if the data has changed.

When [setting an entry](#datastoreset), the entry will only update if the digest does not match an existing entry with the same ID.

The format of the digest is up to the loader, but it must be a string that changes when the data changes. This can be done with the [`generateDigest`](#loadercontextgeneratedigest) function.

#### `DataEntry.rendered`

**Type:** `RenderedContent | undefined`

Stores an object with an entry's rendered content and metadata if it has been rendered to HTML. For example, this can be used to store the rendered content of a Markdown entry, or HTML from a CMS.

If this field is provided, then [the `render()` function and `<Content />` component](/en/guides/content-collections/#rendering-body-content) are available to render the entry in a page.

If the entry has Markdown content then you can use the [`renderMarkdown()`](#loadercontextrendermarkdown) function to generate this object from the Markdown string.

##### `DataEntry.rendered.html`

**Type:** `string`

Contains the rendered HTML string. This is used by [`render()`](/en/reference/modules/astro-content/#render) to return a component that renders this HTML.

##### `DataEntry.rendered.metadata`

**Type:** `object | undefined`

Describes the metadata present in this file. This includes the `imagePaths`, the `headings`, the `frontmatter`, and any other metadata present in the file. When the file has not been rendered as HTML, this value will be `undefined`.

###### `DataEntry.rendered.metadata.imagePaths`

**Type:** `string[]`

Specifies the list of images paths present in this entry. Each path is relative to the [entry `filePath`](#dataentryfilepath).

###### `DataEntry.rendered.metadata.headings`

**Type:** `MarkdownHeading[]`

Specifies the list of headings present in this file. Each heading is described by a `depth` determined by the heading level (`h1 -> h6`), a `slug` generated with [`github-slugger`](https://github.com/Flet/github-slugger), and its `text` content.

###### `DataEntry.rendered.metadata.frontmatter`

**Type:** `Record<string, any>`

Describes the raw frontmatter, parsed from the file. This may include [programmatically injected data from Markdown plugins](/en/guides/markdown-content/#modifying-frontmatter-programmatically).

## Live loader API

This section shows the API for defining a [live loader](#live-loaders).

### The `LiveLoader` object

**Type:** `LiveLoader<TData, TEntryFilter, TCollectionFilter, TError>`

A live loader function returns an object with three required live loader properties. In addition to providing a name for the loader, this object describes how to fetch both single entries and an entire collection from your live data source.

Use the `LiveLoader` generic type to provide type safety in your loader. This type accepts the following type parameters, in this order:

-   **`TData`** (defaults to `Record<string, unknown>`): The data structure of each entry returned by the loader.
-   **`TEntryFilter`** (defaults to `never`): The filter object type accepted by [`getLiveEntry()`](/en/reference/modules/astro-content/#getliveentry) and accessible in [`loadEntry()`](#liveloaderloadentry). Use `never` when you don't support filtering single entries.
-   **`TCollectionFilter`** (defaults to `never`): The filter object type accepted by [`getLiveCollection()`](/en/reference/modules/astro-content/#getlivecollection) and accessible in [`loadCollection()`](#liveloaderloadcollection). Use `never` when you don't support filtering collections.
-   **`TError`** (defaults to `Error`): A [custom `Error` class](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error#custom_error_types) that can be returned by the loader for more granular error handling.

#### `LiveLoader.name`

**Type:** `string`

A unique name for the loader, used in logs.

#### `LiveLoader.loadCollection()`

**Type:** `(context: [LoadCollectionContext](#loadcollectioncontext)<TCollectionFilter>) => Promise<[LiveDataCollection](#livedatacollection)<TData> | { error: TError; }>`

Defines a method to load a collection of entries. This function receives a [context object](#loadcollectioncontext) containing an optional `filter` property and must return the data associated with this collection or the errors.

#### `LiveLoader.loadEntry()`

**Type:** `(context: [LoadEntryContext](#loadentrycontext)<TEntryFilter>) => Promise<[LiveDataEntry](#livedataentry)<TData> | undefined | { error: TError; }>`

Defines a method to load a single entry. This function receives a [context object](#loadentrycontext) containing a `filter` property and returns either the data associated with the requested entry, `undefined` when the entry cannot be found, or the errors.

### `LoadCollectionContext`

**Type:** `{ filter?: TCollectionFilter; }`

This object is passed to the [`loadCollection()` method](#liveloaderloadcollection) of the loader and contains the following properties:

#### `LoadCollectionContext.filter`

**Type:** `Record<string, any> | never`  
**Default:** `never`

An object describing the [filters supported by your loader](#defining-custom-filter-types).

### `LoadEntryContext`

**Type:** `{ filter: TEntryFilter; }`

This object is passed to the [`loadEntry()` method](#liveloaderloadentry) of the loader and contains the following properties:

#### `LoadEntryContext.filter`

**Type:** `Record<string, any> | never`  
**Default:** `never`

An object describing the [filters supported by your loader](#defining-custom-filter-types).

### `LiveDataEntry`

**Type:** `{ id: string; data: TData; rendered?: { html: string }; cacheHint?: [CacheHint](#cachehint); }`

This is the type object that is returned by the [`loadEntry()`](#liveloaderloadentry) method. It contains the following properties:

#### `LiveDataEntry.id`

**Type:** `string`

An identifier for the entry, which must be unique within the collection. This is the key used with [`getLiveEntry()`](/en/reference/modules/astro-content/#getliveentry) for that collection.

#### `LiveDataEntry.data`

**Type:** `Record<string, unknown>`

The actual data for the entry. When a user accesses the collection, this will have TypeScript types generated according to the collection schema.

It is the loader's responsibility to validate and parse the data before returning it.

#### `LiveDataEntry.rendered`

**Type:** `{ html: string }`

An object with an entry's rendered content if it has been rendered to HTML. For example, this can be the rendered content of a Markdown entry, or HTML from a CMS.

If this field is provided, then [the `render()` function and `<Content />` component](/en/guides/content-collections/#rendering-body-content) are available to render the entry in a page.

If the loader does not return a `rendered` property for an entry, the `<Content />` component will render nothing.

#### `LiveDataEntry.cacheHint`

**Type:** [`CacheHint`](#cachehint)

An optional object to provide a hint for how to cache this specific entry.

See the content collection guide to learn how to [use cache hints at entry-level](/en/guides/content-collections/#entry-level-cache-hints).

### `LiveDataCollection`

**Type:** `{ entries: Array<[LiveDataEntry](#livedataentry)<TData>>; cacheHint?: [CacheHint](#cachehint); }`

This is the type object that is returned by the [`loadCollection()`](#liveloaderloadcollection) method. It contains the following properties:

#### `LiveDataCollection.entries`

**Type:** `Array<[LiveDataEntry](#livedataentry)<TData>>`

An array of [`LiveDataEntry`](#livedataentry) objects.

#### `LiveDataCollection.cacheHint`

**Type:** [`CacheHint`](#cachehint)

An optional object providing guidance on how to cache this collection. This object will be merged with the cache hints defined for each individual entry, if provided.

See the content collection guide to learn how to [use cache hints at collection-level](/en/guides/content-collections/#collection-level-cache-hints).

### `CacheHint`

An object that loaders can return through the `cacheHint` property in [`LiveDataCollection`](#livedatacollection) or [`LiveDataEntry`](#livedataentry) to provide hints to assist in [caching the response](/en/guides/caching/). This contains the following properties:

#### `CacheHint.tags`

**Type:** `Array<string>`

An array of string identifiers allowing fine-grained cache control. This allows you to group related content and selectively invalidate cached responses when specific content changes.

The following example defines cache hint tags for a collection of posts filtered by author:

```
return {
  /* ... */
  cacheHint: {
    tags: ["posts", `posts-${filter.author}`],
  },
};
```

#### `CacheHint.lastModified`

**Type:** `Date`

The date of the last modification of the content (e.g., the last update of an entry in a collection). This can be used to set HTTP cache headers like [`Last-Modified`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Last-Modified) and [`If-Modified-Since`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/If-Modified-Since).

The following example defines a cache hint for a single product using its last update date:

```
return {
  /* ... */
  cacheHint: {
    lastModified: new Date(product.updatedAt)
  },
};
```

## [Dev Toolbar App API](https://docharvest.github.io/docs/astro/reference/dev-toolbar-app-reference/)

Contents

astro

Dev Toolbar App API

Astro

Dev Toolbar App API

The Astro Dev Toolbar App API allows you to create [Astro Integrations](/en/reference/integrations-reference/) that add apps to the Astro Dev Toolbar. This allows you to add new features and integrations with third-party services.

<RecipeLinks slugs={\["en/recipes/making-toolbar-apps"\]} />

## Toolbar app integration setup

Integrations can add apps to the dev toolbar in [the `astro:config:setup` hook](/en/reference/integrations-reference/#astroconfigsetup).

```
/**
 * @type {() => import('astro').AstroIntegration}
 */

    },
  },
});
```

### `addDevToolbarApp()`

**Type:** `(entrypoint: DevToolbarAppEntry) => void`  

A function available to [the `astro:config:setup` hook](/en/reference/integrations-reference/#astroconfigsetup) that adds dev toolbar apps. It takes an object with the following required properties to define the toolbar app: [`id`](#id), [`name`](#name), and [`entrypoint`](#entrypoint). Optionally, you can also define an [`icon`](#icon) for your app.

### `id`

**Type:** `string`

A unique identifier for the app. This will be used to uniquely identify the app in hooks and events.

```
{
  id: 'my-app',
  // ...
}
```

### `name`

**Type:** `string`

The name of the app. This will be shown to users whenever the app needs to be referenced using a human-readable name.

```
{
  // ...
  name: 'My App',
  // ...
}
```

### `icon`

**Type:** `[Icon](#icons) | string`  
**Default**: `"?"`

The icon used to display the app in the toolbar. This can either be an icon from [the icon list](#icons), or a string containing the SVG markup of the icon.

```
{
  // ...
  icon: '<svg>...</svg>', // or, e.g. 'astro:logo'
  // ...
}
```

### `entrypoint`

**Type:** `string | URL`

The path to the file that exports the dev toolbar app.

```
{
  // ...
  entrypoint: './my-app.js',
}
```

The function also accepts a `URL` as `entrypoint`:

```
/**
 * @type {() => import('astro').AstroIntegration}
 */

    },
  },
});
```

## Structure of a Dev Toolbar App

A Dev Toolbar App is a `.js` or `.ts` file that default exports an object using the [`defineToolbarApp()` function](#definetoolbarapp) available from the `astro/toolbar` module.

```

    canvas.appendChild(text);
  },
  beforeTogglingOff() {
    const confirmation = window.confirm('Really exit?');
    return confirmation;
  } 
});
```

### `defineToolbarApp()`

**Type:** `(app: DevToolbarApp) => DevToolbarApp`

A function that defines the logic of your toolbar app when it is loaded and toggled off.

This function takes an object with an [`init()`](#init) function that will be called when the dev toolbar app is loaded. It can also take a [`beforeTogglingOff()`](#beforetogglingoff) function that will run when the toolbar app is clicked to toggle off its active status.

### `init()`

**Type:** `(canvas: ShadowRoot, app: ToolbarAppEventTarget, server: ToolbarServerHelpers) => void | Promise<void>`

Although not required, most apps will use this function to define the core behavior of the app. This function will be called only once when the app is loaded, which will either be when the browser is idle or when the user clicks on the app in the UI, depending on which one comes first.

The function receives three arguments to define your app logic: [`canvas`](#canvas) (to render elements to the screen), [`app`](#app) (to send and receive client-side events from the dev toolbar), and [`server`](#server) (to communicate with the server).

#### `canvas`

**Type:** `ShadowRoot`

A standard [ShadowRoot](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot) that the app can use to render its UI. Elements can be created and added to the ShadowRoot using the standard DOM APIs.

Every app receives its own dedicated ShadowRoot for rendering its UI. Additionally, the parent element is positioned using `position: absolute;` so the app UI will not affect the layout of an Astro page.

#### `app`

**Type:** `ToolbarAppEventTarget`  

A standard [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) with a few additional [helpers for client-side events](#client-side-events) that can be used to send and receive events from the Dev toolbar.

```

      canvas.appendChild(text);
    });
  },
});
```

#### `server`

**Type:** `ToolbarServerHelpers`  

An object that can be used to [communicate with the server](#client-server-communication).

```

    server.on('server-message', (data) => {
      console.log(data.message);
    });
  },
});
```

### `beforeTogglingOff()`

**Type:** `(canvas: ShadowRoot) => boolean | Promise<boolean>`  

This optional function will be called when the user clicks on the app icon in the UI to toggle off the app. This function can be used, for example, to perform cleanup operations, or to ask the user for confirmation before toggling off the app.

If a falsy value is returned, the toggling off will be cancelled and the app will stay enabled.

```

    return confirmation;
  }
});
```

#### canvas

**Type:** `ShadowRoot`

The ShadowRoot of the app, can be used to render any UI needed before closing. Same as the [`canvas` argument of the `init` function](#canvas).

## Client-side Events

In addition to the standard methods of an `EventTarget` ([`addEventListener`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget), [`dispatchEvent`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/dispatchEvent), [`removeEventListener`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/removeEventListener)etc.), the [`app`](#app) object also has the following methods:

### `onToggled()`

**Type:** `(callback: (options: {state: boolean})) => void`  

Registers a callback to be called when the user clicks on the app icon in the UI to toggle the app on or off.

```
app.onToggled((options) => {
  console.log(`The app is now ${options.state ? 'enabled' : 'disabled'}!`);
});
```

### `onToolbarPlacementUpdated()`

**Type:** `(callback: (options: {placement: 'bottom-left' | 'bottom-center' | 'bottom-right'})) => void`  

This event is fired when the user changes the placement of the Dev Toolbar. This can, for example, be used to reposition the app's UI when the toolbar is moved.

```
app.onToolbarPlacementUpdated((options) => {
  console.log(`The toolbar is now placed at ${options.placement}!`);
});
```

### `toggleState()`

**Type:** `(options: {state: boolean}) => void`  

Changes the state of the app. This can be used to enable or disable the app programmatically, for example, when the user clicks on a button in the app's UI.

```
app.toggleState({ state: false });
```

### `toggleNotification()`

**Type:** `(options: {state?: boolean, level?: 'error' | 'warning' | 'info'}) => void`  

Toggles a notification on the app icon. This can be used to inform the user that the app requires attention, or remove the current notification.

```
app.toggleNotification({
  state: true,
  level: 'warning',
});
```

#### `state`

**Type:** `boolean`

Indicates whether or not the app has a notification for the user. When `true`, the app icon will be highlighted. Conversely, when `false`, the highlight will be removed. If this property is not specified, `true` will be assumed.

#### `level`

**Type:** `'error' | 'warning' | 'info'`  
**Default:** `'error'`

Indicates the level of the notification. This will be used to determine the color and shape (dark pink circle, gold triangle, or blue square) of the highlight on the app icon. If this property is not specified, `'error'` will be assumed.

## Client-Server Communication

Using [Vite's methods for client-server communication](https://vite.dev/guide/api-plugin.html#client-server-communication), Dev Toolbar Apps and the server can communicate with each other. In order to facilitate sending and receiving custom messages, helper methods are provided for use both in your toolbar app (on the client) and in your integration (on the server).

### On the client

In your app, use the [`server` object on the `init()` hook](#server) to send and receive messages to and from the server.

```

    server.on('server-message', (data) => {
      console.log(data.message);
    });
  },
});
```

#### `send()`

**Type:** `<T>(event: string, payload: T) => void`  

Sends data to the server from logic defined in your toolbar app.

```
init(canvas, app, server) {
  server.send('my-app:my-message', { message: 'Hello!' });
}
```

When sending messages from the client to the server, it is good practice to prefix the event name with the app ID or other namespaces to avoid conflicts with other apps or other integrations that may be listening for messages.

#### `on()`

**Type:** `<T>(event: string, callback: (data: T) => void) => void`  

Registers a callback to be called when the server sends a message with the specified event.

```
init(canvas, app, server) {
  server.on('server-message', (data) => {
    console.log(data.message);
  });
}
```

### On the server

In an integration, such as [the integration that adds your toolbar app](#toolbar-app-integration-setup), use the [`astro:server:setup` hook](/en/reference/integrations-reference/#astroserversetup) to access the `toolbar` object to send and receive messages to and from your apps.

#### `send()`

**Type:** `<T>(event: string, payload: T) => void`  

Sends data to the client.

```
'astro:server:setup': ({ toolbar }) => {
  toolbar.send('server-message', { message: 'Hello!' });
},
```

#### `on()`

**Type:** `<T>(event: string, callback: (data: T) => void) => void`  

Registers a callback to be called when the client sends a message with the specified event.

```
'astro:server:setup': ({ toolbar }) => {
  toolbar.on('my-app:my-message', (data) => {
    console.log(data.message);
  });
},
```

#### `onAppInitialized()`

**Type:** `(appId: string, callback: () => void) => void`  

Registers a callback to be called when the app is initialized.

```
'astro:server:setup': ({ toolbar }) => {
  toolbar.onAppInitialized('my-app', () => {
    console.log('The app is now initialized!');
  });
},
```

:::note The built-in `connection` event from Vite fires **before** Dev Toolbar apps are initialized and therefore cannot be used directly by apps. Use the `onAppInitialized` method to ensure that the app is fully initialized before sending messages to it. :::

#### `onAppToggled()`

**Type:** `(appId: string, callback: (options: {state: boolean}) => void) => void`  

Registers a callback to be called when the user clicks on the app icon in the UI to toggle the app on or off.

```
'astro:server:setup': ({ toolbar }) => {
  toolbar.onAppToggled('my-app', ({ state }) => {
    console.log(`The app is now ${state ? 'enabled' : 'disabled'}!`);
  });
},
```

## Component Library

The Dev Toolbar includes a set of web components that can be used to build apps with a consistent look and feel.

### `astro-dev-toolbar-window`

Shows a window.

The slot of the component will be used as the content of the window.

```
<astro-dev-toolbar-window>
  <p>My content</p>
</astro-dev-toolbar-window>
```

When building a window using JavaScript, slotted content must go inside the light DOM of the component.

```
const myWindow = document.createElement('astro-dev-toolbar-window');
const myContent = document.createElement('p');
myContent.textContent = 'My content';

// use appendChild directly on `window`, not `myWindow.shadowRoot`
myWindow.appendChild(myContent);
```

### `astro-dev-toolbar-button`

Shows a button.

The slot of the component will be used as the content of the button.

```
const myButton = document.createElement('astro-dev-toolbar-button');
myButton.textContent = 'Click me!';
myButton.buttonStyle = "purple";
myButton.size = "medium";

myButton.addEventListener('click', () => {
  console.log('Clicked!');
});
```

#### `size`

**Type:** `"small" | "medium" | "large"`  
**Default:** `"small"`

The size of the button.

#### `button-style`

**Type:** `"ghost" | "outline" | "purple" | "gray" | "red" | "green" | "yellow" | "blue"`  
**Default:** `"purple"`

The style of the button. When using `ghost`, the button itself is invisible and only the content of the button will be shown.

In JavaScript, set this property using the `buttonStyle` property to avoid conflict with the native `style` property.

#### `button-border-radius`

**Type:** `"normal" | "rounded"`  
**Default:** `"normal"`  

The border radius of the button. When using `rounded`, the button will have rounded corners and uniform padding on all sides.

In JavaScript, set this property using the `buttonBorderRadius` property.

### `astro-dev-toolbar-badge`

Shows a badge.

The slot of the component will be used as the content of the badge.

```
<astro-dev-toolbar-badge>My badge</astro-dev-toolbar-badge>
```

#### `size`

**Type:** `"small" | "large"`  
**Default:** `"small"`

The size of the badge.

#### `badge-style`

**Type:** `"purple" | "gray" | "red" | "green" | "yellow" | "blue"`  
**Default:** `"purple"`

The style (color) of the badge.

In JavaScript, set this property using the `badgeStyle` property to avoid conflict with the native `style` property.

### `astro-dev-toolbar-card`

Shows a card. Specify an optional `link` attribute to make the card act like an `<a>` element.

When making a card using JavaScript, a `clickAction` property can be specified to make the card act like a `<button>` element.

The slot of the component will be used as the content of the card.

```
<astro-dev-toolbar-card icon="astro:logo" link="https://github.com/withastro/astro/issues/new/choose">Report an issue</astro-dev-toolbar-card>
```

#### `card-style`

**Type:** `"purple" | "gray" | "red" | "green" | "yellow" | "blue"`  
**Default:** `"purple"`

The style of the card. The color is only applied to the border of the card on hover.

In JavaScript, set this property using the `cardStyle`.

### `astro-dev-toolbar-toggle`

Shows a toggle element, acting as a checkbox. This element internally is a simple wrapper around a native `<input type="checkbox">` element. The checkbox element can be accessed using the `input` property.

```
const toggle = document.createElement('astro-dev-toolbar-toggle');

toggle.input.addEventListener('change', (evt) => {
  console.log(`The toggle is now ${evt.currentTarget.checked ? 'enabled' : 'disabled'}!`);
});
```

#### `toggle-style`

**Type:** `"purple" | "gray" | "red" | "green" | "yellow" | "blue"`  
**Default:** `"gray"`

The style of the toggle.

In JavaScript, set this property using the `toggleStyle` property.

### `astro-dev-toolbar-radio-checkbox`

Shows a radio checkbox. Similar to the `astro-dev-toolbar-toggle` component, this element is a simple wrapper around a native `<input type="radio">` element. The radio element can be accessed using the `input` property.

```
const radio = document.createElement('astro-dev-toolbar-radio-checkbox');

radio.input.addEventListener('change', (evt) => {
  console.log(`The radio is now ${evt.currentTarget.checked ? 'enabled' : 'disabled'}!`);
});
```

#### `radio-style`

**Type:** `"purple" | "gray" | "red" | "green" | "yellow" | "blue"`  
**Default:** `"purple"`

The style of the radio.

In JavaScript, set this property using the `radioStyle` property.

### `astro-dev-toolbar-highlight`

Can be used to highlight an element on the page. In most cases, you'll want to position and resize this element using the `top`, `left`, `width` and `height` CSS properties to match the element you want to highlight.

```
<!-- Highlight the entire page -->
<astro-dev-toolbar-highlight style="top: 0; left: 0; width: 100%; height: 100%;"></astro-dev-toolbar-highlight>
```

```
const elementToHighlight = document.querySelector('h1');
const rect = elementToHighlight.getBoundingClientRect();

const highlight = document.createElement('astro-dev-toolbar-highlight');

highlight.style.top = `${Math.max(rect.top + window.scrollY - 10, 0)}px`;
highlight.style.left = `${Math.max(rect.left + window.scrollX - 10, 0)}px`;
highlight.style.width = `${rect.width + 15}px`;
highlight.style.height = `${rect.height + 15}px`;
highlight.icon = 'astro:logo';
```

#### `highlight-style`

**Type:** `"purple" | "gray" | "red" | "green" | "yellow" | "blue"`  
**Default:** `"purple"`

The style of the highlight.

#### `icon`

An [icon](#icons) to show in the top right corner of the highlight.

### `astro-dev-toolbar-tooltip`

Shows a tooltip with different sections. This component is set to `display: none;` by default and can be made visible using a `data-show="true"` attribute.

Sections are defined using the `sections` property. This property is an array of objects with the following shape:

```
{
	title?: string; // Title of the section
	inlineTitle?: string; // Title of the section, shown inline next to the title
	icon?: Icon; // Icon of the section
	content?: string; // Content of the section
	clickAction?: () => void | Promise<void>; // Action to perform when clicking on the section
	clickDescription?: string; // Description of the action to perform when clicking on the section
}
```

```
const tooltip = document.createElement('astro-dev-toolbar-tooltip');

tooltip.sections = [{
  title: 'My section',
  icon: 'astro:logo',
  content: 'My content',
  clickAction: () => {
    console.log('Clicked!')
  },
  clickDescription: 'Click me!'
}]
```

This component is often combined with the `astro-dev-toolbar-highlight` component to show a tooltip when hovering a highlighted element:

```
const highlight = document.createElement('astro-dev-toolbar-highlight');

// Position the highlight...

const tooltip = document.createElement('astro-dev-toolbar-tooltip');

// Add sections to the tooltip...

highlight.addEventListener('mouseover', () => {
  tooltip.dataset.show = 'true';
});

highlight.addEventListener('mouseout', () => {
  tooltip.dataset.show = 'false';
});
```

### `astro-dev-toolbar-icon`

Shows an icon. An icon from [the icon list](#icons) can be specified using the `icon` attribute, or the SVG markup of an icon can be passed as a slot.

```
<astro-dev-toolbar-icon icon="astro:logo" />
```

```
<astro-dev-toolbar-icon>
  <svg>...</svg>
</astro-dev-toolbar-icon>
```

### `astro-dev-toolbar-select`

Shows a select element. Similar to the `astro-dev-toolbar-toggle` component, this element is a simple wrapper around a native `<select>` element. Use the `element` property to have access to the select element.

```
const mySelect = document.createElement("astro-dev-toolbar-select");
const options = [
  { label: "First option", value: "first" },
  { label: "Second option", value: "second", isDefault: true },
];
const myOptions = options.map((option) => {
  const optionEl = document.createElement("option");
  optionEl.textContent = option.label;
  optionEl.setAttribute("value", option.value);
  optionEl.selected = option.isDefault || false;
  return optionEl;
});

mySelect.selectStyle = "green";
mySelect.append(...myOptions);

mySelect.element.addEventListener("change", (evt) => {
  if (evt.currentTarget instanceof HTMLSelectElement) {
    console.log(`The select value is now ${evt.currentTarget.value}!`);
  }
});
```

#### `select-style`

**Type:** `"purple" | "gray" | "red" | "green" | "yellow" | "blue"`  
**Default:** `"gray"`

The style of the select.

In JavaScript, set this property using the `selectStyle` property.

#### Icons

Currently, the following icons are available and can be used in any component that accepts an icon:

-   `astro:logo`
-   `warning`
-   `arrow-down`
-   `bug`
-   `check-circle`
-   `gear`
-   `lightbulb`
-   `file-search`
-   `star`
-   `checkmark`
-   `dots-three`
-   `copy`
-   `compress`
-   `grid`
-   `puzzle`
-   `approveUser`
-   `checkCircle`
-   `resizeImage`
-   `searchFile`
-   `image`
-   `robot`
-   `sitemap`
-   `gauge`
-   `person-arms-spread`
-   `arrow-left`
-   `houston-detective`

All of the above icons have `fill="currentColor"` set by default and will inherit their color from the parent element.

## [Template directives reference](https://docharvest.github.io/docs/astro/reference/directives-reference/)



## [Error reference](https://docharvest.github.io/docs/astro/reference/error-reference/)

Contents

astro

Error reference

Astro

Error reference

import DontEditWarning from '~/components/DontEditWarning.astro'

The following reference is a complete list of the errors you may encounter while using Astro. For additional assistance, including common pitfalls, please also see our [Troubleshooting Guide](/en/guides/troubleshooting/).

## Astro Errors

-   [**UnknownCompilerError**](/en/reference/errors/unknown-compiler-error/)  
    Unknown compiler error.
-   [**ClientAddressNotAvailable**](/en/reference/errors/client-address-not-available/)  
    `Astro.clientAddress` is not available in current adapter.
-   [**PrerenderClientAddressNotAvailable**](/en/reference/errors/prerender-client-address-not-available/)  
    `Astro.clientAddress` cannot be used inside prerendered routes.
-   [**StaticClientAddressNotAvailable**](/en/reference/errors/static-client-address-not-available/)  
    `Astro.clientAddress` is not available in prerendered pages.
-   [**NoMatchingStaticPathFound**](/en/reference/errors/no-matching-static-path-found/)  
    No static path found for requested path.
-   [**OnlyResponseCanBeReturned**](/en/reference/errors/only-response-can-be-returned/)  
    Invalid type returned by Astro page.
-   [**MissingMediaQueryDirective**](/en/reference/errors/missing-media-query-directive/)  
    Missing value for `client:media` directive.
-   [**NoMatchingRenderer**](/en/reference/errors/no-matching-renderer/)  
    No matching renderer found.
-   [**NoClientEntrypoint**](/en/reference/errors/no-client-entrypoint/)  
    No client entrypoint specified in renderer.
-   [**NoClientOnlyHint**](/en/reference/errors/no-client-only-hint/)  
    Missing hint on `client:only` directive.
-   [**InvalidGetStaticPathParam**](/en/reference/errors/invalid-get-static-path-param/)  
    Invalid value returned by a route from `getStaticPaths()`.
-   [**InvalidGetStaticPathsEntry**](/en/reference/errors/invalid-get-static-paths-entry/)  
    Invalid entry inside `getStaticPaths()`'s return value.
-   [**InvalidGetStaticPathsReturn**](/en/reference/errors/invalid-get-static-paths-return/)  
    Invalid value returned by `getStaticPaths()`.
-   [**GetStaticPathsExpectedParams**](/en/reference/errors/get-static-paths-expected-params/)  
    Missing params property on `getStaticPaths()` route.
-   [**GetStaticPathsInvalidRouteParam**](/en/reference/errors/get-static-paths-invalid-route-param/)  
    Invalid route parameter returned by `getStaticPaths()`.
-   [**GetStaticPathsRequired**](/en/reference/errors/get-static-paths-required/)  
    `getStaticPaths()` function required for dynamic routes.
-   [**ReservedSlotName**](/en/reference/errors/reserved-slot-name/)  
    Invalid slot name.
-   [**NoAdapterInstalled**](/en/reference/errors/no-adapter-installed/)  
    Cannot use server-side rendering without an adapter.
-   [**AdapterSupportOutputMismatch**](/en/reference/errors/adapter-support-output-mismatch/)  
    Adapter does not support server output.
-   [**NoAdapterInstalledServerIslands**](/en/reference/errors/no-adapter-installed-server-islands/)  
    Cannot use server islands without an adapter.
-   [**NoMatchingImport**](/en/reference/errors/no-matching-import/)  
    No import found for component.
-   [**InvalidPrerenderExport**](/en/reference/errors/invalid-prerender-export/)  
    Invalid prerender export.
-   [**InvalidComponentArgs**](/en/reference/errors/invalid-component-args/)  
    Invalid component arguments.
-   [**PageNumberParamNotFound**](/en/reference/errors/page-number-param-not-found/)  
    Page number param not found.
-   [**ImageMissingAlt**](/en/reference/errors/image-missing-alt/)  
    Image missing required "alt" property.
-   [**InvalidImageService**](/en/reference/errors/invalid-image-service/)  
    Error while loading image service.
-   [**MissingImageDimension**](/en/reference/errors/missing-image-dimension/)  
    Missing image dimensions.
-   [**FailedToFetchRemoteImageDimensions**](/en/reference/errors/failed-to-fetch-remote-image-dimensions/)  
    Failed to retrieve remote image dimensions.
-   [**RemoteImageNotAllowed**](/en/reference/errors/remote-image-not-allowed/)  
    Remote image is not allowed.
-   [**UnsupportedImageFormat**](/en/reference/errors/unsupported-image-format/)  
    Unsupported image format.
-   [**UnsupportedImageConversion**](/en/reference/errors/unsupported-image-conversion/)  
    Unsupported image conversion.
-   [**CannotOptimizeSvg**](/en/reference/errors/cannot-optimize-svg/)  
    Cannot optimize SVG.
-   [**PrerenderDynamicEndpointPathCollide**](/en/reference/errors/prerender-dynamic-endpoint-path-collide/)  
    Prerendered dynamic endpoint has path collision.
-   [**PrerenderRouteConflict**](/en/reference/errors/prerender-route-conflict/)  
    Prerendered route generates the same path as another route.
-   [**ExpectedImage**](/en/reference/errors/expected-image/)  
    Expected src to be an image.
-   [**ExpectedImageOptions**](/en/reference/errors/expected-image-options/)  
    Expected image options.
-   [**ExpectedNotESMImage**](/en/reference/errors/expected-not-esmimage/)  
    Expected image options, not an ESM-imported image.
-   [**GetImageNotUsedOnServer**](/en/reference/errors/get-image-not-used-on-server/)  
    `getImage()` must be used on the server.
-   [**IncompatibleDescriptorOptions**](/en/reference/errors/incompatible-descriptor-options/)  
    Cannot set both `densities` and `widths`.
-   [**ImageNotFound**](/en/reference/errors/image-not-found/)  
    Image not found.
-   [**NoImageMetadata**](/en/reference/errors/no-image-metadata/)  
    Could not process image metadata.
-   [**CouldNotTransformImage**](/en/reference/errors/could-not-transform-image/)  
    Could not transform image.
-   [**ResponseSentError**](/en/reference/errors/response-sent-error/)  
    Unable to set response.
-   [**MiddlewareNoDataOrNextCalled**](/en/reference/errors/middleware-no-data-or-next-called/)  
    The middleware didn't return a `Response`.
-   [**MiddlewareNotAResponse**](/en/reference/errors/middleware-not-aresponse/)  
    The middleware returned something that is not a `Response` object.
-   [**EndpointDidNotReturnAResponse**](/en/reference/errors/endpoint-did-not-return-aresponse/)  
    The endpoint did not return a `Response`.
-   [**LocalsNotAnObject**](/en/reference/errors/locals-not-an-object/)  
    Value assigned to `locals` is not accepted.
-   [**LocalsReassigned**](/en/reference/errors/locals-reassigned/)  
    `locals` must not be reassigned.
-   [**AstroResponseHeadersReassigned**](/en/reference/errors/astro-response-headers-reassigned/)  
    `Astro.response.headers` must not be reassigned.
-   [**MiddlewareCantBeLoaded**](/en/reference/errors/middleware-cant-be-loaded/)  
    Can't load the middleware.
-   [**LocalImageUsedWrongly**](/en/reference/errors/local-image-used-wrongly/)  
    Local images must be imported.
-   [**AstroGlobUsedOutside**](/en/reference/errors/astro-glob-used-outside/)  
    Astro.glob() used outside of an Astro file.
-   [**AstroGlobNoMatch**](/en/reference/errors/astro-glob-no-match/)  
    Astro.glob() did not match any files.
-   [**RedirectWithNoLocation**](/en/reference/errors/redirect-with-no-location/)  
    A redirect must be given a location with the `Location` header.
-   [**UnsupportedExternalRedirect**](/en/reference/errors/unsupported-external-redirect/)  
    Unsupported or malformed URL.
-   [**InvalidRedirectDestination**](/en/reference/errors/invalid-redirect-destination/)  
    Invalid redirect destination.
-   [**InvalidDynamicRoute**](/en/reference/errors/invalid-dynamic-route/)  
    Invalid dynamic route.
-   [**MissingSharp**](/en/reference/errors/missing-sharp/)  
    Could not find Sharp.
-   [**UnknownViteError**](/en/reference/errors/unknown-vite-error/)  
    Unknown Vite error.
-   [**FailedToLoadModuleSSR**](/en/reference/errors/failed-to-load-module-ssr/)  
    Could not import file.
-   [**InvalidGlob**](/en/reference/errors/invalid-glob/)  
    Invalid glob pattern.
-   [**FailedToFindPageMapSSR**](/en/reference/errors/failed-to-find-page-map-ssr/)  
    Astro couldn't find the correct page to render.
-   [**MissingLocale**](/en/reference/errors/missing-locale/)  
    The provided locale does not exist.
-   [**MissingIndexForInternationalization**](/en/reference/errors/missing-index-for-internationalization/)  
    Index page not found.
-   [**IncorrectStrategyForI18n**](/en/reference/errors/incorrect-strategy-for-i18n/)  
    Function incompatible with the current strategy.
-   [**NoPrerenderedRoutesWithDomains**](/en/reference/errors/no-prerendered-routes-with-domains/)  
    Prerendered routes aren't supported when internationalization domains are enabled.
-   [**MissingMiddlewareForInternationalization**](/en/reference/errors/missing-middleware-for-internationalization/)  
    Enabled manual internationalization routing without having a middleware.
-   [**InvalidI18nMiddlewareConfiguration**](/en/reference/errors/invalid-i18n-middleware-configuration/)  
    Invalid internationalization middleware configuration.
-   [**CantRenderPage**](/en/reference/errors/cant-render-page/)  
    Astro can't render the route.
-   [**UnhandledRejection**](/en/reference/errors/unhandled-rejection/)  
    Unhandled rejection.
-   [**i18nNotEnabled**](/en/reference/errors/i18n-not-enabled/)  
    Internationalization routing is not enabled.
-   [**i18nNoLocaleFoundInPath**](/en/reference/errors/i18n-no-locale-found-in-path/)  
    The path doesn't contain any locale.
-   [**RouteNotFound**](/en/reference/errors/route-not-found/)  
    Route not found.
-   [**EnvInvalidVariables**](/en/reference/errors/env-invalid-variables/)  
    Invalid environment variables.
-   [**EnvPrefixConflictsWithSecret**](/en/reference/errors/env-prefix-conflicts-with-secret/)  
    `envPrefix` conflicts with secret environment variables.
-   [**ServerOnlyModule**](/en/reference/errors/server-only-module/)  
    Module is only available server-side.
-   [**RewriteWithBodyUsed**](/en/reference/errors/rewrite-with-body-used/)  
    Cannot use `Astro.rewrite()` after the request body has been read.
-   [**ForbiddenRewrite**](/en/reference/errors/forbidden-rewrite/)  
    Forbidden rewrite to a static route.
-   [**UnknownFilesystemError**](/en/reference/errors/unknown-filesystem-error/)  
    An unknown error occurred while reading or writing files to disk.
-   [**CannotExtractFontType**](/en/reference/errors/cannot-extract-font-type/)  
    Cannot extract the font type from the given URL.
-   [**CannotDetermineWeightAndStyleFromFontFile**](/en/reference/errors/cannot-determine-weight-and-style-from-font-file/)  
    Cannot determine weight and style from font file.
-   [**CannotFetchFontFile**](/en/reference/errors/cannot-fetch-font-file/)  
    Cannot fetch the given font file.
-   [**FontFamilyNotFound**](/en/reference/errors/font-family-not-found/)  
    Font family not found.
-   [**FontFileUrlNotFound**](/en/reference/errors/font-file-url-not-found/)  
    Font file URL not found.
-   [**MissingGetFontFileRequestUrl**](/en/reference/errors/missing-get-font-file-request-url/)  
    `experimental_getFontFileURL()` requires the request URL with on-demand rendering.
-   [**UnavailableAstroGlobal**](/en/reference/errors/unavailable-astro-global/)  
    Unavailable Astro global in `getStaticPaths()`.
-   [**UnableToLoadLogger**](/en/reference/errors/unable-to-load-logger/)  
    Unable to load the logger.
-   [**LoggerConfigurationNotSerializable**](/en/reference/errors/logger-configuration-not-serializable/)  
    The configuration of the logger is not serializable.

## CSS Errors

-   [**UnknownCSSError**](/en/reference/errors/unknown-csserror/)  
    Unknown CSS error.
-   [**CSSSyntaxError**](/en/reference/errors/csssyntax-error/)  
    CSS syntax error.

## Markdown Errors

-   [**UnknownMarkdownError**](/en/reference/errors/unknown-markdown-error/)  
    Unknown Markdown error.
-   [**MarkdownFrontmatterParseError**](/en/reference/errors/markdown-frontmatter-parse-error/)  
    Failed to parse Markdown frontmatter.
-   [**InvalidFrontmatterInjectionError**](/en/reference/errors/invalid-frontmatter-injection-error/)  
    Invalid frontmatter injection.
-   [**MdxIntegrationMissingError**](/en/reference/errors/mdx-integration-missing-error/)  
    MDX integration missing.
-   [**UnknownConfigError**](/en/reference/errors/unknown-config-error/)  
    Unknown configuration error.
-   [**ConfigNotFound**](/en/reference/errors/config-not-found/)  
    Specified configuration file not found.
-   [**ConfigLegacyKey**](/en/reference/errors/config-legacy-key/)  
    Legacy configuration detected.

## CLI Errors

-   [**UnknownCLIError**](/en/reference/errors/unknown-clierror/)  
    Unknown CLI error.
-   [**GenerateContentTypesError**](/en/reference/errors/generate-content-types-error/)  
    Failed to generate content types.

## Content Collection Errors

-   [**UnknownContentCollectionError**](/en/reference/errors/unknown-content-collection-error/)  
    Unknown content collection error.
-   [**RenderUndefinedEntryError**](/en/reference/errors/render-undefined-entry-error/)  
    Attempted to render an undefined content collection entry.
-   [**GetEntryDeprecationError**](/en/reference/errors/get-entry-deprecation-error/)  
    Invalid use of `getDataEntryById` or `getEntryBySlug` function.
-   [**InvalidContentEntryFrontmatterError**](/en/reference/errors/invalid-content-entry-frontmatter-error/)  
    Content entry frontmatter does not match schema.
-   [**InvalidContentEntryDataError**](/en/reference/errors/invalid-content-entry-data-error/)  
    Content entry data does not match schema.
-   [**LegacyContentConfigError**](/en/reference/errors/legacy-content-config-error/)  
    Legacy content config file found.
-   [**ContentCollectionMissingLoader**](/en/reference/errors/content-collection-missing-loader/)  
    Content collection is missing a `loader` definition.
-   [**ContentCollectionInvalidType**](/en/reference/errors/content-collection-invalid-type/)  
    Content collection has an invalid `type` field.
-   [**ContentLoaderReturnsInvalidId**](/en/reference/errors/content-loader-returns-invalid-id/)  
    Content loader returned an entry with an invalid `id`.
-   [**ContentEntryDataError**](/en/reference/errors/content-entry-data-error/)  
    Content entry data does not match schema.
-   [**LiveContentConfigError**](/en/reference/errors/live-content-config-error/)  
    Error in live content config.
-   [**ContentLoaderInvalidDataError**](/en/reference/errors/content-loader-invalid-data-error/)  
    Content entry is missing an ID.
-   [**InvalidContentEntrySlugError**](/en/reference/errors/invalid-content-entry-slug-error/)  
    Invalid content entry slug.
-   [**ContentSchemaContainsSlugError**](/en/reference/errors/content-schema-contains-slug-error/)  
    Content schema should not contain `slug`.
-   [**MixedContentDataCollectionError**](/en/reference/errors/mixed-content-data-collection-error/)  
    Content and data cannot be in same collection.
-   [**ContentCollectionTypeMismatchError**](/en/reference/errors/content-collection-type-mismatch-error/)  
    Collection contains entries of a different type.
-   [**DataCollectionEntryParseError**](/en/reference/errors/data-collection-entry-parse-error/)  
    Data collection entry failed to parse.
-   [**DuplicateContentEntrySlugError**](/en/reference/errors/duplicate-content-entry-slug-error/)  
    Duplicate content entry slug.
-   [**UnsupportedConfigTransformError**](/en/reference/errors/unsupported-config-transform-error/)  
    Unsupported transform in content config.
-   [**FileParserNotFound**](/en/reference/errors/file-parser-not-found/)  
    File parser not found.
-   [**FileGlobNotSupported**](/en/reference/errors/file-glob-not-supported/)  
    Glob patterns are not supported in the file loader.

## Action Errors

-   [**ActionsWithoutServerOutputError**](/en/reference/errors/actions-without-server-output-error/)  
    Actions must be used with server output.
-   [**ActionsReturnedInvalidDataError**](/en/reference/errors/actions-returned-invalid-data-error/)  
    Action handler returned invalid data.
-   [**ActionNotFoundError**](/en/reference/errors/action-not-found-error/)  
    Action not found.
-   [**ActionCalledFromServerError**](/en/reference/errors/action-called-from-server-error/)  
    Action called from the server without `Astro.callAction()`.
-   [**ActionsCantBeLoaded**](/en/reference/errors/actions-cant-be-loaded/)  
    Can't load the Astro actions.

## Session Errors

-   [**SessionStorageInitError**](/en/reference/errors/session-storage-init-error/)  
    Session storage could not be initialized.
-   [**SessionStorageSaveError**](/en/reference/errors/session-storage-save-error/)  
    Session data could not be saved.

## Cache Errors

-   [**CacheProviderNotFound**](/en/reference/errors/cache-provider-not-found/)  
    Cache provider not found.
-   [**CacheNotEnabled**](/en/reference/errors/cache-not-enabled/)  
    Cache is not enabled.
-   [**CacheQueryConfigConflict**](/en/reference/errors/cache-query-config-conflict/)  
    Conflicting cache query configuration.

## [Action called from the server without Astro.callAction().](https://docharvest.github.io/docs/astro/reference/errors/action-called-from-server-error/)

Contents

astro

Action called from the server without Astro.callAction().

Astro

Action called from the server without Astro.callAction().

import DontEditWarning from '~/components/DontEditWarning.astro'

> **ActionCalledFromServerError**: Action called from a server-rendered page or endpoint without using `Astro.callAction()`. This wrapper must be used to call actions from server code.

## What went wrong?

Action called from a server page or endpoint without using `Astro.callAction()`.

**See Also:**

-   [`Astro.callAction()` reference](/en/reference/api-reference/#callaction)

## [Action not found.](https://docharvest.github.io/docs/astro/reference/errors/action-not-found-error/)

Contents

astro

Action not found.

Astro

Action not found.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **ActionNotFoundError**: The server received a request for an action named `ACTION_NAME` but could not find a match. If you renamed an action, check that you've updated your `actions/index` file and your calling code to match.

## What went wrong?

The server received a request for an action but could not find a match with the same name.

## [An invalid Action query string was passed by a form.](https://docharvest.github.io/docs/astro/reference/errors/action-query-string-invalid-error/)

Contents

astro

An invalid Action query string was passed by a form.

Astro

An invalid Action query string was passed by a form.

import DontEditWarning from '~/components/DontEditWarning.astro'

:::caution\[Deprecated\] This error is from an older version of Astro and is no longer in use. If you are unable to upgrade your project to a more recent version, then you can consult [unmaintained snapshots of older documentation](/en/upgrade-astro/#older-docs-unmaintained) for assistance. :::

> **ActionQueryStringInvalidError**: The server received the query string `?_astroAction=ACTION_NAME`, but could not find an action with that name. If you changed an action's name in development, remove this query param from your URL and refresh.

## What went wrong?

The server received the query string `?_astroAction=name`, but could not find an action with that name. Use the action function's `.queryString` property to retrieve the form `action` URL.

**See Also:**

-   [Actions RFC](https://github.com/withastro/roadmap/blob/actions/proposals/0046-actions.md)

## [Can't load the Astro actions.](https://docharvest.github.io/docs/astro/reference/errors/actions-cant-be-loaded/)

Contents

astro

Can't load the Astro actions.

Astro

Can't load the Astro actions.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **ActionsCantBeLoaded**: An unknown error was thrown while loading the Astro actions file.

## What went wrong?

Thrown in development mode when the actions file can't be loaded.

## [Action handler returned invalid data.](https://docharvest.github.io/docs/astro/reference/errors/actions-returned-invalid-data-error/)

Contents

astro

Action handler returned invalid data.

Astro

Action handler returned invalid data.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **ActionsReturnedInvalidDataError**: Action handler returned invalid data. Handlers should return serializable data types like objects, arrays, strings, and numbers. Parse error: ERROR

## What went wrong?

Action handler returned invalid data. Handlers should return serializable data types, and cannot return a Response object.

**See Also:**

-   [Actions handler reference](/en/reference/modules/astro-actions/#handler-property)

## [An invalid Action query string was passed by a form.](https://docharvest.github.io/docs/astro/reference/errors/actions-used-with-for-get-error/)

Contents

astro

An invalid Action query string was passed by a form.

Astro

An invalid Action query string was passed by a form.

import DontEditWarning from '~/components/DontEditWarning.astro'

:::caution\[Deprecated\] Deprecated since version 4.13.2. :::

> **ActionsUsedWithForGetError**: Action ACTION\_NAME was called from a form using a GET request, but only POST requests are supported. This often occurs if `method="POST"` is missing on the form.

## What went wrong?

Action was called from a form using a GET request, but only POST requests are supported. This often occurs if `method="POST"` is missing on the form.

**See Also:**

-   [Actions RFC](https://github.com/withastro/roadmap/blob/actions/proposals/0046-actions.md)

## [Actions must be used with server output.](https://docharvest.github.io/docs/astro/reference/errors/actions-without-server-output-error/)

Contents

astro

Actions must be used with server output.

Astro

Actions must be used with server output.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **ActionsWithoutServerOutputError**: A server is required to create callable backend functions. To deploy routes to a server, add an adapter to your Astro config and configure your route for on-demand rendering.

## What went wrong?

Your project must have a server output to create backend functions with Actions.

**See Also:**

-   [On-demand rendering](/en/guides/on-demand-rendering/)

## [Adapter does not support server output.](https://docharvest.github.io/docs/astro/reference/errors/adapter-support-output-mismatch/)

Contents

astro

Adapter does not support server output.

Astro

Adapter does not support server output.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **AdapterSupportOutputMismatch**: The `ADAPTER_NAME` adapter is configured to output a static website, but the project contains server-rendered pages. Please install and configure the appropriate server adapter for your final deployment.

## What went wrong?

The currently configured adapter does not support server-side rendering, which is required for the current project setup.

Depending on your adapter, there may be a different entrypoint to use for server-side rendering. For example, the `@astrojs/vercel` adapter has a `@astrojs/vercel/static` entrypoint for static rendering, and a `@astrojs/vercel/serverless` entrypoint for server-side rendering.

**See Also:**

-   [Server-side rendering](/en/guides/on-demand-rendering/)

## [Astro.glob() did not match any files.](https://docharvest.github.io/docs/astro/reference/errors/astro-glob-no-match/)

Contents

astro

Astro.glob() did not match any files.

Astro

Astro.glob() did not match any files.

import DontEditWarning from '~/components/DontEditWarning.astro'

:::caution\[Deprecated\] This error was removed in Astro v6.0.0 along with the removal of `Astro.glob()`. :::

> **AstroGlobNoMatch**: `Astro.glob(GLOB_STR)` did not return any matching files.

## What went wrong?

`Astro.glob()` did not return any matching files. There might be a typo in the glob pattern.

## [Astro.glob() used outside of an Astro file.](https://docharvest.github.io/docs/astro/reference/errors/astro-glob-used-outside/)

Contents

astro

Astro.glob() used outside of an Astro file.

Astro

Astro.glob() used outside of an Astro file.

import DontEditWarning from '~/components/DontEditWarning.astro'

:::caution\[Deprecated\] This error was removed in Astro v6.0.0 along with the removal of `Astro.glob()`. :::

> **AstroGlobUsedOutside**: `Astro.glob(GLOB_STR)` can only be used in `.astro` files. `import.meta.glob(GLOB_STR)` can be used instead to achieve a similar result.

## What went wrong?

`Astro.glob()` can only be used in `.astro` files. You can use [`import.meta.glob()`](https://vite.dev/guide/features.html#glob-import) instead to achieve the same result.

## [Astro.response.headers must not be reassigned.](https://docharvest.github.io/docs/astro/reference/errors/astro-response-headers-reassigned/)

Contents

astro

Astro.response.headers must not be reassigned.

Astro

Astro.response.headers must not be reassigned.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **AstroResponseHeadersReassigned**: Individual headers can be added to and removed from `Astro.response.headers`, but it must not be replaced with another instance of `Headers` altogether.

## What went wrong?

Thrown when a value is being set as the `headers` field on the `ResponseInit` object available as `Astro.response`.

## [Cache is not enabled.](https://docharvest.github.io/docs/astro/reference/errors/cache-not-enabled/)

Contents

astro

Cache is not enabled.

Astro

Cache is not enabled.

import DontEditWarning from '~/components/DontEditWarning.astro'

> `Astro.cache` is not available because the cache feature is not enabled.

## What went wrong?

Thrown when `Astro.cache` or `context.cache` is used but the cache feature has not been enabled in the Astro config.

## [Cache provider not found.](https://docharvest.github.io/docs/astro/reference/errors/cache-provider-not-found/)

Contents

astro

Cache provider not found.

Astro

Cache provider not found.

import DontEditWarning from '~/components/DontEditWarning.astro'

> Could not resolve the cache provider `PROVIDER`. Make sure the package is installed.

## What went wrong?

Thrown when the configured cache provider cannot be resolved. This usually means the package is not installed or the import path is wrong.

## [Conflicting cache query configuration.](https://docharvest.github.io/docs/astro/reference/errors/cache-query-config-conflict/)

Contents

astro

Conflicting cache query configuration.

Astro

Conflicting cache query configuration.

import DontEditWarning from '~/components/DontEditWarning.astro'

> `query.include` and `query.exclude` cannot be used together.

## What went wrong?

The memory cache provider's `query.include` and `query.exclude` options are mutually exclusive. Use `include` to allowlist specific query parameters that affect the cache key, or `exclude` to blocklist parameters. When `include` is set, all other parameters are automatically ignored.

## [Cannot determine weight and style from font file.](https://docharvest.github.io/docs/astro/reference/errors/cannot-determine-weight-and-style-from-font-file/)

Contents

astro

Cannot determine weight and style from font file.

Astro

Cannot determine weight and style from font file.

import DontEditWarning from '~/components/DontEditWarning.astro'

> An error occurred while determining the weight and style from the local font file.

## What went wrong?

Cannot determine weight and style from font file, update your family config and set `weight` and `style` manually instead.

## [Cannot extract the font type from the given URL.](https://docharvest.github.io/docs/astro/reference/errors/cannot-extract-font-type/)

Contents

astro

Cannot extract the font type from the given URL.

Astro

Cannot extract the font type from the given URL.

import DontEditWarning from '~/components/DontEditWarning.astro'

> An error occurred while trying to extract the font type from the given URL.

## What went wrong?

Cannot extract the font type from the given URL.

## [Cannot fetch the given font file.](https://docharvest.github.io/docs/astro/reference/errors/cannot-fetch-font-file/)

Contents

astro

Cannot fetch the given font file.

Astro

Cannot fetch the given font file.

import DontEditWarning from '~/components/DontEditWarning.astro'

> An error occurred while fetching font file from the given URL.

## What went wrong?

Cannot fetch the given font file.

## [Cannot optimize SVG.](https://docharvest.github.io/docs/astro/reference/errors/cannot-optimize-svg/)

Contents

astro

Cannot optimize SVG.

Astro

Cannot optimize SVG.

import DontEditWarning from '~/components/DontEditWarning.astro'

> An error occurred while optimizing the SVG file with the optimizer.

## [Astro can't render the route.](https://docharvest.github.io/docs/astro/reference/errors/cant-render-page/)

Contents

astro

Astro can't render the route.

Astro

Astro can't render the route.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **CantRenderPage**: Astro cannot find any content to render for this route. There is no file or redirect associated with this route.

## What went wrong?

Astro could not find an associated file with content while trying to render the route. This is an Astro error and not a user error. If restarting the dev server does not fix the problem, please file an issue.

## [Cannot use the astro:config module without enabling the experimental feature.](https://docharvest.github.io/docs/astro/reference/errors/cant-use-astro-config-module-error/)

Contents

astro

Cannot use the astro:config module without enabling the experimental feature.

Astro

Cannot use the astro:config module without enabling the experimental feature.

import DontEditWarning from '~/components/DontEditWarning.astro'

:::caution\[Deprecated\] This error is from an older version of Astro and is no longer in use. If you are unable to upgrade your project to a more recent version, then you can consult [unmaintained snapshots of older documentation](/en/upgrade-astro/#older-docs-unmaintained) for assistance. :::

> **CantUseAstroConfigModuleError**: Cannot import the module "MODULE\_NAME" because the experimental feature is disabled. Enable `experimental.serializeConfig` in your `astro.config.mjs`

## What went wrong?

Cannot use the module `astro:config` without enabling the experimental feature.

## [Astro.clientAddress is not available in current adapter.](https://docharvest.github.io/docs/astro/reference/errors/client-address-not-available/)

Contents

astro

Astro.clientAddress is not available in current adapter.

Astro

Astro.clientAddress is not available in current adapter.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **ClientAddressNotAvailable**: `Astro.clientAddress` is not available in the `ADAPTER_NAME` adapter. File an issue with the adapter to add support.

## What went wrong?

The adapter you're using unfortunately does not support `Astro.clientAddress`.

**See Also:**

-   [Official integrations](/en/guides/integrations/#official-integrations)
-   [`Astro.clientAddress`](/en/reference/api-reference/#clientaddress)

## [Collection does not exist](https://docharvest.github.io/docs/astro/reference/errors/collection-does-not-exist-error/)

Contents

astro

Collection does not exist

Astro

Collection does not exist

import DontEditWarning from '~/components/DontEditWarning.astro'

:::caution\[Deprecated\] Collections that do not exist no longer result in an error. A warning is given instead. :::

> A collection queried via `getCollection()` does not exist.

## What went wrong?

When querying a collection, ensure a collection directory with the requested name exists under `src/content/`.

## [Legacy configuration detected.](https://docharvest.github.io/docs/astro/reference/errors/config-legacy-key/)

Contents

astro

Legacy configuration detected.

Astro

Legacy configuration detected.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **ConfigLegacyKey**: Legacy configuration detected: `LEGACY_CONFIG_KEY`.

## What went wrong?

Astro detected a legacy configuration option in your configuration file.

**See Also:**

-   [Configuration reference](/en/reference/configuration-reference/)

## [Specified configuration file not found.](https://docharvest.github.io/docs/astro/reference/errors/config-not-found/)

Contents

astro

Specified configuration file not found.

Astro

Specified configuration file not found.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **ConfigNotFound**: Unable to resolve `--config "CONFIG_FILE"`. Does the file exist?

## What went wrong?

The specified configuration file using `--config` could not be found. Make sure that it exists or that the path is correct.

**See Also:**

-   [\--config](/en/reference/cli-reference/#--config-path)

## [Content collection has an invalid type field.](https://docharvest.github.io/docs/astro/reference/errors/content-collection-invalid-type/)

Contents

astro

Content collection has an invalid type field.

Astro

Content collection has an invalid type field.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **Example error message:**  
> Invalid collection type "data". Remove the type from your collection definition in your content config file.

## What went wrong?

Content collections should no longer have a `type` field. Remove this field from your content config file. See the [Astro 6 migration guide](/en/guides/upgrade-to/v6/#removed-legacy-content-collections) for more information.

## [Content collection is missing a loader definition.](https://docharvest.github.io/docs/astro/reference/errors/content-collection-missing-loader/)

Contents

astro

Content collection is missing a loader definition.

Astro

Content collection is missing a loader definition.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **Example error message:**  
> Collections must have a `loader` defined. Check your collection definitions in your content config file.  

## What went wrong?

A content collection is missing a `loader` definition. Make sure that each collection in your content config file has a `loader`. See the [Content collections documentation](/en/guides/content-collections/) for more information.

## [Collection contains entries of a different type.](https://docharvest.github.io/docs/astro/reference/errors/content-collection-type-mismatch-error/)

Contents

astro

Collection contains entries of a different type.

Astro

Collection contains entries of a different type.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **ContentCollectionTypeMismatchError**: COLLECTION contains EXPECTED\_TYPE entries, but is configured as a ACTUAL\_TYPE collection.

## What went wrong?

Legacy content collections must contain entries of the type configured. Collections are `type: 'content'` by default. Try adding `type: 'data'` to your collection config for data collections.

**See Also:**

-   [Legacy content collections](/en/guides/upgrade-to/v5/#updating-existing-collections)

## [Content entry data does not match schema.](https://docharvest.github.io/docs/astro/reference/errors/content-entry-data-error/)

Contents

astro

Content entry data does not match schema.

Astro

Content entry data does not match schema.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **Example error message:**  
> **blog** → **post** data does not match collection schema.  
> "title" is required.  
> "date" must be a valid date.

## What went wrong?

A content entry does not match its collection schema. Make sure that all required fields are present, and that all fields are of the correct type. You can check against the collection schema in your `src/content.config.*` file. See the [Content collections documentation](/en/guides/content-collections/) for more information.

## [Content entry is missing an ID.](https://docharvest.github.io/docs/astro/reference/errors/content-loader-invalid-data-error/)

Contents

astro

Content entry is missing an ID.

Astro

Content entry is missing an ID.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **Example error message:**  
> The loader for **blog** returned invalid data.  
> Object is missing required property "id".

## What went wrong?

The loader for a content collection returned invalid data. Inline loaders must return an array of objects with unique ID fields or a plain object with IDs as keys and entries as values.

## [Content loader returned an entry with an invalid id.](https://docharvest.github.io/docs/astro/reference/errors/content-loader-returns-invalid-id/)

Contents

astro

Content loader returned an entry with an invalid id.

Astro

Content loader returned an entry with an invalid id.

## What went wrong?

A content loader returned an invalid `id`. Make sure that the `id` of the entry is a string. See the [Content collections documentation](/en/guides/content-collections/) for more information.

## [Content schema should not contain slug.](https://docharvest.github.io/docs/astro/reference/errors/content-schema-contains-slug-error/)

Contents

astro

Content schema should not contain slug.

Astro

Content schema should not contain slug.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **ContentSchemaContainsSlugError**: A content collection schema should not contain `slug` since it is reserved for slug generation. Remove this from your COLLECTION\_NAME collection schema.

## What went wrong?

A legacy content collection schema should not contain the `slug` field. This is reserved by Astro for generating entry slugs. Remove `slug` from your schema. You can still use custom slugs in your frontmatter.

**See Also:**

-   [Legacy content collections](/en/guides/upgrade-to/v5/#updating-existing-collections)

## [Could not transform image.](https://docharvest.github.io/docs/astro/reference/errors/could-not-transform-image/)

Contents

astro

Could not transform image.

Astro

Could not transform image.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **CouldNotTransformImage**: Could not transform image `IMAGE_PATH`. See the stack trace for more information.

## What went wrong?

Astro could not transform one of your images. Often, this is caused by a corrupted or malformed image. Re-exporting the image from your image editor may fix this issue.

Depending on the image service you are using, the stack trace may contain more information on the specific error encountered.

**See Also:**

-   [Images](/en/guides/images/)

## [CSP feature isn't enabled](https://docharvest.github.io/docs/astro/reference/errors/csp-not-enabled/)

Contents

astro

CSP feature isn't enabled

Astro

CSP feature isn't enabled

import DontEditWarning from '~/components/DontEditWarning.astro'

:::caution\[Deprecated\] This error is from an older version of Astro and is no longer in use. If you are unable to upgrade your project to a more recent version, then you can consult [unmaintained snapshots of older documentation](/en/upgrade-astro/#older-docs-unmaintained) for assistance. :::

> The `security.csp` configuration isn't enabled.

## What went wrong?

The CSP feature isn't enabled

## [CSS syntax error.](https://docharvest.github.io/docs/astro/reference/errors/csssyntax-error/)

Contents

astro

CSS syntax error.

Astro

CSS syntax error.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **Example error messages:**  
> CSSSyntaxError: Missed semicolon  
> CSSSyntaxError: Unclosed string  

## What went wrong?

Astro encountered an error while parsing your CSS, due to a syntax error. This is often caused by a missing semicolon.

## [Data collection entry failed to parse.](https://docharvest.github.io/docs/astro/reference/errors/data-collection-entry-parse-error/)

Contents

astro

Data collection entry failed to parse.

Astro

Data collection entry failed to parse.

import DontEditWarning from '~/components/DontEditWarning.astro'

> `COLLECTION_ENTRY_NAME` failed to parse.

## What went wrong?

Collection entries of `type: 'data'` must return an object with valid JSON (for `.json` entries), YAML (for `.yaml` entries) or TOML (for `.toml` entries).

## [Duplicate content entry slug.](https://docharvest.github.io/docs/astro/reference/errors/duplicate-content-entry-slug-error/)

Contents

astro

Duplicate content entry slug.

Astro

Duplicate content entry slug.

import DontEditWarning from '~/components/DontEditWarning.astro'

> `COLLECTION_NAME` contains multiple entries with the same slug: `SLUG`. Slugs must be unique.

## What went wrong?

Content collection entries must have unique slugs. Duplicates are often caused by the `slug` frontmatter property.

## [The endpoint did not return a Response.](https://docharvest.github.io/docs/astro/reference/errors/endpoint-did-not-return-aresponse/)



## [Invalid Environment Variable](https://docharvest.github.io/docs/astro/reference/errors/env-invalid-variable/)

Contents

astro

Invalid Environment Variable

Astro

Invalid Environment Variable

import DontEditWarning from '~/components/DontEditWarning.astro'

:::caution\[Deprecated\] This error is from an older version of Astro and is no longer in use. If you are unable to upgrade your project to a more recent version, then you can consult [unmaintained snapshots of older documentation](/en/upgrade-astro/#older-docs-unmaintained) for assistance. :::

> **EnvInvalidVariable**: The following environment variable does not match the data type and/or properties defined in `experimental.env.schema`: KEY is not of type TYPE

## What went wrong?

An environment variable does not match the data type and/or properties defined in `experimental.env.schema`.

## [Invalid environment variables.](https://docharvest.github.io/docs/astro/reference/errors/env-invalid-variables/)

Contents

astro

Invalid environment variables.

Astro

Invalid environment variables.

import DontEditWarning from '~/components/DontEditWarning.astro'

> The following environment variables defined in `env.schema` are invalid.

## What went wrong?

Some environment variables do not match the data type and/or properties defined in `env.schema`.

## [envPrefix conflicts with secret environment variables.](https://docharvest.github.io/docs/astro/reference/errors/env-prefix-conflicts-with-secret/)

Contents

astro

envPrefix conflicts with secret environment variables.

Astro

envPrefix conflicts with secret environment variables.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **EnvPrefixConflictsWithSecret**: The following environment variables are declared with `access: "secret"` in `env.schema`, but their names match a prefix in `vite.envPrefix`, which would expose them in client-side bundles:  
>   
> CONFLICTS.MAP((C) =\\ >`- ${C`).join('  
> ')}  
>   
> Either remove the conflicting prefixes from `vite.envPrefix`, or rename these variables to use a prefix not in `vite.envPrefix`.

## What went wrong?

The configured `vite.envPrefix` includes prefixes that match environment variables declared with `access: "secret"` in `env.schema`. This would cause Vite to expose those secret values in client-side JavaScript bundles, bypassing the `access: "secret"` protection.

To fix this, either:

-   Remove the conflicting prefixes from `vite.envPrefix`, or
-   Rename your secret environment variables to use a prefix that is not in `vite.envPrefix`.

## [Unsupported astro:env getSecret](https://docharvest.github.io/docs/astro/reference/errors/env-unsupported-get-secret/)

Contents

astro

Unsupported astro:env getSecret

Astro

Unsupported astro:env getSecret

import DontEditWarning from '~/components/DontEditWarning.astro'

:::caution\[Deprecated\] This error is from an older version of Astro and is no longer in use. If you are unable to upgrade your project to a more recent version, then you can consult [unmaintained snapshots of older documentation](/en/upgrade-astro/#older-docs-unmaintained) for assistance. :::

> **EnvUnsupportedGetSecret**: `astro:env/server` exported function `getSecret` is not supported by your adapter.

## What went wrong?

The `astro:env/server` exported function `getSecret()` is not supported by your adapter.

## [Expected src to be an image.](https://docharvest.github.io/docs/astro/reference/errors/expected-image/)

Contents

astro

Expected src to be an image.

Astro

Expected src to be an image.

* * *

![...]({myImage}) ![...](https://example.com/logo.png) \`\`\`

In most cases, this error happens when the value passed to `src` is undefined.

**See Also:**

-   [Images](/en/guides/images/)

## [Expected image options.](https://docharvest.github.io/docs/astro/reference/errors/expected-image-options/)

Contents

astro

Expected image options.

Astro

Expected image options.

const optimizedImage = await getImage({src: myImage, width: 300, height: 300});

```

In most cases, this error happens because parameters were passed directly instead of inside an object.

**See Also:**
-  [Images](/en/guides/images/)
```

## [Expected image options, not an ESM-imported image.](https://docharvest.github.io/docs/astro/reference/errors/expected-not-esmimage/)

Contents

astro

Expected image options, not an ESM-imported image.

Astro

Expected image options, not an ESM-imported image.

-   const optimizedImage = await getImage( myImage );

-   const optimizedImage = await getImage({ src: myImage });

```

**See Also:**
-  [Images](/en/guides/images/)
```

## [Failed to retrieve remote image dimensions.](https://docharvest.github.io/docs/astro/reference/errors/failed-to-fetch-remote-image-dimensions/)

Contents

astro

Failed to retrieve remote image dimensions.

Astro

Failed to retrieve remote image dimensions.

import DontEditWarning from '~/components/DontEditWarning.astro'

> Failed to get the dimensions for `IMAGE_URL`.

## What went wrong?

Determining the remote image's dimensions failed. This is typically caused by an incorrect URL or attempting to infer the size of an image in the public folder which is not possible.

## [Astro couldn't find the correct page to render.](https://docharvest.github.io/docs/astro/reference/errors/failed-to-find-page-map-ssr/)

Contents

astro

Astro couldn't find the correct page to render.

Astro

Astro couldn't find the correct page to render.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **FailedToFindPageMapSSR**: Astro couldn't find the correct page to render, probably because it wasn't correctly mapped for SSR usage. This is an internal error. Please file an issue.

## What went wrong?

Astro couldn't find the correct page to render, probably because it wasn't correctly mapped for SSR usage. This is an internal error.

## [Could not import file.](https://docharvest.github.io/docs/astro/reference/errors/failed-to-load-module-ssr/)

Contents

astro

Could not import file.

Astro

Could not import file.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **FailedToLoadModuleSSR**: Could not import `IMPORT_NAME`.

## What went wrong?

Astro could not import the requested file. Oftentimes, this is caused by the import path being wrong (either because the file does not exist, or there is a typo in the path)

This message can also appear when a type is imported without specifying that it is a [type import](/en/guides/typescript/#type-imports).

**See Also:**

-   [Type Imports](/en/guides/typescript/#type-imports)

## [Glob patterns are not supported in the file loader.](https://docharvest.github.io/docs/astro/reference/errors/file-glob-not-supported/)

Contents

astro

Glob patterns are not supported in the file loader.

Astro

Glob patterns are not supported in the file loader.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **FileGlobNotSupported**: Glob patterns are not supported in the `file` loader. Use the `glob` loader instead.

## What went wrong?

The `file` loader must be passed a single local file. Glob patterns are not supported. Use the built-in `glob` loader to create entries from patterns of multiple local files.

**See Also:**

-   [Astro's built-in `file()` loader](/en/reference/content-loader-reference/#file-loader)

## [File parser not found.](https://docharvest.github.io/docs/astro/reference/errors/file-parser-not-found/)

Contents

astro

File parser not found.

Astro

File parser not found.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **FileParserNotFound**: No parser was found for 'FILE\_NAME'. Pass a parser function (e.g. `parser: csv`) to the `file` loader.

## What went wrong?

The `file` loader can’t determine which parser to use. Please provide a custom parser (e.g. `csv-parse`) to create a collection from your file type.

**See Also:**

-   [Passing a `parser` to the `file` loader](/en/reference/content-loader-reference/#parser)

## [Font family not found.](https://docharvest.github.io/docs/astro/reference/errors/font-family-not-found/)

Contents

astro

Font family not found.

Astro

Font family not found.

import DontEditWarning from '~/components/DontEditWarning.astro'

> No data was found for the `cssVariable` passed to the `<Font />` component.

## What went wrong?

Font family not found.

## [Font file URL not found.](https://docharvest.github.io/docs/astro/reference/errors/font-file-url-not-found/)

Contents

astro

Font file URL not found.

Astro

Font file URL not found.

import DontEditWarning from '~/components/DontEditWarning.astro'

> The URL passed to the `experimental_getFontFileURL()` function is invalid.

## What went wrong?

Font file URL not found.

## [Forbidden rewrite to a static route.](https://docharvest.github.io/docs/astro/reference/errors/forbidden-rewrite/)

Contents

astro

Forbidden rewrite to a static route.

Astro

Forbidden rewrite to a static route.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **ForbiddenRewrite**: You tried to rewrite the on-demand route 'FROM' with the static route 'TO', when using the 'server' output.  
>   
> The static route 'TO' is rendered by the component 'COMPONENT', which is marked as prerendered. This is a forbidden operation because during the build, the component 'COMPONENT' is compiled to an HTML file, which can't be retrieved at runtime by Astro.

## What went wrong?

`Astro.rewrite()` can't be used to rewrite an on-demand route with a static route when using the `"server"` output.

## [Failed to generate content types.](https://docharvest.github.io/docs/astro/reference/errors/generate-content-types-error/)

Contents

astro

Failed to generate content types.

Astro

Failed to generate content types.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **GenerateContentTypesError**: `astro sync` command failed to generate content collection types: ERROR\_MESSAGE.

## What went wrong?

`astro sync` command failed to generate content collection types.

**See Also:**

-   [Content collections documentation](/en/guides/content-collections/)

## [Invalid use of getDataEntryById or getEntryBySlug function.](https://docharvest.github.io/docs/astro/reference/errors/get-entry-deprecation-error/)

Contents

astro

Invalid use of getDataEntryById or getEntryBySlug function.

Astro

Invalid use of getDataEntryById or getEntryBySlug function.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **GetEntryDeprecationError**: The `METHOD` function is deprecated and cannot be used to query the "COLLECTION" collection. Use `getEntry` instead.

## What went wrong?

The `getDataEntryById` and `getEntryBySlug` functions are deprecated and cannot be used with content collections. Use the `getEntry` function instead.

## [getImage() must be used on the server.](https://docharvest.github.io/docs/astro/reference/errors/get-image-not-used-on-server/)

Contents

astro

getImage() must be used on the server.

Astro

getImage() must be used on the server.

## const optimizedImage = await getImage({ src: myImage, width: 300 });

```

**See Also:**
-  [Images](/en/guides/images/)
-  [`getImage()`](/en/reference/modules/astro-assets/#getimage)
```

## [Missing params property on getStaticPaths() route.](https://docharvest.github.io/docs/astro/reference/errors/get-static-paths-expected-params/)

Contents

astro

Missing params property on getStaticPaths() route.

Astro

Missing params property on getStaticPaths() route.

## }

```
Will create the following route: `site.com/blog/1`.

**See Also:**
-  [`getStaticPaths()`](/en/reference/routing-reference/#getstaticpaths)
-  [`params`](/en/reference/api-reference/#params)
```

## [Invalid route parameter returned by getStaticPaths().](https://docharvest.github.io/docs/astro/reference/errors/get-static-paths-invalid-route-param/)

Contents

astro

Invalid route parameter returned by getStaticPaths().

Astro

Invalid route parameter returned by getStaticPaths().

## }

````

In routes using [rest parameters](/en/guides/routing/#rest-parameters), `undefined` can be used to represent a path with no parameters passed in the URL:

```astro title="/route/[...id].astro"
---

}
---
````

**See Also:**

-   [`getStaticPaths()`](/en/reference/routing-reference/#getstaticpaths)
-   [`params`](/en/reference/api-reference/#params)

## [getStaticPaths RSS helper is not available anymore.](https://docharvest.github.io/docs/astro/reference/errors/get-static-paths-removed-rsshelper/)

Contents

astro

getStaticPaths RSS helper is not available anymore.

Astro

getStaticPaths RSS helper is not available anymore.

import DontEditWarning from '~/components/DontEditWarning.astro'

:::caution\[Deprecated\] Deprecated since Astro 4.0. The RSS helper no longer exists with an error fallback. :::

> **GetStaticPathsRemovedRSSHelper**: The RSS helper has been removed from `getStaticPaths`. Try the new @astrojs/rss package instead.

## What went wrong?

`getStaticPaths` no longer expose an helper for generating a RSS feed. We recommend migrating to the [@astrojs/rss](/en/recipes/rss/#setting-up-astrojsrss)integration instead.

**See Also:**

-   [RSS Guide](/en/recipes/rss/)

## [getStaticPaths() function required for dynamic routes.](https://docharvest.github.io/docs/astro/reference/errors/get-static-paths-required/)

Contents

astro

getStaticPaths() function required for dynamic routes.

Astro

getStaticPaths() function required for dynamic routes.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **GetStaticPathsRequired**: `getStaticPaths()` function is required for dynamic routes. Make sure that you `export` a `getStaticPaths()` function from your dynamic route.

## What went wrong?

In [Static Mode](/en/guides/routing/#static-ssg-mode), all routes must be determined at build time. As such, dynamic routes must `export` a `getStaticPaths()` function returning the different paths to generate.

**See Also:**

-   [Dynamic Routes](/en/guides/routing/#dynamic-routes)
-   [`getStaticPaths()`](/en/reference/routing-reference/#getstaticpaths)
-   [Server-side rendering](/en/guides/on-demand-rendering/)

## [The path doesn't contain any locale.](https://docharvest.github.io/docs/astro/reference/errors/i18n-no-locale-found-in-path/)

Contents

astro

The path doesn't contain any locale.

Astro

The path doesn't contain any locale.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **i18nNoLocaleFoundInPath**: You tried to use an i18n utility on a path that doesn't contain any locale. You can use `pathHasLocale` first to determine if the path has a locale.

## What went wrong?

An i18n utility tried to use the locale from a URL path that does not contain one. You can prevent this error by using `pathHasLocale` to check URLs for a locale first before using i18n utilities.

## [Internationalization routing is not enabled.](https://docharvest.github.io/docs/astro/reference/errors/i18n-not-enabled/)

Contents

astro

Internationalization routing is not enabled.

Astro

Internationalization routing is not enabled.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **i18nNotEnabled**: The `astro:i18n` module cannot be used without enabling `i18n` in your Astro config.

## What went wrong?

The `astro:i18n` module cannot be used without enabling i18n in your Astro config. To enable i18n, add a default locale and a list of supported locales to your Astro config:

```
import { defineConfig } from 'astro'
export default defineConfig({
 i18n: {
	 locales: ['en', 'fr'],
	 defaultLocale: 'en',
	},
})
```

For more information on internationalization support in Astro, see our [Internationalization guide](/en/guides/internationalization/).

**See Also:**

-   [Internationalization](/en/guides/internationalization/)
-   [`i18n` Configuration Reference](/en/reference/configuration-reference/#i18n)

## [Image missing required "alt" property.](https://docharvest.github.io/docs/astro/reference/errors/image-missing-alt/)

Contents

astro

Image missing required "alt" property.

Astro

Image missing required "alt" property.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **ImageMissingAlt**: Image missing "alt" property. "alt" text is required to describe important images on the page.

## What went wrong?

The `alt` property allows you to provide descriptive alt text to users of screen readers and other assistive technologies. In order to ensure your images are accessible, the `Image` component requires that an `alt` be specified.

If the image is merely decorative (i.e. doesn’t contribute to the understanding of the page), set `alt=""` so that screen readers know to ignore the image.

**See Also:**

-   [Images](/en/guides/images/)
-   [Image component](/en/reference/modules/astro-assets/#image-)
-    [Image component#alt](/en/reference/modules/astro-assets/#alt-required)

## [Image not found.](https://docharvest.github.io/docs/astro/reference/errors/image-not-found/)

Contents

astro

Image not found.

Astro

Image not found.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **ImageNotFound**: Could not find requested image `IMAGE_PATH`. Does it exist?

## What went wrong?

Astro could not find an image you imported. Often, this is simply caused by a typo in the path.

Images in Markdown are relative to the current file. To refer to an image that is located in the same folder as the `.md` file, the path should start with `./`

**See Also:**

-   [Images](/en/guides/images/)

## [Cannot set both densities and widths.](https://docharvest.github.io/docs/astro/reference/errors/incompatible-descriptor-options/)

Contents

astro

Cannot set both densities and widths.

Astro

Cannot set both densities and widths.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **IncompatibleDescriptorOptions**: Only one of `densities` or `widths` can be specified. In most cases, you'll probably want to use only `widths` if you require specific widths.

## What went wrong?

Only one of `densities` or `widths` can be specified. Those attributes are used to construct a `srcset` attribute, which cannot have both `x` and `w` descriptors.

**See Also:**

-   [Images](/en/guides/images/)

## [Function incompatible with the current strategy.](https://docharvest.github.io/docs/astro/reference/errors/incorrect-strategy-for-i18n/)

Contents

astro

Function incompatible with the current strategy.

Astro

Function incompatible with the current strategy.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **IncorrectStrategyForI18n**: The function `FUNCTION_NAME` can only be used when the `i18n.routing.strategy` is set to `"manual"`.

## What went wrong?

Some internationalization functions are only available when Astro's own i18n routing is disabled by the configuration setting `i18n.routing: "manual"`.

**See Also:**

-   [`i18n` routing](/en/guides/internationalization/#routing)

## [Invalid component arguments.](https://docharvest.github.io/docs/astro/reference/errors/invalid-component-args/)

Contents

astro

Invalid component arguments.

Astro

Invalid component arguments.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **Example error messages:**  
> InvalidComponentArgs: Invalid arguments passed to `<MyAstroComponent>` component.

## What went wrong?

Astro components cannot be rendered manually via a function call, such as `Component()` or `{items.map(Component)}`. Prefer the component syntax `<Component />` or `{items.map(item => <Component {...item} />)}`.

## [Content entry data does not match schema.](https://docharvest.github.io/docs/astro/reference/errors/invalid-content-entry-data-error/)

Contents

astro

Content entry data does not match schema.

Astro

Content entry data does not match schema.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **Example error message:**  
> **blog** → **post** data does not match collection schema.  
> "title" is required.  
> "date" must be a valid date.

## What went wrong?

A content entry does not match its collection schema. Make sure that all required fields are present, and that all fields are of the correct type. You can check against the collection schema in your `src/content.config.*` file. See the [Content collections documentation](/en/guides/content-collections/) for more information.

## [Content entry frontmatter does not match schema.](https://docharvest.github.io/docs/astro/reference/errors/invalid-content-entry-frontmatter-error/)

Contents

astro

Content entry frontmatter does not match schema.

Astro

Content entry frontmatter does not match schema.

import DontEditWarning from '~/components/DontEditWarning.astro'

:::caution\[Deprecated\] This error only applies to legacy content collections which were removed in Astro 6. :::

> **Example error message:**  
> **blog** → **post.md** frontmatter does not match collection schema.  
> "title" is required.  
> "date" must be a valid date.

## What went wrong?

A Markdown or MDX entry does not match its collection schema. Make sure that all required fields are present, and that all fields are of the correct type. You can check against the collection schema in your `src/content.config.*` file. See the [Content collections documentation](/en/guides/content-collections/) for more information.

## [Invalid content entry slug.](https://docharvest.github.io/docs/astro/reference/errors/invalid-content-entry-slug-error/)

Contents

astro

Invalid content entry slug.

Astro

Invalid content entry slug.

import DontEditWarning from '~/components/DontEditWarning.astro'

> `COLLECTION_NAME` → `ENTRY_ID` has an invalid slug. `slug` must be a string.

## What went wrong?

A collection entry has an invalid `slug`. This field is reserved for generating entry slugs, and must be a string when present.

**See Also:**

-   [The reserved entry `slug` field](/en/guides/content-collections/)

## [Invalid dynamic route.](https://docharvest.github.io/docs/astro/reference/errors/invalid-dynamic-route/)

Contents

astro

Invalid dynamic route.

Astro

Invalid dynamic route.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **InvalidDynamicRoute**: The INVALID\_PARAM param for route ROUTE is invalid. Received **RECEIVED**.

## What went wrong?

A dynamic route param is invalid. This is often caused by an `undefined` parameter or a missing [rest parameter](/en/guides/routing/#rest-parameters).

**See Also:**

-   [Dynamic routes](/en/guides/routing/#dynamic-routes)

## [Invalid frontmatter injection.](https://docharvest.github.io/docs/astro/reference/errors/invalid-frontmatter-injection-error/)

Contents

astro

Invalid frontmatter injection.

Astro

Invalid frontmatter injection.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **InvalidFrontmatterInjectionError**: A remark or rehype plugin attempted to inject invalid frontmatter. Ensure "astro.frontmatter" is set to a valid JSON object that is not `null` or `undefined`.

## What went wrong?

A remark or rehype plugin attempted to inject invalid frontmatter. This occurs when "astro.frontmatter" is set to `null`, `undefined`, or an invalid JSON object.

**See Also:**

-   [Modifying frontmatter programmatically](/en/guides/markdown-content/#modifying-frontmatter-programmatically)

## [Invalid value returned by a route from getStaticPaths().](https://docharvest.github.io/docs/astro/reference/errors/invalid-get-static-path-param/)

Contents

astro

Invalid value returned by a route from getStaticPaths().

Astro

Invalid value returned by a route from getStaticPaths().

## }

```

**See Also:**
-  [`getStaticPaths()`](/en/reference/routing-reference/#getstaticpaths)
-  [`params`](/en/reference/api-reference/#params)
```

## [Invalid entry inside getStaticPaths()'s return value.](https://docharvest.github.io/docs/astro/reference/errors/invalid-get-static-paths-entry/)

Contents

astro

Invalid entry inside getStaticPaths()'s return value.

Astro

Invalid entry inside getStaticPaths()'s return value.

}

```

**See Also:**
-  [`getStaticPaths()`](/en/reference/routing-reference/#getstaticpaths)
```

## [Invalid value returned by getStaticPaths().](https://docharvest.github.io/docs/astro/reference/errors/invalid-get-static-paths-return/)

Contents

astro

Invalid value returned by getStaticPaths().

Astro

Invalid value returned by getStaticPaths().

}

```

**See Also:**
-  [`getStaticPaths()`](/en/reference/routing-reference/#getstaticpaths)
-  [`params`](/en/reference/api-reference/#params)
```

## [Invalid glob pattern.](https://docharvest.github.io/docs/astro/reference/errors/invalid-glob/)

Contents

astro

Invalid glob pattern.

Astro

Invalid glob pattern.

import DontEditWarning from '~/components/DontEditWarning.astro'

:::caution\[Deprecated\] This error was removed in Astro v6.0.0 along with the removal of `Astro.glob()`. :::

> **InvalidGlob**: Invalid glob pattern: `GLOB_PATTERN`. Glob patterns must start with './', '../' or '/'.

## What went wrong?

Astro encountered an invalid glob pattern. This is often caused by the glob pattern not being a valid file path.

**See Also:**

-   [Glob Patterns](/en/guides/imports/#glob-patterns)

## [Invalid internationalization middleware configuration.](https://docharvest.github.io/docs/astro/reference/errors/invalid-i18n-middleware-configuration/)

Contents

astro

Invalid internationalization middleware configuration.

Astro

Invalid internationalization middleware configuration.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **InvalidI18nMiddlewareConfiguration**: The option `redirectToDefaultLocale` can be enabled only when `prefixDefaultLocale` is also set to `true`; otherwise, redirects might cause infinite loops. Enable the option `prefixDefaultLocale` to continue to use `redirectToDefaultLocale`, or ensure both are set to `false`.

## What went wrong?

An invalid i18n middleware configuration was detected.

## [Error while loading image service.](https://docharvest.github.io/docs/astro/reference/errors/invalid-image-service/)

Contents

astro

Error while loading image service.

Astro

Error while loading image service.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **InvalidImageService**: There was an error loading the configured image service. Please see the stack trace for more information.

## What went wrong?

There was an error while loading the configured image service. This can be caused by various factors, such as your image service not properly exporting a compatible object in its default export, or an incorrect path.

If you believe that your service is properly configured and this error is wrong, please [open an issue](https://astro.build/issues/).

**See Also:**

-   [Image Service API](/en/reference/image-service-reference/)

## [Invalid prerender export.](https://docharvest.github.io/docs/astro/reference/errors/invalid-prerender-export/)

Contents

astro

Invalid prerender export.

Astro

Invalid prerender export.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **Example error messages:**  
> InvalidPrerenderExport: A `prerender` export has been detected, but its value cannot be statically analyzed.

## What went wrong?

The `prerender` feature only supports a subset of valid JavaScript — be sure to use exactly `export const prerender = true` so that our compiler can detect this directive at build time. Variables, `let`, and `var` declarations are not supported.

## [Invalid redirect destination.](https://docharvest.github.io/docs/astro/reference/errors/invalid-redirect-destination/)

Contents

astro

Invalid redirect destination.

Astro

Invalid redirect destination.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **Example error message:**  
> InvalidRedirectDestination: The redirect from "/posts" to "/blog" is invalid. The destination "/blog" does not match any existing route in your project.

## What went wrong?

A dynamic redirect destination must match an existing route pattern and include all dynamic parameters from the source route. This error occurs when a redirect with dynamic parameters points to a destination that doesn't correspond to any page in your project, or when the destination route has fewer dynamic parameters than the source route.

**See Also:**

-   [Configured redirects](/en/guides/routing/#configured-redirects)

## [You attempted to rewrite a 404 inside a static page, and this isn't allowed.](https://docharvest.github.io/docs/astro/reference/errors/invalid-rewrite404/)

Contents

astro

You attempted to rewrite a 404 inside a static page, and this isn't allowed.

Astro

You attempted to rewrite a 404 inside a static page, and this isn't allowed.

import DontEditWarning from '~/components/DontEditWarning.astro'

:::caution\[Deprecated\] This error is from an older version of Astro and is no longer in use. If you are unable to upgrade your project to a more recent version, then you can consult [unmaintained snapshots of older documentation](/en/upgrade-astro/#older-docs-unmaintained) for assistance. :::

> **InvalidRewrite404**: Rewriting a 404 is only allowed inside on-demand pages.

## What went wrong?

The user tried to rewrite a 404 page inside a static page.

## [Legacy content config file found.](https://docharvest.github.io/docs/astro/reference/errors/legacy-content-config-error/)

Contents

astro

Legacy content config file found.

Astro

Legacy content config file found.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **Example error message:**  
> Found legacy content config file in "src/content/config.ts". Please move this file to "src/content.config.ts" and ensure each collection has a loader defined.  

## What went wrong?

A legacy content config file was found. Move the file to `src/content.config.ts` and update any collection definitions if needed. See the [Astro 6 migration guide](/en/guides/upgrade-to/v6/#removed-legacy-content-collections) for more information.

## [Error in live content config.](https://docharvest.github.io/docs/astro/reference/errors/live-content-config-error/)

Contents

astro

Error in live content config.

Astro

Error in live content config.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **Example error message:**  
> The schema cannot be a function for live collections. Please use a schema object instead. Check your collection definitions in your live content config file.

## What went wrong?

Error in live content config.

**See Also:**

-   [Defining live content schemas](/en/reference/modules/astro-content/#schema-1)

## [Local images must be imported.](https://docharvest.github.io/docs/astro/reference/errors/local-image-used-wrongly/)

Contents

astro

Local images must be imported.

Astro

Local images must be imported.

* * *

![Cool image]({myImage}) ![Cool image](https://example.com/my_image.png) ![Cool image]({myImage.src}) ![Cool image](../my_image.png) \`\`\`

**See Also:**

-   [Images](/en/guides/images/)

## [Value assigned to locals is not accepted.](https://docharvest.github.io/docs/astro/reference/errors/locals-not-an-object/)

Contents

astro

Value assigned to locals is not accepted.

Astro

Value assigned to locals is not accepted.

return next(); });

## [Astro.locals is not serializable](https://docharvest.github.io/docs/astro/reference/errors/locals-not-serializable/)

Contents

astro

Astro.locals is not serializable

Astro

Astro.locals is not serializable

return next(); });

## [locals must not be reassigned.](https://docharvest.github.io/docs/astro/reference/errors/locals-reassigned/)

Contents

astro

locals must not be reassigned.

Astro

locals must not be reassigned.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **LocalsReassigned**: `locals` cannot be assigned directly.

## What went wrong?

Thrown when a value is being set as the `locals` field on the Astro global or context.

## [The configuration of the logger is not serializable.](https://docharvest.github.io/docs/astro/reference/errors/logger-configuration-not-serializable/)

Contents

astro

The configuration of the logger is not serializable.

Astro

The configuration of the logger is not serializable.

import DontEditWarning from '~/components/DontEditWarning.astro'

> The configuration of the logger is not serializable.

## What went wrong?

The configuration of the logger is not serializable.

## [Content collection frontmatter invalid.](https://docharvest.github.io/docs/astro/reference/errors/markdown-content-schema-validation-error/)

Contents

astro

Content collection frontmatter invalid.

Astro

Content collection frontmatter invalid.

import DontEditWarning from '~/components/DontEditWarning.astro'

:::caution\[Deprecated\] This error is from an older version of Astro and is no longer in use. If you are unable to upgrade your project to a more recent version, then you can consult [unmaintained snapshots of older documentation](/en/upgrade-astro/#older-docs-unmaintained) for assistance. :::

> **Example error message:**  
> Could not parse frontmatter in **blog** → **post.md**  
> "title" is required.  
> "date" must be a valid date.

## What went wrong?

A Markdown document's frontmatter in `src/content/` does not match its collection schema. Make sure that all required fields are present, and that all fields are of the correct type. You can check against the collection schema in your `src/content/config.*` file. See the [Content collections documentation](/en/guides/content-collections/) for more information.

## [Failed to parse Markdown frontmatter.](https://docharvest.github.io/docs/astro/reference/errors/markdown-frontmatter-parse-error/)

Contents

astro

Failed to parse Markdown frontmatter.

Astro

Failed to parse Markdown frontmatter.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **Example error messages:**  
> cannot read an implicit mapping pair; a colon is missed  
> unexpected end of the stream within a double quoted scalar  
> cannot read a block mapping entry; a multiline key may not be an implicit key

## What went wrong?

Astro encountered an error while parsing the frontmatter of your Markdown file. This is often caused by a mistake in the syntax, such as a missing colon or a missing end quote.

## [Image not found.](https://docharvest.github.io/docs/astro/reference/errors/markdown-image-not-found/)

Contents

astro

Image not found.

Astro

Image not found.

import DontEditWarning from '~/components/DontEditWarning.astro'

:::caution\[Deprecated\] This error is no longer Markdown specific and as such, as been replaced by `ImageNotFound` :::

> Could not find requested image `IMAGE_PATH` at `FULL_IMAGE_PATH`.

## What went wrong?

Astro could not find an image you included in your Markdown content. Usually, this is simply caused by a typo in the path.

Images in Markdown are relative to the current file. To refer to an image that is located in the same folder as the `.md` file, the path should start with `./`

**See Also:**

-   [Images](/en/guides/images/)

## [MDX integration missing.](https://docharvest.github.io/docs/astro/reference/errors/mdx-integration-missing-error/)

Contents

astro

MDX integration missing.

Astro

MDX integration missing.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **MdxIntegrationMissingError**: Unable to render FILE. Ensure that the `@astrojs/mdx` integration is installed.

## What went wrong?

Unable to find the official `@astrojs/mdx` integration. This error is raised when using MDX files without an MDX integration installed.

**See Also:**

-   [MDX installation and usage](/en/guides/integrations-guide/mdx/)

## [Can't load the middleware.](https://docharvest.github.io/docs/astro/reference/errors/middleware-cant-be-loaded/)

Contents

astro

Can't load the middleware.

Astro

Can't load the middleware.

throw new Error("Error thrown while loading the middleware.")

## [The middleware didn't return a Response.](https://docharvest.github.io/docs/astro/reference/errors/middleware-no-data-or-next-called/)

Contents

astro

The middleware didn't return a Response.

Astro

The middleware didn't return a Response.

});

## [The middleware returned something that is not a Response object.](https://docharvest.github.io/docs/astro/reference/errors/middleware-not-aresponse/)

Contents

astro

The middleware returned something that is not a Response object.

Astro

The middleware returned something that is not a Response object.

## [experimental_getFontFileURL() requires the request URL with on-demand rendering.](https://docharvest.github.io/docs/astro/reference/errors/missing-get-font-file-request-url/)

Contents

astro

experimental\_getFontFileURL() requires the request URL with on-demand rendering.

Astro

experimental\_getFontFileURL() requires the request URL with on-demand rendering.

import DontEditWarning from '~/components/DontEditWarning.astro'

## What went wrong?

`experimental_getFontFileURL()` requires the request URL with on-demand rendering.

## [Missing image dimensions.](https://docharvest.github.io/docs/astro/reference/errors/missing-image-dimension/)

Contents

astro

Missing image dimensions.

Astro

Missing image dimensions.

import DontEditWarning from '~/components/DontEditWarning.astro'

> Missing width and height attributes for `IMAGE_URL`. When using remote images, both dimensions are required in order to avoid cumulative layout shift (CLS).

## What went wrong?

For remote images, `width` and `height` cannot automatically be inferred from the original file. To avoid cumulative layout shift (CLS), either specify these two properties, or set [`inferSize`](/en/reference/modules/astro-assets/#infersize) to `true` to fetch a remote image's original dimensions.

If your image is inside your `src` folder, you probably meant to import it instead. See [the Imports guide for more information](/en/guides/imports/#other-assets).

**See Also:**

-   [Images](/en/guides/images/)
-   [Image component#width-and-height-required](/en/reference/modules/astro-assets/#width-and-height-required-for-images-in-public)

## [Index page not found.](https://docharvest.github.io/docs/astro/reference/errors/missing-index-for-internationalization/)

Contents

astro

Index page not found.

Astro

Index page not found.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **MissingIndexForInternationalization**: Could not find index page. A root index page is required in order to create a redirect to the index URL of the default locale. (`/DEFAULT_LOCALE`)

## What went wrong?

Astro could not find the index URL of your website. An index page is required so that Astro can create a redirect from the main index page to the localized index page of the default locale when using [`i18n.routing.prefixDefaultLocale`](/en/reference/configuration-reference/#i18nroutingprefixdefaultlocale).

**See Also:**

-   [Internationalization](/en/guides/internationalization/#routing)
-   [`i18n.routing` Configuration Reference](/en/reference/configuration-reference/#i18nrouting)

## [The provided locale does not exist.](https://docharvest.github.io/docs/astro/reference/errors/missing-locale/)

Contents

astro

The provided locale does not exist.

Astro

The provided locale does not exist.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **MissingLocale**: The locale/path `LOCALE` does not exist in the configured `i18n.locales`.

## What went wrong?

Astro can't find the requested locale. All supported locales must be configured in [`i18n.locales`](/en/reference/configuration-reference/#i18nlocales) and have corresponding directories within `src/pages/`.

## [Missing value for client:media directive.](https://docharvest.github.io/docs/astro/reference/errors/missing-media-query-directive/)

Contents

astro

Missing value for client:media directive.

Astro

Missing value for client:media directive.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **MissingMediaQueryDirective**: Media query not provided for `client:media` directive. A media query similar to `client:media="(max-width: 600px)"` must be provided.

## What went wrong?

A [media query](https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries/Using_media_queries) parameter is required when using the `client:media` directive.

```
<Counter client:media="(max-width: 640px)" />
```

**See Also:**

-   [`client:media`](/en/reference/directives-reference/#clientmedia)

## [Enabled manual internationalization routing without having a middleware.](https://docharvest.github.io/docs/astro/reference/errors/missing-middleware-for-internationalization/)

Contents

astro

Enabled manual internationalization routing without having a middleware.

Astro

Enabled manual internationalization routing without having a middleware.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **MissingMiddlewareForInternationalization**: Your configuration setting `i18n.routing: 'manual'` requires you to provide your own i18n `middleware` file.

## What went wrong?

Astro throws an error if the user enables manual routing, but it doesn't have a middleware file.

## [Could not find Sharp.](https://docharvest.github.io/docs/astro/reference/errors/missing-sharp/)

Contents

astro

Could not find Sharp.

Astro

Could not find Sharp.

```

**See Also:**
-  [Default Image Service](/en/guides/images/#default-image-service)
-  [Image Services API](/en/reference/image-service-reference/)
```

## [Content and data cannot be in same collection.](https://docharvest.github.io/docs/astro/reference/errors/mixed-content-data-collection-error/)

Contents

astro

Content and data cannot be in same collection.

Astro

Content and data cannot be in same collection.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **MixedContentDataCollectionError**: **COLLECTION\_NAME** contains a mix of content and data entries. All entries must be of the same type.

## What went wrong?

A legacy content collection cannot contain a mix of content and data entries. You must store entries in separate collections by type.

**See Also:**

-   [Legacy content collections](/en/guides/upgrade-to/v5/#updating-existing-collections)

## [Cannot use server-side rendering without an adapter.](https://docharvest.github.io/docs/astro/reference/errors/no-adapter-installed/)

Contents

astro

Cannot use server-side rendering without an adapter.

Astro

Cannot use server-side rendering without an adapter.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **NoAdapterInstalled**: Cannot use server-rendered pages without an adapter. Please install and configure the appropriate server adapter for your final deployment.

## What went wrong?

To use server-side rendering, an adapter needs to be installed so Astro knows how to generate the proper output for your targeted deployment platform.

**See Also:**

-   [Server-side rendering](/en/guides/on-demand-rendering/)

## [Cannot use server islands without an adapter.](https://docharvest.github.io/docs/astro/reference/errors/no-adapter-installed-server-islands/)

Contents

astro

Cannot use server islands without an adapter.

Astro

Cannot use server islands without an adapter.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **NoAdapterInstalledServerIslands**: Cannot use server islands without an adapter. Please install and configure the appropriate server adapter for your final deployment.

## What went wrong?

To use server islands, the same constraints exist as for server-side rendering, so an adapter is needed.

**See Also:**

-   [On-demand Rendering](/en/guides/on-demand-rendering/)

## [No client entrypoint specified in renderer.](https://docharvest.github.io/docs/astro/reference/errors/no-client-entrypoint/)

Contents

astro

No client entrypoint specified in renderer.

Astro

No client entrypoint specified in renderer.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **NoClientEntrypoint**: `COMPONENT_NAME` component has a `client:CLIENT_DIRECTIVE` directive, but no client entrypoint was provided by `RENDERER_NAME`.

## What went wrong?

Astro tried to hydrate a component on the client, but the renderer used does not provide a client entrypoint to use to hydrate.

**See Also:**

-   [addRenderer option](/en/reference/integrations-reference/#addrenderer-option)
-   [Hydrating framework components](/en/guides/framework-components/#hydrating-interactive-components)

## [Missing hint on client:only directive.](https://docharvest.github.io/docs/astro/reference/errors/no-client-only-hint/)

Contents

astro

Missing hint on client:only directive.

Astro

Missing hint on client:only directive.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **NoClientOnlyHint**: Unable to render `COMPONENT_NAME`. When using the `client:only` hydration strategy, Astro needs a hint to use the correct renderer.

## What went wrong?

`client:only` components are not run on the server, as such Astro does not know (and cannot guess) which renderer to use and require a hint. Like such:

```
	<SomeReactComponent client:only="react" />
```

**See Also:**

-   [`client:only`](/en/reference/directives-reference/#clientonly)

## [Could not process image metadata.](https://docharvest.github.io/docs/astro/reference/errors/no-image-metadata/)

Contents

astro

Could not process image metadata.

Astro

Could not process image metadata.

import DontEditWarning from '~/components/DontEditWarning.astro'

> Could not process image metadata for `IMAGE_PATH`.

## What went wrong?

Astro could not process the metadata of an image you imported. This is often caused by a corrupted or malformed image and re-exporting the image from your image editor may fix this issue.

**See Also:**

-   [Images](/en/guides/images/)

## [No import found for component.](https://docharvest.github.io/docs/astro/reference/errors/no-matching-import/)

Contents

astro

No import found for component.

Astro

No import found for component.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **NoMatchingImport**: Could not render `COMPONENT_NAME`. No matching import has been found for `COMPONENT_NAME`.

## What went wrong?

No import statement was found for one of the components. If there is an import statement, make sure you are using the same identifier in both the imports and the component usage.

## [No matching renderer found.](https://docharvest.github.io/docs/astro/reference/errors/no-matching-renderer/)

Contents

astro

No matching renderer found.

Astro

No matching renderer found.

import DontEditWarning from '~/components/DontEditWarning.astro'

> Unable to render `COMPONENT_NAME`. There are `RENDERER_COUNT` renderer(s) configured in your `astro.config.mjs` file, but none were able to server-side render `COMPONENT_NAME`.

## What went wrong?

None of the installed integrations were able to render the component you imported. Make sure to install the appropriate integration for the type of component you are trying to include in your page.

For JSX / TSX files, [@astrojs/react](/en/guides/integrations-guide/react/), [@astrojs/preact](/en/guides/integrations-guide/preact/) or [@astrojs/solid-js](/en/guides/integrations-guide/solid-js/) can be used. For Vue and Svelte files, the [@astrojs/vue](/en/guides/integrations-guide/vue/) and [@astrojs/svelte](/en/guides/integrations-guide/svelte/) integrations can be used respectively

**See Also:**

-   [Frameworks components](/en/guides/framework-components/)
-   [UI Frameworks](/en/guides/integrations/#official-integrations)

## [No static path found for requested path.](https://docharvest.github.io/docs/astro/reference/errors/no-matching-static-path-found/)

Contents

astro

No static path found for requested path.

Astro

No static path found for requested path.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **NoMatchingStaticPathFound**: A `getStaticPaths()` route pattern was matched, but no matching static path was found for requested path `PATH_NAME`.

## What went wrong?

A [dynamic route](/en/guides/routing/#dynamic-routes) was matched, but no corresponding path was found for the requested parameters. This is often caused by a typo in either the generated or the requested path.

**See Also:**

-   [`getStaticPaths()`](/en/reference/routing-reference/#getstaticpaths)

## [Prerendered routes aren't supported when internationalization domains are enabled.](https://docharvest.github.io/docs/astro/reference/errors/no-prerendered-routes-with-domains/)

Contents

astro

Prerendered routes aren't supported when internationalization domains are enabled.

Astro

Prerendered routes aren't supported when internationalization domains are enabled.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **NoPrerenderedRoutesWithDomains**: Static pages aren't yet supported with multiple domains. To enable this feature, you must disable prerendering for the page COMPONENT.

## What went wrong?

Static pages aren't yet supported with i18n domains. If you wish to enable this feature, you have to disable prerendering.

## [Invalid type returned by Astro page.](https://docharvest.github.io/docs/astro/reference/errors/only-response-can-be-returned/)

Contents

astro

Invalid type returned by Astro page.

Astro

Invalid type returned by Astro page.

## // Alternatively, for redirects, `Astro.redirect()` also returns an instance of `Response` return Astro.redirect('/login');

```

**See Also:**
-  [Response](/en/guides/on-demand-rendering/#response)
```

## [Page number param not found.](https://docharvest.github.io/docs/astro/reference/errors/page-number-param-not-found/)

Contents

astro

Page number param not found.

Astro

Page number param not found.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **PageNumberParamNotFound**: \[paginate()\] page number param `PARAM_NAME` not found in your filepath.

## What went wrong?

The page number parameter was not found in your filepath.

**See Also:**

-   [Pagination](/en/guides/routing/#pagination)

## [Astro.clientAddress cannot be used inside prerendered routes.](https://docharvest.github.io/docs/astro/reference/errors/prerender-client-address-not-available/)

Contents

astro

Astro.clientAddress cannot be used inside prerendered routes.

Astro

Astro.clientAddress cannot be used inside prerendered routes.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **PrerenderClientAddressNotAvailable**: `Astro.clientAddress` cannot be used inside prerendered route NAME.

## What went wrong?

The `Astro.clientAddress` property cannot be used inside prerendered routes.

**See Also:**

-   [On-demand rendering](/en/guides/on-demand-rendering/)
-   [`Astro.clientAddress`](/en/reference/api-reference/#clientaddress)

## [Prerendered dynamic endpoint has path collision.](https://docharvest.github.io/docs/astro/reference/errors/prerender-dynamic-endpoint-path-collide/)

Contents

astro

Prerendered dynamic endpoint has path collision.

Astro

Prerendered dynamic endpoint has path collision.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **PrerenderDynamicEndpointPathCollide**: Could not render `PATHNAME` with an `undefined` param as the generated path will collide during prerendering. Prevent passing `undefined` as `params` for the endpoint's `getStaticPaths()` function, or add an additional extension to the endpoint's filename.

## What went wrong?

The endpoint is prerendered with an `undefined` param so the generated path will collide with another route.

If you cannot prevent passing `undefined`, then an additional extension can be added to the endpoint file name to generate the file with a different name. For example, renaming `pages/api/[slug].ts` to `pages/api/[slug].json.ts`.

**See Also:**

-   [`getStaticPaths()`](/en/reference/routing-reference/#getstaticpaths)
-   [`params`](/en/reference/api-reference/#params)

## [Prerendered route generates the same path as another route.](https://docharvest.github.io/docs/astro/reference/errors/prerender-route-conflict/)

Contents

astro

Prerendered route generates the same path as another route.

Astro

Prerendered route generates the same path as another route.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **PrerenderRouteConflict**: Could not render `PATHNAME` from route `THIS_ROUTE` as it conflicts with higher priority route `WINNING_ROUTE`.

## What went wrong?

Two prerendered routes generate the same path, resulting in a collision. A static path can only be generated by one route.

**See Also:**

-   [Route Priority Order](/en/guides/routing/#route-priority-order)
-   [`prerenderConflictBehavior`](/en/reference/configuration-reference/#prerenderconflictbehavior)

## [A redirect must be given a location with the Location header.](https://docharvest.github.io/docs/astro/reference/errors/redirect-with-no-location/)

Contents

astro

A redirect must be given a location with the Location header.

Astro

A redirect must be given a location with the Location header.

import DontEditWarning from '~/components/DontEditWarning.astro'

## What went wrong?

A redirect must be given a location with the `Location` header.

**See Also:**

-   [`Astro.redirect()`](/en/reference/api-reference/#redirect)

## [Remote image is not allowed.](https://docharvest.github.io/docs/astro/reference/errors/remote-image-not-allowed/)

Contents

astro

Remote image is not allowed.

Astro

Remote image is not allowed.

import DontEditWarning from '~/components/DontEditWarning.astro'

> Remote image `IMAGE_URL` is not allowed by your image configuration.

## What went wrong?

The remote image URL does not match your configured `image.domains` or `image.remotePatterns`.

## [Attempted to render an undefined content collection entry.](https://docharvest.github.io/docs/astro/reference/errors/render-undefined-entry-error/)

Contents

astro

Attempted to render an undefined content collection entry.

Astro

Attempted to render an undefined content collection entry.

import DontEditWarning from '~/components/DontEditWarning.astro'

## What went wrong?

Astro tried to render a content collection entry that was undefined. This can happen if you try to render an entry that does not exist.

## [Invalid slot name.](https://docharvest.github.io/docs/astro/reference/errors/reserved-slot-name/)

Contents

astro

Invalid slot name.

Astro

Invalid slot name.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **ReservedSlotName**: Unable to create a slot named `SLOT_NAME`. `SLOT_NAME` is a reserved slot name. Please update the name of this slot.

## What went wrong?

Certain words cannot be used for slot names due to being already used internally.

**See Also:**

-   [Named slots](/en/basics/astro-components/#named-slots)

## [Unable to set response.](https://docharvest.github.io/docs/astro/reference/errors/response-sent-error/)

Contents

astro

Unable to set response.

Astro

Unable to set response.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **ResponseSentError**: The response has already been sent to the browser and cannot be altered.

## What went wrong?

Making changes to the response, such as setting headers, cookies, and the status code can only be done in [page components](/en/basics/astro-pages/).

**See Also:**

-   [HTML streaming](/en/guides/on-demand-rendering/#html-streaming)

## [Astro couldn't find the route to rewrite, or if was found but it emitted an error during the rendering phase.](https://docharvest.github.io/docs/astro/reference/errors/rewrite-encountered-an-error/)

Contents

astro

Astro couldn't find the route to rewrite, or if was found but it emitted an error during the rendering phase.

Astro

Astro couldn't find the route to rewrite, or if was found but it emitted an error during the rendering phase.

import DontEditWarning from '~/components/DontEditWarning.astro'

:::caution\[Deprecated\] This error cannot be emitted by Astro anymore :::

> **RewriteEncounteredAnError**: The route ROUTE that you tried to render doesn't exist, or it emitted an error during the rendering phase. STACK ? STACK : ''.

## What went wrong?

The user tried to rewrite using a route that doesn't exist, or it emitted a runtime error during its rendering phase.

## [Cannot use Astro.rewrite() after the request body has been read.](https://docharvest.github.io/docs/astro/reference/errors/rewrite-with-body-used/)

Contents

astro

Cannot use Astro.rewrite() after the request body has been read.

Astro

Cannot use Astro.rewrite() after the request body has been read.

Astro.rewrite("/target")

```

**See Also:**
-  [Request.clone()](https://developer.mozilla.org/en-US/docs/Web/API/Request/clone)
-  [Astro.rewrite](/en/reference/api-reference/#rewrite)
```

## [Route not found.](https://docharvest.github.io/docs/astro/reference/errors/route-not-found/)

Contents

astro

Route not found.

Astro

Route not found.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **RouteNotFound**: Astro could not find a route that matches the one you requested.

## What went wrong?

Astro couldn't find a route matching the one provided by the user.

## [Module is only available server-side.](https://docharvest.github.io/docs/astro/reference/errors/server-only-module/)

Contents

astro

Module is only available server-side.

Astro

Module is only available server-side.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **ServerOnlyModule**: The "NAME" module is only available server-side.

## What went wrong?

This module is only available server-side.

## [Session storage was enabled but not configured.](https://docharvest.github.io/docs/astro/reference/errors/session-config-missing-error/)

Contents

astro

Session storage was enabled but not configured.

Astro

Session storage was enabled but not configured.

import DontEditWarning from '~/components/DontEditWarning.astro'

:::caution\[Deprecated\] This error was removed in Astro 5.7, when the Sessions feature stopped being experimental. :::

> The `experimental.session` flag was set to `true`, but no storage was configured. Either configure the storage manually or use an adapter that provides session storage.

## What went wrong?

Thrown when session storage is enabled but not configured.

**See Also:**

-   [Sessions](/en/guides/sessions/)

## [Session flag not set](https://docharvest.github.io/docs/astro/reference/errors/session-config-without-flag-error/)

Contents

astro

Session flag not set

Astro

Session flag not set

import DontEditWarning from '~/components/DontEditWarning.astro'

:::caution\[Deprecated\] This error was removed in Astro 5.7, when the Sessions feature stopped being experimental. :::

> Session config was provided without enabling the `experimental.session` flag

## What went wrong?

Thrown when session storage is configured but the `experimental.session` flag is not enabled.

**See Also:**

-   [Sessions](/en/guides/sessions/)

## [Session storage could not be initialized.](https://docharvest.github.io/docs/astro/reference/errors/session-storage-init-error/)

Contents

astro

Session storage could not be initialized.

Astro

Session storage could not be initialized.

import DontEditWarning from '~/components/DontEditWarning.astro'

> Error when initializing session storage with driver `DRIVER`. `ERROR`

## What went wrong?

Thrown when the session storage could not be initialized.

**See Also:**

-   [Sessions](/en/guides/sessions/)

## [Session data could not be saved.](https://docharvest.github.io/docs/astro/reference/errors/session-storage-save-error/)

Contents

astro

Session data could not be saved.

Astro

Session data could not be saved.

import DontEditWarning from '~/components/DontEditWarning.astro'

> Error when saving session data with driver `DRIVER`. `ERROR`

## What went wrong?

Thrown when the session data could not be saved.

**See Also:**

-   [Sessions](/en/guides/sessions/)

## [Sessions cannot be used with an adapter that doesn't support server output.](https://docharvest.github.io/docs/astro/reference/errors/session-without-supported-adapter-output-error/)

Contents

astro

Sessions cannot be used with an adapter that doesn't support server output.

Astro

Sessions cannot be used with an adapter that doesn't support server output.

import DontEditWarning from '~/components/DontEditWarning.astro'

:::caution\[Deprecated\] This error was removed in Astro 5.7, when the Sessions feature stopped being experimental. :::

> **SessionWithoutSupportedAdapterOutputError**: Sessions require an adapter that supports server output. The adapter must set `"server"` in the `buildOutput` adapter feature.

## What went wrong?

Your adapter must support server output to use sessions.

**See Also:**

-   [Sessions](/en/guides/sessions/)

## [Astro.clientAddress is not available in prerendered pages.](https://docharvest.github.io/docs/astro/reference/errors/static-client-address-not-available/)

Contents

astro

Astro.clientAddress is not available in prerendered pages.

Astro

Astro.clientAddress is not available in prerendered pages.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **StaticClientAddressNotAvailable**: `Astro.clientAddress` is only available on pages that are server-rendered.

## What went wrong?

The `Astro.clientAddress` property is only available when [Server-side rendering](/en/guides/on-demand-rendering/) is enabled.

To get the user's IP address in static mode, different APIs such as [Ipify](https://www.ipify.org/) can be used in a [Client-side script](/en/guides/client-side-scripts/) or it may be possible to get the user's IP using a serverless function hosted on your hosting provider.

**See Also:**

-   [Enabling SSR in Your Project](/en/guides/on-demand-rendering/)
-   [`Astro.clientAddress`](/en/reference/api-reference/#clientaddress)

## [Astro.redirect is not available in static mode.](https://docharvest.github.io/docs/astro/reference/errors/static-redirect-not-available/)

Contents

astro

Astro.redirect is not available in static mode.

Astro

Astro.redirect is not available in static mode.

import DontEditWarning from '~/components/DontEditWarning.astro'

:::caution\[Deprecated\] Deprecated since version 2.6. :::

> **StaticRedirectNotAvailable**: Redirects are only available when using `output: 'server'` or `output: 'hybrid'`. Update your Astro config if you need SSR features.

## What went wrong?

The `Astro.redirect` function is only available when [Server-side rendering](/en/guides/on-demand-rendering/) is enabled.

To redirect on a static website, the [meta refresh attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta) can be used. Certain hosts also provide config-based redirects (ex: [Netlify redirects](https://docs.netlify.com/routing/redirects/)).

**See Also:**

-   [Enabling SSR in Your Project](/en/guides/on-demand-rendering/)
-   [Astro.redirect](/en/reference/api-reference/#redirect)

## [Unable to load the logger.](https://docharvest.github.io/docs/astro/reference/errors/unable-to-load-logger/)

Contents

astro

Unable to load the logger.

Astro

Unable to load the logger.

import DontEditWarning from '~/components/DontEditWarning.astro'

> Couldn't load the logger at the given path.

## What went wrong?

Unable to load the logger.

## [Unavailable Astro global in getStaticPaths().](https://docharvest.github.io/docs/astro/reference/errors/unavailable-astro-global/)

Contents

astro

Unavailable Astro global in getStaticPaths().

Astro

Unavailable Astro global in getStaticPaths().

import DontEditWarning from '~/components/DontEditWarning.astro'

> The Astro global is not available in `getStaticPaths()`.

## What went wrong?

Unavailable Astro global in `getStaticPaths()`.

## [Unhandled rejection.](https://docharvest.github.io/docs/astro/reference/errors/unhandled-rejection/)

Contents

astro

Unhandled rejection.

Astro

Unhandled rejection.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **UnhandledRejection**: Astro detected an unhandled rejection. Here's the stack trace:  
> STACK

## What went wrong?

Astro could not find any code to handle a rejected `Promise`. Make sure all your promises have an `await` or `.catch()` handler.

## [Unknown CLI error.](https://docharvest.github.io/docs/astro/reference/errors/unknown-clierror/)

Contents

astro

Unknown CLI error.

Astro

Unknown CLI error.

import DontEditWarning from '~/components/DontEditWarning.astro'

## What went wrong?

Astro encountered an unknown error while starting one of its CLI commands. The error message should contain more information.

If you can reliably cause this error to happen, we'd appreciate if you could [open an issue](https://astro.build/issues/)

## [Unknown compiler error.](https://docharvest.github.io/docs/astro/reference/errors/unknown-compiler-error/)

Contents

astro

Unknown compiler error.

Astro

Unknown compiler error.

import DontEditWarning from '~/components/DontEditWarning.astro'

> Unknown compiler error.

## What went wrong?

Astro encountered an unknown error while compiling your files. In most cases, this is not your fault, but an issue in our compiler.

If there isn't one already, please [create an issue](https://astro.build/issues/compiler).

**See Also:**

-   [withastro/compiler issues list](https://astro.build/issues/compiler)

## [Unknown configuration error.](https://docharvest.github.io/docs/astro/reference/errors/unknown-config-error/)

Contents

astro

Unknown configuration error.

Astro

Unknown configuration error.

import DontEditWarning from '~/components/DontEditWarning.astro'

## What went wrong?

Astro encountered an unknown error loading your Astro configuration file. This is often caused by a syntax error in your config and the message should offer more information.

If you can reliably cause this error to happen, we'd appreciate if you could [open an issue](https://astro.build/issues/)

**See Also:**

-   [Configuration Reference](/en/reference/configuration-reference/)

## [Unknown content collection error.](https://docharvest.github.io/docs/astro/reference/errors/unknown-content-collection-error/)

Contents

astro

Unknown content collection error.

Astro

Unknown content collection error.

import DontEditWarning from '~/components/DontEditWarning.astro'

## What went wrong?

Astro encountered an unknown error loading your content collections. This can be caused by certain errors inside your `src/content.config.ts` file or some internal errors.

If you can reliably cause this error to happen, we'd appreciate if you could [open an issue](https://astro.build/issues/)

## [Unknown CSS error.](https://docharvest.github.io/docs/astro/reference/errors/unknown-csserror/)

Contents

astro

Unknown CSS error.

Astro

Unknown CSS error.

import DontEditWarning from '~/components/DontEditWarning.astro'

## What went wrong?

Astro encountered an unknown error while parsing your CSS. Oftentimes, this is caused by a syntax error and the error message should contain more information.

**See Also:**

-   [Styles and CSS](/en/guides/styling/)

## [An unknown error occurred while reading or writing files to disk.](https://docharvest.github.io/docs/astro/reference/errors/unknown-filesystem-error/)

Contents

astro

An unknown error occurred while reading or writing files to disk.

Astro

An unknown error occurred while reading or writing files to disk.

import DontEditWarning from '~/components/DontEditWarning.astro'

## What went wrong?

An unknown error occurred while reading or writing files to disk. It can be caused by many things, eg. missing permissions or a file not existing we attempt to read.

## [Unknown Markdown error.](https://docharvest.github.io/docs/astro/reference/errors/unknown-markdown-error/)

Contents

astro

Unknown Markdown error.

Astro

Unknown Markdown error.

import DontEditWarning from '~/components/DontEditWarning.astro'

## What went wrong?

Astro encountered an unknown error while parsing your Markdown. Oftentimes, this is caused by a syntax error and the error message should contain more information.

## [Unknown Vite error.](https://docharvest.github.io/docs/astro/reference/errors/unknown-vite-error/)

Contents

astro

Unknown Vite error.

Astro

Unknown Vite error.

import DontEditWarning from '~/components/DontEditWarning.astro'

## What went wrong?

Vite encountered an unknown error while rendering your project. We unfortunately do not know what happened (or we would tell you!)

If you can reliably cause this error to happen, we'd appreciate if you could [open an issue](https://astro.build/issues/)

**See Also:**

-   [Vite troubleshooting guide](https://vite.dev/guide/troubleshooting.html)

## [Unsupported transform in content config.](https://docharvest.github.io/docs/astro/reference/errors/unsupported-config-transform-error/)

Contents

astro

Unsupported transform in content config.

Astro

Unsupported transform in content config.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **UnsupportedConfigTransformError**: `transform()` functions in your content config must return valid JSON, or data types compatible with the devalue library (including Dates, Maps, and Sets).  
> Full error: PARSE\_ERROR

## What went wrong?

`transform()` functions in your content config must return valid JSON, or data types compatible with the devalue library (including Dates, Maps, and Sets).

**See Also:**

-   [devalue library](https://github.com/rich-harris/devalue)

## [Unsupported or malformed URL.](https://docharvest.github.io/docs/astro/reference/errors/unsupported-external-redirect/)

Contents

astro

Unsupported or malformed URL.

Astro

Unsupported or malformed URL.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **UnsupportedExternalRedirect**: The destination URL in the external redirect from "FROM" to "TO" is unsupported.

## What went wrong?

An external redirect must start with http or https, and must be a valid URL.

**See Also:**

-   [`Astro.redirect()`](/en/reference/api-reference/#redirect)

## [Unsupported image conversion.](https://docharvest.github.io/docs/astro/reference/errors/unsupported-image-conversion/)

Contents

astro

Unsupported image conversion.

Astro

Unsupported image conversion.

import DontEditWarning from '~/components/DontEditWarning.astro'

> **UnsupportedImageConversion**: Converting between vector (such as SVGs) and raster (such as PNGs and JPEGs) images is not currently supported.

## What went wrong?

Astro does not currently supporting converting between vector (such as SVGs) and raster (such as PNGs and JPEGs) images.

**See Also:**

-   [Images](/en/guides/images/)

## [Unsupported image format.](https://docharvest.github.io/docs/astro/reference/errors/unsupported-image-format/)

Contents

astro

Unsupported image format.

Astro

Unsupported image format.

* * *

\`\`\`

## [Configuring experimental flags](https://docharvest.github.io/docs/astro/reference/experimental-flags/)

Contents

astro

Configuring experimental flags

Astro

Configuring experimental flags

Experimental features are available only after enabling a flag in the Astro configuration file.

Astro offers experimental flags to give users early access to new features for testing and feedback.

These flags allow you to participate in feature development by reporting issues and sharing your opinions. These features are not guaranteed to be stable and may include breaking changes even in small `patch` releases while the feature is actively developed.

We recommend [updating Astro](/en/upgrade-astro/#upgrade-to-the-latest-version) frequently, and keeping up with release notes in the [Astro changelog](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md) which will inform you of any changes needed to your project code. The experimental feature documentation will always be updated for the current released version only.

## [Experimental Chrome DevTools workspace](https://docharvest.github.io/docs/astro/reference/experimental-flags/chrome-devtools-workspace/)

Contents

astro

Experimental Chrome DevTools workspace

Astro

Experimental Chrome DevTools workspace

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

Enables experimental [Chrome DevTools workspace integration](https://developer.chrome.com/docs/devtools/workspaces) for the Astro dev server.

This feature allows you to edit files directly in Chrome DevTools and have those changes reflected in your local file system via a connected workspace folder. This is useful for applying edits such as adjusting CSS values without leaving your browser tab.

With this feature enabled, running `astro dev` will automatically configure a Chrome DevTools workspace for your project. Your project will then appear as an available [workspace source that you can connect](#connecting-your-project). Then, changes that you make in the "Sources" panel are automatically saved to your project source code.

To enable this feature, add the experimental flag `chromeDevtoolsWorkspace` to your Astro config:

## Connecting your project

Astro will create the necessary configuration file to support Chrome DevTools workspaces. However, your project must also be [connected as a source](https://developer.chrome.com/docs/devtools/workspaces#manual-connection) to enable file saving.

1.  [Start the Astro dev server](/en/develop-and-build/#start-the-astro-dev-server) with the appropriate CLI command for your package manager.
    
2.  Navigate to your site preview (e.g. `http://localhost:4321/`) in Chrome and open DevTools.
    
3.  Under the **Sources** > **Workspaces** tab, you will find your Astro project folder. Click **Connect** to add your directory as a workspace.
    

See the [Chrome DevTools workspace documentation](https://developer.chrome.com/docs/devtools/workspaces#connect) for more information.

## [Experimental client prerendering](https://docharvest.github.io/docs/astro/reference/experimental-flags/client-prerender/)

Contents

astro

Experimental client prerendering

Astro

Experimental client prerendering

```

Continue to use the `data-astro-prefetch` attribute on any `<a />` link on your site to opt in to prefetching.
Instead of appending a `<link>` tag to the head of the document or fetching the page with JavaScript, a `<script>` tag will be appended with the corresponding speculation rules.

Client side prerendering requires browser support. If the Speculation Rules API is not supported, `prefetch` will fallback to the supported strategy.

See the [Prefetch Guide](/en/guides/prefetch/) for more `prefetch` options and usage.
```

## [Experimental Intellisense for content collections](https://docharvest.github.io/docs/astro/reference/experimental-flags/content-intellisense/)

Contents

astro

Experimental Intellisense for content collections

Astro

Experimental Intellisense for content collections

```

To use this feature with the Astro VS Code extension, you must also enable the `astro.content-intellisense` option in your VS Code settings. For editors using the Astro language server directly, pass the `contentIntellisense: true` initialization parameter to enable this feature.
```

## [Experimental SVG optimization](https://docharvest.github.io/docs/astro/reference/experimental-flags/svg-optimization/)

Contents

astro

Experimental SVG optimization

Astro

Experimental SVG optimization

````

## Usage

No change to using SVG components is required to take advantage of this feature. With experimental SVG optimization enabled, all your SVG component import files will be automatically optimized:

```astro title="src/pages/index.astro"
---

---

<Logo />
````

The SVG will be optimized during the build process, resulting in smaller file sizes in your production build.

Note that this optimization applies to every SVG component import in your project. It is not possible to opt out on a per-component basis.

## SVGO

Astro provides one built-in optimizer using [SVGO](https://svgo.dev/):

#### `plugins`

**Type:** `Array<string | PluginConfig>`  
**Default:** `[]`

An array of [SVGO plugins](https://svgo.dev/docs/plugins/) that will be used to optimize your SVG component imports.

This can include SVGO's [`preset-default`](https://svgo.dev/docs/preset-default/) plugin collection, individual built-in plugins, or [custom plugins](https://svgo.dev/docs/plugins-api/).

To use a plugin’s default configuration, add its name to the array. If you need more control, use the `overrides` parameter to customize specific plugins within `preset-default`, or pass an object with a plugin's `name` to override its individual parameters.

```
svgoOptimizer({
  plugins: [
    {
      name: 'preset-default',
      params: {
        overrides: {
          convertPathData: false,
          convertTransform: {
            degPrecision: 1,
            transformPrecision: 3
          },
          inlineStyles: false
        },
      },
    },
    'removeXMLNS',
    {
      name: "removeXlink",
      params: {
        includeLegacy: true
      }
    }
  ]
});
```

#### Other configuration options

There are a few [SVGO configuration options](https://github.com/svg/svgo/blob/66d503a48c6c95661726262a3068053c429b06a9/lib/types.ts#L335), especially `floatPrecision` and `multipass`, that can be passed directly to your config object:

```
svgoOptimizer({
  multipass: true,
  floatPrecision: 2,
});
```

The `multipass` option sets whether to run the optimization engine multiple times until no further optimizations are found. The `floatPrecision` option sets the number of decimal places to preserve globally, but can be overridden for a specific plugin by specifying a custom value in its `params` property.

### Common use cases

SVGO provides an extensive [default plugin list](https://svgo.dev/docs/preset-default/) with opinionated optimizations. While using this preset is more convenient than adding each plugin individually, you may need to customize it further. For example, it may remove items or clean up too aggressively for your situation, especially when using animations.

### Preserve specific attributes

You may want to preserve certain SVG attributes and elements, such as `<style>`, that SVGO inlines or removes by default:

```
svgoOptimizer({
  plugins: [
    {
      name: 'preset-default',
      params: {
        overrides: {
          inlineStyles: false, // Preserve style elements for CSP hashing
          removeDesc: false // Keep element regardless of contents
        }
      }
    }
  ]
});
```

### Remove specific elements

You can configure plugins to remove specific unwanted elements like metadata or hidden layers. Note that many plugins are already included in `preset-default`, so you typically only need to configure their behavior:

```
svgoOptimizer({
  plugins: [
    {
      name: 'preset-default',
      params: {
        overrides: {
          removeHiddenElems: {
            isHidden: false,
            displayNone: false
          }
        },
      },
    },
    'removeRasterImages'
  ]
});
```

### Optimize for inlining in modern HTML5

Inline SVG does not require the `xmlns` attribute and can be safely converted to the SVG 2 specification. The `removeXMLNS` and `removeXlink` plugins are recommended for this purpose:

```
svgoOptimizer({
  plugins: [
    'preset-default',
    'removeXMLNS',
    {
      name: "removeXlink",
      params: {
        includeLegacy: true
      }
    }
  ]
});
```

## Building an SVG optimizer

The preferred method for implementing a custom SVG optimizer is to export a function that returns the `SvgOptimizer` object and takes the configuration as a parameter:

```

export function mySvgOptimizer(options?: Options): SvgOptimizer {
  return {
    name: "my-optimizer",
    optimize: (contents) => optimize(contents, options),
  }
}
```

### `name`

**Type:** `string`

A unique name for the optimizer, used in logs.

### `optimize()`

**Type:** `(contents: string) => string | Promise<string>`

Processes the SVG contents.

## How it works

SVG optimization happens during the build process, not at runtime:

-   In **development mode**, SVG files are not optimized to ensure faster rebuild times and a smoother development experience.
-   In **production builds**, all imported SVG files are optimized once during the build process, resulting in smaller file sizes.
-   There is **no runtime overhead** - optimized SVGs are served as pre-processed static assets.

While the optimization process may slightly increase your build times, the result is smaller file sizes and faster page loads for your users.

## [Astro Font Provider API](https://docharvest.github.io/docs/astro/reference/font-provider-reference/)

Contents

astro

Astro Font Provider API

Astro

Astro Font Provider API

The [Fonts API](/en/guides/fonts/) allows you to access fonts in a unified way. Each family requires the use of an Astro Font Provider, which either downloads font files from a remote service or loads local font files from disk.

## Built-in providers

Astro exports built-in font providers from `astro/config`:

##### `weight`

**Type:** `number | string`  
**Default:** `undefined`

A [font weight](https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight):

```
weight: 200
```

If the associated font is a [variable font](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_fonts/Variable_fonts_guide), you can specify a range of weights:

```
weight: "100 900"
```

When the value is not set, by default Astro will try to infer the value based on the first [`source`](#src).

##### `style`

**Type:** `"normal" | "italic" | "oblique"`  
**Default:** `undefined`

A [font style](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style):

```
style: "normal"
```

When the value is not set, by default Astro will try to infer the value based on the first [`source`](#src).

##### `src`

**Type:** `(string | URL | { url: string | URL; tech?: string })[]`

Font [sources](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/src). It can be a path relative to the root, a package import or a URL. URLs are particularly useful if you inject local fonts through an integration:

```
src: ["./src/assets/fonts/MyFont.woff2", "./src/assets/fonts/MyFont.woff"]
```

```
src: [new URL("./custom.ttf", import.meta.url)]
```

```
src: ["my-package/SomeFont.ttf"]
```

:::caution We recommend not putting your font files in [the `public/` directory](/en/reference/configuration-reference/#publicdir). Since Astro will copy these files into that folder at build time, this will result in duplicated files in your build output. Instead, store them somewhere else in your project, such as in [`src/`](/en/reference/configuration-reference/#srcdir). :::

You can also specify a [tech](https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/src#tech) by providing objects:

```
src: [{ url:"./src/assets/fonts/MyFont.woff2", tech: "color-COLRv1" }]
```

##### Other properties

The following options from font families are also available for local font families within variants:

-   [display](/en/reference/configuration-reference/#fontdisplay)
-   [unicodeRange](/en/reference/configuration-reference/#fontunicoderange)
-   [stretch](/en/reference/configuration-reference/#fontstretch)
-   [featureSettings](/en/reference/configuration-reference/#fontfeaturesettings)
-   [variationSettings](/en/reference/configuration-reference/#fontvariationsettings)

### NPM

Retrieves fonts from NPM packages, either from locally installed packages in `node_modules` or from a CDN:

```
provider: fontProviders.npm()
```

The provider automatically detects fonts from your `package.json` dependencies and can resolve fonts from packages like `@fontsource/*`, `@fontsource-variable/*`, and other known font packages.

#### Provider options

The NPM provider accepts the following configuration options:

##### `cdn`

**Type:** `string`  
**Default:** `'https://cdn.jsdelivr.net/npm'`

CDN to use for fetching npm packages remotely:

```
provider: fontProviders.npm({ cdn: 'https://esm.sh' })
```

##### `remote`

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

Whether to fall back to fetching from the CDN when local resolution fails. Set to `false` to only resolve from locally installed packages:

```
provider: fontProviders.npm({ remote: false })
```

#### Family options

The provider comes with the following family-specific options that can be added in the [`font.options` object](/en/reference/configuration-reference/#fontoptions).

##### `package`

**Type:** `string`  
**Default:** Auto-detected or inferred from family name

The NPM package name. When not specified, the provider will try to find the font family in known font package patterns or infer based on Fontsource conventions:

```
{
  // ...
  provider: fontProviders.npm(),
  options: {
    package: '@fontsource/roboto'
  }
}
```

##### `version`

**Type:** `string`  
**Default:** `'latest'`

The version of the package (used for CDN resolution only):

```
{
  // ...
  provider: fontProviders.npm(),
  options: {
    version: '5.0.0'
  }
}
```

##### `file`

**Type:** `string`  
**Default:** `'index.css'`

The entry CSS file to parse from the package:

```
{
  // ...
  provider: fontProviders.npm(),
  options: {
    file: 'latin.css'
  }
}
```

## Building a font provider

If you do not wish to use one of the [built-in providers](#built-in-providers) (e.g. you want to use a [3rd-party unifont provider](#supporting-a-3rd-party-unifont-provider) or [build something for a private registry](#supporting-a-private-registry)), you can build your own.

The preferred method for implementing a custom font provider is to export a function that returns [the `FontProvider` object](#the-font-provider-object) and takes the [configuration](#config) as a parameter.

### The font provider object

A `FontProvider` is an object containing required [`name`](#name) and [`resolveFont()`](#resolvefont) properties. It also has optional [`config`](#config), [`init()`](#init) and [`listFonts()`](#listfonts) properties available.

The `FontProvider` type accepts a generic for family [options](/en/reference/configuration-reference/#fontoptions).

#### `name`

**Type:** `string`

A unique name for the provider, used in logs and for identification.

#### `resolveFont()`

**Type:** `(options: ResolveFontOptions) => Awaitable<{ fonts: FontFaceData[] } | undefined>`  

Used to retrieve and return font face data based on the given options.

#### `config`

**Type:** `Record<string, any>`  
**Default:** `undefined`

A serializable object, used for identification.

#### `init()`

**Type:** `(context: FontProviderInitContext) => Awaitable<void>`  
**Default:** `undefined`

Optional callback, used to perform any initialization logic.

##### `context.storage`

**Type:** `Storage`

Useful for caching.

##### `context.root`

**Type:** `URL`

The project root, useful for resolving local files paths.

#### `listFonts()`

**Type:** `() => Awaitable<string[] | undefined>`  
**Default:** `undefined`

Optional callback, used to return the list of available font names.

### Supporting a private registry

The following example defines a font provider for a private registry:

    ```

    },
    listFonts: () => {
      return Object.keys(data);
    },
    resolveFont: ({ familyName, ...rest }) => {
      const fonts = data[familyName];
      if (fonts) {
        return { fonts };
      }
      return undefined;
    },
  };
}
```

```

}

    },
    listFonts: () => {
      return Object.keys(data);
    },
    resolveFont: ({ familyName, ...rest }) => {
      const fonts = data[familyName];
      if (fonts) {
        return { fonts };
      }
      return undefined;
    },
  };
}
```

```

}

    },
    listFonts: () => {
      return Object.keys(data);
    },
    // options is typed as FamilyOptions | undefined
    resolveFont: ({ familyName, options, ...rest }) => {
      const fonts = data[familyName];
      if (fonts) {
        return { fonts };
      }
      return undefined;
    },
  };
}
```

You can then register this font provider in the Astro config:

### Supporting a 3rd-party unifont provider

You can define an Astro font provider using a unifont provider under the hood:

	```

	let initializedProvider: InitializedProvider | undefined;
	return {
		name: provider._name,
		async init(context) {
			initializedProvider = await provider(context);
		},
		async resolveFont({ familyName, ...rest }) {
			return await initializedProvider?.resolveFont(familyName, rest);
		},
		async listFonts() {
			return await initializedProvider?.listFonts?.();
		},
	};
}
```

	```

	let initializedProvider: InitializedProvider | undefined;
	return {
		name: provider._name,
		config,
		async init(context) {
			initializedProvider = await provider(context);
		},
		async resolveFont({ familyName, ...rest }) {
			return await initializedProvider?.resolveFont(familyName, rest);
		},
		async listFonts() {
			return await initializedProvider?.listFonts?.();
		},
	};
}
```

	```

	let initializedProvider: InitializedProvider<AcmeFamilyOptions> | undefined;
	return {
		name: provider._name,
		async init(context) {
			initializedProvider = await provider(context);
		},
		async resolveFont({ familyName, ...rest }) {
			return await initializedProvider?.resolveFont(familyName, rest);
		},
		async listFonts() {
			return await initializedProvider?.listFonts?.();
		},
	};
}
```

You can then register this font provider in the Astro config:

## [Image Service API](https://docharvest.github.io/docs/astro/reference/image-service-reference/)

Contents

astro

Image Service API

Astro

Image Service API

`astro:assets` was designed to make it easy for any image optimization service to build a service on top of Astro.

## What is an Image Service?

Astro provides two types of image services: Local and External.

-   **Local services** handle image transformations directly at build for static sites, or at runtime both in development mode and for on-demand rendering. These are often wrappers around libraries like Sharp, ImageMagick, or Squoosh. In dev mode and in production routes rendered on demand, local services use an API endpoint to do the transformation.
-   **External services** point to URLs and can add support for services such as Cloudinary, ImageKit, Vercel, or any [RIAPI](https://github.com/riapi/riapi)\-compliant server.

## Building using the Image Services API

Service definitions take the shape of an exported default object with various required methods ("hooks").

External services provide a `getURL()` that points to the `src` of the output `<img>` tag.

Local services provide a `transform()` method to perform transformations on your image, and `getURL()` and `parseURL()` methods to use an endpoint for dev mode and when rendered on demand.

Both types of services can provide `getHTMLAttributes()` to determine the other attributes of the output `<img>` and `validateOptions()` to validate and augment the passed options.

### External Services

An external service points to a remote URL to be used as the `src` attribute of the final `<img>` tag. This remote URL is responsible for downloading, transforming, and returning the image.

```

const service: ExternalImageService = {
  validateOptions(options: ImageTransform, imageConfig: AstroConfig['image']) {
    const serviceConfig = imageConfig.service.config;

    // Enforce the user set max width.
    if (options.width && options.width > serviceConfig.maxWidth) {
      console.warn(`Image width ${options.width} exceeds max width ${serviceConfig.maxWidth}. Falling back to max width.`);
      options.width = serviceConfig.maxWidth;
    }

    return options;
  },
  getURL(options, imageConfig) {
    return `https://mysupercdn.com/${options.src}?q=${options.quality}&w=${options.width}&h=${options.height}`;
  },
  getHTMLAttributes(options, imageConfig) {
    const { src, format, quality, ...attributes } = options;
		return {
			...attributes,
			loading: options.loading ?? 'lazy',
			decoding: options.decoding ?? 'async',
		};
	}
};

```

### Local Services

To create your own local service, you can point to the [built-in endpoint](https://github.com/withastro/astro/blob/main/packages/astro/src/assets/endpoint/generic.ts) (`/_image`), or you can additionally create your own endpoint that can call the service's methods.

```

const service: LocalImageService<AstroConfig["image"]> = {
  getURL(options: ImageTransform, imageConfig) {
    const searchParams = new URLSearchParams();
		searchParams.append('href', typeof options.src === "string" ? options.src : options.src.src);
		options.width && searchParams.append('w', options.width.toString());
		options.height && searchParams.append('h', options.height.toString());
		options.quality && searchParams.append('q', options.quality.toString());
		options.format && searchParams.append('f', options.format);
    return `/my_custom_endpoint_that_transforms_images?${searchParams}`;
    // Or use the built-in endpoint, which will call your parseURL and transform functions:
    // return `/_image?${searchParams}`;
  },
  parseURL(url: URL, imageConfig) {
    const params = url.searchParams;
    return {
      src: params.get('href')!,
      width: params.has('w') ? parseInt(params.get('w')!) : undefined,
      height: params.has('h') ? parseInt(params.get('h')!) : undefined,
			format: params.get('f'),
      quality: params.get('q'),
    };
  },
  async transform(inputBuffer: Uint8Array, options: { src: string, [key: string]: any }, imageConfig) {
    const { buffer } = await mySuperLibraryThatEncodesImages(options);
    return {
      data: buffer,
      format: options.format,
    };
  },
  getHTMLAttributes(options, imageConfig) {
		let targetWidth = options.width;
		let targetHeight = options.height;
		if (typeof options.src === "object") {
			const aspectRatio = options.src.width / options.src.height;

			if (targetHeight && !targetWidth) {
				targetWidth = Math.round(targetHeight * aspectRatio);
			} else if (targetWidth && !targetHeight) {
				targetHeight = Math.round(targetWidth / aspectRatio);
			}
		}

		const { src, width, height, format, quality, ...attributes } = options;

		return {
			...attributes,
			width: targetWidth,
			height: targetHeight,
			loading: attributes.loading ?? 'lazy',
			decoding: attributes.decoding ?? 'async',
		};
	},
  propertiesToHash: ['src', 'width', 'height', 'format', 'quality'], 
};
```

At build time for static sites and pre-rendered routes, both `<Image />` and `getImage(options)` call the `transform()` function. They pass options either through component attributes or an `options` argument, respectively. The transformed images will be built to a `dist/_astro` folder. Their file names will contain a hash of the properties passed to `propertiesToHash`. This property is optional and will default to `['src', 'width', 'height', 'format', 'quality']`. If your custom image service has more options that change the generated images, add these to the array.

In dev mode and when using an adapter to render on demand, Astro doesn't know ahead of time which images need to be optimized. Astro uses a GET endpoint (by default, `/_image`) to process the images at runtime. `<Image />` and `getImage()` pass their options to `getURL()`, which will return the endpoint URL. Then, the endpoint calls `parseURL()` and passes the resulting properties to `transform()`.

#### getConfiguredImageService & imageConfig

If you implement your own endpoint as an Astro endpoint, you can use [`getConfiguredImageService`](/en/reference/modules/astro-assets/#getconfiguredimageservice) and [`imageConfig`](/en/reference/modules/astro-assets/#imageconfig) to call your service's `parseURL` and `transform` methods and provide the image config.

To access the image service config ([`image.service.config`](/en/reference/configuration-reference/#imageservice)), you can use `imageConfig.service.config`.

```

  const imageTransform = imageService.parseURL(new URL(request.url), imageConfig);
  // ... fetch the image from imageTransform.src and store it in inputBuffer
  const { data, format } = await imageService.transform(inputBuffer, imageTransform, imageConfig);
  return new Response(data, {
			status: 200,
			headers: {
				'Content-Type': mime.getType(format) || ''
      }
    }
  );
}
```

[See the built-in endpoint](https://github.com/withastro/astro/blob/main/packages/astro/src/assets/endpoint/generic.ts) for a full example.

## Hooks

### `getURL()`

**Type:** `(options: [ImageTransform](/en/reference/modules/astro-assets/#imagetransform), imageConfig: [AstroConfig['image']](/en/reference/configuration-reference/#image-options)) => string | Promise<string>`  

**Required for local and external services**

For local services, this hook returns the URL of the endpoint that generates your image (for on-demand rendering and in dev mode). It is unused during build. The local endpoint that `getURL()` points to may call both `parseURL()` and `transform()`.

For external services, this hook returns the final URL of the image.

For both types of services, `options` are the properties passed by the user as attributes of the `<Image />` component or as options to `getImage()`.

### `parseURL()`

**Type:** `(url: URL, imageConfig: [AstroConfig['image']](/en/reference/configuration-reference/#image-options)) => { src: string, [key: string]: any } | undefined | Promise<{ src: string, [key: string]: any }> | Promise<undefined>`  

**Required for local services only; unavailable for external services**

This hook parses the generated URLs by `getURL()` back into an object with the different properties to be used by `transform` (for on-demand rendering and in dev mode). It is unused during build.

### `transform()`

**Type:** `(inputBuffer: Uint8Array, options: { src: string, [key: string]: any }, imageConfig: [AstroConfig['image']](/en/reference/configuration-reference/#image-options)) => Promise<{ data: Uint8Array; format: [ImageOutputFormat](/en/reference/modules/astro-assets/#imageoutputformat) }>`  

**Required for local services only; unavailable for external services**

This hook transforms and returns the image and is called during the build to create the final asset files.

You must return a `format` to ensure that the proper MIME type is served to users for on-demand rendering and development mode.

### `getHTMLAttributes()`

**Type:** `(options: [ImageTransform](/en/reference/modules/astro-assets/#imagetransform), imageConfig: [AstroConfig['image']](/en/reference/configuration-reference/#image-options) ) => Record<string, any> | Promise<Record<string, any>>`  

**Optional for both local and external services**

This hook returns all additional attributes used to render the image as HTML, based on the parameters passed by the user (`options`).

### `getSrcSet()`

**Type:** `(options: [ImageTransform](/en/reference/modules/astro-assets/#imagetransform), imageConfig: [AstroConfig['image']](/en/reference/configuration-reference/#image-options) ) => UnresolvedSrcSetValue[] | Promise<UnresolvedSrcSetValue[]>`  

**Optional for both local and external services.**

This hook generates multiple variants of the specified image, for example, to generate a `srcset` attribute on an `<img>` or `<picture>`'s `source`.

This hook returns an array of objects with the following properties:

```

	descriptor?: string;
	attributes?: Record<string, any>;
};
```

### `validateOptions()`

**Type:** `(options: [ImageTransform](/en/reference/modules/astro-assets/#imagetransform), imageConfig: [AstroConfig['image']](/en/reference/configuration-reference/#image-options) ) => ImageTransform | Promise<ImageTransform>`

**Optional for both local and external services**

This hook allows you to validate and augment the options passed by the user. This is useful for setting default options, or telling the user that a parameter is required.

[See how `validateOptions()` is used in Astro built-in services](https://github.com/withastro/astro/blob/0ab6bad7dffd413c975ab00e545f8bc150f6a92f/packages/astro/src/assets/services/service.ts#L124).

### `getRemoteSize()`

**Type:** `(url: string, imageConfig: [AstroConfig['image']](/en/reference/configuration-reference/#image-options) ) => Omit<[ImageMetadata](/en/reference/modules/astro-assets/#imagemetadata-1), 'src' | 'fsPath'> | Promise<Omit<[ImageMetadata](/en/reference/modules/astro-assets/#imagemetadata-1), 'src' | 'fsPath'>>`

**Optional for both local and external services**

This hook allows you to extend the behavior of [`inferRemoteSize()`](/en/reference/modules/astro-assets/#inferremotesize). This is useful for reducing network traffic by caching images, or when you can predict image information from the image URL.

## User configuration

Configure the image service to use in `astro.config.mjs`. The config takes the following form:

## Typing custom image service props

If your image service supports additional props in Astro’s `<Image>` component, `<Picture>` component, or the `getImage()` function, you can add types for these by extending the `Astro.CustomImageProps` interface.

For example, to add a custom `blur` prop that your image service supports:

```
declare namespace Astro {
  interface CustomImageProps {
    /** Apply a Gaussian blur with this radius to the image. */
    blur?: number;
  }
}
```

You can expose these types to users by making your image service an [Astro integration](/en/reference/integrations-reference/) and using the [`injectTypes()`](/en/reference/integrations-reference/#injecttypes-option) helper.

Then, users will be able to get autocomplete and type safety for your custom props:

```
<Image blur="yes" src={myPhoto}  />
//     ^^^^^^^^^^
//     Type 'string' is not assignable to type 'number | undefined'.
```

## [Astro Integration API](https://docharvest.github.io/docs/astro/reference/integrations-reference/)



## [Legacy flags](https://docharvest.github.io/docs/astro/reference/legacy-flags/)

Contents

astro

Legacy flags

Astro

Legacy flags

```

This flag preserves some legacy v4 content collections features:

- Supports `type: 'content'` and `type: 'data'` without loaders
- Preserves legacy entry API: `entry.slug` and `entry.render()`
- Uses path-based entry IDs instead of slug-based IDs

This is a temporary migration helper. Migrate collections to the Content Layer API, then disable this flag.
```

## [Astro Logger API](https://docharvest.github.io/docs/astro/reference/logger-reference/)

Contents

astro

Astro Logger API

Astro

Astro Logger API

The Logger API provides greater control over Astro's logging infrastructure. This allows you to replace the default console output with custom logging implementations and connect to log aggregation services.

This API includes three ready-to-use loggers and allows you to integrate your own loggers and compose them.

## Custom loggers

You can create a custom logger by providing the correct configuration to the `logger` setting. It accepts an object with a mandatory `entrypoint`, the module where the logger is exported, and an optional configuration to pass to the logger. The configuration must be serializable.

The logger function must be exported as `default`.

When you define a custom logger, you are in charge of all logs, even the ones emitted by Astro.

The following example defines a custom logger exported by the `@org/custom-logger` package and accepting only one parameter to configure the logging `level`:

The following example implements a minimal logger returning an [`AstroLoggerDestination` object](#astrologgerdestination) with the required `write()` function:

```

type LoggerOptions = {
  level: AstroLoggerLevel
}

function orgLogger(options: LoggerOptions = {}): AstroLoggerDestination {
  const { level = 'info' } = options;
  return {
    write(message: AstroLoggerMessage) {
      // Use this utility to understand if the message should be printed 
      if (matchesLevel(message.level, level)) {
        // log message somewhere and take the level into consideration
      }
    }
  }
}
```

You can now add your own logs during the rendering of a page using [the runtime APIs](/en/reference/api-reference/#logger).

## Log level

A level is an internal, arbitrary score assigned to each message. When a logger is configured with a certain level, only the messages with a level equal to or higher are printed.

There are three levels, from the highest to the lowest score:

1.  `error`
2.  `warn`
3.  `info`

The following example configures the JSON logger to print only messages that have the `warn` level or higher:

The `astro/logger` package exposes a [`matchesLevel()`](#matcheslevel) helper to check the log level. This can be useful when [building a custom logger](#custom-loggers).

```

matchesLevel("error", "info");
```

## Built-in loggers

Astro offers built-in loggers that applications can use.

### `logHandlers.json()`

A logger that outputs messages in a JSON format. A log would look like this:

```
{ "message": "<the message>", "label": "router", "level": "info", "time": "<UNIX timestamp>"  }
```

#### JSON logger options

\*\*Type:\*\* \`{ pretty: boolean; level: AstroLoggerLevel; }\`  
\*\*Default:\*\* \`{ pretty: false, level: 'info' }\`

The `json` logger accepts the following options:

-   `pretty`: when `true`, the JSON log is printed on multiple lines. Defaults to `false`.
-   `level`: the [level](#log-level) of logs that should be printed.

### `logHandlers.console()`

A logger that prints messages using the `console` as its destination. Based on the level of the message, it uses different channels:

-   `error` messages are printed using `console.error()`.
-   `warn` messages are printed using `console.warn()`.
-   `info` messages are printed using `console.info()`.

#### Console logger options

\*\*Type:\*\* \`{ level: AstroLoggerLevel }\`  
\*\*Default:\*\* \`{ level: 'info' }\`

The `console` logger accepts the following options:

-   `level`: the [level](#log-level) of logs that should be printed.

### `logHandlers.node()`

A logger that prints messages to [`process.stdout`](https://nodejs.org/api/process.html#processstdout) and [`process.stderr`](https://nodejs.org/api/process.html#processstderr). Level `error` messages are printed to `stderr`, while the others are printed to `stdout`.

This is Astro's default logger.

#### Node logger options

\*\*Type:\*\* \`{ level: AstroLoggerLevel }\`  
\*\*Default:\*\* \`{ level: 'info' }\`

The `node` logger accepts the following options:

-   `level`: the [level](#log-level) of logs that should be printed.

### `logHandlers.compose()`

A particular function that allows configuring multiple loggers in an arbitrary order. The same message is broadcast to all loggers.

The following example composes the console logger and JSON logger using the default log level:

## Types reference

The following types can be imported from the `astro` specifier.

### `AstroLoggerDestination`

This is the interface that custom loggers must implement.

#### `AstroLoggerDestination.write()`

**Type:** `(message: AstroLoggerMessage) => void`

A mandatory method called for each log and accepting an [`AstroLoggerMessage`](#astrologgermessage).

#### `AstroLoggerDestination.flush()`

**Type:** `() => Promise<void> | void`

An optional function called at the end of each request. This is useful for advanced loggers that need to flush log messages while keeping the connection to the destination alive.

#### `AstroLoggerDestination.close()`

**Type:** `() => Promise<void> | void`

An optional function called before a server is shut down. This function is usually called by adapters such as `@astrojs/node`.

### `AstroLoggerLevel`

**Type:** `'debug' |'info' |'warn' | 'error' | 'silent'`

Specifies the verbosity level of logs:

-   `info`, `warn`, and `error`: defines the minimal [log level](#log-level) to print.
-   `silent`: this is equivalent to the [`--silent` CLI flag](/en/reference/cli-reference/#--silent) and enables silent logging.
-   `debug`: this is equivalent to the [`--debug` CLI flag](/en/reference/cli-reference/#--verbose) and enables verbose logging, including Vite logging.

### `AstroLoggerMessage`

**Type:** `{ label: string | null; level: AstroLoggerLevel; message: string; newLine: boolean; }`

The incoming object from the [`AstroLoggerDestination.write()`](#astrologgerdestinationwrite) function:

-   `message`: the message being logged.
-   `level`: the level of the message.
-   `label`: an arbitrary label assigned to the log message.
-   `newLine`: whether this message should add a trailing newline.

## APIs reference

The following APIs can be imported from the `astro/logger` specifier.

### `matchesLevel()`

**Type:** `matchesLevel(messageLevel: AstroLoggerLevel, configuredLevel: AstroLoggerLevel) => boolean`

Given two [log levels](#log-level), it returns whether the first level matches the second level.

```

matchesLevel("error", "info"); // true
matchesLevel("info", "error"); // false
```

## [Actions API Reference](https://docharvest.github.io/docs/astro/reference/modules/astro-actions/)

Contents

astro

Actions API Reference

Astro

Actions API Reference

Actions help you build a type-safe backend you can call from client code and HTML forms. All utilities to define and call actions are exposed by the `astro:actions` module. For examples and usage instructions, [see the Actions guide](/en/guides/actions/).

## Imports from `astro:actions`

### `defineAction()`

**Type:** `({ accept, input, handler }) => [ActionClient](#actionclient)`

A utility to define new actions in the `src/actions/index.ts` file. This accepts a [`handler()`](#handler-property) function containing the server logic to run, and an optional [`input`](#input-validator) property to validate input parameters at runtime.

```

}
</script>
```

In order for Astro to recognize this property, you may need to restart the dev server or [run the `astro sync` command](/en/reference/cli-reference/#astro-sync) (`s + enter`).

### `isInputError()`

**Type:** `(error?: unknown) => boolean`

A utility used to check whether [an `ActionError`](#actionerror) is an input validation error. When the `input` validator is a `z.object()`, input errors include a `fields` object with error messages grouped by name.

See the [form input errors guide](/en/guides/actions/#displaying-form-input-errors) for more on using `isInputError()`.

### `isActionError()`

**Type:** `(error?: unknown) => boolean`

A utility to check whether your action raised [an `ActionError`](#actionerror) within the [handler property](#handler-property). This is useful when narrowing the type of a generic error.

```
---
---

<script>

async () => {
  const { data, error } = await actions.myAction({ /* ... */ });
  if (isActionError(error)) {
    // Handle action-specific errors
    console.log(error.code);
  }
}
</script>
```

### `ActionError`

The `ActionError()` constructor is used to create errors thrown by an action `handler`. This accepts a `code` property describing the error that occurred (example: `"UNAUTHORIZED"`), and an optional `message` property with further details.

The following example creates a new `ActionError` when the user is not logged in:

```

      }
      return locals.user;
    },
  }),
}
```

You can also use `ActionError` to narrow the error type when handling the results of an action:

```
---
---

<script>

async () => {
  const { data, error } = await actions.myAction({ /* ... */ });
  if (error instanceof ActionError) {
    // Handle action-specific errors
    console.log(error.code);
  }
}
</script>
```

#### `code`

**Type:** `[ActionErrorCode](#actionerrorcode)`

Defines a human-readable version of an [HTTP status code](#actionerrorcode).

#### `message`

**Type:** `string`

An optional property to describe the error (e.g. "User must be logged in.").

#### `stack`

**Type:** `string`

An optional property to pass the stack trace.

### `getActionContext()`

**Type:** `(context: [APIContext](/en/reference/api-reference/)) => AstroActionContext`  

A function called from your middleware handler to retrieve information about inbound action requests. This returns an `action` object with information about the request, a `deserializeActionResult()` method, and the `setActionResult()` and `serializeActionResult()` functions to programmatically set the value returned by `Astro.getActionResult()`.

`getActionContext()` lets you programmatically get and set action results using middleware, allowing you to persist action results from HTML forms, gate action requests with added security checks, and more.

```

  if (action?.calledFrom === 'form') {
    const result = await action.handler();
    setActionResult(action.name, serializeActionResult(result));
  }
  return next();
});
```

#### `action`

**Type:** `{ calledFrom: "rpc" | "form"; name: string; handler: () => Promise<[SafeResult](#saferesult)>; } | undefined`

An object containing information about an inbound action request. It is available from [`getActionContext()`](#getactioncontext), and provides the action `name`, `handler`, and whether the action was called from a client-side RPC function (e.g. `actions.newsletter()`) or an HTML form action.

```

  if (action?.calledFrom === 'rpc' && action.name.startsWith('private')) {
    // Check for a valid session token
  }
  // ...
});
```

##### `action.calledFrom`

**Type:** `"rpc" | "form"`

Whether an action was called using an RPC function or an HTML form action.

##### `action.name`

**Type:** `string`

The name of the action. Useful to track the source of an action result during a redirect.

##### `action.handler()`

**Type:** `() => Promise<[SafeResult](#saferesult)>`

A method to programmatically call an action to get the result.

#### `setActionResult()`

**Type:** `(actionName: string, actionResult: SerializedActionResult) => void`

A function to programmatically set the value returned by `Astro.getActionResult()` in middleware. It is passed the action name and an action result serialized by [`serializeActionResult()`](#serializeactionresult). Calling this function from middleware will disable Astro's own action result handling.

This is useful when calling actions from an HTML form to persist and load results from a session.

```

  if (action?.calledFrom === 'form') {
    const result = await action.handler();
    // ... handle the action result
    setActionResult(action.name, serializeActionResult(result));
  }
  return next();
});
```

See the [advanced sessions guide](/en/guides/actions/#advanced-persist-action-results-with-a-session) for a sample implementation using Netlify Blob.

#### `serializeActionResult()`

**Type:** `(res: [SafeResult](#saferesult)) => SerializedActionResult`

Serializes an action result to JSON for persistence. This is required to properly handle non-JSON return values like `Map` or `Date` as well as the `ActionError` object.

Call this function when serializing an action result to be passed to `setActionResult()`:

```

  if (action) {
    const result = await action.handler();
    setActionResult(action.name, serializeActionResult(result));
  }
  // ...
});
```

#### `deserializeActionResult()`

**Type:** `(res: SerializedActionResult) => [SafeResult](#saferesult)`

Reverses the effect of [`serializeActionResult()`](#serializeactionresult) and returns an action result to its original state. This is useful to access the `data` and `error` objects on a serialized action result.

### `getActionPath()`

**Type:** `(action: [ActionClient](#actionclient)) => string`

A utility that accepts an action and returns a URL path so you can execute an action call as a `fetch()` operation directly. This allows you to provide details such as custom headers when you call your action. Then, you can [handle the custom-formatted returned data](/en/guides/actions/#handling-returned-data) as needed, just as if you had called an action directly.

This example shows how to call a defined `like` action passing the `Authorization` header and the [`keepalive`](https://developer.mozilla.org/en-US/docs/Web/API/Request/keepalive) option:

```
<script>

  link.delete(ACTION_QUERY_PARAMS.actionName);
  link.delete(ACTION_QUERY_PARAMS.actionPayload);

  return redirect(link, 303);
};
```

## `astro:actions` types

### `ActionAPIContext`

A subset of the [Astro context object](/en/reference/api-reference/). The following properties are not available: `callAction`, `getActionResult`, `props`, and `redirect`.

### `ActionClient`

**Types:**

-   `(input?: any) => Promise<[SafeResult](#saferesult)>`
-   `{ queryString?: string; orThrow: (input?: any) => Promise<Awaited<TOutput>>; }`

Represents an action to be called on the client. You can use it as a function that accepts input data and returns a Promise with a [`SafeResult` object](#saferesult) containing the action result or validation errors.

The following example shows how you can provide error handling with an `if` statement when incrementing the like count fails:

```
---
---

<!-- your template -->

<script>

const post = document.querySelector('article');
const button = document.querySelector('button');
button?.addEventListener('click', async () => {
  const { data: updatedLikes, error } = await actions.likePost({ postId: post?.id });
  if (error) {
    /* handle errors */
  }
})
</script>
```

Alternatively, you can use it as an object giving you access to the `queryString` and an alternative `orThrow()` method.

#### `ActionClient.queryString`

**Type:** `string`

A string representation of the action that can be used to construct form action URLs. This can be useful when your form component is used in multiple places but you need to redirect to a different URL on submit.

The following example uses `queryString` to construct a URL that will be passed to the form `action` attribute through a custom prop:

```
---

const feedbackUrl = new URL('/feedback', Astro.url);
feedbackUrl.search = actions.myAction.queryString;
---
<FeedbackForm sendTo={feedbackUrl.pathname} />
```

#### `ActionClient.orThrow()`

**Type:** `(input?: any) => Promise<Awaited<TOutput>>`

A method that throws an error on failure instead of returning the errors. This is useful when you want exceptions rather than error handling.

The following example uses `orThrow()` to skip error handling when incrementing the like count fails:

```
---
---

<!-- your template -->

<script>

const post = document.querySelector('article');
const button = document.querySelector('button');
button?.addEventListener('click', async () => {
  const updatedLikes = await actions.likePost.orThrow({ postId: post?.id });
})
</script>
```

### `ActionErrorCode`

**Type:** `string`

A union type of standard HTTP status codes [defined by IANA](https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml) using the human-readable versions as uppercase strings separated by an underscore (e.g. `BAD_REQUEST` or `PAYLOAD_TOO_LARGE`).

### `ActionInputSchema`

**Type:** `ZodType`

A utility type that automatically infers the TypeScript type of an action's input based on its Zod schema. This can be useful to reference an action's [`input` validator type](#input-validator) as an object in your own type definitions.

Returns `never` when [`input` validator](#input-validator) is omitted.

The following example uses `ActionInputSchema` on an action named `contact` to:

-   Retrieve the Zod schema type for the input of the action.
-   Retrieve the expected input type of the action's validator.

```
---

type ContactSchema = ActionInputSchema<typeof actions.contact>;
type ContactInput = z.input<ContactSchema>;
---
```

### `ActionReturnType`

**Type:** `Awaited<ReturnType<ActionHandler>>`

A utility type that extracts the output type from [an action handler](#defineaction). This unwraps both the `Promise` (if the handler is async) and the `ReturnType` to give you the [actual output type](#saferesult). This can be useful if you need to reference an action's output type in your own type definitions.

The following example uses `ActionReturnType` to retrieve the expected output type for an action named `contact`:

```
---

type ContactResult = ActionReturnType<typeof actions.contact>;
---
```

### `SafeResult`

**Type:** `{ data: TOutput, error: undefined } | { data: undefined, error: ActionError }`

Represents the result of an action call:

-   on success, `data` contains the output of the action and `error` is `undefined`.
-   on failure, `error` contains an [`ActionError`](#actionerror) with validation errors or runtime errors, and `data` is `undefined`.

## [Adapter Server Entrypoint API Reference](https://docharvest.github.io/docs/astro/reference/modules/astro-app/)

Contents

astro

Adapter Server Entrypoint API Reference

Astro

Adapter Server Entrypoint API Reference

This module helps adapter authors [build a server entrypoint](/en/reference/adapter-reference/#building-a-server-entrypoint) while supporting pages rendered in development mode or that have been prebuilt through `astro build`.

`astro/app` is used internally for [Astro's official server adapters](/en/guides/on-demand-rendering/#server-adapters), and is also publicly available for you to build a custom adapter for your specific runtime or deploy host.

:::tip\[Publishing your adapter\] Use the appropriate keywords when you [publish your adapter to NPM](/en/guides/integrations/#categories) so that your adapter will be listed in our [Integrations Directory](https://astro.build/integrations/). :::

Astro uses the standard [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) and [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) objects. Hosts using a different API for requests/responses should convert to these types in their adapter. For example, Astro exposes [helpers to work with NodeJS](#imports-from-astroappnode).

## Imports from `astro/app/entrypoint`

The following helpers are imported from the `entrypoint` directory in the app module:

### `createApp()`

**Type:** `(options?: { streaming: boolean }) => [App](#the-app-instance)`  

Returns an [`App` instance](#the-app-instance) that includes methods to work with standard Request and Response objects when [building an adapter's server entrypoint](/en/reference/adapter-reference/#building-a-server-entrypoint).

```

const app = createApp();

addEventListener("fetch", event => {
  event.respondWith(
    app.render(event.request)
  );
});
```

#### Options

The `createApp()` function accepts the following options.

##### `options.streaming`

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

Defines whether HTML streaming is enabled. In most cases, disabling streaming is not recommended as it improves performance and generally provides a better visitor experience.

HTML streaming breaks a document into chunks to send over the network and render on the page in order. This normally results in visitors seeing your HTML as fast as possible, but factors such as network conditions and waiting for data fetches can block page rendering.

However, when you need to disable HTML streaming (e.g. your host only supports non-streamed HTML caching at the CDN level), you can opt out of the default behavior by passing `streaming: false` to `createApp()`:

##### `app.match()`

**Type:** `(request: Request, allowPrerenderedRoutes = false) => [RouteData](/en/reference/integrations-reference/#routedata) | undefined`

Determines whether a request is matched by the Astro app's routing rules.

```
if(app.match(request)) {
  const response = await app.render(request);
}
```

You can usually call `app.render(request)` without using `.match` because Astro handles 404s if you provide a `404.astro` file. Use `app.match(request)` if you want to handle 404s in a different way.

By default, prerendered routes aren't returned, even if they are matched. You can change this behavior by using `true` as the second argument.

##### `app.getAdapterLogger()`

**Type:** `() => [AstroIntegrationLogger](/en/reference/integrations-reference/#astrointegrationlogger)`  

Returns an [instance of the Astro logger](/en/reference/integrations-reference/#astrointegrationlogger) available to the adapter's runtime environment.

```
const logger = app.getAdapterLogger();
try {
  /* Some logic that can throw */
} catch {
  logger.error("Your custom error message using Astro logger.");
}
```

##### `app.getAllowedDomains()`

**Type:** `() => Partial<[RemotePattern](/en/reference/modules/astro-assets/#remotepattern)>[] | undefined`  

Returns a list of permitted host patterns for incoming requests when using on-demand rendering [as configured in `security.allowedDomains`](/en/reference/configuration-reference/#securityalloweddomains).

##### `app.removeBase()`

**Type:** `(pathname: string) => string`  

Removes the base from the given path. This is useful when you need to look up assets from the filesystem.

##### `app.setCookieHeaders()`

**Type:** `(response: Response) => Generator<string, string[], any>`  

Returns a generator that yields individual cookie header values from a `Response` object. This is used to properly handle multiple cookies that may have been set during request processing.

The following example appends a `Set-Cookie` header for each header obtained from a response:

```
for (const setCookieHeader of app.setCookieHeaders(response)) {
  response.headers.append('Set-Cookie', setCookieHeader);
}
```

## Imports from `astro/app/node`

The following helpers are imported from the `node` directory in the app module:

This module is used in conjunction with [the methods provided by `createApp()`](#createapp) to convert a [NodeJS `IncomingMessage`](https://nodejs.org/api/http.html#class-httpincomingmessage) into a web-standard `Request` and stream a web-standard `Response` into a [NodeJS `ServerResponse`](https://nodejs.org/api/http.html#class-httpserverresponse).

### `createRequest()`

**Type:** `(req: NodeRequest, options?: { skipBody?: boolean; allowedDomains?: Partial<[RemotePattern](/en/reference/modules/astro-assets/#remotepattern)>[]; }) => Request`  

Converts a NodeJS `IncomingMessage` into a standard `Request` object. An optional object can be passed as a second argument to further control how the request is created. This is useful if you want to ignore the body (defaults to `false`) or pass the configured [`allowedDomains`](/en/reference/configuration-reference/#securityalloweddomains) to the request.

The following example creates a `Request` and passes it to [`app.render()`](#apprender):

```

const app = createApp();

const server = createServer(async (req, res) => {
  const request = createRequest(req);
  const response = await app.render(request);
})
```

### `writeResponse()`

**Type:** `(source: Response, destination: ServerResponse) => Promise<ServerResponse<IncomingMessage> | undefined>`  

Streams a web-standard `Response` into a NodeJS server response. This function takes a `Response` object and the initial `ServerResponse` before returning a promise of a `ServerResponse` object.

The following example creates a `Request`, passes it to [`app.render()`](#apprender), and writes the response:

```

const app = createApp();

const server = createServer(async (req, res) => {
  const request = createRequest(req);
  const response = await app.render(request);
  await writeResponse(response, res);
})
```

## `astro/app` types

The following types are imported from the app module:

### `RenderOptions`

**Type:** `{addCookieHeader?: boolean; clientAddress?: string; locals?: object; prerenderedErrorPageFetch?: (url: ErrorPagePath) => Promise<Response>; waitUntil?: (promise: Promise<unknown>) => void; routeData?: RouteData;}`

Describes the options for controlling the routes rendering.

#### `RenderOptions.addCookieHeader`

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

Whether or not to automatically add all cookies written by [`Astro.cookie.set()`](/en/reference/api-reference/#cookiesset) to the response headers.

When set to `true`, they will be added to the `Set-Cookie` header of the response as comma-separated key-value pairs. You can use the standard `response.headers.getSetCookie()` API to read them individually.

```
const response = await app.render(request, { addCookieHeader: true });
```

#### `RenderOptions.clientAddress`

**Type:** `string`  
**Default:** `request[Symbol.for("astro.clientAddress")]`

The client IP address that will be made available as [`Astro.clientAddress`](/en/reference/api-reference/#clientaddress) in pages, and as `ctx.clientAddress` in API routes and middleware.

The example below reads the `x-forwarded-for` header and passes it as `clientAddress`. This value becomes available to the user as `Astro.clientAddress`.

```
const clientAddress = request.headers.get("x-forwarded-for");
const response = await app.render(request, { clientAddress });
```

#### `RenderOptions.locals`

**Type:** `object`

The [`context.locals` object](/en/reference/api-reference/#locals) used to store and access information during the lifecycle of a request.

The example below reads a header named `x-private-header`, attempts to parse it as an object, and passes it to `locals`, which can then be passed to any [middleware function](/en/guides/middleware/).

```
const privateHeader = request.headers.get("x-private-header");
let locals = {};
try {
  if (privateHeader) {
    locals = JSON.parse(privateHeader);
  }
} finally {
  const response = await app.render(request, { locals });
}
```

#### `RenderOptions.prerenderedErrorPageFetch()`

**Type:** `(url: ErrorPagePath) => Promise<Response>`  
**Default:** `fetch`  

A function that allows you to provide custom implementations for fetching prerendered error pages.

This is used to override the default `fetch()` behavior, for example, when `fetch()` is unavailable or when you cannot call the server from itself.

The following example reads `500.html` and `404.html` from disk instead of performing an HTTP call:

```
return app.render(request, {
  prerenderedErrorPageFetch: async (url: string): Promise<Response> => {
    if (url.includes("/500")) {
      const content = await fs.promises.readFile("500.html", "utf-8");
      return new Response(content, {
        status: 500,
        headers: { "Content-Type": "text/html" },
      });
    }

    const content = await fs.promises.readFile("404.html", "utf-8");
    return new Response(content, {
      status: 404,
      headers: { "Content-Type": "text/html" },
    });
  }
});
```

If not provided, Astro will fallback to its default behavior for fetching error pages.

#### `RenderOptions.waitUntil()`

**Type:** `(promise: Promise<unknown>) => void`  

An optional runtime hook for background work after the response is sent.

Adapters can pass this through to let runtime cache providers schedule work such as cache writes or stale-while-revalidate without blocking the response path.

The following example forwards a runtime's `waitUntil()` implementation to [`app.render()`](#apprender) in an [adapter server entrypoint](/en/reference/adapter-reference/#building-a-server-entrypoint):

```

const app = createApp();

}
```

#### `RenderOptions.routeData`

**Type:** [`RouteData`](/en/reference/integrations-reference/#routedata)  
**Default:** `app.match(request)`

Defines the information about a route. This is useful when you already know the route to render. Doing so will bypass the internal call to [`app.match()`](#appmatch) to determine the route to render.

```
const routeData = app.match(request);
if (routeData) {
  return app.render(request, { routeData });
} else {
  /* adapter-specific 404 response */
  return new Response(..., { status: 404 });
}
```

## [Image and Assets API Reference](https://docharvest.github.io/docs/astro/reference/modules/astro-assets/)

Contents

astro

Image and Assets API Reference

Astro

Image and Assets API Reference

Astro provides built-in components and helper functions for optimizing and displaying your images. For features and usage examples, [see our image guide](/en/guides/images/).

## Imports from `astro:assets`

The following helpers are imported from the virtual assets module:

### `<Image />`

The `<Image />` component optimizes and transforms images.

```
---
// import the Image component and the image

  import myImportedImage from '../assets/my-local-image.png';
  ---
  <Image src={myImportedImage} alt="descriptive text" />
```

-   **Images in the `public/` folder** - use the image's **file path relative to the public folder**:
    
    ```
    ---
    import { Image } from 'astro:assets';
    ---
    <Image
      src="/images/my-public-image.png"
      alt="descriptive text"
      width="200"
      height="150"
    />
    ```
    
-   **Remote images** - use the image's **full URL** as the property value:
    
    ```
    ---
    import { Image } from 'astro:assets';
    ---
    <Image
      src="https://example.com/remote-image.jpg"
      alt="descriptive text"
      width="200"
      height="150"
    />
    ```
    

#### `alt` (required)

**Type:** `string`

Use the required `alt` attribute to provide a string of [descriptive alt text](https://www.w3.org/WAI/tutorials/images/) for images.

If an image is merely decorative (i.e. doesn't contribute to the understanding of the page), set `alt=""` so that screen readers and other assistive technologies know to ignore the image.

#### `width` and `height` (required for images in `public/`)

**Type:** ``number | `${number}` | undefined``

These properties define the dimensions to use for the image.

When a `layout` type is set, these are automatically generated based on the image's dimensions and in most cases should not be set manually.

When using images in their original aspect ratio, `width` and `height` are optional. These dimensions can be automatically inferred from image files located in `src/`. For remote images, add [the `inferSize` attribute set to `true`](#infersize) on the `<Image />` or `<Picture />` component or use [`inferRemoteSize()` function](#inferremotesize).

However, both of these properties are required for images stored in your `public/` folder as Astro is unable to analyze these files.

#### `densities`

**Type:** ``(number | `${number}x`)[] | undefined``  

A list of pixel densities to generate for the image.

The `densities` attribute is not compatible with having the `layout` prop or `image.layout` config set, and will be ignored if set.

If provided, this value will be used to generate a `srcset` attribute on the `<img>` tag. Do not provide a value for `widths` when using this value.

Densities that are equal to widths larger than the original image will be ignored to avoid upscaling the image.

```
---

---
<Image
  src={myImage}
  width={myImage.width / 2}
  densities={[1.5, 2]}
  alt="A description of my image."
/>
```

```
<!-- Output -->
<img
  src="/_astro/my_image.hash.webp"
  srcset="
    /_astro/my_image.hash.webp 1.5x
    /_astro/my_image.hash.webp 2x
  "
  alt="A description of my image."
  width="800"
  height="450"
  loading="lazy"
  decoding="async"
/>
```

#### `widths`

**Type:** `number[] | undefined`  

A list of widths to generate for the image.

If provided, this value will be used to generate a `srcset` attribute on the `<img>` tag. A [`sizes` property](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/sizes) must also be provided.

The `widths` and `sizes` attributes will be automatically generated for images using a `layout` property. Providing these values is generally not needed, but can be used to override any automatically generated values.

Do not provide a value for `densities` when using this value. Only one of these two values can be used to generate a `srcset`.

Widths that are larger than the original image will be ignored to avoid upscaling the image.

```
---

---
<Image src="https://example.com/cat.png" inferSize alt="A cat sleeping in the sun." />
```

As of Astro 5.17.3, `inferSize` only fetches dimensions for [authorized remote image domains](/en/guides/images/#authorizing-remote-images). Remote images outside the allowlist are not fetched.

#### `priority`

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

Allows you to automatically set the `loading`, `decoding`, and `fetchpriority` attributes to their optimal values for above-the-fold images.

```
---

---
<Image src={myImage} priority alt="A description of my image" />
```

When `priority="true"` (or the shorthand syntax `priority`) is added to the `<Image />` or `<Picture />` component, it will add the following attributes to instruct the browser to load the image immediately:

```
loading="eager"
decoding="sync"
fetchpriority="high"
```

These individual attributes can still be set manually if you need to customize them further.

#### `layout`

**Type:** `'constrained' | 'full-width' | 'fixed' | 'none'`  
**Default:** `image.layout | 'none'`  

Determines how the image should resize when its container changes size. Can be used to override the default configured value for [`image.layout`](/en/reference/configuration-reference/#imagelayout).

```
---

---
<Image src={myImage} alt="A description of my image." layout='constrained' width={800} height={600} />
```

When a layout is set, `srcset` and `sizes` attributes are automatically generated based on the image's dimensions and the layout type. The previous `<Image />` component will generate the following HTML output:

```
<img
  src="/_astro/my_image.hash3.webp"
  srcset="/_astro/my_image.hash1.webp 640w,
      /_astro/my_image.hash2.webp 750w,
      /_astro/my_image.hash3.webp 800w,
      /_astro/my_image.hash4.webp 828w,
      /_astro/my_image.hash5.webp 1080w,
      /_astro/my_image.hash6.webp 1280w,
      /_astro/my_image.hash7.webp 1600w"
  alt="A description of my image"
  sizes="(min-width: 800px) 800px, 100vw"
  loading="lazy"
  decoding="async"
  fetchpriority="auto"
  width="800"
  height="600"
  style="--fit: cover; --pos: center;"
  data-astro-image="constrained"
>
```

`layout` supports the following values:

-   `constrained` - The image will scale down to fit the container, maintaining its aspect ratio, but will not scale up beyond the specified `width` and `height`, or the image's original dimensions.
    
    Use this if you want the image to display at the requested size where possible, but shrink to fit smaller screens. This matches the default behavior for images when using Tailwind. If you're not sure, this is probably the layout you should choose.
    
-   `full-width` - The image will scale to fit the width of the container, maintaining its aspect ratio.
    
    Use this for hero images or other images that should take up the full width of the page.
    
-   `fixed` - The image will maintain the requested dimensions and not resize. It will generate a `srcset` to support high density displays, but not for different screen sizes.
    
    Use this if the image will not resize, for example icons or logos smaller than any screen width, or other images in a fixed-width container.
    
-   `none` - The image will not be responsive. No `srcset` or `sizes` will be automatically generated, and no styles will be applied.
    
    This is useful if you have enabled a default layout, but want to disable it for a specific image.
    

For example, with `constrained` set as the default layout, you can override any individual image's `layout` property:

```
---

---
<Image src={myImage} alt="This will use constrained layout" width={800} height={600} />
<Image src={myImage} alt="This will use full-width layout" layout="full-width" />
<Image src={myImage} alt="This will disable responsive images" layout="none" />
```

The value for `layout` also defines the default styles applied to the `<img>` tag to determine how the image should resize according to its container:

```
:where([data-astro-image]) {
	object-fit: var(--fit);
	object-position: var(--pos);
}
:where([data-astro-image='full-width']) {
	width: 100%;
}
:where([data-astro-image='constrained']) {
	max-width: 100%;
}
```

#### `fit`

**Type:** `'contain' | 'cover' | 'fill' | 'none' | 'scale-down'`  
**Default:** `image.objectFit | 'cover'`  

Defines how a image should be cropped if its aspect ratio is changed.

Values match those of CSS `object-fit`. Defaults to `cover`, or the value of [`image.objectFit`](/en/reference/configuration-reference/#imageobjectfit) if set. Can be used to override the default `object-fit` styles.

#### `position`

**Type:** `string`  
**Default:** `image.objectPosition | 'center'`  

Defines the position of the image crop for a image if the aspect ratio is changed.

Values match those of CSS `object-position`. Defaults to `center`, or the value of [`image.objectPosition`](/en/reference/configuration-reference/#imageobjectposition) if set. Can be used to override the default `object-position` styles.

#### `background`

**Type:** `string | undefined`  

The background color to use when flattening an image to transform it into the requested output `format`.

By default, Sharp uses a black background when flattening an image. Specifying a different background color is especially useful when transforming images with transparent backgrounds to a format that does not support transparency (e.g. `.jpeg`):

```
<Image
  src={myImage}
  alt="A description of my image"
  format="jpeg"
  background="#ffffff"
/>
```

Values are passed directly to the image service. Sharp accepts [any value the `color-string` package can parse](https://github.com/Qix-/color-string/blob/master/README.md#parsing).

### `<Picture />`

The `<Picture />` component generates an optimized image with multiple formats and/or sizes.

```
---

---

<Font cssVariable="--font-roboto" />
```

The `<Font />` component accepts the following properties:

#### `cssVariable` (required)

**Type:** `CssVariable`  
**Example type:** `"--font-roboto" | "--font-comic-sans" | ...`

The [`cssVariable`](/en/reference/configuration-reference/#fontcssvariable) registered in your Astro configuration:

```
---

---

<Font cssVariable="--font-roboto" />
```

#### `preload`

**Type:** `boolean | { weight?: string | number; style?: string; subset?: string }[]`  
**Default:** `false`

Whether to output [preload links](https://web.dev/learn/performance/optimize-web-fonts#preload) or not. With the `preload` directive, the browser will immediately begin downloading all possible font links during page load:

```
---

---

<Font cssVariable="--font-roboto" preload />
```

Be very intentional about which fonts you preload. Preloading too many fonts can impact performance, as this can block loading other important resources or may download fonts that are not needed for the current page.

To selectively control which font files are preloaded, you can provide an array of objects describing any combination of font `weight`, `style`, or `subset` to preload:

```
---

---

<Font
  cssVariable="--font-roboto"
  preload={[
    { subset: "latin", style: "normal" },
    { weight: "400" },
  ]}
/>
```

Variable weight font files will be preloaded if any weight within its range is requested. For example, a font file for font weight `100 900` will be included when `400` is specified in a `preload` object.

### `getImage()`

**Type:** `(options: [UnresolvedImageTransform](#unresolvedimagetransform)) => Promise<[GetImageResult](#getimageresult)>`

:::caution `getImage()` relies on server-only APIs and will throw an error on the client.

If you need the resulting image URL client-side, you can [pass the `src` from a server-rendered `getImage()` call to the client](/en/guides/images/#generating-images-with-getimage). :::

The `getImage()` function is intended for generating images destined to be used somewhere else than directly in HTML, for example in an [API Route](/en/guides/endpoints/#server-endpoints-api-routes). It also allows you to create your own custom `<Image />` component.

This takes an options object with the [same properties as the Image component](#image-) (except `alt`) and returns a [`GetImageResult` object](#getimageresult).

The following example generates an AVIF `background-image` for a `<div />`:

```
---

const { width, height } = await inferRemoteSize("https://example.com/cat.png");
```

### `getConfiguredImageService()`

**Type:** `() => Promise<[ImageService](#imageservice)>`  

Retrieves the resolved [image service](/en/reference/configuration-reference/#imageservice).

### `imageConfig`

**Type:** [`AstroConfig["image"]`](/en/reference/configuration-reference/#image-options)  

The [configuration options for images](/en/reference/configuration-reference/#image-options) set by the user and merged with all defaults.

### `fontData`

**Type:** `Record<CssVariable, Array<[FontData](#fontdata-1)>>`  

An object where each key is a [`cssVariable`](/en/reference/configuration-reference/#fontcssvariable) and the value is an array describing the associated fonts. Each font is an object containing an array of `src` available for that font and the following optional properties: `weight` and `style`:

```

const fontPath = fontData["--font-roboto"][0]?.src[0]?.url;

if (fontPath === undefined) {
  throw new Error("Cannot find the font path.");
}

const url = experimental_getFontFileURL(fontPath);
const buffer = await fetch(url).then((res) => res.arrayBuffer());
```

When called on a route [rendered on-demand](/en/guides/on-demand-rendering/), the request URL needs to be provided:

```

  // ...
};
```

## `astro:assets` types

The following types are imported from the virtual assets module:

### `LocalImageProps`

**Type:** `ImageSharedProps<T> & { src: [ImageMetadata](#imagemetadata-1) | Promise<{ default: ImageMetadata; }> }`

Describes the [properties of a local image](#image-). This ensures that [`src`](#src-required) matches the shape of an imported image.

Learn more about [imported images in `src/`](/en/guides/images/#images-in-src) with an example usage.

### `RemoteImageProps`

**Types:**

-   `ImageSharedProps<T> & { src: string; inferSize: true; }`
-   `ImageSharedProps<T> & { src: string; inferSize?: false | undefined; }`

Describes the [properties of a remote image](#image-). This ensures that when [`inferSize`](#infersize) is not provided or is set to `false`, both [`width` and `height`](#width-and-height-required-for-images-in-public) are required.

### `FontData`

**Type:** `{ src: Array<{ url: string; format?: string; tech?: string }>; weight?: string; style?: string; subset?: string; }`  

Describes the font data associated with a given font family.

#### `FontData.src`

**Type:** `Array<{ url: string; format?: string; tech?: string }>`

An array of objects describing the available font files for a given font family. Each object contains a `url` and, optionally, the associated [`format`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/src#font_formats) and [`tech`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@font-face/src#font_technologies).

#### `FontData.weight`

**Type:** `string`

Specifies the font weight (e.g. `400`, `600`).

#### `FontData.style`

**Type:** `string`

Specifies the font style (e.g. `normal`, `italic`).

#### `FontData.subset`

**Type:** `string`

Specifies the font subset (e.g. `latin`, `cyrillic`).

## Imports from `astro/assets`

The following helpers are imported from the regular assets module:

### `baseService`

**Type:** `Omit<[LocalImageService](#localimageservice), 'transform'>`

The built-in local image service which can be extended to [create a custom image service](/en/reference/image-service-reference/).

The following example reuses the `baseService` to create a new image service:

```

const newImageService = {
 getURL: baseService.getURL,
 parseURL: baseService.parseURL,
 getHTMLAttributes: baseService.getHTMLAttributes,
 async transform(inputBuffer, transformOptions) {...}
}
```

### `getConfiguredImageService()`

See [`getConfiguredImageService()`](#getconfiguredimageservice) from `astro:assets`.

### `getImage()`

**Type:** `(options: [UnresolvedImageTransform](#unresolvedimagetransform), imageConfig: [AstroConfig['image']](/en/reference/configuration-reference/#image-options)) => Promise<[GetImageResult](#getimageresult)>`

A function similar to [`getImage()`](#getimage) from `astro:assets` with two required arguments: an `options` object with [the same properties as the Image component](#image-) and a second object for the [image configuration](/en/reference/configuration-reference/#image-options).

### `isLocalService()`

**Type:** `(service: [ImageService](#imageservice) | undefined) => boolean`

Checks the type of an image service and returns `true` when this is a [local service](#localimageservice).

## `astro/assets` types

The following types are imported from the regular assets module:

### `LocalImageProps`

See [`LocalImageProps`](#localimageprops) from `astro:assets`.

### `RemoteImageProps`

See [`RemoteImageProps`](#remoteimageprops) from `astro:assets`.

## Imports from `astro/assets/utils`

The following helpers are imported from the `utils` directory in the regular assets module and can be used to [build an image service](/en/reference/image-service-reference/):

### `isRemoteAllowed()`

**Type:** `(src: string, { domains, remotePatterns }: { domains: string[], remotePatterns: [RemotePattern](#remotepattern)[] }) => boolean`  

Determines whether a given remote resource, identified by its source URL, is allowed based on specified domains and remote patterns.

```

const url = new URL('https://example.com/images/test.jpg');
const domains = ['example.com', 'anotherdomain.com'];
const remotePatterns = [
  {
    protocol: 'https',
    hostname: 'images.example.com',
    pathname: '/**', // Allow any path under this hostname
  }
];

isRemoteAllowed(url.href, { domains, remotePatterns }); // Output: `true`
```

### `matchHostname()`

**Type:** `(url: URL, hostname?: string, allowWildcard = false) => boolean`  

Matches a given URL's hostname against a specified hostname, with optional support for wildcard patterns.

```

const url = new URL('https://sub.example.com/path/to/resource');

matchHostname(url, 'example.com'); // Output: `false`
matchHostname(url, 'example.com', true); // Output: `true`
```

### `matchPathname()`

**Type:** `(url: URL, pathname?: string, allowWildcard = false) => boolean`  

Matches a given URL's pathname against a specified pattern, with optional support for wildcards.

```

const testURL = new URL('https://example.com/images/photo.jpg');

matchPathname(testURL, '/images/photo.jpg'); // Output: `true`
matchPathname(testURL, '/images/'); // Output: `false`
matchPathname(testURL, '/images/*', true); // Output: `true`
```

### `matchPattern()`

**Type:** `(url: URL, remotePattern: [RemotePattern](#remotepattern)) => boolean`  

Evaluates whether a given URL matches the specified remote pattern based on protocol, hostname, port, and pathname.

```

const url = new URL('https://images.example.com/photos/test.jpg');
const remotePattern = {
  protocol: 'https',
  hostname: 'images.example.com',
  pathname: '/photos/**', // Allow all files under /photos/
};

matchPattern(url, remotePattern); // Output: `true`
```

### `matchPort()`

**Type:** `(url: URL, port?: string) => boolean`  
**Default:** `true`  

Checks if the given URL's port matches the specified port. If no port is provided, it returns `true`.

```

const urlWithPort = new URL('https://example.com:8080/resource');
const urlWithoutPort = new URL('https://example.com/resource');

matchPort(urlWithPort, '8080'); // Output: `true`
matchPort(urlWithoutPort, '8080'); // Output: `false`
```

### `matchProtocol()`

**Type:** `(url: URL, protocol?: string) => boolean`  
**Default:** `true`  

Compares the protocol of the provided URL with a specified protocol. This returns `true` if the protocol matches or if no protocol is provided.

```

const secureUrl = new URL('https://example.com/resource');
const regularUrl = new URL('http://example.com/resource');

matchProtocol(secureUrl, 'https'); // Output: `true`
matchProtocol(regularUrl, 'https'); // Output: `false`
```

### `isESMImportedImage()`

**Type:** `(src: [ImageMetadata](#imagemetadata-1) | string) => boolean`  

Determines if the given source is an ECMAScript Module (ESM) imported image.

```

const imageMetadata = {
  src: '/images/photo.jpg',
  width: 800,
  height: 600,
  format: 'jpg',
};
const filePath = '/images/photo.jpg';

isESMImportedImage(imageMetadata); // Output: `true`
isESMImportedImage(filePath); // Output: `false`
```

### `isRemoteImage()`

**Type:** `(src: [ImageMetadata](#imagemetadata-1) | string) => boolean`  

Determines if the provided source is a remote image URL in the form of a string.

```

const imageUrl = 'https://example.com/images/photo.jpg';
const localImage = {
  src: '/images/photo.jpg',
  width: 800,
  height: 600,
  format: 'jpg',
};

isRemoteImage(imageUrl); // Output: `true`
isRemoteImage(localImage); // Output: `false`
```

### `resolveSrc()`

**Type:** `(src: [UnresolvedImageTransform['src']](#unresolvedimagetransformsrc)) => Promise<string | [ImageMetadata](#imagemetadata-1)>`  

Returns the image source. This function ensures that if `src` is a Promise (e.g., a dynamic `import()`), it is awaited and the correct `src` is extracted. If `src` is already a resolved value, it is returned as-is.

```

const resolvedLocal = await resolveSrc(localImage);
// Example value: `{ src: '/@fs/home/username/dev/astro-project/src/images/photo.jpg', width: 800, height: 600, format: 'jpg' }`

const resolvedRemote = await resolveSrc("https://example.com/remote-img.jpg");
// Value: `"https://example.com/remote-img.jpg"`

const resolvedDynamic = await resolveSrc(import("./images/dynamic-image.jpg"))
// Example value: `{ src: '/@fs/home/username/dev/astro-project/src/images/dynamic-image.jpg', width: 800, height: 600, format: 'jpg' }`
```

### `imageMetadata()`

**Type:** `(data: Uint8Array, src?: string) => Promise<Omit<[ImageMetadata](#imagemetadata-1), 'src' | 'fsPath'>>`  

Extracts image metadata such as dimensions, format, and orientation from the provided image data.

```

const binaryImage = new Uint8Array([/* ...binary image data... */]);
const sourcePath = '/images/photo.jpg';

const metadata = await imageMetadata(binaryImage, sourcePath);
// Example value:
// {
//    width: 800,
//    height: 600,
//    format: 'jpg',
//    orientation: undefined
// }
```

### `emitImageMetadata()`

**Type:** `(id: string | undefined, fileEmitter?: Rollup.EmitFile) => Promise<([ImageMetadata](#imagemetadata-1) & { contents?: Buffer }) | undefined>`  

Processes an image file and emits its metadata and optionally its contents. In build mode, the function uses `fileEmitter` to generate an asset reference. In development mode, it resolves to a local file URL with query parameters for metadata.

```

const imageId = '/images/photo.jpg';
const metadata = await emitImageMetadata(imageId);
// Example value:
// {
//    src: '/@fs/home/username/dev/astro-project/src/images/photo.jpg?origWidth=800&origHeight=600&origFormat=jpg',
//    width: 800,
//    height: 600,
//    format: 'jpg',
//    contents: Uint8Array([...])
// }
```

### `emitClientAsset()`

**Type:** `(pluginContext: [Rollup.PluginContext](https://rollupjs.org/plugin-development/#plugin-context), options: Rollup.EmitFile) => string`  

Emits a client asset that will be moved to the client directory for assets (e.g. `dist/client/_astro/`) during SSR builds. This function is intended for integration authors who need to emit assets (such as images) from server-rendered content that should be available on the client.

Use this instead of [Rollup `pluginContext.emitFile()`](https://rollupjs.org/plugin-development/#this-emitfile) directly when working in a Vite plugin context and you need the emitted asset to be moved to the client output directory.

```

function myVitePlugin() {
  return {
    name: 'my-plugin',
    transform(code, id) {
      const handle = emitClientAsset(this, {
        type: 'asset',
        name: 'my-image.png',
        source: imageBuffer,
      });
      // Returns the asset handle similar to `emitFile()`
    }
  }
}
```

### `getOrigQueryParams()`

**Type:** `(params: URLSearchParams) => Pick<[ImageMetadata](#imagemetadata-1), 'width' | 'height' | 'format'> | undefined`  

Retrieves the `width`, `height`, and `format` of an image from a [`URLSearchParams` object](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams). If any of these parameters are missing or invalid, the function returns `undefined`.

```

const url = new URL('https://example.com/image.jpg?width=800&height=600&format=jpg');
const origParams = getOrigQueryParams(url.searchParams);
// Example value:
// {
//    width: 800,
//    height: 600,
//    format: 'jpg'
// }
```

### `inferRemoteSize()`

**Type:** `(url: string) => Promise<Omit<[ImageMetadata](#imagemetadata-1), 'src' | 'fsPath'>>`  

Infers the dimensions of a remote image by streaming its data and analyzing it progressively until sufficient metadata is available.

```

const remoteImageUrl = 'https://example.com/image.jpg';
const imageSize = await inferRemoteSize(remoteImageUrl);
// Example value:
// {
//    width: 1920,
//    height: 1080,
//    format: 'jpg'
// }
```

### `propsToFilename()`

**Type:** `(filePath: string, transform: [ImageTransform](#imagetransform), hash: string) => string`  

Generates a formatted filename for an image based on its source path, transformation properties, and a unique hash.

The formatted filename follows this structure:

`<prefixDirname>/<baseFilename>_<hash><outputExtension>`

-   `prefixDirname`: If the image is an ESM imported image, this is the directory name of the original file path; otherwise, it will be an empty string.
-   `baseFilename`: The base name of the file or a hashed short name if the file is a `data:` URI.
-   `hash`: A unique hash string generated to distinguish the transformed file.
-   `outputExtension`: The desired output file extension derived from the `transform.format` or the original file extension.

```

const filePath = '/images/photo.jpg';
const transform = { format: 'png', src: filePath };
const hash = 'abcd1234';

const filename = propsToFilename(filePath, transform, hash);
// Example value: '/images/photo_abcd1234.png'
```

### `hashTransform()`

**Type:** `(transform: [ImageTransform](#imagetransform), imageService: string, propertiesToHash: string[]) => string`  

Transforms the provided `transform` object into a hash string based on selected properties and the specified `imageService`.

```

const transform = {
  src: '/images/photo.jpg',
  width: 800,
  height: 600,
  format: 'jpg',
};
const imageService = 'astro/assets/services/sharp';
const propertiesToHash = ['width', 'height', 'format'];

const hash = hashTransform(transform, imageService, propertiesToHash);
// Example value: 'd41d8cd98f00b204e9800998ecf8427e'
```

## `astro` types

### `GetImageResult`

**Type:** `object`  

Describes the result of the transformation after the call to [`getImage()`](/en/reference/modules/astro-assets/#getimage).

#### `GetImageResult.attributes`

**Type:** `Record<string, any>`

Defines the additional HTML attributes needed to render the image (e.g. width, height, style).

#### `GetImageResult.options`

**Type:** [`ImageTransform`](#imagetransform)

Describes the transformation settings after validation.

#### `GetImageResult.rawOptions`

**Type:** [`ImageTransform`](#imagetransform)

Describes the original transformation settings.

#### `GetImageResult.src`

**Type:** `string`

The path to the generated image.

#### `GetImageResult.srcSet`

**Type:** `{ values: { transform: [ImageTransform](#imagetransform); descriptor?: string; attributes?: Record<string, any>; url: string; }[]; attribute: string; }`  

An object describing how to render the [`srcset` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img#srcset).

##### `GetImageResult.srcSet.values`

**Type:** `{ transform: [ImageTransform](#imagetransform); descriptor?: string; attributes?: Record<string, any>; url: string; }[]`

An array of generated values where each entry includes a URL and a size descriptor. This can be used to manually generate the value of the `srcset` attribute.

##### `GetImageResult.srcSet.attribute`

**Type:** `string`

A value ready to use in the `srcset` attribute.

### `ImageTransform`

**Type:** `object`

Defines the options accepted by the image transformation service. This contains a required `src` property, optional predefined properties, and any additional properties required by the image service:

#### `ImageTransform.src`

**Type:** `[ImageMetadata](#imagemetadata-1) | string`

Defines the path to a local image in the `public` directory, the URL of a remote image, or the data from an imported image.

#### `ImageTransform.width`

**Type:** `number | undefined`

The width of the image.

#### `ImageTransform.height`

**Type:** `number | undefined`

The height of the image.

#### `ImageTransform.widths`

**Type:** `number[] | undefined`  

A list of widths to generate for the image.

#### `ImageTransform.densities`

**Type:** ``(number | `${number}x`)[] | undefined``  

A list of pixel densities to generate for the image.

#### `ImageTransform.quality`

**Type:** `[ImageQuality](#imagequality) | undefined`

The desired quality for the output image.

#### `ImageTransform.format`

**Type:** `[ImageOutputFormat](#imageoutputformat) | undefined`

The desired format for the output image.

#### `ImageTransform.fit`

**Type:** `'fill' | 'contain' | 'cover' | 'none' | 'scale-down' | string | undefined`  

Defines a list of allowed values for the `object-fit` CSS property, extensible with any string.

#### `ImageTransform.position`

**Type:** `string | undefined`  

Controls the value for the `object-position` CSS property.

### `UnresolvedImageTransform`

**Type:** `Omit<[ImageTransform](#imagetransform), "src"> & { src: [ImageMetadata](#imagemetadata-1) | string | Promise<{ default: ImageMetadata }>; inferSize?: boolean; }`

Represents an image with transformation options. This contains the same properties as the [`ImageTransform` type](#imagetransform) with a different `src` type and an additional `inferSize` property.

#### `UnresolvedImageTransform.src`

**Type:** `[ImageMetadata](#imagemetadata-1) | string | Promise<{ default: ImageMetadata }>`

The path to an image imported or located in the `public` directory, or the URL of a remote image.

#### `UnresolvedImageTransform.inferSize`

**Type:** `boolean`

Determines whether the width and height of the image should be inferred.

See also the [`inferSize` attribute](/en/reference/modules/astro-assets/#infersize) available on `<Image />`.

### `ImageMetadata`

**Type:** `{ src: string; width: number; height: number; format: [ImageInputFormat](#imageinputformat); orientation?: number; }`  

Describes the data collected during image import. This contains the following properties:

#### `ImageMetadata.src`

**Type:** `string`

The absolute path of the image on the filesystem.

#### `ImageMetadata.width`

**Type:** `number`

The width of the image.

#### `ImageMetadata.height`

**Type:** `number`

The height of the image.

#### `ImageMetadata.format`

**Type:** [`ImageInputFormat`](#imageinputformat)

The format of the image.

#### `ImageMetadata.orientation`

**Type:** `number`  

The image orientation when its metadata contains this information.

### `ImageInputFormat`

**Type:** `"jpeg" | "jpg" | "png" | "tiff" | "webp" | "gif" | "svg" | "avif"`  

Describes a union of supported formats for imported images.

### `ImageOutputFormat`

**Type:** `string | "jpeg" | "jpg" | "png" | "webp" | "svg" | "avif"`  

Specifies the format for output images. This can be a predefined literal or any string.

### `ImageQuality`

**Type:** `[ImageQualityPreset](#imagequalitypreset) | number`  

Represents the perceptual quality of the output image as a union of predefined literals, a string, or a number.

### `ImageQualityPreset`

**Type:** `string | "low" | "mid" | "high" | "max"`  

Defines the available presets to control image quality, extensible with any string.

### `RemotePattern`

**Type:** `{ hostname?: string; pathname?: string; protocol?: string; port?: string; }`  

Describes a remote host through four optional properties: `hostname`, `pathname`, `protocol`, and `port`.

### `ImageService`

**Type:** `[ExternalImageService](#externalimageservice) | [LocalImageService](#localimageservice)`

Defines the hooks that a local or external image service must provide.

### `ExternalImageService`

**Type:** `object`

Defines the hooks that an external image transformation service must provide. This requires a [`getUrl()` hook](/en/reference/image-service-reference/#geturl) and supports [three additional hooks](/en/reference/image-service-reference/#hooks).

Learn how to build [external services](/en/reference/image-service-reference/#external-services) in the Image Service API reference with example usage.

### `LocalImageService`

**Type:** `object`

Defines the hooks that a local image transformation service must provide. This requires [`getUrl()`](/en/reference/image-service-reference/#geturl), [`parseUrl()`](/en/reference/image-service-reference/#parseurl), and [`transform()`](/en/reference/image-service-reference/#transform) hooks, and supports [additional hooks](/en/reference/image-service-reference/#hooks).

Learn how to build [local services](/en/reference/image-service-reference/#local-services) in the Image Service API reference with example usage.

### `ImageServiceConfig`

**Type:** `{ entrypoint: 'astro/assets/services/sharp' | string; config?: T; }`  

Describes the configuration object for an image service. This contains the following properties:

#### `ImageServiceConfig.entrypoint`

**Type:** `'astro/assets/services/sharp' | string`

A package or path to the image service module. This can be Astro's built-in Sharp service or a third-party service.

#### `ImageServiceConfig.config`

**Type:** `Record<string, any>`

A configuration object passed to the image service. The shape depends on the specific service being used.

## [Config imports API Reference](https://docharvest.github.io/docs/astro/reference/modules/astro-config/)

Contents

astro

Config imports API Reference

Astro

Config imports API Reference

This virtual module `astro:config` exposes a non-exhaustive, serializable, type-safe version of the Astro configuration. There are two submodules for accessing different subsets of your configuration values: [`/client`](#imports-from-astroconfigclient) and [`/server`](#imports-from-astroconfigserver).

All available config values can be accessed from `astro:config/server`. However, for code executed on the client, only those values exposed by `astro:config/client` will be available. This protects your information by only making some data available to the client.

## Imports from `astro:config/client`

The following helpers are imported from the `client` directory of the virtual config module.

Use this submodule for client-side code:

```

function addForwardSlash(path) {
  if (trailingSlash === "always") {
    return path.endsWith("/") ? path : path + "/"
  } else {
    return path
  }
}
```

See more about the configuration imports available from `astro:config/client`:

-   [`i18n`](/en/reference/configuration-reference/#i18n)
-   [`trailingSlash`](/en/reference/configuration-reference/#trailingslash)
-   [`base`](/en/reference/configuration-reference/#base)
-   [`build.format`](/en/reference/configuration-reference/#buildformat)
-   [`site`](/en/reference/configuration-reference/#site)
-   [`compressHTML`](/en/reference/configuration-reference/#compresshtml)

## Imports from `astro:config/server`

The following helpers are imported from the `server` directory of the virtual config module.

These imports include everything available from `astro:config/client` as well as additional sensitive information about your file system configuration that is not safe to expose to the client.

Use this submodule for server side code:

```

        // generate data from some operation
        let data = JSON.stringify([]);
        writeFileSync(fileURLToPath(file), data, "utf-8");
      }
    }
  }
}
```

See more about the configuration imports available from `astro:config/server`:

-   [`i18n`](/en/reference/configuration-reference/#i18n)
-   [`trailingSlash`](/en/reference/configuration-reference/#trailingslash)
-   [`base`](/en/reference/configuration-reference/#base)
-   [`build.format`](/en/reference/configuration-reference/#buildformat)
-   [`build.client`](/en/reference/configuration-reference/#buildclient)
-   [`build.server`](/en/reference/configuration-reference/#buildserver)
-   [`build.assetsPrefix`](/en/reference/configuration-reference/#buildassetsprefix)
-   [`site`](/en/reference/configuration-reference/#site)
-   [`srcDir`](/en/reference/configuration-reference/#srcdir)
-   [`cacheDir`](/en/reference/configuration-reference/#cachedir)
-   [`outDir`](/en/reference/configuration-reference/#outdir)
-   [`publicDir`](/en/reference/configuration-reference/#publicdir)
-   [`root`](/en/reference/configuration-reference/#root)
-   [`compressHTML`](/en/reference/configuration-reference/#compresshtml)

## Imports from `astro/config`

The following helpers are imported from the regular config module:

### `defineConfig()`

**Type:** `(config: [AstroUserConfig](/en/reference/configuration-reference/)) => AstroUserConfig`

Configures your project with type safety [in a supported Astro configuration file](/en/guides/configuring-astro/#the-astro-config-file).

### `envField`

**Type:** `object`  

Describes the supported data types when [defining environment variables](/en/reference/configuration-reference/#envschema).

Each data type must define the [variable type](/en/guides/environment-variables/#variable-types) with `context` (`"client"` or `"server"`) and `access` (`"secret"` or `"public"`). In addition, you can define a `default` value, specify whether the variable is `optional` (default `false`), and some data types provide optional validation methods.

Learn more about [using type safe environment variables](/en/guides/environment-variables/#type-safe-environment-variables) in your Astro project.

#### `envField.string()`

**Type:** `(options: StringFieldInput) => StringField`

Defines an environment variable of string type. You can perform [string validation with Zod](https://zod.dev/api#strings) using the following properties: `max`, `min`, `length`, `url`, `includes`, `startsWith`, and `endsWith`.

The following example defines the expected shape for an environment variable storing an API URL:

Learn more about [configuring a no-op passthrough service](/en/guides/images/#configure-no-op-passthrough-service).

### `sessionDrivers`

**Type:** `object`  

Describes the [built-in driver](/en/reference/session-driver-reference/#built-in-drivers) used [for session storage](/en/reference/configuration-reference/#session-options).

The following example configures the Redis driver to enable sessions:

```

export default defineConfig({
  session: {
    driver: sessionDrivers.redis({
      url: process.env.REDIS_URL
    }),
  }
})
```

Learn more about [using sessions](/en/guides/sessions/) in your Astro project.

### `sharpImageService()`

**Type:** `(config?: SharpImageServiceConfig) => [ImageServiceConfig](/en/reference/modules/astro-assets/#imageserviceconfig)`  

Retrieves the Sharp service used to process Astro’s image assets. This takes an optional object describing the [configuration options for Sharp](/en/reference/configuration-reference/#imageservice).

### `validateConfig()`

See [`validateConfig()` in the Programmatic API reference](/en/reference/programmatic-reference/#validateconfig).

## [Content Collections API Reference](https://docharvest.github.io/docs/astro/reference/modules/astro-content/)

Contents

astro

Content Collections API Reference

Astro

Content Collections API Reference

Build-time content collections offer APIs to configure, query, and render your local Markdown, MDX, Markdoc, YAML, TOML, or JSON files, as well as remote content.

Live content collections offer APIs to configure, query, and render fresh, up-to-the-moment live data from remote sources.

For features and usage examples, [see our content collections guide](/en/guides/content-collections/).

## Imports from `astro:content`

### `defineCollection()`

**Type:** `(input: CollectionConfig) => CollectionConfig`

A utility to configure a collection in a `src/content.config.*` file.

```

const blog = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/data/blog' }),
  schema: z.object({
    title: z.string(),
    permalink: z.string().optional(),
  }),
});

// Expose your defined collection to Astro
// with the `collections` export
```

This function accepts the following properties:

#### `loader`

**Type:** `() => Promise<Array<{ id: string, [key: string]: any }> | Record<string, Record<string, any>>> | [Loader](/en/reference/content-loader-reference/#object-loader-api)`

Either an object or a function that allows you to load data from any source, local or remote, into a build-time content collection. (For live collections, see the [live `loader`](#loader-1) property.)

Learn about [build-time collection loaders](/en/guides/content-collections/#build-time-collection-loaders) with guided explanations and example usage.

#### `schema`

**Type:** `ZodType | (context: [SchemaContext](#schemacontext)) => ZodType`

An optional Zod object or function that returns a Zod object to configure the type and shape of document frontmatter for a collection. Each value must use [a Zod validator](/en/reference/modules/astro-zod/#common-data-type-validators). (For live collections, see the [live `schema`](#schema-1) property.)

Learn about [defining a collection schema](/en/guides/content-collections/#defining-the-collection-schema) using Zod with guided explanations, example usage, and common datatypes.

### `defineLiveCollection()`

**Type:** `(config: LiveCollectionConfig) => LiveCollectionConfig`

A utility to configure a live collection in a `src/live.config.*` file.

```

const products = defineLiveCollection({
  loader: storeLoader({
    apiKey: process.env.STORE_API_KEY,
    endpoint: 'https://api.example.com/v1',
  }),
});

// Expose your defined collection to Astro
// with the `collections` export
```

This function accepts the following properties:

#### `loader`

**Type:** `LiveLoader`

An object that allows you to load data at runtime from a remote source into a live content collection. (For build-time collections, see the [build-time `loader`](#loader) property.)

Learn how to [create a live loader](/en/guides/content-collections/#creating-a-live-loader) with guided explanations and example usage.

#### `schema`

**Type:** `ZodType`

An optional Zod object to configure the type and shape of your data for a live collection. Each value must use [a Zod validator](https://github.com/colinhacks/zod). (For build-time collections, see the [build-time `schema`](#schema) property.)

When you define a schema, it will take precedence over the [live loader’s types](/en/reference/content-loader-reference/#live-loader-api) when you query the collection.

Learn about [using Zod schemas with live collections](/en/guides/content-collections/#using-zod-schemas-with-live-collections) through guided explanations and usage examples.

### `reference()`

**Type:** `(collection: [CollectionKey](#collectionkey)) => ZodEffects<ZodString, { collection: CollectionKey, id: string }>`  

A function used in the content config to define a relationship, or "reference", from one collection to another. This accepts a collection name and transforms the reference into an object containing the collection name and the reference id.

This example defines references from a blog author to the `authors` collection and an array of related posts to the same `blog` collection:

```

const blog = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/data/blog' }),
  schema: z.object({
    // Reference a single author from the `authors` collection by `id`
    author: reference('authors'),
    // Reference an array of related posts from the `blog` collection by `slug`
    relatedPosts: z.array(reference('blog')),
  })
});

const authors = defineCollection({
  loader: file("src/data/authors.json"),
  schema: z.object({ /* ... */ })
});
```

Validation of referenced entries happens at runtime when using `getEntry()` or `getEntries()`:

```
// if a referenced entry is invalid, this will return undefined.
const relatedPosts = await getEntries(blogPost.data.relatedPosts);
```

Learn how to [define and use collection references](/en/guides/content-collections/#defining-collection-references) with guided explanations and usage examples.

### `getCollection()`

**Type:** `(collection: [CollectionKey](#collectionkey), filter?: (entry: [CollectionEntry](#collectionentry)) => boolean) => CollectionEntry[]`

A function that retrieves a list of content collection entries by collection name.

It returns all items in the collection by default, and accepts an optional `filter` function to narrow by entry properties. This allows you to query for only some items in a collection based on `id` or frontmatter values via the `data` object.

```
---

// Get all `src/data/blog/` entries
const allBlogPosts = await getCollection('blog');

// Only return posts with `draft: true` in the frontmatter
const draftBlogPosts = await getCollection('blog', ({ data }) => {
  return data.draft === true;
});
---
```

Learn how to [query build time collections](/en/guides/content-collections/#querying-build-time-collections) with guided explanations and example usage.

### `getLiveCollection()`

**Type:** `(collection: string, filter?: LiveLoaderCollectionFilterType) => Promise<[LiveDataCollectionResult](#livedatacollectionresult)>`

A function that retrieves a list of live content collection entries by collection name.

It returns all items in the collection by default, and accepts an optional `filter` object whose shape is defined by the collection's loader. This allows you to query for only some items in a collection or retrieve data in a different form, depending on your API's capabilities.

```
---

// Get all `products` entries from your API
const { entries: allProducts } = await getLiveCollection('products');

// Only return `products` that should be featured
const { entries: featuredProducts } = await getLiveCollection('products', { featured: true });
---
```

Learn how to [access live collections data](/en/guides/content-collections/#accessing-live-data) with guided explanations and example usage.

### `getEntry()`

**Types:**

-   `(collection: [CollectionKey](#collectionkey), id: string) => Promise<[CollectionEntry](#collectionentry) | undefined>`
-   `({ collection: [CollectionKey](#collectionkey), id: string }) => Promise<[CollectionEntry](#collectionentry) | undefined>`

A function that retrieves a single collection entry by collection name and the entry `id`. `getEntry()` can also be used to get referenced entries to access the `data` or `body` properties:

```
---

// Get `src/content/blog/enterprise.md`
const enterprisePost = await getEntry('blog', 'enterprise');

// Get `src/content/captains/picard.json`
const picardProfile = await getEntry('captains', 'picard');

// Get the profile referenced by `data.captain`
const enterpriseCaptainProfile = await getEntry(enterprisePost.data.captain);
---
```

Learn more about [querying build time collections](/en/guides/content-collections/#querying-build-time-collections) with guided explanations and example usage.

### `getLiveEntry()`

**Type:** `(collection: string, filter: string | LiveLoaderEntryFilterType) => Promise<[LiveDataEntryResult](#livedataentryresult)>`

A function that retrieves a single live collection entry by collection name and an optional filter, either as an `id` string or as a type-safe object.

```
---

const { entry: liveCollectionsPost } = await getLiveEntry('blog', Astro.params.id);
const { entry: mattDraft } = await getLiveEntry('blog', {
  status: 'draft',
  author: 'matt',
});
---
```

Learn how to [access live collections data](/en/guides/content-collections/#accessing-live-data) with guided explanations and example usage.

### `getEntries()`

**Type:** `({ collection: [CollectionKey](#collectionkey), id: string }[]) => [CollectionEntry](#collectionentry)[]`

A function that retrieves multiple collection entries from the same collection. This is useful for [returning an array of referenced entries](/en/guides/content-collections/#defining-collection-references) to access their associated `data` and `body` properties.

```
---

const enterprisePost = await getEntry('blog', 'enterprise');

// Get related posts referenced by `data.relatedPosts`
const enterpriseRelatedPosts = await getEntries(enterprisePost.data.relatedPosts);
---
```

### `render()`

**Type:** `(entry: [CollectionEntry](#collectionentry)) => Promise<RenderResult>`

A function to compile a given entry for rendering. This returns the following properties:

-   `<Content />` - A component used to render the document's contents in an Astro file.
-   `headings` - A generated list of headings, [mirroring Astro's `getHeadings()` utility](/en/guides/markdown-content/#available-properties) on Markdown and MDX imports.
-   `remarkPluginFrontmatter` \- The modified frontmatter object after any [Markdown plugins have been applied](/en/guides/markdown-content/#modifying-frontmatter-programmatically). Set to type `any`.

```
---

const entry = await getEntry('blog', 'entry-1');

if (!entry) {
   // Handle Error, for example:
  throw new Error('Could not find blog post 1');
}
const { Content, headings, remarkPluginFrontmatter } = await render(entry);
---
```

Learn how to [render the body content of entries](/en/guides/content-collections/#rendering-body-content) with guided explanations and example usage.

## `astro:content` types

### `CollectionEntry`

Query functions including [`getCollection()`](#getcollection), [`getEntry()`](#getentry), and [`getEntries()`](#getentries) each return entries with the `CollectionEntry` type. This type is available as a utility from `astro:content`:

A generic type to use with the name of the collection you're querying to represent a single entry in that collection. For example, an entry in your `blog` collection would have the type `CollectionEntry<'blog'>`.

Each `CollectionEntry` is an object with the following values:

#### `CollectionEntry.id`

**Type:** `string`

A unique ID. Note that all IDs from Astro's built-in `glob()` loader are slugified.

#### `CollectionEntry.collection`

**Type:** [`CollectionKey`](#collectionkey)

The name of a collection in which entries are located. This is the name used to reference the collection in your schema and in querying functions.

#### `CollectionEntry.data`

**Type:** `CollectionSchema<TCollectionName>`

An object of frontmatter properties inferred from your collection schema ([see `defineCollection()` reference](#definecollection)). Defaults to `any` if no schema is configured.

#### `CollectionEntry.body`

**Type:** `string | undefined`

A string containing the raw, uncompiled body of the Markdown or MDX document.

Note that if [`retainBody`](/en/reference/content-loader-reference/#retainbody) is set to `false`, this value will be `undefined` instead of containing the raw file contents.

#### `CollectionEntry.rendered`

**Type:** `RenderedContent | undefined`

The rendered content of an entry as [stored by your loader](/en/reference/content-loader-reference/#dataentryrendered). For example, this can be the rendered content of a Markdown entry, or HTML from a CMS.

#### `CollectionEntry.filePath`

**Type:** `string | undefined`

The path to an entry relative to your project directory. This value is only available for local entries.

### `CollectionKey`

**Example Type:** `'blog' | 'authors' | ...`  

A string union of all collection names defined in your `src/content.config.*` file. This type can be useful when defining a generic function wrapping the built-in `getCollection()`.

```

  });
}
```

### `SchemaContext`

The `context` object that `defineCollection` uses for the function shape of `schema`. This type can be useful when building reusable schemas for multiple collections.

This includes the following property:

-   `image` - The `image()` schema helper that allows you [to use local images in Content Collections](/en/guides/images/#images-in-content-collections)

```

const blog = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/data/blog' }),
  schema: ({ image }) => z.object({
    title: z.string(),
    permalink: z.string().optional(),
    image: imageSchema({ image })
  }),
});
```

## `astro` types

### `LiveDataCollectionResult`

**Type:** `{ entries?: Array<[LiveDataEntry](/en/reference/content-loader-reference/#livedataentry)<TData>>; error?: TError | LiveCollectionError; cacheHint?: [CacheHint](/en/reference/content-loader-reference/#cachehint); }`  

An object returned by [`getLiveCollection()`](#getlivecollection) containing the data fetched by the live loader. It has the following properties:

#### `LiveDataCollectionResult.entries`

**Type:** `Array<[LiveDataEntry](/en/reference/content-loader-reference/#livedataentry)<TData>> | undefined`

An array of [`LiveDataEntry`](/en/reference/content-loader-reference/#livedataentry) objects returned by the loader.

The following example accesses the returned entries for a live collection named `products`:

```
---

const { entries: allProducts } = await getLiveCollection('products');
---
```

Learn how to [access live data](/en/guides/content-collections/#accessing-live-data) with guided explanations and example usage.

#### `LiveDataCollectionResult.error`

**Type:** `TError | LiveCollectionError | undefined`

An error returned when the loader failed to load the collection. This can be a custom error defined by the loader or a built-in error.

The following example accesses the error returned when retrieving data from a live collection named `products`:

```
---

const { error } = await getLiveCollection('products');
---
```

Learn more about [error handling](/en/guides/content-collections/#error-handling) with guided explanations and example usage.

#### `LiveDataCollectionResult.cacheHint`

**Type:** `[CacheHint](/en/reference/content-loader-reference/#cachehint) | undefined`

An object providing guidance on how to cache this collection.

If you have [configured a cache provider](/en/guides/caching/#configure-caching), pass the cache hint directly to [`Astro.cache.set()`](/en/reference/api-reference/#cacheset):

```
---

if (cacheHint) {
  Astro.cache.set(cacheHint);
}
Astro.cache.set({ maxAge: 600 });
---
```

You can also use cache hints to set response headers manually:

```
---

const { cacheHint } = await getLiveCollection('products');

if (cacheHint?.tags) {
  Astro.response.headers.set('Cache-Tag', cacheHint.tags.join(','));
}
if (cacheHint?.lastModified) {
  Astro.response.headers.set('Last-Modified', cacheHint.lastModified.toUTCString());
}
---
```

### `LiveDataEntryResult`

**Type:** `{ entry?: [LiveDataEntry](/en/reference/content-loader-reference/#livedataentry)<TData>; error?: TError | LiveCollectionError; cacheHint?: [CacheHint](/en/reference/content-loader-reference/#cachehint); }`  

An object returned by [`getLiveEntry()`](#getliveentry) containing the data fetched by the live loader. It has the following properties:

#### `LiveDataEntryResult.entry`

**Type:** `[LiveDataEntry](/en/reference/content-loader-reference/#livedataentry)<TData> | undefined`

The [`LiveDataEntry`](/en/reference/content-loader-reference/#livedataentry) object returned by the loader.

The following example accesses the requested entry in a live collection named `products`:

```
---

const { entry } = await getLiveEntry('products', Astro.params.id);
---
```

Learn how to [access live data](/en/guides/content-collections/#accessing-live-data) with guided explanations and example usage.

#### `LiveDataEntryResult.error`

**Type:** `TError | LiveCollectionError | undefined`

An error returned when the loader failed to load the entry. This can be a custom error defined by the loader or a built-in error.

The following example accesses the requested entry in a live collection named `products` and any error, and redirects to the 404 page if an error exists:

```
---

const { entry, error } = await getLiveEntry('products', Astro.params.id);

if (error) {
  return Astro.redirect('/404');
}
---
<h1>{entry.data.name}</h1>
```

Learn more about [error handling](/en/guides/content-collections/#error-handling) with guided explanations and example usage.

#### `LiveDataEntryResult.cacheHint`

**Type:** `[CacheHint](/en/reference/content-loader-reference/#cachehint) | undefined`

An object providing data that can be used to inform a caching strategy.

If you have [configured a cache provider](/en/guides/caching/#configure-caching), pass the cache hint directly to [`Astro.cache.set()`](/en/reference/api-reference/#cacheset):

```
---

if (cacheHint) {
  Astro.cache.set(cacheHint);
}
Astro.cache.set({ maxAge: 300 });
---
```

You can also use cache hints to set response headers manually:

```
---

const { cacheHint } = await getLiveEntry('products', Astro.params.id);

if (cacheHint?.tags) {
  Astro.response.headers.set('Cache-Tag', cacheHint.tags.join(','));
}
if (cacheHint?.lastModified) {
  Astro.response.headers.set('Last-Modified', cacheHint.lastModified.toUTCString());
}
---
```

## [Environment Variables API Reference](https://docharvest.github.io/docs/astro/reference/modules/astro-env/)

Contents

astro

Environment Variables API Reference

Astro

Environment Variables API Reference

The `astro:env` API lets you configure a type-safe schema for environment variables you have set. This allows you to indicate whether they should be available on the server or the client, and define their data type and additional properties. For examples and usage instructions, [see the `astro:env` guide](/en/guides/environment-variables/#type-safe-environment-variables).

## Imports from `astro:env`

### `getSecret()`

The `getSecret()` helper function allows retrieving the raw value of an environment variable by its key.

For example, you can retrieve a boolean value as a string:

```
import {
  FEATURE_FLAG, // boolean
  getSecret
} from 'astro:env/server'

getSecret('FEATURE_FLAG') // string | undefined
```

This can also be useful to get a secret not defined in your schema, for example one that depends on dynamic data from a database or API.

If you need to retrieve environment variables programmatically, we recommend using `getSecret()` instead of `process.env` (or equivalent). Because its implementation is provided by your adapter, you won't need to update all your calls if you switch adapters. It defaults to `process.env` in dev and build.

## [Fetch routing API reference](https://docharvest.github.io/docs/astro/reference/modules/astro-fetch/)

Contents

astro

Fetch routing API reference

Astro

Fetch routing API reference

The `astro/fetch` module provides [advanced routing](/en/guides/routing/#advanced-routing) handlers built on top of the standard Fetch API.

## Imports from `astro/fetch`

### `FetchState`

The per-request state object. Create one at the start of your `fetch` method:

```

const state = new FetchState(request);
```

`FetchState` tracks the matched route, cookies, session providers, and other per-request data. All handler functions require it as their first argument.

Learn how to [compose handlers](/en/guides/routing/#composing-individual-handlers) with `FetchState` in the advanced routing guide.

#### Properties

##### `state.request`

**Type:** `Request`

The incoming [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object.

##### `state.url`

**Type:** `URL`

A normalized [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) derived from the request.

##### `state.pathname`

**Type:** `string`

The base-stripped, decoded pathname of the request (e.g. `/about` or `/blog/my-post`).

##### `state.routeData`

**Type:** `[RouteData](/en/reference/integrations-reference/#routedata) | undefined`

The matched route for this request, if any. This is resolved automatically when the `FetchState` is created.

##### `state.cookies`

**Type:** `AstroCookies`

An [`AstroCookies`](/en/reference/api-reference/#cookies) instance for reading and setting cookies on this request.

##### `state.locals`

**Type:** `App.Locals`

A request-scoped object for storing custom data. This is the same [`locals`](/en/reference/api-reference/#locals) object available in [middleware](/en/guides/middleware/) and [API routes](/en/guides/endpoints/#server-endpoints-api-routes).

##### `state.params`

**Type:** `Params | undefined`

Route parameters derived from the matched route and pathname (e.g. `{ slug: 'my-post' }` for a `[slug].astro` route).

##### `state.status`

**Type:** `number`  
**Default:** `200`

The HTTP status code for the response. You can set this before rendering to control the response status (e.g. `state.status = 404`).

##### `state.response`

**Type:** `Response | undefined`  
**Default:** `undefined`

The `Response` produced by handlers after rendering completes. This is set automatically by [`pages()`](#pages) and [`middleware()`](#middleware), allowing you to inspect or use the response later in the pipeline:

```
const response = await middleware(state, (s) => pages(s));
// state.response is now the same object as response
```

#### Methods

##### `state.rewrite()`

**Type:** `(payload: [RewritePayload](/en/reference/modules/astro-middleware/#rewritepayload)) => Promise<Response>`

Triggers a [rewrite](/en/guides/routing/#rewrites) to a different route. The `payload` can be a pathname string (`'/other-page'`), a URL, or a `Request`:

```
const response = await state.rewrite('/other-page');
```

### `astro()`

**Type:** `(state: [FetchState](#fetchstate)) => Promise<Response>`

The all-in-one handler that runs the full Astro pipeline (sessions, cache, redirects, trailing-slash, actions, middleware, pages, and i18n) in the default order. Use this when you want to add logic before or after Astro without changing the internal pipeline order:

```

    // custom pre-processing here...
    const response = await astro(state);
    // custom post-processing here...
    return response;
  },
};
```

### `actions()`

**Type:** `(state: [FetchState](#fetchstate)) => Promise<Response | undefined> | undefined`

Handles [Astro Actions](/en/guides/actions/) (RPC and form submissions). Returns a `Response` for RPC actions, or `undefined` for form actions and non-action requests. Check the return value to decide whether to continue rendering:

```
const actionResponse = await actions(state);
if (actionResponse) return actionResponse;
// otherwise continue to page rendering...
```

### `cache()`

**Type:** `(state: [FetchState](#fetchstate), next: () => Promise<Response>) => Promise<Response>`

Wraps a render callback with [cache](/en/guides/caching/) provider logic. Handles runtime caching, CDN-based providers, and the no-cache case.

### `i18n()`

**Type:** `(state: [FetchState](#fetchstate), response: Response) => Promise<Response>`

Post-processes a response against your [i18n configuration](/en/guides/internationalization/). Handles locale redirects, 404s for invalid locales, and fallback routing. Call this after rendering:

```
const response = await middleware(state, (s) => pages(s));
return i18n(state, response);
```

### `middleware()`

**Type:** `(state: [FetchState](#fetchstate), next: (state: FetchState) => Promise<Response>) => Promise<Response>`

Runs Astro's middleware chain (from `src/middleware.ts`). The `next` callback is called at the bottom of the chain to produce the response, typically by calling `pages()`:

```
const response = await middleware(state, (s) => pages(s));
```

### `pages()`

**Type:** `(state: [FetchState](#fetchstate)) => Promise<Response>`

Dispatches the request to the matched Astro route (page, endpoint, or fallback). This is the core rendering handler, and most custom pipelines will include it.

### `redirects()`

**Type:** `(state: [FetchState](#fetchstate)) => Promise<Response> | undefined`

Handles redirect routes defined in your [Astro config](/en/reference/configuration-reference/#redirects). Returns a redirect `Response` if the matched route is a redirect, or `undefined` if the caller should continue processing.

### `sessions()`

**Type:** `(state: [FetchState](#fetchstate)) => Promise<void> | void`

Registers the [session](/en/guides/sessions/) provider. Sessions are created lazily when your code accesses `ctx.session` and persisted automatically at the end of the request. Call this early in the pipeline (before middleware runs):

```
await sessions(state);
// ...render pipeline...
```

### `trailingSlash()`

**Type:** `(state: [FetchState](#fetchstate)) => Response | undefined`

Checks if the request pathname needs [trailing-slash](/en/reference/configuration-reference/#trailingslash) normalization and returns a redirect `Response` if so. Returns `undefined` when no redirect is needed.

## [Hono routing API reference](https://docharvest.github.io/docs/astro/reference/modules/astro-hono/)

Contents

astro

Hono routing API reference

Astro

Hono routing API reference

The `astro/hono` module provides [advanced routing](/en/guides/routing/#advanced-routing) handlers built as Hono-compatible wrappers.

## Imports from `astro/hono`

The `astro/hono` module exports the same handler names as [`astro/fetch`](/en/reference/modules/astro-fetch/), but each returns a Hono middleware function. This lets you mix Astro handlers with any Hono middleware from the ecosystem.

Learn how to [use Hono](/en/guides/routing/#using-with-hono) with Astro in the advanced routing guide.

## [Internationalization API Reference](https://docharvest.github.io/docs/astro/reference/modules/astro-i18n/)

Contents

astro

Internationalization API Reference

Astro

Internationalization API Reference

This module provides functions to help you create URLs using your project's configured locales.

Creating routes for your project with the i18n router will depend on certain configuration values you have set that affect your page routes. When creating routes with these functions, be sure to take into account your individual settings for:

-   [`base`](/en/reference/configuration-reference/#base)
-   [`trailingSlash`](/en/reference/configuration-reference/#trailingslash)
-   [`build.format`](/en/reference/configuration-reference/#buildformat)
-   [`site`](/en/reference/configuration-reference/#site)

Also, note that the returned URLs created by these functions for your `defaultLocale` will reflect your `i18n.routing` configuration.

For features and usage examples, [see our i18n routing guide](/en/guides/internationalization/).

## Imports from `astro:i18n`

### `getRelativeLocaleUrl()`

**Type:** `(locale: string, path?: string, options?: GetLocaleOptions) => string`

Use this function to retrieve a relative path for a locale. If the locale doesn't exist, Astro throws an error.

```
---

getRelativeLocaleUrl("fr");
// returns /fr

getRelativeLocaleUrl("fr", "");
// returns /fr/

getRelativeLocaleUrl("fr", "getting-started");
// returns /fr/getting-started

getRelativeLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog"
}); 
// returns /blog/fr-ca/getting-started

getRelativeLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog",
  normalizeLocale: false
}); 
// returns /blog/fr_CA/getting-started
---
```

### `getAbsoluteLocaleUrl()`

**Type:** `(locale: string, path?: string, options?: GetLocaleOptions) => string`

Use this function to retrieve an absolute path for a locale when \[`site`\] has a value. If \[`site`\] isn't configured, the function returns a relative URL. If the locale doesn't exist, Astro throws an error.

```
---

// If `site` is set to be `https://example.com`

getAbsoluteLocaleUrl("fr"); 
// returns https://example.com/fr

getAbsoluteLocaleUrl("fr", ""); 
// returns https://example.com/fr/

getAbsoluteLocaleUrl("fr", "getting-started"); 
// returns https://example.com/fr/getting-started

getAbsoluteLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog"
}); 
// returns https://example.com/blog/fr-ca/getting-started

getAbsoluteLocaleUrl("fr_CA", "getting-started", {
  prependWith: "blog",
  normalizeLocale: false
}); 
// returns https://example.com/blog/fr_CA/getting-started
---
```

### `getRelativeLocaleUrlList()`

**Type:** `(path?: string, options?: GetLocaleOptions) => string[]`

Use this like [`getRelativeLocaleUrl`](#getrelativelocaleurl) to return a list of relative paths for all the locales.

### `getAbsoluteLocaleUrlList()`

**Type:** `(path?: string, options?: GetLocaleOptions) => string[]`

Use this like [`getAbsoluteLocaleUrl`](/en/guides/internationalization/#custom-locale-paths) to return a list of absolute paths for all the locales.

### `getPathByLocale()`

**Type:** `(locale: string) => string`

A function that returns the `path` associated to one or more `codes` when [custom locale paths](/en/guides/internationalization/#custom-locale-paths) are configured.

```

  } else {
    return redirectToDefaultLocale(context, 302);
  }
})
```

### `redirectToFallback()`

**Type:** `(context: APIContext, response: Response) => Promise<Response>`  

:::note Available only when `i18n.routing` is set to `"manual"` :::

A function that allows you to use your [`i18n.fallback` configuration](/en/reference/configuration-reference/#i18nfallback) in your own middleware.

```

  if (response.status >= 300) {
    return redirectToFallback(context, response)
  }
  return response;
})
```

### `notFound()`

**Type:** `(context: APIContext, response?: Response) => Promise<Response> | undefined`  

:::note Available only when `i18n.routing` is set to `"manual"` :::

Use this function in your routing middleware to return a 404 when:

-   the current path isn't a root. e.g. `/` or `/<base>`
-   the URL doesn't contain a locale

When a `Response` is passed, the new `Response` emitted by this function will contain the same headers of the original response.

```

  if (pathNotFound) {
    return pathNotFound;
  }
  return next();
})
```

### `middleware()`

**Type:** `(options: { fallbackType: "redirect" | "rewrite", prefixDefaultLocale: boolean, redirectToDefaultLocale: boolean }) => MiddlewareHandler`  

:::note Available only when `i18n.routing` is set to `"manual"` :::

A function that allows you to programmatically create the Astro i18n middleware.

This is useful when you still want to use the default i18n logic, but add only a few exceptions to your website.

```

const customLogic = defineMiddleware(async (context, next) => {
  const response = await next();

  // Custom logic after resolving the response.
  // It's possible to catch the response coming from Astro i18n middleware.

  return response;
});
```

### `requestHasLocale()`

**Type:** `(context: APIContext) => boolean`  

:::note Available only when `i18n.routing` is set to `"manual"` :::

Checks whether the current URL contains a configured locale. Internally, this function will use `APIContext#url.pathname`.

```

  }
  return new Response("Not found", { status: 404 });
})
```

### `normalizeTheLocale()`

**Type:** `(locale: string) => string`

Replaces underscores (`_`) with hyphens (`-`) in the given locale before returning a lowercase version.

```
---

normalizeTheLocale("it_VT") // returns `it-vt`
// Assuming the current locale is `"pt-PT"`:
normalizeTheLocale(Astro.currentLocale) // returns `pt-pt`
---
```

### `pathHasLocale()`

**Type:** `(path: string) => boolean`  

Checks whether the given path contains a configured locale.

This is useful to prevent errors before using an i18n utility that relies on a locale from a URL path.

```
export default defineConfig({
  i18n: {
    locales: [
      { codes: ["it-VT", "it"], path: "italiano" },
      "es"
    ]
  }
})
```

```
---

pathHasLocale("italiano"); // returns `true`
pathHasLocale("es"); // returns `true`
pathHasLocale('/es/blog/'); // returns `true`
pathHasLocale("it-VT"); // returns `false`
---
```

### `toCodes()`

**Type:** `(locales: Locales) => string[]`  

Retrieves the configured locale codes for each locale defined in your configuration. When multiple codes are associated to a locale, only the first one will be added to the array.

```
export default defineConfig({
  i18n: {
    locales: [
      { codes: ["it-VT", "it"], path: "italiano" },
      "es"
    ]
  }
})
```

```
---

toCodes(i18n!.locales); // ["it-VT", "es"]
---
```

### `toPaths()`

**Type:** `(locales: Locales) => string[]`  

Retrieves the configured locale paths for each locale defined in your configuration.

```
export default defineConfig({
  i18n: {
    locales: [
      { codes: ["it-VT", "it"], path: "italiano" },
      "es"
    ]
  }
})
```

```
---

toPaths(i18n!.locales); // ["italiano", "es"]
---
```

## [Middleware API Reference](https://docharvest.github.io/docs/astro/reference/modules/astro-middleware/)

Contents

astro

Middleware API Reference

Astro

Middleware API Reference

Middleware allows you to intercept requests and responses and inject behaviors dynamically every time a page or endpoint is about to be rendered. For features and usage examples, [see our middleware guide](/en/guides/middleware/).

## Imports from `astro:middleware`

The following helpers are imported from the virtual middleware module:

### `defineMiddleware()`

**Type:** `(fn: [MiddlewareHandler](#middlewarehandler)) => MiddlewareHandler`

A function for defining a middleware function with type safety. When you use this utility, the [`context`](#context) and [`next()`](#next) arguments are automatically typed, and you will get a TypeScript error if you try to return a [value not supported in your middleware](#middlewarehandler).

### `sequence()`

**Type:** `(...handlers: [MiddlewareHandler](#middlewarehandler)[]) => MiddlewareHandler`

A function that accepts middleware functions as arguments, and will execute them in the order in which they are passed.

```

async function validation(context, next) {/* ... */}
async function auth(context, next) {/* ... */}
async function greeting(context, next) {/* ... */}
```

## Imports from `astro/middleware`

The following helpers can be imported from the regular middleware module when you build an [Astro Integration](/en/reference/integrations-reference/):

### `createContext()`

**Type:** `(context: [CreateContext](#createcontext-1)) => [APIContext](/en/reference/api-reference/)`  

A low-level API to create an [`APIContext`](/en/reference/api-reference/)to be passed to an Astro middleware [`onRequest()` function](#onrequest).

This function can be used by integrations/adapters to programmatically execute the Astro middleware.

### `defineMiddleware()`

See [`defineMiddleware()`](#definemiddleware) from `astro:middleware`.

### `sequence()`

See [`sequence()`](#sequence) from `astro:middleware`.

### `trySerializeLocals()`

**Type:** `(value: unknown) => string`  

A low-level API that takes in any value and tries to return a serialized version (a string) of it. If the value cannot be serialized, the function will throw a runtime error.

## `astro/middleware` types

The following types are imported from the regular middleware module:

### `CreateContext`

**Type:** `{ request: Request; params?: Params; userDefinedLocales?: string[]; defaultLocale: string; locals: App.Locals; clientAddress?: string }`  

An object to [create a context](#createcontext) to be passed to an Astro middleware. This contains the following properties:

#### `CreateContext.request`

**Type:** `Request`

The incoming [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) object.

#### `CreateContext.params`

**Type:** `Params`

An object containing the optional parameters to be passed to [`Astro.params`](/en/reference/api-reference/#params).

#### `CreateContext.userDefinedLocales`

**Type:** `string[]`  

A list of supported locales defined in the [user's `i18n` configuration](/en/reference/configuration-reference/#i18nlocales).

#### `CreateContext.defaultLocale`

**Type:** `string`  

The default locale defined in the [user's `i18n` configuration](/en/reference/configuration-reference/#i18ndefaultlocale).

#### `CreateContext.locals`

**Type:** `App.Locals`  

An object for storing arbitrary information from a middleware, accessible to the user via [`Astro.locals`](/en/reference/api-reference/#locals).

Learn more about [storing data in `locals`](/en/guides/middleware/#storing-data-in-contextlocals) with example usage.

#### `CreateContext.clientAddress`

**Type:** `string`  

The [IP address](https://en.wikipedia.org/wiki/IP_address) of the request.

This must be provided by the adapter or platform from a trusted source (e.g. socket address, platform-provided header).

If not provided, accessing `clientAddress` will throw an error.

## `astro` types

### `MiddlewareHandler`

**Type:** `(context: [APIContext](/en/reference/api-reference/), next: [MiddlewareNext](#middlewarenext)) => Promise<Response> | Response | Promise<void> | void`

Represents an Astro middleware function. Middleware handlers receive two arguments and can either return a `Response` directly or call `next()` to invoke the next middleware in the chain. Alternatively, you can use [`defineMiddleware()`](#definemiddleware) to get type safety for your middleware.

The following example imports the `MiddlewareHandler` type to get type safety in the [`onRequest()`](#onrequest) function:

A middleware handler receives the following properties:

#### `context`

**Type:** [`APIContext`](/en/reference/api-reference/)

An [Astro context](/en/reference/api-reference/) object mirroring many of the `Astro` global properties.

#### `next()`

**Type:** [`MiddlewareNext`](#middlewarenext)  

A function that calls all the subsequent middleware in the chain and returns a `Response`. For example, other middleware could modify the HTML body of a response and awaiting the result of `next()` would allow your middleware to respond to those changes.

Since Astro v4.13.0, `next()` accepts an optional URL path parameter in the form of a string, `URL`, or `Request` to [rewrite](/en/guides/routing/#rewrites) the current request without retriggering a new rendering phase.

The following example uses `next()` to serve content from a different path when the current path matches `/old-path`:

```

  }
  return next();
};
```

### `MiddlewareNext`

**Type:** `(rewritePayload?: [RewritePayload](#rewritepayload)) => Promise<Response>`  

Represents the [`next()` function](#next) passed to middleware handlers.

### `RewritePayload`

**Type:** `string | URL | Request`  

Represents the destination for a [rewrite](/en/guides/routing/#rewrites) when passed to the [`next()`](#next) function.

## Middleware exports

When defining your project’s middleware in `src/middleware.js`, export the following user-defined functions:

### `onRequest()`

**Type:** [`MiddlewareHandler`](#middlewarehandler)

A required exported function from `src/middleware.js` that will be called before rendering every page or API route. It receives two arguments: [`context`](#context) and [`next()`](#next). `onRequest()` must return a `Response`: either directly, or by calling `next()`.

```

};
```

## [Static Paths API Reference](https://docharvest.github.io/docs/astro/reference/modules/astro-static-paths/)

Contents

astro

Static Paths API Reference

Astro

Static Paths API Reference

This module provides utilities to help adapters collect static paths from within their target runtime (e.g. `workerd`). This only provides a real implementation in the `prerender` Vite environment. In other environments, it returns a no-op implementation.

## Imports from `astro:static-paths`

### `StaticPaths`

Allows adapters to collect all paths that need to be prerendered from within their target runtime. This is useful when [implementing a custom prerenderer](/en/reference/adapter-reference/#custom-prerenderer) that runs in a non-Node environment:

The `StaticPaths` constructor accepts a required [SSR manifest](/en/reference/integrations-reference/#ssrmanifest) and an object describing the route cache and providing a method to access the component used to render the route. The preferred method to initiate a `StaticPaths` instance is to pass it an [app instance](/en/reference/modules/astro-app/#the-app-instance).

The following example initializes a `StaticPaths` instance from an app in an adapter server entrypoint:

```

const app = createApp();
const staticPaths = new StaticPaths(app);
```

#### `StaticPaths.getAll()`

**Type:** `() => Promise<Array<{ pathname: string, route: [RouteData](/en/reference/integrations-reference/#routedata) }>>`

Retrieves all paths that should be prerendered. This returns a promise that resolves to an array of objects describing the route path and its data.

The following example collects all static paths to be pre-rendered before returning them as `Response` in an adapter handler:

```

    // Endpoint to collect static paths during build
    if (pathname === '/__astro_static_paths') {
      const staticPaths = new StaticPaths(app);
      const paths = await staticPaths.getAll();
      // Returns array of { pathname: string, route: RouteData }
      return new Response(JSON.stringify({ paths }));
    }
    
    // ... handle other requests
  };
}
```

## [View Transitions Router API Reference](https://docharvest.github.io/docs/astro/reference/modules/astro-transitions/)

Contents

astro

View Transitions Router API Reference

Astro

View Transitions Router API Reference

These modules provide functions to control and interact with the View Transitions API and client-side router.

:::note This API is compatible with the `<ClientRouter />` included in `astro:transitions`, but can't be used with native browser MPA routing. :::

For features and usage examples, [see our View Transitions guide](/en/guides/view-transitions/).

## Imports from `astro:transitions`

### `<ClientRouter />`

Opt in to using view transitions on individual pages by importing and adding the `<ClientRouter />` routing component to `<head>` on every desired page.

```
---

---
<html lang="en">
  <head>
    <title>My Homepage</title>
    <ClientRouter />
  </head>
  <body>
    <h1>Welcome to my website!</h1>
  </body>
</html>
```

See more about how to [control the router](/en/guides/view-transitions/#router-control) and [add transition directives](/en/guides/view-transitions/#transition-directives) to page elements and components.

The `<ClientRouter />` component accepts the following props:

#### \`fallback\`

**Type:** [`Fallback`](#fallback)  
**Default:** `animate`

Defines the fallback strategy to use for browsers that do not support the [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API).

### `fade`

**Type:** `(opts: { duration?: string | number }) => TransitionDirectionalAnimations`

Utility function to support customizing the duration of the built-in `fade` animation.

```
---

---

<!-- Fade transition with the default duration -->
<div transition:animate="fade" />

<!-- Fade transition with a duration of 400 milliseconds -->
<div transition:animate={fade({ duration: '0.4s' })} />
```

### `slide`

**Type:** `(opts: { duration?: string | number }) => TransitionDirectionalAnimations`

Utility function to support customizing the duration of the built-in `slide` animation.

```
---

---

<!-- Slide transition with the default duration -->
<div transition:animate="slide" />

<!-- Slide transition with a duration of 400 milliseconds -->
<div transition:animate={slide({ duration: '0.4s' })} />
```

## Imports from `astro:transitions/client`

### `navigate()`

**Type:** `(href: string, options?: Options) => void`  

Executes a navigation to the given `href` using the View Transitions API.

This function signature is based on the [`navigate` function from the browser Navigation API](https://developer.mozilla.org/en-US/docs/Web/API/Navigation/navigate). Although based on the Navigation API, this function is implemented on top of the [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) to allow for navigation without reloading the page.

`navigate()` does not perform sanitization on the `href` parameter. [Sanitize user input](/en/guides/view-transitions/#navigating-with-user-input) if you use it to determine the URL to navigate to.

#### `history` option

**Type:** `'auto' | 'push' | 'replace'`  
**Default:** `'auto'`  

Defines how this navigation should be added to the browser history.

-   `'push'`: the router will use `history.pushState` to create a new entry in the browser history.
-   `'replace'`: the router will use `history.replaceState` to update the URL without adding a new entry into navigation.
-   `'auto'` (default): the router will attempt `history.pushState`, but if the URL cannot be transitioned to, the current URL will remain with no changes to the browser history.

This option follows the [`history` option](https://developer.mozilla.org/en-US/docs/Web/API/Navigation/navigate#history) from the browser Navigation API but simplified for the cases that can happen on an Astro project.

#### `formData` option

**Type:** `FormData`  

A `FormData` object for `POST` requests.

When this option is provided, the requests to the navigation target page will be sent as a `POST` request with the form data object as the content.

Submitting an HTML form with view transitions enabled will use this method instead of the default navigation with page reload. Calling this method allows triggering the same behavior programmatically.

#### `info` option

**Type:** `any`  

Arbitrary data to be included in the `astro:before-preparation` and `astro:before-swap` events caused by this navigation.

This option mimics the [`info` option](https://developer.mozilla.org/en-US/docs/Web/API/Navigation/navigate#info) from the browser Navigation API.

#### `state` option

**Type:** `any`  

Arbitrary data to be associated with the `NavigationHistoryEntry` object created by this navigation. This data can then be retrieved using the [`history.getState` function](https://developer.mozilla.org/en-US/docs/Web/API/NavigationHistoryEntry/getState) from the History API.

This option mimics the [`state` option](https://developer.mozilla.org/en-US/docs/Web/API/Navigation/navigate#state) from the browser Navigation API.

#### `sourceElement` option

**Type:** `Element`  

The element that triggered this navigation, if any. This element will be available in the following events:

-   [`astro:before-preparation`](#astrobefore-preparation-event)
-   [`astro:before-swap`](#astrobefore-swap-event)

### `supportsViewTransitions`

**Type:** `boolean`  

Whether or not view transitions are supported and enabled in the current browser.

### `transitionEnabledOnThisPage()`

**Type:** `() => boolean`  

Whether or not the current page has view transitions enabled for client-side navigation. This can be used to make components that behave differently when they are used on pages with view transitions.

### `getFallback()`

**Type:** `() => [Fallback](#fallback)`  
**Default:** `animate`  

Returns the fallback strategy to use (`animate` by default) in browsers that do not support view transitions.

See the guide on [Fallback control](/en/guides/view-transitions/#fallback-control) for how to choose and configure the fallback behavior.

### `swapFunctions`

**Type:** `object`  

An object containing the utility functions used to build Astro’s default swap function. These can be useful when [building a custom swap function](/en/guides/view-transitions/#building-a-custom-swap-function).

`swapFunctions` provides the following methods:

#### `deselectScripts()`

**Type:** `(newDocument: Document) => void`

Marks scripts in the new document that should not be executed. Those scripts are already in the current document and are not flagged for re-execution using [`data-astro-rerun`](/en/guides/view-transitions/#data-astro-rerun).

#### `swapRootAttributes()`

**Type:** `(newDocument: Document) => void`

Swaps the attributes between the document roots, like the `lang` attribute. This also includes Astro-injected internal attributes like `data-astro-transition`, which makes the transition direction available to Astro-generated CSS rules.

When making a custom swap function, it is important to call this function so as not to break the view transition's animations.

#### `swapHeadElements()`

**Type:** `(newDocument: Document) => void`

Removes every element from the current document's `<head>` that is not persisted to the new document. Then appends all new elements from the new document's `<head>` to the current document's `<head>`.

#### `saveFocus()`

**Type:** `() => () => void`

Stores the element in focus on the current page and returns a function that when called, if the focused element was persisted, returns the focus to it.

#### `swapBodyElement()`

**Type:** `(newBody: Element, oldBody: Element) => void`

Replaces the old body with the new body. Then, goes through every element in the old body that should be persisted and have a matching element in the new body and swaps the old element back in place.

## `astro:transitions/client` types

### `Direction`

**Type:** `'forward' | 'back'`  

A union of animation directions:

-   `forward`: navigating to the next page in the history or to a new page.
-   `back`: navigating to the previous page in the history.

### `Fallback`

**Type:** `'none' | 'animate' | 'swap'`  

A union of fallback strategies to use in browsers that do not support view transitions:

-   `animate`: Astro will simulate view transitions using custom attributes before updating page content.
-   `swap`: Astro will not attempt to animate the page. Instead, the old page will be immediately replaced by the new one.
-   `none`: Astro will not do any animated page transitions at all. Instead, you will get full page navigation in non-supporting browsers.

Learn more about [controlling the fallback strategy](/en/guides/view-transitions/#fallback-control) with the `ClientRouter`.

### `NavigationTypeString`

**Type:** `'push' | 'replace' | 'traverse'`  

A union of supported history navigation events.

### `TransitionBeforePreparationEvent`

**Type:** `Event`  

Represents an [`astro:before-preparation` event](#astrobefore-preparation-event). This can be useful to type the event received by a listener:

```
---
---

<script>
  import type { TransitionBeforePreparationEvent } from "astro:transitions/client";

  function listener(event: TransitionBeforePreparationEvent) {
    /* do something */
  }

  document.addEventListener("astro:before-preparation", listener);
</script>
```

### `TransitionBeforeSwapEvent`

**Type:** `Event`  

Represents an [`astro:before-swap` event](#astrobefore-swap-event). This can be useful to type the event received by a listener:

```
---
---

<script>
  import type { TransitionBeforeSwapEvent } from "astro:transitions/client";

  function listener(event: TransitionBeforeSwapEvent) {
    /* do something */
  }

  document.addEventListener("astro:before-swap", listener);
</script>
```

## Lifecycle events

### `astro:before-preparation` event

**Type:** [`TransitionBeforePreparationEvent`](#transitionbeforepreparationevent)  

An event dispatched at the beginning of a navigation using the View Transitions router. This event happens before any request is made and any browser state is changed.

This event has the attributes:

-   [`info`](#info)
-   [`sourceElement`](#sourceelement)
-   [`navigationType`](#navigationtype)
-   [`direction`](#direction-1)
-   [`from`](#from)
-   [`to`](#to)
-   [`formData`](#formdata)
-   [`loader()`](#loader)

Read more about how to use this event on the [View Transitions guide](/en/guides/view-transitions/#astrobefore-preparation).

### `astro:after-preparation` event

**Type:** `Event`  

An event dispatched after the next page in a navigation using View Transitions router is loaded.

This event has no attributes.

Read more about how to use this event on the [View Transitions guide](/en/guides/view-transitions/#astroafter-preparation).

### `astro:before-swap` event

**Type:** [`TransitionBeforeSwapEvent`](#transitionbeforeswapevent)  

An event dispatched after the next page is parsed, prepared, and linked into a document in preparation for the transition but before any content is swapped between the documents.

This event can't be canceled. Calling `preventDefault()` is a no-op.

This event has the attributes:

-   [`info`](#info)
-   [`sourceElement`](#sourceelement)
-   [`navigationType`](#navigationtype)
-   [`direction`](#direction-1)
-   [`from`](#from)
-   [`to`](#to)
-   [`viewTransition`](#viewtransition)
-   [`swap()`](#swap)

Read more about how to use this event on the [View Transitions guide](/en/guides/view-transitions/#astrobefore-swap).

### `astro:after-swap` event

**Type:** `Event`

An event dispatched after the contents of the page have been swapped but before the view transition ends.

The history entry and scroll position have already been updated when this event is triggered.

### `astro:page-load` event

**Type:** `Event`

An event dispatched after a page completes loading, whether from a navigation using view transitions or native to the browser.

When view transitions is enabled on the page, code that would normally execute on `DOMContentLoaded` should be changed to execute on this event.

### Lifecycle events attributes

The following attributes are common to both the [`astro:before-preparation`](#astrobefore-preparation-event) and [`astro:before-swap`](#astrobefore-swap-event) events, except for some that are only available with one or the other.

#### `info`

**Type:** `any`

Arbitrary data defined during navigation.

This is the literal value passed on the [`info` option](#info-option) of the [`navigate()` function](#navigate).

#### `sourceElement`

**Type:** `Element | undefined`

The element that triggered the navigation. This can be, for example, an `<a>` element that was clicked.

When using the [`navigate()` function](#navigate), this will be the element specified in the call.

#### `newDocument`

**Type:** `Document`

The document for the next page in the navigation. The contents of this document will be swapped in place of the contents of the current document.

#### `navigationType`

**Type:** [`NavigationTypeString`](#navigationtypestring)

Which kind of history navigation is happening.

-   `push`: a new `NavigationHistoryEntry` is being created for the new page.
-   `replace`: the current `NavigationHistoryEntry` is being replaced with an entry for the new page.
-   `traverse`: no `NavigationHistoryEntry` is created. The position in the history is changing. The direction of the traversal is given on the [`direction` attribute](#direction-1).

#### `direction`

**Type:** `string`

The direction of the transition:

-   In an [`astro:before-preparation` event](#astrobefore-preparation-event), this can be used to define custom directions. The property is writable and accepts any string.
-   In an [`astro:before-swap` event](#astrobefore-swap-event), this can be used to retrieve the transition direction. The property is readonly and its value can be a predefined [`Direction`](#direction) or any string that an `astro:before-preparation` event listener might have set.

#### `from`

**Type:** `URL`

The URL of the page initiating the navigation.

#### `to`

**Type:** `URL`

The URL of the page being navigated to. This property can be modified, the value at the end of the lifecycle will be used in the `NavigationHistoryEntry` for the next page.

#### `formData`

**Type:** `FormData | undefined`  
**Available in:** [`astro:before-preparation` event](#astrobefore-preparation-event)

When set, a `POST` request will be sent to the [`to` URL](#to) with the given `FormData` object as the content instead of the normal `GET` request.

When submitting an HTML form with view transitions enabled, this field is automatically set to the data in the form. When using the [`navigate()` function](#navigate), this value is the same as given in the options.

#### `loader()`

**Type:** `() => Promise<void>`  
**Available in:** [`astro:before-preparation` event](#astrobefore-preparation-event)

Implementation of the following phase in the navigation (loading the next page). This implementation can be overridden to add extra behavior.

#### `viewTransition`

**Type:** [`ViewTransition`](https://developer.mozilla.org/en-US/docs/Web/API/ViewTransition)  
**Available in:** [`astro:before-swap` event](#astrobefore-swap-event)

The view transition object used in this navigation. On browsers that do not support the [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API), this is an object implementing the same API for convenience but without the DOM integration.

#### `swap()`

**Type:** `() => void`  
**Available in:** [`astro:before-swap` event](#astrobefore-swap-event)

Calls the default document swap logic. By default, this implementation will call the following functions in order:

1.  [`deselectScripts()`](#deselectscripts)
2.  [`swapRootAttributes()`](#swaprootattributes)
3.  [`swapHeadElements()`](#swapheadelements)
4.  [`saveFocus()`](#savefocus)
5.  [`swapBodyElement()`](#swapbodyelement)

Read more about [building a custom swap function](/en/guides/view-transitions/#building-a-custom-swap-function) in the View Transitions guide.

## [Zod API Reference](https://docharvest.github.io/docs/astro/reference/modules/astro-zod/)

Contents

astro

Zod API Reference

Astro

Zod API Reference

[Zod](https://github.com/colinhacks/zod) is a TypeScript-based schema declaration and validation library. This allows you to define schemas you can use to validate data and transform data, from a simple type (e.g. `string`, `number`) to complex data structures (e.g. nested objects).

The `astro/zod` module exposes a re-export of Zod that gives you access to all the features of Zod v4. By using this module, you do not need to install Zod yourself. This also ensures that your project uses the same API versions as Astro when using features such as [Content Collections](/en/guides/content-collections/) or [Actions](/en/guides/actions/).

See the [Zod website](https://zod.dev/) for complete documentation on how Zod works and what features are available.

## Imports from `astro/zod`

### `z`

**Type:** `object`

The `z` utility gives you access to validators for a wide range of data types, methods and types for working with your data.

Learn more about the `z` utility in [Zod documentation](https://zod.dev/basics)

#### Common data type validators

With Zod, you can validate any type of data, such as [primitives](https://zod.dev/api#primitives), [objects](https://zod.dev/api#objects), [arrays](https://zod.dev/api#arrays) and more.

The following example shows a cheatsheet of many common Zod data types to create a `user` schema:

```

const user = z.object({
  username: z.string(),
  name: z.string().min(2),
  email: z.email(),
  role: z.enum(["admin", "editor"]),
  language: z.enum(["en", "fr", "es"]).default("en"),
  hobbies: z.array(z.string()),
  age: z.number(),
  isEmailConfirmed: z.boolean(),
  inscriptionDate: z.date(),
  website: z.url().optional(),
});
```

#### Extracting a TypeScript type

Zod allows you to create a TypeScript type from any schema [using Zod type inference](https://zod.dev/basics#inferring-types). This can be useful for describing an expected data structure when [defining component props](/en/guides/typescript/#component-props).

The following example create a `User` type based on the previous schema:

```
type User = z.infer<typeof user>;

/* The `User` type will be:
 * type User = {
 *   username: string;
 *   name: string;
 *   email: string;
 *   role: "admin" | "editor";
 *   language: "en" | "fr" | "es";
 *   hobbies: string[];
 *   age: number;
 *   isEmailConfirmed: boolean;
 *   inscriptionDate: Date;
 *   website?: string | undefined;
 * }
 */
```

#### Using Zod methods

Zod provides various schema methods to [customize error messages](https://zod.dev/error-customization), [transform data](https://zod.dev/api#transforms), or create [custom validation logics](https://zod.dev/api#refinements).

```
// Customize the error message
const nonEmptyStrings = z.array(z.string()).nonempty("Can't be empty!");

// Validate a data from a schema
nonEmptyStrings.parse([]); // will throws our custom error

// Create an object from a URL for a decorative img
const decorativeImg = z.string().transform((value) => {
  return { src: value, alt: "" };
});

// Create a custom validator and error message for a string
const constrainedString = z
  .string()
  .refine((val) => val.length > 0 && val.length <= 255, {
    error: "Must be between 1 and 255 characters.",
  });
```

### Individual imports

Alternatively, you can import all the Zod validators, methods and types available in the [`z` utility](#z) directly from the module.

The following example imports `coerce` to create a `Date` object from a date string:

```

const publishedOn = coerce.date();
const publicationDate = publishedOn.parse("2025-12-03");
```

## [Programmatic Astro API (experimental)](https://docharvest.github.io/docs/astro/reference/programmatic-reference/)

Contents

astro

Programmatic Astro API (experimental)

Astro

Programmatic Astro API (experimental)

If you need more control when running Astro, the `"astro"` package exports APIs to programmatically run the CLI commands. There are also two `astro:config` helpers that can programmatically [validate](#validateconfig) and [merge](#mergeconfig) configurations.

These APIs are experimental and their API signature may change. Any updates will be mentioned in the [Astro changelog](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md) and the information below will always show the current, up-to-date information.

## Commands

The following [CLI commands](/en/reference/cli-reference/) can be run programmatically.

### `dev()`

**Type:** `(inlineConfig: [AstroInlineConfig](#astroinlineconfig)) => Promise<[DevServer](#devserver)>`

Similar to [`astro dev`](/en/reference/cli-reference/#astro-dev), it runs Astro's development server.

```

const devServer = await dev({
  root: "./my-project",
});

// Stop the server if needed
await devServer.stop();
```

#### `DevServer`

```

	handle: (req: http.IncomingMessage, res: http.ServerResponse<http.IncomingMessage>) => void;
	watcher: vite.FSWatcher;
	stop(): Promise<void>;
}
```

##### `DevServer.address`

**Type:** `AddressInfo`

The address the dev server is listening on.

This property contains the value returned by Node's [`net.Server#address()` method](https://nodejs.org/api/net.html#serveraddress).

##### `DevServer.handle()`

**Type:** `(req: http.IncomingMessage, res: http.ServerResponse<http.IncomingMessage>) => void`

A handle for raw Node HTTP requests. You can call `handle()` with an [`http.IncomingMessage`](https://nodejs.org/api/http.html#class-httpincomingmessage) and an [`http.ServerResponse`](https://nodejs.org/api/http.html#class-httpserverresponse) instead of sending a request through the network.

##### `DevServer.watcher`

**Type:** `vite.FSWatcher`

The [Chokidar file watcher](https://github.com/paulmillr/chokidar#getting-started) as exposed by [Vite's development server](https://vite.dev/guide/api-javascript#vitedevserver).

##### `DevServer.stop()`

**Type:** `Promise<void>`

Stops the development server. This closes all idle connections and stops listening for new connections.

Returns a `Promise` that resolves once all pending requests have been fulfilled and all idle connections have been closed.

### `build()`

**Type:** `(inlineConfig: [AstroInlineConfig](#astroinlineconfig), options?: [BuildOptions](#buildoptions)) => Promise<void>`

Similar to [`astro build`](/en/reference/cli-reference/#astro-build), it builds your site for deployment.

```

await build({
  root: "./my-project",
});
```

#### `BuildOptions`

```

	teardownCompiler?: boolean;
}
```

##### `BuildOptions.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.

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

**Type:** `(inlineConfig: [AstroInlineConfig](#astroinlineconfig)) => Promise<[PreviewServer](#previewserver)>`

Similar to [`astro preview`](/en/reference/cli-reference/#astro-preview), it starts a local server to serve your build output.

If no adapter is set in the configuration, the preview server will only serve the built static files. If an adapter is set in the configuration, the preview server is provided by the adapter. Adapters are not required to provide a preview server, so this feature may not be available depending on your adapter of choice.

```

const previewServer = await preview({
  root: "./my-project",
});

// Stop the server if needed
await previewServer.stop();
```

### `sync()`

**Type:** `(inlineConfig: [AstroInlineConfig](#astroinlineconfig)) => Promise<void>`

Similar to [`astro sync`](/en/reference/cli-reference/#astro-sync), it generates TypeScript types for all Astro modules.

```

await sync({
  root: "./my-project",
});
```

## Utilities

The following utilities can be [imported from `astro/config`](/en/reference/modules/astro-config/#imports-from-astroconfig) and used to manipulate or validate the configuration before passing it to CLI commands.

### `mergeConfig()`

**Type:** `(defaults: [AstroConfig](/en/reference/configuration-reference/), overrides: DeepPartial<AstroConfig>) => AstroConfig`  

Takes an Astro configuration object and a partial object containing any set of valid Astro configuration options, and returns a valid Astro configuration combining the two values such that:

-   Arrays are concatenated (including integrations).
-   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.

```

mergeConfig(
  {
    output: "static",
    site: "https://example.com",
    integrations: [partytown()],
    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: [partytown(), 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<[AstroConfig](/en/reference/configuration-reference/)>`  

Validates an object as if it were exported from `astro.config.mjs` and imported by Astro. This takes the following arguments:

-   The configuration to be validated.
-   The [root directory of the project](/en/reference/configuration-reference/#root).
-   The [Astro command that is being executed](/en/reference/cli-reference/#astro-commands) (e.g. `build`, `dev`, `sync`)

The returned promise resolves to the validated configuration, filled with all default values appropriate for the given Astro command.

```

const config = await validateConfig({
  integrations: [partytown()],
}, "./my-project", "build");

// defaults are applied
await rm(config.outDir, { recursive: true, force: true });
```

## `astro` types

### `AstroInlineConfig`

The `AstroInlineConfig` type is used by all of the [command APIs](#commands). It extends from the user [Astro config](/en/reference/configuration-reference/) type:

```
interface AstroInlineConfig extends AstroUserConfig {
	configFile?: string | false;
	mode?: string;
	logLevel?: "debug" | "info" | "warn" | "error" | "silent";
}
```

#### `AstroInlineConfig.configFile`

**Type:** `string | false`  
**Default:** `undefined`

A custom path to the Astro config file.

If this value is undefined (default) or unset, Astro will search for an `astro.config.(js,mjs,ts,mts)` file relative to the `root` and load the config file if found.

If a relative path is set, it will resolve based on the `root` option.

Set to `false` to disable loading any config files.

The inline config passed in this object will take highest priority when merging with the loaded user config.

#### `AstroInlineConfig.mode`

**Type:** `string`  
**Default:** `"development"` when running `astro dev`, `"production"` when running `astro build`  

The mode used when developing or building your site (e.g. `"production"`, `"testing"`).

This value is passed to Vite using [the `--mode` flag](/en/reference/cli-reference/#--mode-string) when the `astro build` or `astro dev` commands are run to determine the value of `import.meta.env.MODE`. This also determines which `.env` files are loaded, and therefore the values of `astro:env`. See the [environment variables page](/en/guides/environment-variables/) for more details.

To output a development-based build, you can run `astro build` with the [`--devOutput` flag](/en/reference/cli-reference/#--devoutput).

#### `AstroInlineConfig.logLevel`

**Type:** `"debug" | "info" | "warn" | "error" | "silent"`  
**Default:** `"info"`

The logging level to filter messages logged by Astro.

-   `"debug"`: Log everything, including noisy debugging diagnostics.
-   `"info"`: Log informational messages, warnings, and errors.
-   `"warn"`: Log warnings and errors.
-   `"error"`: Log errors only.
-   `"silent"`: No logging.

### `PreviewServer`

```

	port: number;
	closed(): Promise<void>;
	stop(): Promise<void>;
}
```

#### `PreviewServer.host`

**Type:** `string`

The host where the server is listening for connections.

Adapters are allowed to leave this field unset. The value of `host` is implementation-specific.

#### `PreviewServer.port`

**Type:** `number`

The port where the server is listening for connections.

#### `PreviewServer.stop()`

**Type:** `Promise<void>`

Asks the preview server to close, stop accepting requests, and drop idle connections.

The returned `Promise` resolves when the close request has been sent. This does not mean that the server has closed yet. Use the [`closed()`](#previewserverclosed) method if you need to ensure the server has fully closed.

#### `PreviewServer.closed()`

**Type:** `Promise<void>`

Returns a `Promise` that will resolve once the server is closed and reject if an error happens on the server.

## [Astro Renderer API](https://docharvest.github.io/docs/astro/reference/renderer-reference/)

Contents

astro

Astro Renderer API

Astro

Astro Renderer API

Astro is designed to support any UI framework. This ability is powered by renderers, which are [integrations](/en/reference/integrations-reference/). See the [front-end frameworks guide](/en/guides/framework-components/) to learn how to use UI components from different frameworks in Astro.

## What is a renderer?

A renderer is a special kind of [integration](/en/reference/integrations-reference/) that tells Astro how to detect and render component syntaxes it does not handle natively, such as [UI framework components](/en/guides/framework-components/). A renderer consists of two parts:

-   a server module imported during development and production builds to render components to HTML.
-   an optional client module imported in the browser to hydrate components with [client directives](/en/reference/directives-reference/#client-directives).

## Building a renderer

When you need to add support for a new component syntax in Astro, create an integration and call `addRenderer()` in the [`astro:config:setup`](/en/reference/integrations-reference/#astroconfigsetup) hook. This allows you to define the [server entrypoint](#building-a-server-entrypoint) that Astro should use for rendering components. Optionally, you can also define the [client entrypoint](#building-a-client-entrypoint) used for hydration.

The following example shows how to register a renderer in an Astro integration:

```

      },
    },
  };
}
```

## Building a server entrypoint

You will need to create a file that runs during server-side rendering and defines how to render the component syntax. The server module must default-export an object that implements the [`SSRLoadedRendererValue`](#ssrloadedrenderervalue) interface.

The following example shows a minimal server-side renderer implementing `check()` and `renderToStaticMarkup()`:

```

async function check(Component: unknown) {
  return typeof Component === 'function' && Component.name === 'MyCustomComponent';
}

async function renderToStaticMarkup(
  Component: any,
  props: Record<string, unknown>,
  slots: Record<string, string>,
  metadata?: AstroComponentMetadata,
) {
  const rendered = Component(props);

  return {
    attrs: metadata?.hydrate ? { 'data-my-renderer': 'true' } : undefined,
    html: `<${rendered.tag}>${rendered.text}${slots.default ?? ''}</${rendered.tag}>`,
  };
}

const renderer: NamedSSRLoadedRendererValue = {
  name: 'my-renderer',
  check,
  renderToStaticMarkup,
};
```

## Building a client entrypoint

When your renderer supports [client directives](/en/reference/directives-reference/#client-directives), create a client entrypoint that defines how to hydrate components in the browser. The client module must default-export a function that receives the island element and returns an async hydrator function.

Astro dispatches a custom `astro:unmount` event on the island's root element each time an island is removed from the page. You can listen for this event in your client entrypoint to clean up any mounted application state.

The following example shows a minimal client entrypoint that hydrates components in the browser:

```

    if (client === 'only') {
      element.innerHTML = '';
    }

    const node = document.createElement(rendered.tag);
    node.textContent = rendered.text;
    element.appendChild(node);

    element.addEventListener('astro:unmount', () => node.remove(), { once: true });
  };
```

## Renderer types reference

The following types can be imported from the `astro` module:

### `AstroComponentMetadata`

**Type:** `{ displayName: string; hydrate?: 'load' | 'idle' | 'visible' | 'media' | 'only'; hydrateArgs?: any; componentUrl?: string; componentExport?: { value: string; namespace?: boolean }; astroStaticSlot: true; }`

Contains information about the component being rendered, including its hydration directive.

#### `AstroComponentMetadata.displayName`

**Type:** `string`

Defines the component name, used for error messages and debugging.

#### `AstroComponentMetadata.hydrate`

**Type:** `'load' | 'idle' | 'visible' | 'media' | 'only'`

Defines the [client directive](/en/reference/directives-reference/#client-directives) used on the component. If no value is provided, the component will not be hydrated on the client.

Renderers can use this value to conditionally include client-side hydration state. For example, a renderer can skip serializing transfer state for components that will not be hydrated:

```
async function renderToStaticMarkup(Component, props, children, metadata) {
  const willHydrate = !!metadata?.hydrate;
  // Skip serializing hydration state if the component won't be hydrated
  return render(Component, props, { includeTransferState: willHydrate });
}
```

#### `AstroComponentMetadata.hydrateArgs`

**Type:** `any`

Specifies the additional arguments passed to the hydration directive.

For example, this could be the media query string for `client:media` (i.e. `"(max-width: 768px)"`) or the renderer hint for `client:only` (i.e. `"react"`).

#### `AstroComponentMetadata.componentUrl`

**Type:** `string`

Defines the URL of the component's source file.

#### `AstroComponentMetadata.componentExport`

**Type:** `{ value: string; namespace?: boolean }`

Describes the component's export Astro will load on the client for hydrated components.

##### `AstroComponentMetadata.componentExport.namespace`

**Type:** `boolean`

Indicates whether the export is a namespace export.

##### `AstroComponentMetadata.componentExport.value`

**Type:** `string`

Defines the name of the export (e.g. `"default"` for default exports).

#### `AstroComponentMetadata.astroStaticSlot`

**Type:** `true`

Indicates that Astro supports the static slot optimization for this component. Renderers that set [`supportsAstroStaticSlot`](#ssrloadedrenderervaluesupportsastrostaticslot) to `true` can use this in combination with [`hydrate`](#astrocomponentmetadatahydrate) to determine how to render slots.

### `AstroRenderer`

**Type:** `{ name: string; clientEntrypoint?: string | URL; serverEntrypoint: string | URL; }`

Describes a [component renderer added by an integration](/en/reference/integrations-reference/#addrenderer-option).

#### `AstroRenderer.name`

**Type:** `string`

Defines the unique renderer's public name.

#### `AstroRenderer.clientEntrypoint`

**Type:** `string | URL`

Defines the import path of the renderer that runs on the client whenever your component is used.

#### `AstroRenderer.serverEntrypoint`

**Type:** `string | URL`

Defines the import path of the renderer that runs during server-side requests or static builds whenever your component is used.

### `NamedSSRLoadedRendererValue`

Extends [`SSRLoadedRendererValue`](#ssrloadedrenderervalue) with a required `name` property.

### `SSRLoadedRenderer`

**Type:** `Pick<[AstroRenderer](#astrorenderer), 'name' | 'clientEntrypoint'> & { ssr: [SSRLoadedRendererValue](#ssrloadedrenderervalue); }`

Describes a renderer available for the server to use. This is a subset of [`AstroRenderer`](#astrorenderer) with additional properties.

#### `SSRLoadedRenderer.ssr`

**Type:** [`SSRLoadedRendererValue`](#ssrloadedrenderervalue)

Defines the functions and configuration used by the server for this framework.

### `SSRLoadedRendererValue`

**Type:** `object`

Contains the functions and configuration necessary to render components on the server from a specific UI framework.

#### `SSRLoadedRendererValue.name`

**Type:** `string`

Specifies the name identifier for the renderer.

#### `SSRLoadedRendererValue.check()`

**Type:** `(Component: any, props: any, slots: Record<string, string>, metadata?: [AstroComponentMetadata](#astrocomponentmetadata)) => Promise<boolean>`

Determines whether the renderer can handle a component. This function is called for each registered renderer until one returns `true`.

#### `SSRLoadedRendererValue.renderToStaticMarkup()`

**Type:** `(Component: any, props: any, slots: Record<string, string>, metadata?: [AstroComponentMetadata](#astrocomponentmetadata)) => Promise<{ html: string; attrs?: Record<string, string>; }>`

Renders a framework component on the server and returns the resulting HTML string along with any optional attributes to be passed to the client entrypoint.

#### `SSRLoadedRendererValue.supportsAstroStaticSlot`

**Type:** `boolean`  

Indicates whether the renderer supports Astro's static slot optimization. When true, Astro prevents the removal of nested slots within islands.

#### `SSRLoadedRendererValue.renderHydrationScript()`

**Type:** `() => string`  

Returns an HTML string to inject once per page before the first hydrated component handled by this renderer. This is useful for renderers that need page-level hydration setup.

## [Routing Reference](https://docharvest.github.io/docs/astro/reference/routing-reference/)

Contents

astro

Routing Reference

Astro

Routing Reference

There is no separate routing configuration in Astro.

Every [supported page file](/en/basics/astro-pages/#supported-page-files) located within the special `src/pages/` directory creates a route. When the file name contains a [parameter](#params), a route can create multiple pages dynamically, otherwise it creates a single page.

By default, all Astro page routes and endpoints are generated and prerendered at build time. [On-demand server rendering](/en/guides/on-demand-rendering/) can be set for individual routes, or as the default.

## `prerender`

**Type:** `boolean`  
**Default:** `true` in static mode (default); `false` with `output: 'server'` configuration  

A value exported from each individual route to determine whether or not it is prerendered.

By default, all pages and endpoints are prerendered and will be statically generated at build time. You can opt out of prerendering on one or more routes, and you can have both static and on-demand rendered routes in the same project.

### Per-page override

You can override the default value to enable [on demand rendering](/en/guides/on-demand-rendering/) for an individual route by exporting `prerender` with the value `false` from that file:

```
---

}
---
<!-- Your HTML template here. -->
```

`getStaticPaths()` can also be used in static file endpoints for [dynamic routing](/en/guides/endpoints/#params-and-dynamic-routing).

:::tip When using TypeScript, use the [`GetStaticPaths`](/en/guides/typescript/#infer-getstaticpaths-types) type utility to ensure type-safe access of your `params` and `props`. :::

:::caution The `getStaticPaths()` function executes in its own isolated scope once, before any page loads. Therefore you can't reference anything from its parent scope, other than file imports. The compiler will warn you if you break this requirement. :::

### `params`

The `params` key of each object in the array returned by `getStaticPaths()` tells Astro what routes to build.

The keys in `params` must match the parameters defined in your component file path. The value for each `params` object must match the parameters used in the page name. `params` are encoded into the URL, so only strings are supported as values.

For example,`src/pages/posts/[id].astro`has an `id` parameter in its file name. The following `getStaticPaths()` function in this `.astro` component tells Astro to statically generate `posts/1`, `posts/2`, and `posts/3` at build time.

```
---

}

const { id } = Astro.params;
---
<h1>{id}</h1>
```

### Data passing with `props`

To pass additional data to each generated page, you can set a `props` value on each object in the array returned by `getStaticPaths()`. Unlike `params`, `props` are not encoded into the URL and so aren't limited to only strings.

For example, if you generate pages with data fetched from a remote API, you can pass the full data object to the page component inside of `getStaticPaths()`. The page template can reference the data from each post using `Astro.props`.

```
---

  const data = await response.json();

  return data.map((post) => {
    return {
      params: { id: post.id },
      props: { post },
    };
  });
}

const { id } = Astro.params;
const { post } = Astro.props;
---
<h1>{id}: {post.name}</h1>
```

### `routePattern`

**Type:** `string`  

A property available in [`getStaticPaths()`](#getstaticpaths) options to access the current [`routePattern`](/en/reference/api-reference/#routepattern) as a string.

This provides data from the [Astro render context](/en/reference/api-reference/) that would not otherwise be available within the scope of `getStaticPaths()` and can be useful to calculate the `params` and `props` for each page route.

`routePattern` always reflects the original dynamic segment definition in the file path (e.g. `/[...locale]/[files]/[slug]`), unlike `params`, which are explicit values for a page (e.g. `/fr/fichiers/article-1/`).

The following example shows how to localize your route segments and return an array of static paths by passing `routePattern` to a custom `getLocalizedData()` helper function. The [params](/en/reference/routing-reference/#params) object will be set with explicit values for each route segment: `locale`, `files`, and `slug`. Then, these values will be used to generate the routes and can be used in your page template via `Astro.params`.

```
---

  const data = await response.json();

  console.log(routePattern); // [...locale]/[files]/[slug]

  // Call your custom helper with `routePattern` to generate the static paths
  return data.flatMap((file) => getLocalizedData(file, routePattern));
}

const { locale, files, slug } = Astro.params;
---
```

### `paginate()`

A function that can be returned from [`getStaticPaths()`](#getstaticpaths) to divide a collection of content items into separate pages.

`paginate()` will automatically generate the necessary array to return from `getStaticPaths()` to create one URL for every page of your paginated collection. The page number will be passed as a `param`, and the page data will be passed as a `page` prop.

The following example fetches and passes 150 items to the `paginate` function, and creates static, prerendered pages at build time that will display 10 items per page:

```
---

  const result = await response.json();
  const allPokemon = result.results;

  // Return a paginated collection of paths for all items
  return paginate(allPokemon, { pageSize: 10 });
}

const { page } = Astro.props;
---
```

`paginate()` has the following arguments:

-   `data` - array containing the page’s data passed to the `paginate()` function
-   `options` - Optional object with the following properties:
    -   `pageSize` - The number of items shown per page (`10` by default)
    -   `params` - Send additional parameters for creating dynamic routes
    -   `props` - Send additional props to be available on each page

`paginate()` assumes a file name of `[page].astro` or `[...page].astro`. The `page` param becomes the page number in your URL:

-   `/posts/[page].astro` would generate the URLs `/posts/1`, `/posts/2`, `/posts/3`, etc.
-   `/posts/[...page].astro` would generate the URLs `/posts`, `/posts/2`, `/posts/3`, etc.

#### The pagination `page` prop

**Type:** `Page<TData>`

Pagination will pass a `page` prop to every rendered page that represents a single page of data in the paginated collection. This includes the data that you've paginated (`page.data`) as well as metadata for the page (`page.url`, `page.start`, `page.end`, `page.total`, etc). This metadata is useful for things like a "Next Page" button or a "Showing 1-10 of 100" message.

##### `page.data`

**Type:** `Array<TData>`

Array of data returned from the `paginate()` function for the current page.

##### `page.start`

**Type:** `number`

Index of the first item on the current page, starting at `0`. (e.g. if `pageSize: 25`, this would be `0` on page 1, `25` on page 2, etc.)

##### `page.end`

**Type:** `number`

Index of the last item on the current page.

##### `page.size`

**Type:** `number`  
**Default:** `10`

The total number of items per page.

##### `page.total`

**Type:** `number`

The total number of items across all pages.

##### `page.currentPage`

**Type:** `number`

The current page number, starting with `1`.

##### `page.lastPage`

**Type:** `number`

The total number of pages.

##### `page.url.current`

**Type:** `string`

Get the URL of the current page (useful for canonical URLs). If a value is set for [`base`](/en/reference/configuration-reference/#base), the URL starts with that value.

##### `page.url.prev`

**Type:** `string | undefined`

Get the URL of the previous page (will be `undefined` if on page 1). If a value is set for [`base`](/en/reference/configuration-reference/#base), prepend the base path to the URL.

##### `page.url.next`

**Type:** `string | undefined`

Get the URL of the next page (will be `undefined` if no more pages). If a value is set for [`base`](/en/reference/configuration-reference/#base), prepend the base path to the URL.

##### `page.url.first`

**Type:** `string | undefined`  

Get the URL of the first page (will be `undefined` if on page 1). If a value is set for [`base`](/en/reference/configuration-reference/#base), prepend the base path to the URL.

##### `page.url.last`

**Type:** `string | undefined`  

Get the URL of the last page (will be `undefined` if no more pages). If a value is set for [`base`](/en/reference/configuration-reference/#base), prepend the base path to the URL.

## [Astro Session Driver API](https://docharvest.github.io/docs/astro/reference/session-driver-reference/)

Contents

astro

Astro Session Driver API

Astro

Astro Session Driver API

Astro [sessions](/en/guides/sessions/) allow you to share data between requests for on-demand rendered pages. They require an Astro Session Driver to store session data.

## Built-in drivers

Astro exports built-in session drivers from `astro/config`:

```

}

export function memoryDriver(config: Config = {}): SessionDriverConfig {
    return {
        entrypoint: new URL('./runtime.js', import.meta.url),
        config,
    }
}
```

It is then registered in the Astro config:

```

export default function(config): SessionDriver {
    return redisDriver({
        ...config,
        tls: true
    })
}
```

## [Build your first Astro Blog](https://docharvest.github.io/docs/astro/tutorial/0-introduction/)

Contents

astro

Build your first Astro Blog

Astro

Build your first Astro Blog

In this tutorial, you'll learn Astro's key features by building a fully-functioning blog, from zero to full launch! 🚀

Along the way, you'll:

-   Set up your development environment
-   Create pages and blog posts for your website
-   Build with Astro components
-   Query and work with local files
-   Add interactivity to your site
-   Deploy your site to the web

Want a preview of what you're going to build? You can view the final project on [GitHub](https://github.com/withastro/blog-tutorial-demo) or open a working version in an online coding environment such as [StackBlitz](https://stackblitz.com/github/withastro/blog-tutorial-demo/tree/complete?file=src%2Fpages%2Findex.astro).

:::note If you would rather start exploring Astro with a pre-built Astro site, you can visit [https://astro.new](https://astro.new) and choose a starter template to open and edit in an online editor. :::

\## Checklist \- \[ \] Looks great! I'm ready to get started!

## [About this Tutorial](https://docharvest.github.io/docs/astro/tutorial/0-introduction/1/)

Contents

astro

About this Tutorial

Astro

About this Tutorial

## What do I need to know to get started?

If you have some basic familiarity with **HTML**, **Markdown**, **CSS**, and a little **JavaScript**, then you're totally good to go! You'll be able to complete the entire tutorial just by following the instructions. Astro is for everyone! 🧑‍🚀 👩‍🚀 👨‍🚀

You will also need a [GitHub](https://github.com) (or similar) account for publishing your project to the web.

How do I use the checklists at the bottom of each page?

You check them off!

At the end of each page, you'll find a clickable checklist of tasks you should now be able to do. Check these items off to see your progress in the Tutorial Tracker.

Using the tracker is optional, but it can help you remember your place if you complete the tutorial over multiple visits. You can also leave some checklists blank as a reminder of units that you want to revisit later.

(This data is only saved to your browser's local storage and is not available elsewhere. No data is sent to, nor stored by Astro.)

Unit 1 is things I already know how to do. Can I skip it?

You can use the lessons inside [Unit 1](/en/tutorial/1-setup/) to make sure you have the development tools and online accounts you'll need to complete the tutorial. It will walk you through creating a new Astro project, storing it on GitHub, and deploying it to Netlify.

If you [create a new, empty Astro project](/en/install-and-setup/) and are comfortable with your setup, you can safely skip ahead to [Unit 2](/en/tutorial/2-pages/) where you will start making new pages in your project.

What if I need help, or want to learn more about Astro?

Our [friendly Astro Discord server](https://astro.build/chat) is the place to be!

Hop into the support forum channel to ask questions, or say hi and chat in `#general` or `#off-topic`.

Where can I leave feedback about this tutorial?

This tutorial is a project of our Docs team. You can find us on Discord in the `#docs` channel, or file issues to the [Docs repo on GitHub](https://github.com/withastro/docs/issues).

## Checklist for moving on

\- \[ \] I'm ready to build this thing!

## [Check in: Unit 1 - Setup](https://docharvest.github.io/docs/astro/tutorial/1-setup/)



## [Prepare your dev environment](https://docharvest.github.io/docs/astro/tutorial/1-setup/1/)



## [Create your first Astro project](https://docharvest.github.io/docs/astro/tutorial/1-setup/2/)



## [Write your first line of Astro](https://docharvest.github.io/docs/astro/tutorial/1-setup/3/)



## [Store your repository online](https://docharvest.github.io/docs/astro/tutorial/1-setup/4/)



## [Deploy your site to the web](https://docharvest.github.io/docs/astro/tutorial/1-setup/5/)



## [Check in: Unit 2 - Pages](https://docharvest.github.io/docs/astro/tutorial/2-pages/)

Contents

astro

Check in: Unit 2 - Pages

Astro

Check in: Unit 2 - Pages

Now that you have a working site on the web, it's time to add pages and posts!

## Looking ahead

In this unit, you will:

-   Create your first Astro pages with the `.astro` syntax
-   Add blog posts with Markdown (`.md`) files
-   Style an individual page with `<style>`
-   Apply global styles across pages

Along the way, you'll learn how the **two sections of a `.astro` file** work together to create a page, and how to use variables and conditional rendering on your pages.

\## Checklist \- \[ \] I am ready to make some new pages for my Astro website!

## [Create your first Astro page](https://docharvest.github.io/docs/astro/tutorial/2-pages/1/)



## [Write your first Markdown blog post](https://docharvest.github.io/docs/astro/tutorial/2-pages/2/)



## [Add dynamic content about you](https://docharvest.github.io/docs/astro/tutorial/2-pages/3/)



## [Style your About page](https://docharvest.github.io/docs/astro/tutorial/2-pages/4/)



## [Add site-wide styling](https://docharvest.github.io/docs/astro/tutorial/2-pages/5/)



## [Check in: Unit 3 - Components](https://docharvest.github.io/docs/astro/tutorial/3-components/)

Contents

astro

Check in: Unit 3 - Components

Astro

Check in: Unit 3 - Components

Now that you have `.astro` and `.md` files generating entire pages on your website, it's time to make and reuse smaller bits of HTML with Astro components!

## Looking ahead

In this unit, you'll learn how to create **Astro components** to reuse code for common elements across your website.

You'll build:

-   A Navigation component that presents a menu of links to your pages
-   A Footer component to include at the bottom of each page
-   A Social Media component, used in the Footer, that links to profile pages
-   An interactive Menu component to toggle the Navigation on mobile

Along the way, you'll use CSS and JavaScript to build a responsive design that reacts to screen sizes and user input.

\## Checklist \- \[ \] I am ready to build some Astro components!

## [Make a reusable Navigation component](https://docharvest.github.io/docs/astro/tutorial/3-components/1/)



## [Create a social media footer](https://docharvest.github.io/docs/astro/tutorial/3-components/2/)



## [Build it yourself - Header](https://docharvest.github.io/docs/astro/tutorial/3-components/3/)



## [Send your first script to the browser](https://docharvest.github.io/docs/astro/tutorial/3-components/4/)



## [Check in: Unit 4 - Layouts](https://docharvest.github.io/docs/astro/tutorial/4-layouts/)

Contents

astro

Check in: Unit 4 - Layouts

Astro

Check in: Unit 4 - Layouts

Now that you can build with components, it's time to create some custom layouts!

## Looking ahead

In this unit, you'll build layouts to share common elements and styles across your pages and blog posts.

To do this, you will:

-   Create reusable layout components
-   Pass content to your layouts with `<slot />`
-   Pass data from Markdown frontmatter to your layouts
-   Nest multiple layouts

## Checklist

\- \[ \] I am ready to take my page design to the next level with layouts!

## [Build your first layout](https://docharvest.github.io/docs/astro/tutorial/4-layouts/1/)



## [Create and pass data to a custom blog layout](https://docharvest.github.io/docs/astro/tutorial/4-layouts/2/)

Contents

astro

Create and pass data to a custom blog layout

Astro

Create and pass data to a custom blog layout

````
---
<meta charset="utf-8" />
<h1>{frontmatter.title}</h1>
<p>Written by {frontmatter.author}</p>
<slot />
```
````

3.  Add the following frontmatter property in `post-1.md`
    
    ```
    ---
    layout: ../../layouts/MarkdownPostLayout.astro
    title: 'My First Blog Post'
    pubDate: 2022-07-01
    description: 'This is the first post of my new Astro blog.'
    author: 'Astro Learner'
    image:
        url: 'https://docs.astro.build/assets/rose.webp' 
        alt: 'The Astro logo on a dark background with a pink glow.'
    tags: ["astro", "blogging", "learning in public"]
    ---
    ```
    
4.  Check your browser preview again at `http://localhost:4321/posts/post-1` and notice what the layout has added to your page.
    
5.  Add the same layout property to your two other blog posts `post-2.md` and `post-3.md`. Verify in your browser that your layout is also applied to these posts.
    

:::tip When using layouts, you now have the option of including elements, like a page title, in the Markdown content or in the layout. Remember to visually inspect your page preview and make any adjustments necessary to avoid duplicated elements. :::

## Try it yourself - Customize your blog post layout

**Challenge**: Identify items common to every blog post, and use `MarkdownPostLayout.astro` to render them, instead of writing them in your Markdown in `post-1.md` and in every future blog post.

Here's an example of refactoring your code to include the `pubDate` in the layout component instead of writing it in the body of your Markdown:

```
Published on: 2022-07-01

Welcome to my _new blog_ about learning Astro! Here, I will share my learning journey as I build a new website.
```

```
---
const { frontmatter } = Astro.props;
---
<meta charset="utf-8" />
<h1>{frontmatter.title}</h1>
<p>Published on: {frontmatter.pubDate.toString().slice(0,10)}</p>
<p>Written by {frontmatter.author}</p>
<slot />
```

Refactor as much as you think is useful to you, and add as much to your layout as you want, remembering that everything that you add to your layout is one less thing you will write in each and every blog post!

Here is an example of a refactored layout that leaves only individual blog post content rendered by the slot. Feel free to use this, or create your own!

```
---
const { frontmatter } = Astro.props;
---
<meta charset="utf-8" />
<h1>{frontmatter.title}</h1>
<p>{frontmatter.pubDate.toString().slice(0,10)}</p>
<p><em>{frontmatter.description}</em></p>
<p>Written by: {frontmatter.author}</p>
<img src={frontmatter.image.url} width="300" alt={frontmatter.image.alt} />
<slot />
```

:::note\[Avoid duplication\] Anything rendered by your layout does **not** need to be typed into your blog post! If you notice any duplication when you check your browser preview, then be sure to remove content from your Markdown file. :::

### Test your knowledge

Can you figure out what should go in the blanks so that the following two components together produce working Astro code?

1.  ```
    ---
    layout: ../../__________/MyMarkdownLayout.astro
    title: "Learning About Markdown in Astro"
    author: Astro Learner
    ____: 2022-08-08
    ---
    I learned so much today! Astro allows me to write in Markdown, but also use variables from the frontmatter. I can even access those values in an Astro layout component.
    ```
    
2.  ```
    ---
    import ____________ from '../components/Footer.astro'
    const { ___________ } = Astro.props
    ---
    <h1>{frontmatter.title}</h1>
    <p>Written by: {frontmatter.______} on {frontmatter.pubDate}</p>
    < _______ />
    <Footer />
    ```
    
    Show the blanks filled in!
    
    ```
    1.  ```markdown title="src/pages/posts/learning-astro.md" "layouts" "pubDate"
        ---
        layout: ../../layouts/MyMarkdownLayout.astro
        title: "Learning About Markdown in Astro"
        author: Astro Learner
        pubDate: 2022-08-08
        ---
        I learned so much today! Astro allows me to write in Markdown, but also use variables from the frontmatter. I can even access those values in an Astro layout component.
        ```
    
    2.  ```astro title="src/layouts/MyMarkdownLayout.astro" " Footer " " frontmatter " "author" "slot"
        ---
        import Footer from '../components/Footer.astro'
        const { frontmatter } = Astro.props
        ---
        <h1>{frontmatter.title}</h1>
        <p>Written by: {frontmatter.author} on {frontmatter.pubDate}</p>
        <slot />
        <Footer />
        ```
    ```
    

## Checklist

\- \[ \] I can add a layout property to a Markdown blog post in its YAML frontmatter. - \[ \] I can create a separate layout for Markdown posts. - \[ \] I can use values from a blog post's frontmatter in a layout component.

### Resources

-   [Markdown Layouts in Astro](/en/guides/markdown-content/#frontmatter-layout-property)
    
-   [Markdown Layout Props](/en/basics/layouts/#markdown-layout-props)
    
-   [Introduction to YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f)

## [Combine layouts to get the best of both worlds](https://docharvest.github.io/docs/astro/tutorial/4-layouts/3/)



## [Check in: Unit 5 - Astro API](https://docharvest.github.io/docs/astro/tutorial/5-astro-api/)

Contents

astro

Check in: Unit 5 - Astro API

Astro

Check in: Unit 5 - Astro API

Now that you have some blog posts, it's time to use Astro's API to work with your files!

## Looking ahead

In this unit, you'll supercharge your blog with an index page, tag pages, and an RSS feed.

Along the way, you'll learn how to use:

-   `import.meta.glob()` to access data from files in your project
-   `getStaticPaths()` to create multiple pages (routes) at once
-   The Astro RSS package to create an RSS feed

## Checklist

\- \[ \] I am ready to add some blog features to my Astro project!

## [Create a blog post archive](https://docharvest.github.io/docs/astro/tutorial/5-astro-api/1/)



## [Generate tag pages](https://docharvest.github.io/docs/astro/tutorial/5-astro-api/2/)



## [Build a tag index page](https://docharvest.github.io/docs/astro/tutorial/5-astro-api/3/)



## [Add an RSS feed](https://docharvest.github.io/docs/astro/tutorial/5-astro-api/4/)



## [Check in: Unit 6 - Astro Islands](https://docharvest.github.io/docs/astro/tutorial/6-islands/)

Contents

astro

Check in: Unit 6 - Astro Islands

Astro

Check in: Unit 6 - Astro Islands

Now that you have a fully functioning blog, it's time to add some interactive islands to your site!

## Looking ahead

In this unit, you'll use **Astro islands** to bring frontend framework components into your Astro site.

You will:

-   Add a UI framework, Preact, to your Astro project
-   Use Preact to create an interactive greeting component
-   Learn when you might _not_ choose islands for interactivity

## Checklist

\- \[ \] I am ready to add some interactivity to my site, and start living that island life!

## [Build your first Astro island](https://docharvest.github.io/docs/astro/tutorial/6-islands/1/)



## [Back on dry land. Take your blog from day to night, no island required!](https://docharvest.github.io/docs/astro/tutorial/6-islands/2/)



## [Congratulations!](https://docharvest.github.io/docs/astro/tutorial/6-islands/3/)

Contents

astro

Congratulations!

Astro

Congratulations!

There's one more edit to make...

```
---

const pageTitle = "About Me";

const identity = {
  firstName: "Sarah",
  country: "Canada",
  occupation: "Technical Writer",
  hobbies: ["photography", "birdwatching", "baseball"],
};

const skills = ["HTML", "CSS", "JavaScript", "React", "Astro", "Writing Docs"];

const happy = true;
const finished = false;
const finished = true;
const goal = 3;

const skillColor = "crimson";
const fontWeight = "bold";
const textCase = "uppercase";
---
```

We hope you learned a little about the basics of Astro, and had fun along the way!

You can find the code for the project in this tutorial on [GitHub](https://github.com/withastro/blog-tutorial-demo/tree/complete) or open a working version in an online code environment like [StackBlitz](https://stackblitz.com/github/withastro/blog-tutorial-demo/tree/complete?file=src/pages/index.astro).

Check out our docs for guides and reference material, and visit our Discord to ask questions, get help or just hang out!

Welcome to the universe, astronaut. 👩🏼‍🚀👨🏿‍🚀🧑‍🚀👩🏾‍🚀

## Checklist

\- \[ \] I can't wait to start my next Astro project! 🚀

## Share your achievement!

Congratulations on completing the Astro blog tutorial! Share your achievement with the world and let everyone know you're an Astronaut now!

Share on Twitter Share on Reddit Share on Bluesky

## Next Steps

You can enhance this project's final code with one of our tutorial extensions, or start your next Astro project!

## [Optional: Make a content collection](https://docharvest.github.io/docs/astro/tutorial/6-islands/4/)



## [Upgrade Astro](https://docharvest.github.io/docs/astro/upgrade-astro/)

Contents

astro

Upgrade Astro

Astro

Upgrade Astro

This guide covers how to update your version of Astro and related dependencies, how to learn what has changed from one version to the next, and how to understand Astro's versioning system and corresponding documentation updates.

## What has changed?

The latest release of Astro is .

You can find an exhaustive list of all changes in [Astro's changelog](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md), and important instructions for upgrading to each new [major version](#major-changes) in our [upgrade guides](#upgrade-guides).

## Upgrade to the latest version

Update your project's version of Astro and all official integrations to the latest versions with one command using your package manager:

\`\`\`shell # Upgrade Astro and official integrations together npx @astrojs/upgrade \`\`\` \`\`\`shell # Upgrade Astro and official integrations together pnpm dlx @astrojs/upgrade \`\`\` \`\`\`shell # Upgrade Astro and official integrations together yarn dlx @astrojs/upgrade \`\`\`

### Manual Upgrading

To update Astro and integrations to their current versions manually, use the appropriate command for your package manager.

\`\`\`shell # Example: upgrade Astro with React and Partytown integrations npm install astro@latest @astrojs/react@latest @astrojs/partytown@latest \`\`\` \`\`\`shell # Example: upgrade Astro with React and Partytown integrations pnpm add astro@latest @astrojs/react@latest @astrojs/partytown@latest \`\`\` \`\`\`shell # Example: upgrade Astro with React and Partytown integrations yarn add astro@latest @astrojs/react@latest @astrojs/partytown@latest \`\`\`

### Install a specific version number

To install a specific [version of Astro](https://www.npmjs.com/package/astro?activeTab=versions) or integrations, use the appropriate command for your package manager.

\`\`\`shell npm install astro@4.5.3 @astrojs/react@3.0.10 \`\`\` \`\`\`shell pnpm add astro@4.5.3 @astrojs/react@3.0.10 \`\`\` \`\`\`shell yarn add astro@4.5.3 @astrojs/react@3.0.10 \`\`\`

## Documentation updates

This documentation is updated for each [minor release](#minor-changes) and [major version release](#major-changes). When new features are added, or existing usage changes, the docs will update to reflect the **current behavior of Astro**. If your project is not updated, then you may notice some behaviors do not match the up-to-date documentation.

New features are added to docs with the specific version number in which they were added. This means that if you have not updated to the latest release of Astro, some documented features may be unavailable. Always check the `Added in:` version number and make sure your project is updated before attempting to use new features!

If you have not upgraded to the latest major version of Astro, you may encounter significant differences between the Astro documentation and your project's behavior. We strongly recommend upgrading to the current major version of Astro as soon as you are able. Both the code and the documentation for earlier versions is unsupported.

### Upgrade Guides

After every [major version release](#major-changes), you will find an **upgrade guide** with information about important changes and instructions for upgrading your project code.

The main Astro documentation pages are always **accurate for the latest released version of Astro**. They do not describe or compare to how things worked in previous versions, nor do they highlight updated or changed behavior.

See the upgrade guides below for an explanation of changes, comparing the new version to the old. The upgrade guides include everything that could require you to change your own code: breaking changes, deprecations, feature removals and replacements as well as updated usage guidance. Each change to Astro includes a "What should I do?" section to help you successfully update your project code.

-   [Upgrade to v7](/en/guides/upgrade-to/v7/)
-   [Upgrade to v6](/en/guides/upgrade-to/v6/)
-   [Upgrade to v5](/en/guides/upgrade-to/v5/)
-   [Upgrade to v4](/en/guides/upgrade-to/v4/)
-   [Upgrade to v3](/en/guides/upgrade-to/v3/)
-   [Upgrade to v2](/en/guides/upgrade-to/v2/)
-   [Upgrade to v1](/en/guides/upgrade-to/v1/)

### Older docs (unmaintained)

Documentation for older versions of Astro is not maintained, but is available as a static snapshot. Use these versions of docs if you are unable to upgrade your project, but still wish to consult guides and reference:

-   [unmaintained v6.4.8 snapshot](https://v6.docs.astro.build/en/getting-started/)
-   [unmaintained v5.18.0 snapshot](https://v5.docs.astro.build/en/getting-started/)
-   [unmaintained v4.16.17 snapshot](https://v4.docs.astro.build/en/getting-started/)
-   [unmaintained v3.6.3 snapshot](https://web.archive.org/web/20231203051122/https://docs.astro.build/en/getting-started/)
-   [unmaintained v2.10.15 snapshot](https://web.archive.org/web/20230822134745/https://docs.astro.build/en/getting-started)

## Semantic versioning

Astro attempts to adhere as much as possible to [semantic versioning](https://semver.org/), which is a set of rules developers use to determine how to assign a version number to a release. Semantic version follows a predictable pattern to inform users of the kind of changes they can expect from one version to the next.

Semantic versioning enforces a pattern of `X.Y.Z` for software version numbers. These values represent **major (X)**, **minor (Y)**, and **patch (Z)** updates.

### Patch changes

Patch changes are the least disruptive changes. They do not change the way you use Astro, and no change to your own code is required when you update.

When Astro issues a "patch" version, the last number increases. (e.g. `astro@4.3.14` -> `astro@4.3.15`)

Patches may be released for reasons such as:

-   Internal changes that do not change Astro’s functionality:
    -   refactors
    -   performance improvements
    -   increase or change in test coverage
    -   aligning with stated documentation and expected behavior
-   Improvements to logging and error messages.
-   Re-releases after a failed release.

Patch changes also include **most bug fixes**, even in cases where users were taking advantage of existing unintended or undesirable behavior.

### Minor changes

Minor releases primarily introduce new features and improvements that you may wish to try, but require no changes to your code. Some existing features may also be **deprecated** (marked for deletion in a future version while continuing to function) in a minor release, giving you the opportunity to prepare for their eventual removal.

Minor releases include changes such as:

-   **Deprecations** of existing features/options with a warning that they will be removed in an upcoming major release.
-   Introduction of new functionalities.
-   Introduction of new options in the integration hooks.
-   Introduction of new functionalities in `astro/app`, notably used for creating new adapters.

A minor release may also include smaller, patch changes at the same time.

### Major changes

Major releases will include breaking changes to at least some existing code. These breaking changes are always documented in an ["Upgrade to vX" guide](#upgrade-guides) in Astro.

Major releases allow Astro to make significant changes not only to internal logic, but also to intended behavior and usage. Documentation will be updated to reflect the latest version only, and **static, unmaintained snapshots of older docs** are available as a historical record for older projects that are not yet upgraded.

Major releases include changes such as:

-   Removal of previously deprecated functionalities.
-   Changes of existing functionalities.
-   Changes of existing options in the integration hooks.
-   Changes of existing options and functionalities in `astro/app`, notably used for creating new adapters.

A major release may also include some non-breaking changes and improvements that would normally be released separately in a minor or patch release.

### Exceptions

-   **Experimental features**. Releasing versions of Astro without adhering to semantic versioning allows Astro developers the greatest flexibility to explore, and even radically change course, during the development of experimental features. Therefore, the behavior of these features can break in minor and patch changes.
    
    These features are usually accompanied by an ongoing, public [Request for Consideration (RFC) stage 3](https://github.com/withastro/roadmap#stage-3-rfc--development). It is expected that beta users will follow for updates, and leave early feedback on the discussion to help guide development of these features.
    
    Once these features are out of their experimental period, they will follow the normal semantic versioning contract.
    
-   **Improvements to the documentation** (e.g. reference and error messages). They are built from source for the `docs` repository. This allows Astro to quickly update docs fixes and improvements in the cases where documentation source content is stored in the main `astro` repository.
    

### Node.js support and upgrade policies

#### Support

-   Astro supports the [**latest _Maintenance_ LTS** version of Node.js](https://nodejs.org/en/about/previous-releases#release-schedule).
-   Astro supports the [**current _Active_ LTS** version of Node.js](https://nodejs.org/en/about/previous-releases#release-schedule)
-   Astro can support odd versions of Node.js.

#### Upgrade

The following rules define when Astro may deprecate, drop, or add support for versions of Node.js:

-   Odd versions of Node.js can be deprecated and/or dropped when the next even version of Node.js published. This change can occur in a **minor** release of Astro, after a reasonable period of extended support as decided by the Astro Core team.
-   Upgrading the minimum **_Maintenance_ LTS** (within the same major range, e.g. from `22.14.*` to `22.20.*`) version of Node.js can occur in a **minor** release of Astro.
    -   Security exception: If a security flaw in Node.js that **affects Astro** is disclosed and fixed, the Core team can bump the minimum version of the **_Maintenance_ LTS** in a **patch** release.
-   Upgrading minor or major versions of Node.js (**not** Maintenance LTS) occurs only in major versions of Astro.
    -   Security exception: If a security flaw in Node.js that **affects Astro** is disclosed and fixed, the Core team can bump the minimum version in a **minor** release.

### Extended maintenance

The Core team will provide extended maintenance **for security fixes only** for one previous major version. This means that if the current major is `v4.*`, the Core team will back port security fixes and issue a new `v3.*` release.