``` Navigate to and click on one of your posts to make sure your dynamic route is working! #### Server side rendering [Section titled Server side rendering](#server-side-rendering) If you’ve [opted in to SSR mode](/en/guides/on-demand-rendering/), you will use a dynamic route that uses a `slug` parameter to fetch the data from Contentful. Create a `[slug].astro` page in `src/pages/posts`. Use [`Astro.params`](/en/reference/api-reference/#params) to get the slug from the URL, then pass that to `getEntries`: src/pages/posts/\[slug].astro ```astro --- import { contentfulClient } from "../../lib/contentful"; import type { BlogPost } from "../../lib/contentful"; const { slug } = Astro.params; const data = await contentfulClient.getEntries({ content_type: "blogPost", "fields.slug": slug, }); --- ``` If the entry is not found, you can redirect the user to the 404 page using [`Astro.redirect`](/en/guides/routing/#dynamic-redirects). src/pages/posts/\[slug].astro ```astro --- import { contentfulClient } from "../../lib/contentful"; import type { BlogPost } from "../../lib/contentful"; const { slug } = Astro.params; try { const data = await contentfulClient.getEntries({ content_type: "blogPost", "fields.slug": slug, }); } catch (error) { return Astro.redirect("/404"); } --- ``` To pass post data to the template section, create a `post` object outside the `try/catch` block. Use `documentToHtmlString` to convert `content` from a Document to HTML, and use the Date constructor to format the date. `title` can be left as-is. Then, add these properties to your `post` object. src/pages/posts/\[slug].astro ```astro --- import Layout from "../../layouts/Layout.astro"; import { contentfulClient } from "../../lib/contentful"; import { documentToHtmlString } from "@contentful/rich-text-html-renderer"; import type { BlogPost } from "../../lib/contentful"; let post; const { slug } = Astro.params; try { const data = await contentfulClient.getEntries({ content_type: "blogPost", "fields.slug": slug, }); const { title, date, content } = data.items[0].fields; post = { title, date: new Date(date).toLocaleDateString(), content: documentToHtmlString(content), }; } catch (error) { return Astro.redirect("/404"); } --- ``` Finally, you can reference `post` to display your blog post in the template section. src/pages/posts/\[slug].astro ```astro --- import Layout from "../../layouts/Layout.astro"; import { contentfulClient } from "../../lib/contentful"; import { documentToHtmlString } from "@contentful/rich-text-html-renderer"; import type { BlogPost } from "../../lib/contentful"; let post; const { slug } = Astro.params; try { const data = await contentfulClient.getEntries({ content_type: "blogPost", "fields.slug": slug, }); const { title, date, content } = data.items[0].fields; post = { title, date: new Date(date).toLocaleDateString(), content: documentToHtmlString(content), }; } catch (error) { return Astro.redirect("/404"); } --- {post?.title}

{post?.title}

{post?.date}

``` ### Publishing your site [Section titled Publishing your site](#publishing-your-site) To deploy your website, visit our [deployment guides](/en/guides/deploy/) and follow the instructions for your preferred hosting provider. #### Rebuild on Contentful changes [Section titled Rebuild on Contentful changes](#rebuild-on-contentful-changes) If your project is using Astro’s default static mode, you will need to set up a webhook to trigger a new build when your content changes. If you are using Netlify or Vercel as your hosting provider, you can use its webhook feature to trigger a new build from Contentful events. ##### Netlify [Section titled Netlify](#netlify) To set up a webhook in Netlify: 1. Go to your site dashboard and click on **Build & deploy**. 2. Under the **Continuous Deployment** tab, find the **Build hooks** section and click on **Add build hook**. 3. Provide a name for your webhook and select the branch you want to trigger the build on. Click on **Save** and copy the generated URL. ##### Vercel [Section titled Vercel](#vercel) To set up a webhook in Vercel: 1. Go to your project dashboard and click on **Settings**. 2. Under the **Git** tab, find the **Deploy Hooks** section. 3. Provide a name for your webhook and the branch you want to trigger the build on. Click **Add** and copy the generated URL. ##### Adding a webhook to Contentful [Section titled Adding a webhook to Contentful](#adding-a-webhook-to-contentful) In your Contentful space **settings**, click on the **Webhooks** tab and create a new webhook by clicking the **Add Webhook** button. Provide a name for your webhook and paste the webhook URL you copied in the previous section. Finally, hit **Save** to create the webhook. Now, whenever you publish a new blog post in Contentful, a new build will be triggered and your blog will be updated. # Cosmic & Astro > Add content to your Astro project using Cosmic as a CMS [Cosmic](https://www.cosmicjs.com/) is a [headless CMS](https://www.cosmicjs.com/headless-cms) that provides an admin dashboard to manage content and an API that can integrate with a diverse range of frontend tools. ## Prerequisites [Section titled Prerequisites](#prerequisites) 1. **An Astro project**- If you’d like to start with a fresh Astro project, read the [installation guide](/en/install-and-setup/). This guide follows a simplified version of the [Astro Headless CMS Theme](https://astro.build/themes/details/cosmic-cms-blog/) with [Tailwind CSS](https://tailwindcss.com/) for styling. 2. **A Cosmic account and Bucket** - [Create a free Cosmic account](https://app.cosmicjs.com/signup) if you don’t have one. After creating your account, you’ll be prompted to create a new empty project. There’s also a [Simple Astro Blog template](https://www.cosmicjs.com/marketplace/templates/simple-astro-blog) available (this is the same template as the Astro Headless CMS Theme) to automatically import all of the content used in this guide. 3. **Your Cosmic API keys** - From your Cosmic dashboard, you will need to locate both the **Bucket slug** and **Bucket read key** in order to connect to Cosmic. ## Integrating Cosmic with Astro [Section titled Integrating Cosmic with Astro](#integrating-cosmic-with-astro) ### Installing Necessary Dependencies [Section titled Installing Necessary Dependencies](#installing-necessary-dependencies) Add the [Cosmic JavaScript SDK](https://www.npmjs.com/package/@cosmicjs/sdk) to fetch data from your Cosmic Bucket. * npm ```shell npm install @cosmicjs/sdk ``` * pnpm ```shell pnpm add @cosmicjs/sdk ``` * Yarn ```shell yarn add @cosmicjs/sdk ``` ### Configuring API Keys [Section titled Configuring API Keys](#configuring-api-keys) Create a `.env` file at the root of your Astro project (if it does not already exist). Add both the **Bucket slug** and **Bucket read key** available from your Cosmic dashboard as public environment variables. .env ```ini PUBLIC_COSMIC_BUCKET_SLUG=YOUR_BUCKET_SLUG PUBLIC_COSMIC_READ_KEY=YOUR_READ_KEY ``` ## Fetching Data from Cosmic [Section titled Fetching Data from Cosmic](#fetching-data-from-cosmic) 1. Create a new file called `cosmic.js`. Place this file inside of the `src/lib` folder in your project. 2. Add the following code to fetch data from Cosmic using the SDK and your environment variables. The example below creates a function called `getAllPosts()` to fetch metadata from Cosmic `posts` objects: src/lib/cosmic.js ```js import { createBucketClient } from '@cosmicjs/sdk' const cosmic = createBucketClient({ bucketSlug: import.meta.env.PUBLIC_COSMIC_BUCKET_SLUG, readKey: import.meta.env.PUBLIC_COSMIC_READ_KEY }) export async function getAllPosts() { const data = await cosmic.objects .find({ type: 'posts' }) .props('title,slug,metadata,created_at') return data.objects } ``` Read more about [queries in the Cosmic documentation](https://www.cosmicjs.com/docs/api/queries). 3. Import your query function in a `.astro` component. After fetching data, the results from the query can be used in your Astro template. The following example shows fetching metadata from Cosmic `posts` and passing these values as props to a `` component to create a list of blog posts: src/pages/index.astro ```astro --- import Card from '../components/Card.astro' import { getAllPosts } from '../lib/cosmic' const data = await getAllPosts() ---

tag)} /> )) }

``` [View source code for the Card component](https://github.com/cosmicjs/simple-astro-blog/blob/main/src/components/Card.astro) ## Building a Blog with Astro and Cosmic [Section titled Building a Blog with Astro and Cosmic](#building-a-blog-with-astro-and-cosmic) You can manage your Astro blog’s content using Cosmic and create webhooks to automatically redeploy your website when you update or add new content. ### Cosmic Content Objects [Section titled Cosmic Content Objects](#cosmic-content-objects) The following instructions assume that you have an **Object Type** in Cosmic called **posts**. Each individual blog post is a `post` that is defined in the Cosmic dashboard with the following Metafields: 1. **Text input** - Author 2. **Image** - Cover Image 3. **Repeater** - Tags * **Text input** - Title 4. **Text area** - Excerpt 5. **Rich Text** - Content ### Displaying a List of Blog Posts in Astro [Section titled Displaying a List of Blog Posts in Astro](#displaying-a-list-of-blog-posts-in-astro) Using the same [data-fetching method](#fetching-data-from-cosmic) as above, import the `getAllPosts()` query from your script file and await the data. This function provides metadata about each `post` which can be displayed dynamically. The example below passes these values to a `` component to display a formatted list of blog posts: src/pages/index.astro ```astro --- import Card from '../components/Card.astro' import { getAllPosts } from '../lib/cosmic' const data = await getAllPosts() ---

tag)} /> )) }

``` ### Generating Individual Blog Posts with Astro [Section titled Generating Individual Blog Posts with Astro](#generating-individual-blog-posts-with-astro) To generate an individual page with full content for each blog post, create a [dynamic routing page](/en/guides/routing/#dynamic-routes) at `src/pages/blog/[slug].astro`. This page will export a `getStaticPaths()` function to generate a page route at the `slug` returned from each `post` object. This function is called at build time and generates and renders all of your blog posts at once. To access your data from Cosmic: * Query Cosmic inside of `getStaticPaths()` to fetch data about each post and provide it to the function. * Use each `post.slug` as a route parameter, creating the URLs for each blog post. * Return each `post` inside of `Astro.props`, making the post data available to HTML template portion of the page component for rendering. The HTML markup below uses various data from Cosmic, such as the post title, cover image, and the **rich text content** (full blog post content). Use [set:html](/en/reference/directives-reference/#sethtml) on the element displaying the rich text content from Cosmic to render HTML elements on the page exactly as fetched from Cosmic. src/pages/blog/\[slug].astro ```astro --- import { getAllPosts } from '../../lib/cosmic' import { Image } from 'astro:assets' export async function getStaticPaths() { const data = (await getAllPosts()) || [] return data.map((post) => { return { params: { slug: post.slug }, props: { post } } }) } const { post } = Astro.props ---

{post.title}

{post.metadata.author?.title}

{ post.metadata.cover_image && ( {`Cover

) }

``` ### Publishing your site [Section titled Publishing your site](#publishing-your-site) To deploy your website, visit the [deployment guides](/en/guides/deploy/) and follow the instructions for your preferred hosting provider. #### Rebuild on Cosmic content updates [Section titled Rebuild on Cosmic content updates](#rebuild-on-cosmic-content-updates) You can set up a webhook in Cosmic directly to trigger a redeploy of your site on your hosting platform (e.g. Vercel) whenever you update or add content Objects. Under “Settings” > “webhooks”, add the URL endpoint from Vercel and select the Object Type you would like to trigger the webhook. Click “Add webhook” to save it. ##### Netlify [Section titled Netlify](#netlify) To set up a webhook in Netlify: 1. Go to your site dashboard and click on **Build & deploy**. 2. Under the **Continuous Deployment** tab, find the **Build hooks** section and click on **Add build hook**. 3. Provide a name for your webhook and select the branch you want to trigger the build on. Click on **Save** and copy the generated URL. ##### Vercel [Section titled Vercel](#vercel) To set up a webhook in Vercel: 1. Go to your project dashboard and click on **Settings**. 2. Under the **Git** tab, find the **Deploy Hooks** section. 3. Provide a name for your webhook and the branch you want to trigger the build on. Click **Add** and copy the generated URL. ## Themes [Section titled Themes](#themes) * [![](/_astro/simple-astro-blog.Dl86rePH_ZijHC7.webp) Astro Headless CMS Blog](https://astro.build/themes/details/cosmic-cms-blog/) # Craft CMS & Astro > Add content to your Astro project using Craft CMS as a CMS [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 [Section titled Official Resources](#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 [Section titled Community Resources](#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/) # Crystallize & Astro > Add content to your Astro project using Crystallize as a CMS [Crystallize](https://crystallize.com/) is a headless content management system for eCommerce that exposes a GraphQL API. ## Example [Section titled Example](#example) src/pages/index.astro ```astro --- // Fetch your catalogue paths from Crystallize GraphQL API import BaseLayout from '../../layouts/BaseLayout.astro'; import { createClient } from '@crystallize/js-api-client'; 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) ---

{catalogue.name}

``` # DatoCMS & Astro > Add content to your Astro project using DatoCMS [DatoCMS](https://datocms.com/) is a web-based, headless CMS to manage digital content for your sites and apps. ## Integrating with Astro [Section titled Integrating with Astro](#integrating-with-astro) In this guide, you will fetch content data from DatoCMS in your Astro project, then display it on a page. ## Prerequisites [Section titled Prerequisites](#prerequisites) To get started, you will need to have the following: * **An Astro project** - If you don’t have an Astro project yet, you can follow the instructions in our [Installation guide](/en/install-and-setup/). * **A DatoCMS account and project** - If you don’t have an account, you can [sign up for a free account](https://dashboard.datocms.com/signup). * **The read-only API Key for your DatoCMS project** - You can find it in the admin dashboard of your project, under “Settings” > “API Tokens”. ## Setting up the credentials [Section titled Setting up the credentials](#setting-up-the-credentials) Create a new file (if one does not already exist) named `.env` in the root of your Astro project. Add a new environment variable as follows, using the API key found in your DatoCMS admin dashboard: .env ```ini DATOCMS_API_KEY=YOUR_API_KEY ``` For TypeScript support, declare the typing of this environment variable in the `env.d.ts` file in the `src/` folder. If this file does not exist, you can create it and add the following: src/env.d.ts ```ts interface ImportMetaEnv { readonly DATOCMS_API_KEY: string; } ``` Your root directory should now include these files: * src/ * **env.d.ts** * **.env** * astro.config.mjs * package.json ## Create a Model in DatoCMS [Section titled Create a Model in DatoCMS](#create-a-model-in-datocms) In the DatoCMS admin dashboard of your project, navigate to “Settings” > “Models” and create a new Model called “Home” with the “Single Instance” toggle selected. This will create a home page for your project. In this model, add a new text field for the page title. Navigate to the “Content” tab in your project and click on your newly-created home page. You can now add a title. Save the page, and continue. ## Fetching data [Section titled Fetching data](#fetching-data) In your Astro project, navigate to the page that will fetch and display your CMS content. Add the following query to fetch the content for `home` using the DatoCMS GraphQL API. This example displays the page title from DatoCMS on `src/pages/index.astro`: src/pages/index.astro ```astro --- const response = await fetch('https://graphql.datocms.com/', { method: 'POST', headers: { 'Content-Type': 'application/json', Accept: 'application/json', Authorization: `Bearer ${import.meta.env.DATOCMS_API_KEY}`, }, body: JSON.stringify({ query: `query Homepage { home { title } } `, }), }); const json = await response.json(); const data = json.data.home; ---

{data.title}

``` This GraphQL query will fetch the `title` field in the `home` page from your DatoCMS Project. When you refresh your browser, you should see the title on your page. ## Adding Dynamic modular content blocks [Section titled Adding Dynamic modular content blocks](#adding-dynamic-modular-content-blocks) If your DatosCMS project includes [modular content](https://www.datocms.com/docs/content-modelling/modular-content), then you will need to build a corresponding `.astro` component for each block of content (e.g. a text section, a video, a quotation block, etc.) that the modular field allows in your project. The example below is a `` Astro component for displaying a “Multiple-paragraph text” block from DatoCMS. src/components/Text.astro ```astro --- export interface TextProps { text: string } export interface Props { item: TextProps } const { item } = Astro.props; ---

``` To fetch these blocks, edit your GraphQL query to include the modular content block you created in DatoCMS. In this example, the modular content block is named **content** in DatoCMS. This query also includes the unique `_modelApiKey` of each item to check which block should be displayed in the modular field, based on which block was chosen by the content author in the DatoCMS editor. Use a switch statement in the Astro template to allow for dynamic rendering based on the data received from the query. The following example represents a DatoCMS modular content block that allows an author to choose between a text field (``) and an image (``) rendered on the home page: src/pages/index.astro ```astro --- import Image from '../components/Image.astro'; import Text from '../components/Text.astro'; const response = await fetch('https://graphql.datocms.com/', { method: 'POST', headers: { 'Content-Type': 'application/json', Accept: 'application/json', Authorization: `Bearer ${import.meta.env.DATOCMS_API_KEY}`, }, body: JSON.stringify({ query: `query Homepage { home { title content { ... on ImageRecord { _modelApiKey image{ url } } ... on TextRecord { _modelApiKey text(markdown: true) } } } } `, }), }); const json = await response.json(); const data = json.data.home; ---

{data.title}

{ data.content.map((item: any) => { switch (item._modelApiKey) { case 'image': return ; case 'text': return ; default: return null; } }) } ``` ## Publishing your site [Section titled Publishing your site](#publishing-your-site) To deploy your website, visit our [deployment guides](/en/guides/deploy/) and follow the instructions for your preferred hosting provider. ## Publish on DatoCMS content changes [Section titled Publish on DatoCMS content changes](#publish-on-datocms-content-changes) If your project is using Astro’s default static mode, you will need to set up a webhook to trigger a new build when your content changes. If you are using Netlify or Vercel as your hosting provider, you can use its webhook feature to trigger a new build when you change content in DatoCMS. ### Netlify [Section titled Netlify](#netlify) To set up a webhook in Netlify: 1. Go to your site dashboard and click on **Build & deploy**. 2. Under the **Continuous Deployment** tab, find the **Build hooks** section and click on **Add build hook**. 3. Provide a name for your webhook and select the branch you want to trigger the build on. Click on **Save** and copy the generated URL. ### Vercel [Section titled Vercel](#vercel) To set up a webhook in Vercel: 1. Go to your project dashboard and click on **Settings**. 2. Under the **Git** tab, find the **Deploy Hooks** section. 3. Provide a name for your webhook and the branch you want to trigger the build on. Click **Add** and copy the generated URL. ### Adding a webhook to DatoCMS [Section titled Adding a webhook to DatoCMS](#adding-a-webhook-to-datocms) In your DatoCMS project admin dashboard, navigate to the **Settings** tab and click **Webhooks**. Click the plus icon to create a new webhook and give it a name. In the URL field, paste the URL generated by your preferred hosting service. As Trigger, select whichever option suits your needs. (For example: build every time a new record is published.) ## Starter project [Section titled Starter project](#starter-project) You can also check out the [Astro blog template](https://www.datocms.com/marketplace/starters/astro-template-blog) on the DatoCMS marketplace to learn how to create a blog with Astro and DatoCMS. # Decap CMS & Astro > Add content to your Astro project using Decap as a CMS [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 [Section titled Installing DecapCMS](#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: * npm ```shell npm install decap-cms-app ``` * pnpm ```shell pnpm add decap-cms-app ``` * Yarn ```shell yarn add decap-cms-app ``` 2. Import the package into a ` ``` ## Configuration [Section titled Configuration](#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: /public/admin/config.yml ```yml 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 /src/pages/admin.html ```html Content Manager ``` 5. To enable media uploads to a specific folder via the Decap editor, add an appropriate path: /public/admin/config.yml ```yml 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 [Section titled Usage](#usage) Navigate to `yoursite.com/admin/` to use the Decap CMS editor. ## Authentication [Section titled Authentication](#authentication) ### Decap CMS with Netlify Identity [Section titled Decap CMS with Netlify Identity](#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 [Section titled Decap CMS with External OAuth Clients](#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 [Section titled Community Resources](#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 ## Production Sites [Section titled Production Sites](#production-sites) The following sites use Astro + Decap CMS in production: * [yunielacosta.com](https://www.yunielacosta.com/) by Yuniel Acosta — [source code on GitHub](https://github.com/yacosta738/yacosta738.github.io) (Netlify CMS) * [portfolioris.nl](https://www.portfolioris.nl/) by Joris Hulsbosch – [source code on GitHub](https://github.com/portfolioris/portfolioris.nl) ## Themes [Section titled Themes](#themes) * [![](/_astro/astros.CA8z6dbD_Z1fUXSm.webp) Astros](https://astro.build/themes/details/astros) * [![](/_astro/enhanced-astro-starter.BDAzOMVv_ghcL4.webp) Enhanced Astro Starter](https://astro.build/themes/details/enhanced-astro-starter) * [![](/_astro/astro-decap-starter.CuC8RtgM_IaqHQ.webp) Astro Decap CMS Starter](https://astro.build/themes/details/astro-decap-cms-starter) # Directus & Astro > Add content to your Astro project using Directus as a CMS [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 [Section titled Official Resources](#official-resources) * [Getting Started with Directus and Astro](https://docs.directus.io/blog/getting-started-directus-astro.html). ## Community Resources [Section titled Community Resources](#community-resources) * Add yours! # Drupal & Astro > Add content to your Astro project using Drupal as a CMS [Drupal](https://www.drupal.org/) is an open-source content management tool. ## Prerequisites [Section titled Prerequisites](#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 [Section titled Integrating Drupal with Astro](#integrating-drupal-with-astro) ### Installing the JSON:API Drupal module [Section titled Installing the JSON:API Drupal module](#installing-the-jsonapi-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` [Section titled Adding the Drupal URL in .env](#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: .env ```ini DRUPAL_BASE_URL="https://drupal.ddev.site/" ``` Restart the dev server to use this environment variable in your Astro project. ### Setting up Credentials [Section titled Setting up Credentials](#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. .env ```ini 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 [Section titled Installing dependencies](#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. - npm ```shell npm install jsona drupal-jsonapi-params ``` - pnpm ```shell pnpm add jsona drupal-jsonapi-params ``` - Yarn ```shell yarn add jsona drupal-jsonapi-params ``` ## Fetching data from Drupal [Section titled Fetching data from Drupal](#fetching-data-from-drupal) Your content is fetched from a JSON:API URL. ### Drupal JSON:API URL structure [Section titled Drupal JSON:API URL structure](#drupal-jsonapi-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 [Section titled Retrieving only certain fields](#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 [Section titled Filtering](#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 [Section titled Building a Drupal query](#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: ```astro --- import {Jsona} from "jsona"; import {DrupalJsonApiParams} from "drupal-jsonapi-params"; import type {TJsonApiBody} from "jsona/lib/JsonaTypes"; // Get the Drupal base URL export const baseUrl: string = import.meta.env.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); --- {articles?.length ? articles.map((article: any) => (

{article.title}

)):

No Content found

} ``` 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 [Section titled Making a blog with Astro and Drupal](#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 [Section titled Prerequisites](#prerequisites-1) 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 [Section titled Displaying a list of articles](#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. src/types.ts ```ts export interface Path { alias: string pid: number langcode: string } export interface DrupalNode extends Record { 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: src/api/drupal.ts ```ts 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. src/api/drupal.ts ```ts 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 as Promise */ export const fetchUrl = async (url: string): Promise => { 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. src/api/drupal.ts ```ts 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 as Promise */ export const fetchUrl = async (url: string): Promise => { 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 */ export const getArticles = async (): Promise => { 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. src/pages/articles/index.astro ```astro --- 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. src/pages/articles/index.astro ```astro --- 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(); --- My news site

My news site

{article.title}

Published on {article.created}

``` ### Generating individual blog posts [Section titled Generating individual blog posts](#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. src/pages/articles/\[path].astro ```astro --- 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. src/pages/articles/\[path].astro ```astro --- 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. src/pages/articles/\[path].astro ```astro --- 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; --- {title}

{title}

{date}

``` 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 [Section titled Publishing your site](#publishing-your-site) To deploy your website, visit our [deployment guides](/en/guides/deploy/) and follow the instructions for your preferred hosting provider. # Flotiq & Astro > Add content to your Astro project using Flotiq as a CMS [Flotiq](https://flotiq.com) 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 [Section titled Integrating with Astro](#integrating-with-astro) This guide will use the Flotiq headless CMS API with an Astro project to display content on your website. ### Prerequisites [Section titled Prerequisites](#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). 3. **Flotiq read-only API key** - Find out [how to obtain your key](https://flotiq.com/docs/API/). ### Setting up the Environment variables [Section titled Setting up the Environment variables](#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: .env ```ini FLOTIQ_API_KEY=__YOUR_FLOTIQ_API_KEY__ ``` ### Defining a Content Type in Flotiq [Section titled Defining a Content Type in Flotiq](#defining-a-content-type-in-flotiq) First, you need to define an example [Content Type Definition](https://flotiq.com/docs/panel/content-types/) 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/) using this `Blog Post` type. ### Installing the Flotiq TypeScript SDK [Section titled Installing the Flotiq TypeScript SDK](#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: * npm ```sh npm install flotiq-api-ts ``` * pnpm ```sh pnpm add flotiq-api-ts ``` * Yarn ```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: src/lib/flotiq.ts ```ts import { FlotiqApi } from "flotiq-api-ts"; export const flotiq = new FlotiqApi(import.meta.env.FLOTIQ_API_KEY); ``` This configuration can now be used throughout your project. ### Fetching and Displaying Data from Flotiq [Section titled Fetching and Displaying Data from Flotiq](#fetching-and-displaying-data-from-flotiq) 1. Fetch the `Blog Post` data on an Astro page using your content’s custom API `BlogpostAPI`: src/pages/index.astro ```astro --- 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: src/pages/index.astro ```astro --- import { flotiq } from "../lib/flotiq"; const posts = await flotiq.BlogpostAPI.list(); --- Astro {posts.data?.map((post) => (

{post.title}

{post.internal?.createdAt}

))} ``` 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 [Section titled Generating Individual Pages](#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 [Section titled Static Site Generation](#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: src/pages/posts/\[slug].astro ```astro --- 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: src/pages/posts/\[slug].astro ```astro --- 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; --- {post.title}

{post.title}

``` 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 [Section titled On-demand Rendering](#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: src/pages/posts/\[slug].astro ```astro --- 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: src/pages/posts/\[slug].astro ```astro --- 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'); } --- {post.title}

{post.title}

``` 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 [Section titled Refreshing the SDK After Content Type Changes](#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: * npm ```sh npm rebuild flotiq-api-ts ``` * pnpm ```sh pnpm rebuild flotiq-api-ts ``` * Yarn ```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 [Section titled Publishing Your Site](#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 [Section titled Redeploy on Flotiq Changes](#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/) for more details. ## Official Resources [Section titled Official Resources](#official-resources) * [Flotiq documentation](https://flotiq.com/docs) # Front Matter CMS & Astro > Add content to your Astro project using Front Matter CMS [Front Matter CMS](https://frontmatter.codes/) brings the CMS to your editor, it runs within Visual Studio Code, Gitpod, and many more. ## Integration with Astro [Section titled Integration with Astro](#integration-with-astro) In this section, we’ll walk through how to add Front Matter CMS to your Astro project. ### Prerequisites [Section titled Prerequisites](#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 [Section titled Install the Front Matter CMS extension](#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 [Section titled Project initialization](#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 [Section titled Project configuration](#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 [Section titled Content-type configuration](#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.json ```json "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 [Section titled Preview your articles in the editor](#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 [Section titled Create new articles](#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 [Section titled Using Markdoc with Front Matter CMS](#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.json ```json "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.json ```json "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 [Section titled Official Resources](#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 > Add content to your Astro project using Ghost as a CMS [Ghost](https://github.com/TryGhost/Ghost) is an open-source, headless content management system built on Node.js. ## Integrating with Astro [Section titled Integrating with Astro](#integrating-with-astro) In this section, we’ll use the [Ghost content API](https://ghost.org/docs/content-api/) to bring your data into your Astro project. ### Prerequisites [Section titled Prerequisites](#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 Ghost site** - It is assumed that you have a site set up with Ghost. If you don’t you can set one up on a [local environment.](https://ghost.org/docs/install/local/) 3. **Content API Key** - You can make an integration under your site’s `Settings > Integrations`. From there you can find your `Content API key` ### Setting up credentials [Section titled Setting up credentials](#setting-up-credentials) To add your site’s credentials to Astro, create an `.env` file in the root of your project with the following variable: .env ```ini CONTENT_API_KEY=YOUR_API_KEY ``` Now, you should be able to use this environment variable in your project. If you would like to have IntelliSense for your environment variable, you can create a `env.d.ts` file in the `src/` directory and configure `ImportMetaEnv` like this: src/env.d.ts ```ts interface ImportMetaEnv { readonly CONTENT_API_KEY: string; } ``` 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: * src/ * **env.d.ts** * **.env** * astro.config.mjs * package.json ### Installing dependencies [Section titled Installing dependencies](#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: * npm ```shell npm install @tryghost/content-api npm install --save @types/tryghost__content-api ``` * pnpm ```shell pnpm add @tryghost/content-api pnpm add --save-dev @types/tryghost__content-api ``` * Yarn ```shell yarn add @tryghost/content-api yarn add --dev @types/tryghost__content-api ``` ## Making a blog with Astro and Ghost [Section titled Making a blog with Astro and Ghost](#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 [Section titled Prerequisites](#prerequisites-1) 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 [Section titled Fetching Data](#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. src/lib/ghost.ts ```ts import GhostContentAPI from '@tryghost/content-api'; // Create API instance with site credentials export const ghostClient = new GhostContentAPI({ url: 'http://127.0.0.1:2368', // This is the default URL if your site is running on a local environment key: import.meta.env.CONTENT_API_KEY, version: 'v5.0', }); ``` ### Displaying a list of posts [Section titled Displaying a list of posts](#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. src/pages/index.astro ```astro --- import { ghostClient } from '../lib/ghost'; 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. src/pages/index.astro ```astro --- import { ghostClient } from '../lib/ghost'; const posts = await ghostClient.posts .browse({ limit: 'all', }) .catch((err) => { console.error(err); }); --- Astro + Ghost 👻 { posts.map((post) => (

{post.title}

)) } ``` ### Generating pages [Section titled Generating pages](#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. src/pages/post/\[slug].astro ```astro --- import { ghostClient } from '../../lib/ghost'; export async function getStaticPaths() { const posts = await ghostClient.posts .browse({ limit: 'all', }) .catch((err) => { console.error(err); }); 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. src/pages/post/\[slug].astro ```astro --- import { ghostClient } from '../../lib/ghost'; export async function getStaticPaths() { const posts = await ghostClient.posts .browse({ limit: 'all', }) .catch((err) => { console.error(err); }); return posts.map((post) => { return { params: { slug: post.slug, }, props: { post: post, }, }; }); } const { post } = Astro.props; --- {post.title}

{post.title}

{post.reading_time} min read

``` Note `` 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 [Section titled Publishing your site](#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 [Section titled Community Resources](#community-resources) * [`astro-starter-ghost`](https://github.com/PhilDL/astro-starter-ghost) on GitHub * [`astro-ghostcms`](https://github.com/MatthiesenXYZ/astro-ghostcms) on GitHub * [Astro + Ghost + Tailwind CSS](https://andr.ec/posts/astro-ghost-blog/) by Andre Carrera * [Ghost CMS & Astro Tutorial](https://matthiesen.xyz/blog/astro-ghostcms) by Adam Matthiesen # Hashnode & Astro > Add content to your Astro project using Hashnode as a CMS [Hashnode](https://hashnode.com/) is a hosted CMS that allows you to create a blog or publication. ## Integrating with Astro [Section titled Integrating with Astro](#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 [Section titled Prerequisites](#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 [Section titled Installing dependencies](#installing-dependencies) Install the `graphql-request` package using the package manager of your choice: * npm ```shell npm install graphql-request ``` * pnpm ```shell pnpm add graphql-request ``` * Yarn ```shell yarn add graphql-request ``` ## Making a blog with Astro and Hashnode [Section titled Making a blog with Astro and Hashnode](#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 [Section titled Prerequisites](#prerequisites-1) 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 [Section titled Fetching Data](#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`: * src/ * lib/ * **client.ts** * **schema.ts** * pages/ * index.astro * astro.config.mjs * package.json 2. Initialize an API instance with the GraphQLClient using the URL from your Hashnode Website. src/lib/client.ts ```ts 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( 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( 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. src/lib/schema.ts ```ts 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 export type AllPostsData = z.infer export type PostData = z.infer ``` ### Displaying a list of posts [Section titled Displaying a list of posts](#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. src/pages/index.astro ```astro --- import { getAllPosts } from '../lib/client'; const data = await getAllPosts(); const allPosts = data.publication.posts.edges; --- Astro + Hashnode { allPosts.map((post) => (

{post.node.title}

{post.node.brief}

)) } ``` ### Generating pages [Section titled Generating pages](#generating-pages) 1. Create the page `src/pages/post/[slug].astro` to [dynamically generate a page](/en/guides/routing/#dynamic-routes) for each post. * src/ * … * lib/ * client.ts * schema.ts * pages/ * index.astro * post/ * **\[slug].astro** * astro.config.mjs * package.json 2. Import and use `getAllPosts()` and `getPost()` to fetch the data from Hashnode and generate individual page routes for each post. src/pages/post/\[slug].astro ```astro --- 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: src/pages/post/\[slug].astro ```astro --- 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); --- {post.title}

{post.title}

{post.readTimeInMinutes} min read

``` Note `` 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 [Section titled Publishing your site](#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 [Section titled Community Resources](#community-resources) * [`astro-hashnode`](https://github.com/matthiesenxyz/astro-hashnode) on GitHub # Hygraph & Astro > Add content to your Astro project using Hygraph as a CMS [Hygraph](https://hygraph.com/) is a federated content management platform. It exposes a GraphQL endpoint for fetching content. ## Integrating with Astro [Section titled Integrating with Astro](#integrating-with-astro) In this section, you’ll create a [Hygraph](https://hygraph.com/) GraphQL endpoint to fetch with Astro. ### Prerequisites [Section titled Prerequisites](#prerequisites) To get started, you will need to have the following: 1. **A Hygraph account and project**. If you don’t have an account, you can [sign up for free](https://app.hygraph.com/signup) and create a new project. 2. **Hygraph access permissions** - In `Project Settings > API Access`, configure Public Content API permissions to allow read requests without authentication. If you haven’t set any permissions, you can click **Yes, initialize defaults** to add the required permissions to use the “High Performance Content API”. ### Setting up the endpoint [Section titled Setting up the endpoint](#setting-up-the-endpoint) To add your Hygraph endpoint to Astro, create a `.env` file in the root of your project with the following variable: .env ```ini HYGRAPH_ENDPOINT=YOUR_HIGH_PERFORMANCE_API ``` Now, you should be able to use this environment variable in your project. If you would like to have IntelliSense for your environment variables, you can create a `env.d.ts` file in the `src/` directory and configure `ImportMetaEnv` like this: src/env.d.ts ```ts interface ImportMetaEnv { readonly HYGRAPH_ENDPOINT: string; } ``` Note Read more about [using environment variables](/en/guides/environment-variables/) and `.env` files in Astro. Your root directory should now include these new files: * src/ * **env.d.ts** * **.env** * astro.config.mjs * package.json ### Fetching data [Section titled Fetching data](#fetching-data) Fetch data from your Hygraph project by using the `HYGRAPH_ENDPOINT`. For example, to fetch entries of a `blogPosts` content type that has a string field `title`, create a GraphQL query to fetch that content. Then, define the type of the content, and set it as the type of the response. src/pages/index.astro ```astro --- interface Post { title: string; } const query = { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ query: ` { blogPosts { title } }`, }), }; const response = await fetch(import.meta.env.HYGRAPH_ENDPOINT, query); const json = await response.json(); const posts: Post[] = json.data.blogPosts; --- Astro

Astro

{ posts.map((post) => (

{post.title}

)) } ``` ## Deploy [Section titled Deploy](#deploy) ### Configuring Netlify Webhook [Section titled Configuring Netlify Webhook](#configuring-netlify-webhook) To set up a webhook in Netlify: 1. Deploy your site to Netlify with [this guide](/en/guides/deploy/netlify/). Remember to add your `HYGRAPH_ENDPOINT` to the environment variables. 2. Then Go to your Hygraph project dashboard and click on **Apps**. 3. Go to the marketplace and search for Netlify and follow the instructions provided. 4. If all went good, now you can deploy your website with a click in the Hygraph interface. ## Community Resources [Section titled Community Resources](#community-resources) * [Hygraph + Astro example with `marked` for markdown parsing](https://github.com/camunoz2/example-astrowithhygraph) # Keystatic & Astro > Add content to your Astro project using Keystatic as a CMS [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: * npm ```shell npm create @keystatic@latest ``` * pnpm ```shell pnpm create @keystatic@latest ``` * Yarn ```shell yarn create @keystatic ``` Select the Astro template, and you’ll be ready to [deploy](#deploying-keystatic--astro)! ## Prerequisites [Section titled Prerequisites](#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 [Section titled Installing dependencies](#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. * npm ```shell npx astro add react markdoc ``` * pnpm ```shell pnpm astro add react markdoc ``` * Yarn ```shell yarn astro add react markdoc ``` You will also need two Keystatic packages: * npm ```shell npm install @keystatic/core @keystatic/astro ``` * pnpm ```shell pnpm add @keystatic/core @keystatic/astro ``` * Yarn ```shell yarn add @keystatic/core @keystatic/astro ``` ## Adding the Astro integration [Section titled Adding the Astro integration](#adding-the-astro-integration) Add the Astro integration from `@keystatic/astro` in your Astro config file: astro.config.mjs ```js import { defineConfig } from 'astro/config' import react from '@astrojs/react' import markdoc from '@astrojs/markdoc' import keystatic from '@keystatic/astro' // https://astro.build/config export default defineConfig({ integrations: [react(), markdoc(), keystatic()], output: 'static', }) ``` ## Creating a Keystatic config file [Section titled Creating a Keystatic config file](#creating-a-keystatic-config-file) A Keystatic config file is required to define your content schema. This file will also allow you to connect a project to a specific GitHub repository (if you decide to do so). Create a file called `keystatic.config.ts` in the root of the project and add the following code to define both your storage type (`local`) and a single content collection (`posts`): keystatic.config.ts ```ts import { config, fields, collection } from '@keystatic/core'; export default config({ storage: { kind: 'local', }, collections: { posts: collection({ label: 'Posts', slugField: 'title', path: 'src/content/posts/*', format: { contentField: 'content' }, schema: { title: fields.slug({ name: { label: 'Title' } }), content: fields.markdoc({ label: 'Content', }), }, }), }, }); ``` 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 [Section titled Running Keystatic locally](#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 [Section titled Creating a new post](#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: ```markdown --- title: My First Post --- This is my very first post. I am **super** excited! ``` ## Rendering Keystatic content [Section titled Rendering Keystatic content](#rendering-keystatic-content) Use Astro’s Content Collections API to [query and display your posts and collections](/en/guides/content-collections/#querying-collections), just as you would in any Astro project. ### Displaying a collection list [Section titled Displaying a collection list](#displaying-a-collection-list) The following example displays a list of each post title, with a link to an individual post page. ```tsx --- import { getCollection } from 'astro:content' const posts = await getCollection('posts') ---

{post.data.title}

``` ### Displaying a single entry [Section titled Displaying a single entry](#displaying-a-single-entry) To display content from an individual post, you can import and use the `` component to [render your content to HTML](/en/guides/content-collections/#rendering-body-content): ```tsx --- import { getEntry } from 'astro:content' const post = await getEntry('posts', 'my-first-post') const { Content } = await post.render() ---

{post.data.title}

``` 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 [Section titled Deploying Keystatic + Astro](#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 [Section titled Official Resources](#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 > Add content to your Astro project using KeystoneJS as a CMS [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 > Add content to your Astro project using Kontent.ai as CMS [Kontent.ai](https://www.kontent.ai/) is a headless CMS that allows you to manage content in a structured and modular way, supported by AI capabilities. ## Integrating with Astro [Section titled Integrating with Astro](#integrating-with-astro) In this section, you’ll use the [Kontent.ai TypeScript SDK](https://github.com/kontent-ai/delivery-sdk-js) to connect your Kontent.ai project to your Astro application. ### Prerequisites [Section titled Prerequisites](#prerequisites) To get started, you’ll need the following: 1. **Kontent.ai project** - If you don’t have a Kontent.ai account yet, [sign up for free](https://app.kontent.ai/sign-up) and create a new project. 2. **Delivery API keys** - You will need the Environment ID for published content and the Preview API key for fetching drafts (optional). Both keys are located in the **Environment Settings -> API keys** tab in Kontent.ai. ### Setting up credentials [Section titled Setting up credentials](#setting-up-credentials) To add your Kontent.ai credentials to Astro, create a `.env` file in the root of your project with the following variables: .env ```ini KONTENT_ENVIRONMENT_ID=YOUR_ENVIRONMENT_ID KONTENT_PREVIEW_API_KEY=YOUR_PREVIEW_API_KEY ``` Now, these environment variables can be used in your Astro project. If you would like to get [TypeScript IntelliSense for these environment variables](/en/guides/environment-variables/#intellisense-for-typescript), you can create a new `env.d.ts` file in the `src/` directory and configure `ImportMetaEnv` like this: src/env.d.ts ```ts interface ImportMetaEnv { readonly KONTENT_ENVIRONMENT_ID: string; readonly KONTENT_PREVIEW_API_KEY: string; } ``` Your root directory should now include these new files: * src/ * **env.d.ts** * **.env** * astro.config.mjs * package.json ### Installing dependencies [Section titled Installing dependencies](#installing-dependencies) To connect Astro with your Kontent.ai project, install the [Kontent.ai TypeScript SDK](https://github.com/kontent-ai/delivery-sdk-js): * npm ```shell npm install @kontent-ai/delivery-sdk ``` * pnpm ```shell pnpm add @kontent-ai/delivery-sdk ``` * Yarn ```shell yarn add @kontent-ai/delivery-sdk ``` Next, create a new file called `kontent.ts` in the `src/lib/` directory of your Astro project. src/lib/kontent.ts ```ts import { createDeliveryClient } from "@kontent-ai/delivery-sdk"; export const deliveryClient = createDeliveryClient({ environmentId: import.meta.env.KONTENT_ENVIRONMENT_ID, previewApiKey: import.meta.env.KONTENT_PREVIEW_API_KEY, }); ``` Note Read more on [getting environment variables in Astro](/en/guides/environment-variables/#getting-environment-variables). This implementation creates a new `DeliveryClient` object using credentials from the `.env` file. Previews The `previewApiKey` is optional. When used, you can [configure each query](https://github.com/kontent-ai/delivery-sdk-js#enable-preview-mode-per-query) to the Delivery API endpoint to return the latest versions of content items regardless of their state in the workflow. Otherwise, only published items are returned. Finally, the root directory of your Astro project should now include these new files: * src/ * lib/ * **kontent.ts** * env.d.ts * .env * astro.config.mjs * package.json ### Fetching data [Section titled Fetching data](#fetching-data) The `DeliveryClient` is now available to all components. To fetch content, use the `DeliveryClient` and method chaining to define your desired items. This example shows a basic fetch of blog posts and renders their titles in a list: src/pages/index.astro ```astro --- import { deliveryClient } from "../lib/kontent"; const blogPosts = await deliveryClient .items() .type("blogPost") .toPromise() --- Astro

{blogPost.elements.title.value}

``` You can find more querying options in the [Kontent.ai documentation](https://kontent.ai/learn/develop/hello-world/get-content/javascript). ## Making a blog with Astro and Kontent.ai [Section titled Making a blog with Astro and Kontent.ai](#making-a-blog-with-astro-and-kontentai) With the setup above, you are now able to create a blog that uses Kontent.ai as the source of content. ### Prerequisites [Section titled Prerequisites](#prerequisites-1) 1. **Kontent.ai project** - For this tutorial, using a blank project is recommended. If you already have some content types in your content model, you may use them, but you will need to modify the code snippets to match your content model. 2. **Astro project configured for content fetching from Kontent.ai** - see above for more details on how to set up an Astro project with Kontent.ai ### Setting up content model [Section titled Setting up content model](#setting-up-content-model) In Kontent.ai, navigate to **Content model** and create a new content type with the following fields and values: * **Name:** Blog Post * Elements: * Text field * **Name:** Title * **Element Required:** yes * Rich text field * **Name:** Teaser * **Element Required:** yes * **Allowed in this element:** only check Text * Rich text field * **Name:** Content * **Element Required:** yes * Date & time field * **Name:** Date * URL slug field * **Name:** URL slug * **Element Required:** yes * **Auto-generate from:** select “Title” Then, click on **Save Changes**. ### Creating content [Section titled Creating content](#creating-content) Now, navigate to **Content & assets** tab and create a new content item of type **Blog Post**. Fill the fields using these values: * **Content item name:** Astro * **Title:** Astro is amazing * **Teaser:** Astro is an all-in-one framework for building fast websites faster. * **Content:** You can use JavaScript to implement the website functionality, but no client bundle is necessary. * **Date & time:** select today * **URL slug:** astro-is-amazing When you’re finished, publish the blog post using the **Publish** button at the top. *Note: Feel free to create as many blog posts as you like before moving to the next step.* ### Generating content model in TypeScript [Section titled Generating content model in TypeScript](#generating-content-model-in-typescript) Next, you’ll generate TypeScript types out of your content model. Note This step is optional but provides a much better developer experience and allows you to discover potential problems at build time rather than at runtime. First, install the [Kontent.ai JS model generator](https://github.com/kontent-ai/model-generator-js), [ts-node](https://github.com/TypeStrong/ts-node), and [dotenv](https://github.com/motdotla/dotenv): * npm ```shell npm install @kontent-ai/model-generator ts-node dotenv ``` * pnpm ```shell pnpm add @kontent-ai/model-generator ts-node dotenv ``` * Yarn ```shell yarn add @kontent-ai/model-generator ts-node dotenv ``` Then, add the following script to package.json: package.json ```json { ... "scripts": { ... "regenerate:models": "ts-node --esm ./generate-models.ts" }, } ``` Because the types require structural information about your project that is not available in the public API, you also need to add a Content Management API key to the `.env` file. You can generate the key under **Environment settings -> API keys -> Management API**. .env ```ini KONTENT_ENVIRONMENT_ID=YOUR_ENVIRONMENT_ID KONTENT_PREVIEW_API_KEY=YOUR_PREVIEW_API_KEY KONTENT_MANAGEMENT_API_KEY=YOUR_MANAGEMENT_API_KEY ``` Finally, add the script `generate-models.ts` that configures the model generator to generate the models: generate-models.ts ```ts import { generateModelsAsync, textHelper } from '@kontent-ai/model-generator' import { rmSync, mkdirSync } from 'fs' import * as dotenv from 'dotenv' dotenv.config() const runAsync = async () => { rmSync('./src/models', { force: true, recursive: true }) mkdirSync('./src/models') // change working directory to models process.chdir('./src/models') await generateModelsAsync({ sdkType: 'delivery', apiKey: process.env.KONTENT_MANAGEMENT_API_KEY ?? '', environmentId: process.env.KONTENT_ENVIRONMENT_ID ?? '', addTimestamp: false, isEnterpriseSubscription: false, }) } // Self-invocation async function ;(async () => { await runAsync() })().catch(err => { console.error(err) throw err }) ``` Now, execute it: * npm ```shell npm run regenerate:models ``` * pnpm ```shell pnpm run regenerate:models ``` * Yarn ```shell yarn run regenerate:models ``` ### Displaying a list of blog posts [Section titled Displaying a list of blog posts](#displaying-a-list-of-blog-posts) Now you’re ready to fetch some content. Go to the Astro page where you want to display a list of all blog posts, for example, the homepage `index.astro` in `src/pages`. Fetch all blog posts in the frontmatter of the Astro page: src/pages/index.astro ```astro --- import { deliveryClient } from '../lib/kontent'; import type { BlogPost } from '../models'; import { contentTypes } from '../models/project/contentTypes'; const blogPosts = await deliveryClient .items .type(contentTypes.blog_post.codename) .toPromise() --- ``` If you skipped the model generation, you can also use an untyped object and string literal to define the type: ```ts const blogPosts = await deliveryClient .items() .type("blogPost") .toPromise() ``` The fetch call will return a `response` object which contains a list of all blog posts in `data.items`. In the HTML section of the Astro page, you can use the `map()` function to list the blog posts: src/pages/index.astro ```astro --- import { deliveryClient } from '../lib/kontent'; import type { BlogPost } from '../models'; import { contentTypes } from '../models/project/contentTypes'; const blogPosts = await deliveryClient .items .type(contentTypes.blogPost.codename) .toPromise() --- Astro

Blog posts

{blogPost.elements.title.value}

``` ### Generating individual blog posts [Section titled Generating individual blog posts](#generating-individual-blog-posts) The last step of the tutorial is to generate detailed blog post pages. #### Static site generation [Section titled Static site generation](#static-site-generation) In this section, you’ll use the [Static (SSG) Mode](/en/guides/routing/#static-ssg-mode) with Astro. First, create a file `[slug].astro` in `/src/pages/blog/` which needs to export a function `getStaticPaths` that collects all data from the CMS: src/pages/blog/\[slug].astro ```astro --- import { deliveryClient } from '../../lib/kontent'; import type { BlogPost } from '../../models'; import { contentTypes } from '../../models/project/contentTypes'; export async function getStaticPaths() { const blogPosts = await deliveryClient .items() .type(contentTypes.blog_post.codename) .toPromise() --- ``` So far, the function fetches all blog posts from Kontent.ai. The code snippet is exactly the same as what you used on the home page. Next, the function must export paths and data for each blog post. You named the file `[slug].astro`, so the param which represents the URL slug is called `slug`: src/pages/blog/\[slug].astro ```astro --- import { deliveryClient } from '../../lib/kontent'; import type { BlogPost } from '../../models'; import { contentTypes } from '../../models/project/contentTypes'; export async function getStaticPaths() { const blogPosts = await deliveryClient .items() .type(contentTypes.blog_post.codename) .toPromise() return blogPosts.data.items.map(blogPost => ({ params: { slug: blogPost.elements.url_slug.value }, props: { blogPost } })) } --- ``` The last part is to provide the HTML template and display each blog post: src/pages/blog/\[slug].astro ```astro --- import { deliveryClient } from '../../lib/kontent'; import type { BlogPost } from '../../models'; import { contentTypes } from '../../models/project/contentTypes'; export async function getStaticPaths() { const blogPosts = await deliveryClient .items() .type(contentTypes.blog_post.codename) .toPromise() return blogPosts.data.items.map(blogPost => ({ params: { slug: blogPost.elements.url_slug.value }, props: { blogPost } })) } const blogPost: BlogPost = Astro.props.blogPost --- {blogPost.elements.title.value}

{blogPost.elements.title.value}

{new Date(blogPost.elements.date.value ?? "")} ``` Navigate to your Astro preview ( by default) to see the rendered blog post. #### On-demand rendering [Section titled On-demand rendering](#on-demand-rendering) If your routes are [rendered on demand](/en/guides/on-demand-rendering/), you will use dynamic routes to fetch the page data from Kontent.ai. Create a new file `[slug].astro` in `/src/pages/blog/` and add the following code. The data fetching is very similar to previous use cases but adds an `equalsFilter` that lets us find the right blog post based on the used URL: src/pages/blog/\[slug].astro ```astro --- import { deliveryClient } from '../../lib/kontent'; import type { BlogPost } from '../../models'; import { contentTypes } from '../../models/project/contentTypes'; const { slug } = Astro.params let blogPost: BlogPost; try { const data = await deliveryClient .items() .equalsFilter(contentTypes.blog_post.elements.url_slug.codename, slug ?? '') .type(contentTypes.blog_post.codename) .limitParameter(1) .toPromise() blogPost = data.data.items[0] } catch (error) { return Astro.redirect('/404') } --- ``` If you’re not using generated types, you can instead use string literals to define the content item type and the filtered element codename: ```ts const data = await deliveryClient .items() .equalsFilter("url_slug", slug ?? '') .type("blog_post") .limitParameter(1) .toPromise() ``` Lastly, add the HTML code to render the blog post. This part is the same as with static generation: src/pages/blog/\[slug].astro ```astro --- import { deliveryClient } from '../../lib/kontent'; import type { BlogPost } from '../../models'; import { contentTypes } from '../../models/project/contentTypes'; const { slug } = Astro.params let blogPost: BlogPost; try { const data = await deliveryClient .items() .equalsFilter(contentTypes.blog_post.elements.url_slug.codename, slug ?? '') .type(contentTypes.blog_post.codename) .limitParameter(1) .toPromise() blogPost = data.data.items[0] } catch (error) { return Astro.redirect('/404') } --- {blogPost.elements.title.value}

{blogPost.elements.title.value}

{new Date(blogPost.elements.date.value ?? '')} ``` ### Publishing your site [Section titled Publishing your site](#publishing-your-site) To deploy your website, visit the [deployment guides](/en/guides/deploy/) and follow the instructions for your preferred hosting provider. #### Rebuild on Kontent.ai changes [Section titled Rebuild on Kontent.ai changes](#rebuild-on-kontentai-changes) If your project is using Astro’s default static mode, you will need to set up a webhook to trigger a new build when your content changes. If you are using Netlify or Vercel as your hosting provider, you can use its webhook feature to trigger a new build from Kontent.ai events. ##### Netlify [Section titled Netlify](#netlify) To set up a webhook in Netlify: 1. Go to your site dashboard and click on **Build & deploy**. 2. Under the **Continuous Deployment** tab, find the **Build hooks** section and click on **Add build hook**. 3. Provide a name for your webhook and select the branch you want to trigger the build on. Click on **Save** and copy the generated URL. ##### Vercel [Section titled Vercel](#vercel) To set up a webhook in Vercel: 1. Go to your project dashboard and click on **Settings**. 2. Under the **Git** tab, find the **Deploy Hooks** section. 3. Provide a name for your webhook and the branch you want to trigger the build on. Click **Add** and copy the generated URL. ##### Adding a webhook to Kontent.ai [Section titled Adding a webhook to Kontent.ai](#adding-a-webhook-to-kontentai) In the [Kontent.ai app](https://kontent.ai/learn/docs/webhooks/javascript), go to **Environment settings -> Webhooks**. Click on **Create new webhook** and provide a name for your new webhook. Paste in the URL you copied from Netlify or Vercel and select which events should trigger the webhook. By default, for rebuilding your site when published content changes, you only need **Publish** and **Unpublish** events under **Delivery API triggers**. When you’re finished, click on Save. Now, whenever you publish a new blog post in Kontent.ai, a new build will be triggered and your blog will be updated. # microCMS & Astro > Add content to your Astro project using microCMS [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 [Section titled Official Resources](#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/) # Payload CMS & Astro > Add content to your Astro project using Payload as a CMS [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 [Section titled Integrating with Astro](#integrating-with-astro) ### Prerequisites [Section titled Prerequisites](#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. 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 [Section titled Configuring Astro for your PayloadCMS collection](#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: src/collections/Posts.ts ```ts import { CollectionConfig } from "payload/types"; 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, }, ], }; export default Posts; ``` 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. src/payload.config.ts ```ts 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. ```json { "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 [Section titled Fetching Data](#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: src/pages/index.astro ```astro --- import HomeLayout from "../layouts/HomeLayout.astro"; const res = await fetch("http://localhost:5000/api/posts") // http://localhost:4321/api/posts by default const posts = await res.json() --- { posts.docs.map((post) => (

)) } ``` ## Building a blog with PayloadCMS and Astro [Section titled Building a blog with PayloadCMS and Astro](#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` src/pages/index.astro ```astro --- import HomeLayout from "../layouts/HomeLayout.astro"; const res = await fetch("http://localhost:5000/api/posts") // http://localhost:4321/api/posts by default const posts = await res.json() ---

Astro + PayloadCMS 🚀

Blog posts list:

)) }

``` ### Using the PayloadCMS API to generate pages [Section titled Using the PayloadCMS API to generate pages](#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. src/pages/posts/\[slug].astro ```astro --- import PostLayout from "../../layouts/PostLayout.astro" const {title, content} = Astro.props // The getStaticPaths() is required for static Astro sites. // If using SSR, you will not need this function. export async function getStaticPaths() { let data = await fetch("http://localhost:5000/api/posts") let posts = await data.json() return posts.docs.map((post) => { return { params: {slug: post.slug}, props: {title: post.title, content: post.content}, }; }); } ---

``` ### Publishing your site [Section titled Publishing your site](#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 [Section titled Community Resources](#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 > Add content to your Astro project using Prepr as a CMS [Prepr CMS](https://www.prepr.io/) is a headless CMS with built-in personalization. ## Integrating with Astro [Section titled Integrating with Astro](#integrating-with-astro) Prepr CMS provides a [GraphQL API](https://docs.prepr.io/reference/graphql/v1/overview) to connect your data to Astro. ### Prerequisites [Section titled Prerequisites](#prerequisites) To get started, you will need the following: * A new or existing Astro project configured for [on-demand rendering](/en/guides/on-demand-rendering/). * [A free Prepr account](https://signup.prepr.io/) * [A Prepr environment with existing blog posts](https://docs.prepr.io/account/set-up-environments#create-an-envirntonment). These posts must include a `title` and `content`. Other fields are optional. ### Setting up credentials [Section titled Setting up credentials](#setting-up-credentials) To add the Prepr endpoint to your Astro project, create a `.env file` in the root of your project if one does not already exist and add the following variable: .env ```ini PREPR_ENDPOINT=YOUR_PREPR_API_URL ``` You will find your `YOUR_PREPR_API_URL` value from your Prepr account settings: 1. Go to **Settings > Access tokens** to view both your Preview and Production access tokens. 2. Use the **API URL** value from the **GraphQL Production** access token to only retrieve published content items for your Astro site. ### Configuring the Prepr endpoint [Section titled Configuring the Prepr endpoint](#configuring-the-prepr-endpoint) Create a new folder `src/lib/` and add a new file called `prepr.js`. This is where you will configure the Prepr endpoint. Add the following code to fetch your data from Prepr CMS: src/lib/prepr.js ```js export async function Prepr(query, variables) { const response = await fetch(import.meta.env.PREPR_ENDPOINT, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ query, variables }), }) return response } ``` Your root directory should now include these files: * lib/ * **prepr.js** * src/ * … * **.env** * astro.config.mjs * package.json ### Fetching data [Section titled Fetching data](#fetching-data) You will fetch your data from Prepr by writing queries to interact with its GraphQL API. #### Create a GraphQL query to retrieve your blog articles: [Section titled Create a GraphQL query to retrieve your blog articles:](#create-a-graphql-query-to-retrieve-your-blog-articles) 1. Create a new folder `src/queries/` and add a file named `get-articles.js`. 2. Add the following query to this file to retrieve all articles: src/queries/get-articles.js ```js const GetArticles = ` query { Articles { items { _id _slug title } } } ` export default GetArticles ``` 3. To display a linked list of your blog posts on a page, import and execute your query, including the necessary Prepr endpoint. You will then have access to all your posts titles and their slugs to render to the page. (In the next step, you will [create individual pages for your blog posts](#creating-individual-blog-post-pages).) src/pages/index.astro ```astro --- import Layout from '../layouts/Layout.astro'; import { Prepr } from '../lib/prepr.js'; import GetArticles from '../queries/get-articles.js'; const response = await Prepr(GetArticles) const { data } = await response.json() const articles = data.Articles ---

My blog site

{ articles.items.map((post) => (

{post.title}

``` Your root directory should include these new files: * lib/ * prepr.js * **queries** / * **get-articles.js** * src/ * … * .env * astro.config.mjs * package.json #### Creating individual blog post pages [Section titled Creating individual blog post pages](#creating-individual-blog-post-pages) To create a page for each blog post, you will execute a new GraphQL query on a [dynamic routing](/en/guides/routing/#server-ssr-mode) `.astro` page. This query will fetch a specific article by its slug and a new page will be created for each individual blog post. 1. Create a file called `get-article-by-slug.js` in the `queries` folder and add the following to query a specific article by its slug and return data such as the article `title` and `content`: src/lib/queries/get-article-by-slug.js ```js const GetArticleBySlug = ` query ($slug: String) { Article (slug: $slug) { _id title content { __typename ... on Text { body text } ... on Assets { items { url } } } } }` export default GetArticleBySlug ``` Tip You can create and [test GraphQL queries](https://docs.prepr.io/reference/graphql/v1/test-queries) using the [Apollo explorer](https://studio.apollographql.com/sandbox/explorer) in Prepr. Open the API Explorer from the *Article* content item page in Prepr. The Article content is stored in a *Dynamic content field*. Check out the GraphQL docs for more details on [how to fetch the data within this field](https://docs.prepr.io/reference/graphql/v1/schema-field-types-dynamic-content-field). 2. Inside the `src/pages` folder, create a file called `[…slug].astro`. Add the following code to import and execute the query from the previous step and display the retrieved article: src/pages/\[...slug].astro ```astro --- import Layout from '../layouts/Layout.astro'; import {Prepr} from '../lib/prepr.js'; import GetArticleBySlug from '../queries/get-article-by-slug.js'; const { slug } = Astro.params; const response = await Prepr(GetArticleBySlug, {slug}) const { data } = await response.json() const article = data.Article ---

{article.title}

{ article.content.map((content) => (

{ content.__typename === "Assets" &&

} { content.__typename === 'Text' &&

}

)) }

``` Your root directory should now include these new files: * lib/ * prepr.js * queries/ * get-articles.js * **get-article-by-slug.js** * src/ * pages/ * index.astro * **\[…slug].astro** * .env * astro.config.mjs * package.json Now, when you click an article link from the main list of blog posts, you will be taken to a page with its individual content. ### Publishing your site [Section titled Publishing your site](#publishing-your-site) To deploy your Prepr blog, visit our [deployment guides](/en/guides/deploy/) and follow the instructions for your preferred hosting provider. ## Official Resources [Section titled Official Resources](#official-resources) * Follow the [Prepr CMS Astro quickstart](https://github.com/preprio/astro-quick-start) guide to make a simple blog with Astro and Prepr CMS. * Check out the [Connecting Prepr CMS to Astro](https://docs.prepr.io/connecting-front-end-apps/astro) for an overview of Astro and Prepr CMS resources. # Prismic & Astro > Add content to your Astro project using Prismic as a CMS [Prismic](https://prismic.io/) is a headless content management system. ## Community Resources [Section titled Community Resources](#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 > Add content to your Astro project using Sanity as a CMS [Sanity](http://sanity.io) is a headless content management system that focuses on [structured content](https://www.sanity.io/structured-content-platform). ## Official Resources [Section titled Official Resources](#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) ## Themes [Section titled Themes](#themes) * [![](/_astro/astro-chef-project.CkjCJgM-_ZI34Cs.webp) The Balanced Chef](https://astro.build/themes/details/the-balanced-chef/) # Sitecore Experience Manager & Astro > Add content to your project using Sitecore as your CMS. [Sitecore Experience Manager (XM)](https://www.sitecore.com/products/experience-manager) is an enterprise-level content management system built on ASP.NET. ## Getting started [Section titled Getting started](#getting-started) 1. [Create a Sitecore Headless website](https://doc.sitecore.com/xp/en/developers/sxa/103/sitecore-experience-accelerator/create-a-headless-tenant-and-site.html) following Sitcore’s official documentation. 2. Run the following project initialization command in your terminal: ```shell npx @astro-sitecore-jss/create-astro-sitecore-jss@latest ``` 3. Follow the instructions in the terminal to create your project. ## Community Resources [Section titled Community Resources](#community-resources) * [Sitecore JavaScript Software Development Kit for Astro](https://github.com/exdst/jss-astro-public) on GitHub * [Introduction to Sitecore with Astro](https://exdst.com/posts/20231002-sitecore-astro) * [Starting Your First Sitecore Astro Project](https://exdst.com/posts/20240103-first-sitecore-astro-project) # Spinal & Astro > Add content to your project using Spinal as your CMS. [Spinal](https://spinalcms.com/cms-for-astro/) is a commercial, SaaS-focused, Git-based CMS. ## Getting started [Section titled Getting started](#getting-started) 1. [Create a Spinal account](https://spinalcms.com/signup/). 2. Connect your GitHub account to Spinal. 3. Select your Astro repository when prompted. All Markdown content from the selected folder will be imported into your Spinal account and is ready to be edited. ## Official Resources [Section titled Official Resources](#official-resources) * [Documentation theme built for Astro with Tailwind CSS](https://spinalcms.com/resources/astro-documentation-theme-with-tailwind-css/) ## Production Sites [Section titled Production Sites](#production-sites) The following sites use Astro + Spinal in production: * [spinalcms.com](https://spinalcms.com/) (all blog articles, documentation, changelog, feature pages, etc.) # Headless Statamic & Astro > Add content to your Astro project using Statamic as a CMS [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 [Section titled Integrating with Astro](#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 [Section titled Prerequisites](#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 [Section titled Fetching Data](#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 [Section titled REST API](#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): "src/pages/index.astro ```astro --- const res = await fetch("https://[YOUR-SITE]/api/collections/posts/entries?sort=-date") const posts = await res.json() ---

Astro + Statamic 🚀

{ posts.map((post) => (

)) } ``` #### GraphQL [Section titled GraphQL](#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): "src/pages/index.astro ```astro --- 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; ---

Astro + Statamic 🚀

{ entries.data.map((post) => (

)) } ``` ### Publishing your site [Section titled Publishing your site](#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 [Section titled Community Resources](#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/) ## Themes [Section titled Themes](#themes) * [![](/_astro/creek.CgpBUanV_Z1gsxon.webp) Creek](https://astro.build/themes/details/creek/) # Storyblok & Astro > Add content to your Astro project using Storyblok as a CMS [Storyblok](https://www.storyblok.com/) is a component-based headless CMS that allows you to manage your content using reusable components called Bloks. ## Integrating with Astro [Section titled Integrating with Astro](#integrating-with-astro) In this section, you will use the [Storyblok integration](https://github.com/storyblok/storyblok-astro) to connect Storyblok to Astro. ### Prerequisites [Section titled Prerequisites](#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 Storyblok account and space - If you don’t have an account yet, [sign up for free](https://app.storyblok.com/#/signup) and create a new space. 3. Storyblok Preview token - This token will be used to fetch drafts and published versions of your content. You can find and generate your API token in the Access Tokens tab of your Storyblok space settings. ### Setting up credentials [Section titled Setting up credentials](#setting-up-credentials) To add your Storyblok credentials to Astro, create a `.env` file in the root of your project with the following variable: .env ```ini STORYBLOK_TOKEN=YOUR_PREVIEW_TOKEN ``` Now, you should be able to use these environment variables in your project. Your root directory should now include this new file: * src/ * … * .env * astro.config.mjs * package.json ### Installing dependencies [Section titled Installing dependencies](#installing-dependencies) To connect Astro with your Storyblok space, install the official [Storyblok integration](https://github.com/storyblok/storyblok-astro) using the command below for your preferred package manager: * npm ```shell npm install @storyblok/astro vite ``` * pnpm ```shell pnpm add @storyblok/astro vite ``` * Yarn ```shell yarn add @storyblok/astro vite ``` ### Configuring Storyblok [Section titled Configuring Storyblok](#configuring-storyblok) Modify your Astro config file to include the Storyblok integration: astro.config.mjs ```js import { defineConfig } from 'astro/config'; import storyblok from '@storyblok/astro'; import { loadEnv } from 'vite'; const env = loadEnv("", process.cwd(), 'STORYBLOK'); export default defineConfig({ integrations: [ storyblok({ accessToken: env.STORYBLOK_TOKEN, components: { // Add your components here }, apiOptions: { // Choose your Storyblok space region region: 'us', // optional, or 'eu' (default) }, }) ], }); ``` The Storyblok integration requires an object with the following properties: 1. `accessToken` - This references the Storyblok API token that you added in the previous step. Tip Since the Astro config file does not normally support environment variables, use the `loadEnv` function from Vite to load them. 2. `components` - An object that maps Storyblok component names to paths to your local components. This is required to render your Storyblok Bloks in Astro. Note The component paths are relative to the `src` directory. For example, if your component is located at `src/storyblok/MyComponent.astro`, the path would be `storyblok/MyComponent` (without the `.astro` extension). 3. `apiOptions` - An object containing [Storyblok API options](https://github.com/storyblok/storyblok-astro#options). Caution By default, the region is `eu`. If your Storyblok space was created in the US region, you will need to set the region to `us`. ### Connecting Bloks to Astro components [Section titled Connecting Bloks to Astro components](#connecting-bloks-to-astro-components) To connect your Bloks to Astro, create a new folder named `storyblok` in the `src` directory. This folder will contain all the Astro components that will match your Bloks in your Storyblok Blok library. In this example, you have a `blogPost` Blok content type in your Storyblok library with the following fields: * `title` - A text field * `description` - A text field * `content` - A rich text field Our goal is to create the equivalent Astro component that will use these fields to render its content. To do this, create a new file named `BlogPost.astro` inside `src/storyblok` with the following content: src/storyblok/BlogPost.astro ```astro --- import { storyblokEditable, renderRichText } from '@storyblok/astro' const { blok } = Astro.props const content = renderRichText(blok.content) ---

{blok.title}

{blok.description}

``` The `blok` property contains the data that you will receive from Storyblok. It also contains the fields that were defined in the `blogPost` content type Blok in Storyblok. To render our content, the integration provides utility functions such as: * `storyblokEditable` - it adds the necessary attributes to the elements so that you can edit them in Storyblok. * `renderRichText` - it transforms the rich text field into HTML. Your root directory should include this new file: * src/ * storyblok/ * BlogPost.astro * .env * astro.config.mjs * package.json Finally, to connect the `blogPost` Blok to the `BlogPost` component, add a new property to your components object in your Astro config file. * The key is the name of the Blok in Storyblok. In this case, it is `blogPost`. * The value is the path to the component. In this case, it is `storyblok/BlogPost`. Caution The `key` should exactly match your Blok name in Storyblok to be referenced correctly. If these don’t match, or you’re trying to reference a component that doesn’t exist in Storyblok, you’ll get an error. astro.config.mjs ```js import { defineConfig } from 'astro/config'; import storyblok from '@storyblok/astro'; import { loadEnv } from 'vite'; const env = loadEnv("", process.cwd(), 'STORYBLOK'); export default defineConfig({ integrations: [ storyblok({ accessToken: env.STORYBLOK_TOKEN, components: { blogPost: 'storyblok/BlogPost', }, apiOptions: { region: 'us', }, }) ], }); ``` ### Fetching data [Section titled Fetching data](#fetching-data) To test the setup, in Storyblok create a new story with the `blogPost` content type named `test-post`. In Astro, create a new page in the `src/pages/` directory named `test-post.astro` with the following content: src/pages/test-post.astro ```astro --- import { useStoryblokApi } from '@storyblok/astro' import StoryblokComponent from '@storyblok/astro/StoryblokComponent.astro' const storyblokApi = useStoryblokApi() const { data } = await storyblokApi.get("cdn/stories/test-post", { version: import.meta.env.DEV ? "draft" : "published", }); const content = data.story.content; --- ``` To query your data, use the `useStoryblokApi` hook. This will initialize a new client instance using your integration configuration. To render your content, pass the `content` property of the Story to the `StoryblokComponent` as a `blok` prop. This component will render the Bloks that are defined inside the `content` property. In this case, it will render the `BlogPost` component. ## Making a blog with Astro and Storyblok [Section titled Making a blog with Astro and Storyblok](#making-a-blog-with-astro-and-storyblok) With the integration set up, you can now create a blog with Astro and Storyblok. ### Prerequisites [Section titled Prerequisites](#prerequisites-1) 1. A Storyblok space - For this tutorial, we recommend using a new space. If you already have a space with Bloks, feel free to use them, but you will need to modify the code to match the Blok names and content types. 2. An Astro project integrated with Storyblok - See [integrating with Astro](#integrating-with-astro) for instructions on how to set up the integration. ### Creating a blok library [Section titled Creating a blok library](#creating-a-blok-library) To create Bloks, go to the Storyblok app and click on the Block Library tab. Click on the `+ New blok` button and create the following Bloks: 1. `blogPost` - A content type Blok with the following fields: * `title` - A text field * `description` - A text field * `content` - A rich text field 2. `blogPostList` - An empty nestable Blok 3. `page` - A content type Blok with the following fields: * `body` - A nestable Blok ### Creating content [Section titled Creating content](#creating-content) To add new content, go to the content section by clicking on the Content tab. Using the Blok library that you created in the previous step, create the following stories: 1. `home` - A content type story with the `page` Blok. Inside the `body` field, add a `blogPostList` Blok. 2. `blog/no-javascript` - A story with the `blogPost` content type inside the blog folder. ```yaml title: No JavaScript description: A sample blog post content: Hi there! This blog post doesn't use JavaScript. ``` 3. `blog/astro-is-amazing` - A story with the `blogPost` content type inside the blog folder. ```yaml title: Astro is amazing description: We love Astro content: Hi there! This blog post was build with Astro. ``` Now that you have your content ready, return to your Astro project and start building your blog. ### Connecting Bloks to components [Section titled Connecting Bloks to components](#connecting-bloks-to-components) To connect your newly created Bloks to Astro components, create a new folder named `storyblok` in your `src` directory and add the following files: `Page.astro` is a nestable Block content type component that will recursively render all the Bloks inside the `body` property of the `page` Blok. It also adds the `storyblokEditable` attributes to the parent element which will allow us to edit the page in Storyblok. src/storyblok/Page.astro ```astro --- import { storyblokEditable } from '@storyblok/astro' import StoryblokComponent from "@storyblok/astro/StoryblokComponent.astro"; const { blok } = Astro.props ---
{ blok.body?.map((blok) => { return }) }
``` `BlogPost.astro` will render the `title`, `description` and `content` properties of the `blogPost` Blok. To transform the `content` property from a rich text field to HTML, you can use the `renderRichText` helper function. src/storyblok/BlogPost.astro ```astro --- import { storyblokEditable, renderRichText } from '@storyblok/astro' const { blok } = Astro.props const content = renderRichText(blok.content) ---

{blok.title}

{blok.description}

``` `BlogPostList.astro` is a nestable Blok content type component that will render a list of blog post previews. It uses the `useStoryblokApi` hook to fetch all the stories with the content type of `blogPost`. It uses the `version` query parameter to fetch the draft versions of the stories when in development mode and the published versions when building for production. `Astro.props` is used to set up the editor in Storyblok. Additional props can also be passed to your component here, if needed. src/storyblok/BlogPostList.astro ```astro --- import { storyblokEditable } from '@storyblok/astro' import { useStoryblokApi } from '@storyblok/astro' const storyblokApi = useStoryblokApi(); const { data } = await storyblokApi.get('cdn/stories', { version: import.meta.env.DEV ? "draft" : "published", content_type: 'blogPost', }) const posts = data.stories.map(story => { return { title: story.content.title, date: new Date(story.published_at).toLocaleDateString("en-US", {dateStyle: "full"}), description: story.content.description, slug: story.full_slug, } }) const { blok } = Astro.props ---
{posts.map(post => (
{post.date} {post.title}
{post.description}

))}
``` Finally, add your components to the `components` property of the `storyblok` config object in `astro.config.mjs`. The key is the name of the Blok in Storyblok, and the value is the path to the component relative to `src`. astro.config.mjs ```js import { defineConfig } from 'astro/config'; import storyblok from '@storyblok/astro'; import { loadEnv } from 'vite'; const env = loadEnv("", process.cwd(), 'STORYBLOK'); export default defineConfig({ integrations: [ storyblok({ accessToken: env.STORYBLOK_TOKEN, components: { blogPost: 'storyblok/BlogPost', blogPostList: 'storyblok/BlogPostList', page: 'storyblok/Page', }, apiOptions: { region: 'us', }, }) ], }); ``` ### Generating pages [Section titled Generating pages](#generating-pages) To create a route for a specific `page`, you can fetch its content directly from the Storyblok API and pass it to the `StoryblokComponent` component. Remember to make sure you have added the `Page` component to your astro.config.mjs. Create an `index.astro` file in `src/pages/` to render the `home` page: src/pages/index.astro ```astro --- import { useStoryblokApi } from '@storyblok/astro' import StoryblokComponent from '@storyblok/astro/StoryblokComponent.astro' import BaseLayout from '../layouts/BaseLayout.astro' const storyblokApi = useStoryblokApi(); const { data } = await storyblokApi.get('cdn/stories/home', { version: import.meta.env.DEV ? "draft" : "published", }); const content = data.story.content; --- Storyblok & Astro ``` To generate pages for all of your blog posts, create a `.astro` page that will create dynamic routes. This approach varies depending on whether your routes are prerendered (the default in Astro) or [rendered on demand](/en/guides/on-demand-rendering/). #### Static site generation [Section titled Static site generation](#static-site-generation) If you are using Astro’s default static site generation, you will use [dynamic routes](/en/guides/routing/#dynamic-routes) and the `getStaticPaths` function to generate your project pages. Create a new directory `src/pages/blog/` and add a new file called `[...slug].astro` with the following code: src/pages/blog/\[...slug].astro ```astro --- import { useStoryblokApi } from '@storyblok/astro' import StoryblokComponent from '@storyblok/astro/StoryblokComponent.astro' export async function getStaticPaths() { const sbApi = useStoryblokApi(); const { data } = await sbApi.get("cdn/stories", { content_type: "blogPost", version: import.meta.env.DEV ? "draft" : "published", }); const stories = Object.values(data.stories); return stories.map((story) => { return { params: { slug: story.slug }, }; }); } const sbApi = useStoryblokApi(); const { slug } = Astro.params; const { data } = await sbApi.get(`cdn/stories/blog/${slug}`, { version: import.meta.env.DEV ? "draft" : "published", }); const story = data.story; --- Storyblok & Astro ``` This file will generate a page for each story, with the slug and content fetched from the Storyblok API. Note When adding folders inside of Storyblok, include them in the slug when interacting with the Storyblok API. For example, in the GET request above we can use cdn/stories/blog, with a blog folder inside rather than using them at the root. #### On-demand rendering [Section titled On-demand rendering](#on-demand-rendering) If you are [rendering your routes on demand with an adapter](/en/guides/on-demand-rendering/), you will use dynamic routes to fetch the page data from Storyblok. Create a new directory `src/pages/blog/` and add a new file called `[...slug].astro` with the following code: src/pages/blog/\[...slug].astro ```astro --- import { useStoryblokApi } from '@storyblok/astro' import StoryblokComponent from '@storyblok/astro/StoryblokComponent.astro' const storyblokApi = useStoryblokApi() const slug = Astro.params.slug; let content; try { const { data } = await storyblokApi.get(`cdn/stories/blog/${slug}`, { version: import.meta.env.DEV ? "draft" : "published", }); content = data.story.content } catch (error) { return Astro.redirect('/404') } --- Storyblok & Astro ``` This file will fetch and render the page data from Storyblok that matches the dynamic `slug` parameter. Since you are using a redirect to `/404`, create a 404 page in `src/pages`: src/pages/404.astro ```astro Not found
Sorry, this page does not exist.
``` If the story is not found, the request will be redirected to the 404 page. ### Publishing your site [Section titled Publishing your site](#publishing-your-site) To deploy your website, visit our [deployment guides](/en/guides/deploy/) and follow the instructions for your preferred hosting provider. #### Rebuild on Storyblok changes [Section titled Rebuild on Storyblok changes](#rebuild-on-storyblok-changes) If your project is using Astro’s default static mode, you will need to set up a webhook to trigger a new build when your content changes. If you are using Netlify or Vercel as your hosting provider, you can use its webhook feature to trigger a new build from Storyblok events. ##### Netlify [Section titled Netlify](#netlify) To set up a webhook in Netlify: 1. Go to your site dashboard and click on Build & deploy. 2. Under the Continuous Deployment tab, find the Build hooks section and click on Add build hook. 3. Provide a name for your webhook and select the branch you want to trigger the build on. Click on Save and copy the generated URL. ##### Vercel [Section titled Vercel](#vercel) To set up a webhook in Vercel: 1. Go to your project dashboard and click on Settings. 2. Under the Git tab, find the Deploy Hooks section. 3. Provide a name for your webhook and the branch you want to trigger the build on. Click Add and copy the generated URL. ##### Adding a webhook to Storyblok [Section titled Adding a webhook to Storyblok](#adding-a-webhook-to-storyblok) In your Storyblok space Settings, click on the Webhooks tab. Paste the webhook URL you copied in the Story published & unpublished field and hit `Save` to create a webhook. Now, whenever you publish a new story, a new build will be triggered and your blog will be updated. ## Official Resources [Section titled Official Resources](#official-resources) * Storyblok provides an [Astro Integration](https://www.storyblok.com/mp/announcing-storyblok-astro) to add Storyblok to your project. ## Community Resources [Section titled Community Resources](#community-resources) * [Getting the Visual Editor to work for Storyblok + Astro](https://dev.to/sandrarodgers/getting-the-visual-editor-to-work-for-storyblok-astro-2gja) by Sandra Rodgers * [Astro + Storyblok: SSR preview for instant visual editing](https://dev.to/jgierer12/astro-storyblok-ssr-preview-for-instant-visual-editing-3g9m) by Jonas Gierer * [Astro-Storyblok Previews Site with Netlify’s Branch Deploys Feature](https://dev.to/sandrarodgers/astro-storyblok-previews-site-with-netlifys-branch-deploys-feature-44dh) by Sandra Rodgers # Strapi & Astro > Add content to your Astro project using Strapi Headless CMS [Strapi](https://strapi.io/) is an open-source, customizable, headless CMS. ## Integrating with Astro [Section titled Integrating with Astro](#integrating-with-astro) This guide will build a wrapper function to connect Strapi with Astro. ### Prerequisites [Section titled Prerequisites](#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 Strapi CMS server - You can [set up a Strapi server on a local environment](https://docs.strapi.io/dev-docs/quick-start). ### Adding the Strapi URL in `.env` [Section titled Adding the Strapi URL in .env](#adding-the-strapi-url-in-env) To add your Strapi URL to Astro, create a `.env` file in the root of your project (if one does not already exist) and add the following variable: .env ```ini STRAPI_URL="http://127.0.0.1:1337" # or use your IP address ``` Restart the dev server to use this environment variable in your Astro project. If you would like to have IntelliSense for your environment variable, you can create a `env.d.ts` file in the `src/` directory and configure `ImportMetaEnv` like this: src/env.d.ts ```ts interface ImportMetaEnv { readonly STRAPI_URL: string; } ``` Your root directory should now include the new file(s): * src/ * env.d.ts * .env * astro.config.mjs * package.json ### Creating the API wrapper [Section titled Creating the API wrapper](#creating-the-api-wrapper) Create a new file at `src/lib/strapi.ts` and add the following wrapper function to interact with the Strapi API: src/lib/strapi.ts ```ts interface Props { endpoint: string; query?: Record; wrappedByKey?: string; wrappedByList?: boolean; } /** * Fetches data from the Strapi API * @param endpoint - The endpoint to fetch from * @param query - The query parameters to add to the url * @param wrappedByKey - The key to unwrap the response from * @param wrappedByList - If the response is a list, unwrap it * @returns / export default async function fetchApi({ endpoint, query, wrappedByKey, wrappedByList, }: Props): Promise { if (endpoint.startsWith('/')) { endpoint = endpoint.slice(1); } const url = new URL(`${import.meta.env.STRAPI_URL}/api/${endpoint}`); if (query) { Object.entries(query).forEach(([key, value]) => { url.searchParams.append(key, value); }); } const res = await fetch(url.toString()); let data = await res.json(); if (wrappedByKey) { data = data[wrappedByKey]; } if (wrappedByList) { data = data[0]; } return data as T; } ``` This function requires an object with the following properties: 1. `endpoint` - The endpoint you are fetching. 2. `query` - The query parameters to add to the end of URL 3. `wrappedByKey` - The `data` key in the object that wraps your `Response`. 4. `wrappedByList` - A parameter to “unwrap” the list returned by Strapi, and return only the first item. ### Optional: Creating the Article interface [Section titled Optional: Creating the Article interface](#optional-creating-the-article-interface) If you are using TypeScript, create the following Article interface to correspond to the Strapi content types at `src/interfaces/article.ts`: src/interfaces/article.ts ```ts export default interface Article { id: number; attributes: { title: string; description: string; content: string; slug: string; createdAt: string; updatedAt: string; publishedAt: string; }; } ``` Note You can modify this interface, or create multiple interfaces, to correspond to your own project data. src/ * interfaces/ * article.ts * lib/ * strapi.ts * env.d.ts * .env * astro.config.mjs * package.json ### Displaying a list of articles [Section titled Displaying a list of articles](#displaying-a-list-of-articles) 1. Update your home page `src/pages/index.astro` to display a list of blog posts, each with a description and a link to its own page. 2. Import the wrapper function and the interface. Add the following API call to fetch your articles and return a list: src/pages/index.astro ```astro --- import fetchApi from '../lib/strapi'; import type Article from '../interfaces/article'; const articles = await fetchApi({ endpoint: 'articles', // the content type to fetch wrappedByKey: 'data', // the key to unwrap the response }); --- ``` The API call requests data from `http://localhost:1337/api/articles` and returns `articles`: an array of json objects representing your data: ```json [ { id: 1, attributes: { title: "What's inside a Black Hole", description: "Maybe the answer is in this article, or not...", content: "Well, we don't know yet...", slug: "what-s-inside-a-black-hole", createdAt: "2023-05-28T13:19:46.421Z", updatedAt: "2023-05-28T13:19:46.421Z", publishedAt: "2023-05-28T13:19:45.826Z" } }, // ... ] ``` 3. Using data from the `articles` array returned by the API, display your Strapi blog posts in a list. These posts will link to their own individual pages, which you will create in the next step. src/pages/index.astro ```astro --- import fetchApi from '../lib/strapi'; import type Article from '../interfaces/article'; const articles = await fetchApi({ endpoint: 'articles?populate=image', wrappedByKey: 'data', }); --- Strapi & Astro

{ articles.map((article) => (
{article.attributes.title}
)) }

``` ### Generating article pages [Section titled Generating article pages](#generating-article-pages) Create the file `src/pages/blog/[slug].astro` to [dynamically generate a page](/en/guides/routing/#dynamic-routes) for each article. * src/ * interfaces/ * article.ts * lib/ * strapi.ts * pages/ * index.astro * blog/ * \[slug].astro * env.d.ts * .env * astro.config.mjs * package.json #### Static site generation [Section titled Static site generation](#static-site-generation) In Astro’s default static mode (SSG), use [`getStaticPaths()`](/en/reference/routing-reference/#getstaticpaths) to fetch your list of articles from Strapi. "src/pages/blog/\[slug].astro ```astro --- import fetchApi from '../../lib/strapi'; import type Article from '../../interfaces/article'; export async function getStaticPaths() { const articles = await fetchApi({ endpoint: 'articles', wrappedByKey: 'data', }); return articles.map((article) => ({ params: { slug: article.attributes.slug }, props: article, })); } type Props = Article; const article = Astro.props; --- ``` Create the template for each page using the properties of each post object. "src/pages/blog/\[slug].astro ```astro --- import fetchApi from '../../lib/strapi'; import type Article from '../../interfaces/article'; export async function getStaticPaths() { const articles = await fetchApi({ endpoint: 'articles', wrappedByKey: 'data', }); return articles.map((article) => ({ params: { slug: article.attributes.slug }, props: article, })); } type Props = Article; const article = Astro.props; --- {article.attributes.title}

{article.attributes.title}

{article.attributes.content}
{article.attributes.content}
``` Tip Make sure to choose the right rendering for your content. For markdown check out our [markdown guide](/en/guides/markdown-content/). If you are rendering html refer to [this guide](/en/reference/directives-reference/#sethtml) for safety. #### On-demand rendering [Section titled On-demand rendering](#on-demand-rendering) If you’ve [opted into on-demand rendering with an adapter](/en/guides/on-demand-rendering/), [generate your dynamic routes](/en/guides/routing/#server-ssr-mode) using the following code: Create the `src/pages/blog/[slug].astro` file: src/pages/blog/\[slug].astro ```astro --- import fetchApi from '../../../lib/strapi'; import type Article from '../../../interfaces/article'; const { slug } = Astro.params; let article: Article; try { article = await fetchApi
({ endpoint: 'articles', wrappedByKey: 'data', wrappedByList: true, query: { 'filters[slug][$eq]': slug || '', }, }); } catch (error) { return Astro.redirect('/404'); } --- {article.attributes.title}

{article.attributes.title}

{article.attributes.content}
{article.attributes.content}
``` This file will fetch and render the page data from Strapi that matches the dynamic `slug` parameter. Since you are using a redirect to `/404`, create a 404 page in `src/pages`: src/pages/404.astro ```astro Not found
Sorry, this page does not exist.
``` If the article is not found, the user will be redirected to this 404 page and be greeted by a lovely cat. ### Publishing your site [Section titled Publishing your site](#publishing-your-site) To deploy your website, visit our [deployment guides](/en/guides/deploy/) and follow the instructions for your preferred hosting provider. #### Rebuild on changes [Section titled Rebuild on changes](#rebuild-on-changes) If your project is using Astro’s default static mode, you will need to set up a webhook to trigger a new build when your content changes. If you are using Netlify or Vercel as your hosting provider, you can use its webhook feature to trigger a new build from Strapi. ##### Netlify [Section titled Netlify](#netlify) To set up a webhook in Netlify: 1. Go to your site dashboard and click on Build & deploy. 2. Under the Continuous Deployment tab, find the Build hooks section and click on Add build hook. 3. Provide a name for your webhook and select the branch you want to trigger the build on. Click on Save and copy the generated URL. ##### Vercel [Section titled Vercel](#vercel) To set up a webhook in Vercel: 1. Go to your project dashboard and click on Settings. 2. Under the Git tab, find the Deploy Hooks section. 3. Provide a name for your webhook and the branch you want to trigger the build on. Click Add and copy the generated URL. ##### Adding a webhook to Strapi [Section titled Adding a webhook to Strapi](#adding-a-webhook-to-strapi) Follow [the Strapi webhooks guide](https://strapi.io/blog/webhooks) to create a webhook in your Strapi admin panel. ## Official Resources [Section titled Official Resources](#official-resources) * [Strapi Blog Guide For React](https://strapi.io/blog/build-a-blog-with-next-react-js-strapi) by Strapi # Tina CMS & Astro > Add content to your Astro project using Tina as a CMS [Tina CMS](https://tina.io/) is a Git-backed headless content management system. ## Integrating with Astro [Section titled Integrating with Astro](#integrating-with-astro) To get started, you’ll need an existing Astro project. 1. Run the following command to install Tina into your Astro project. * npm ```shell npx @tinacms/cli@latest init ``` * pnpm ```shell pnpm dlx @tinacms/cli@latest init ``` * Yarn ```shell yarn dlx @tinacms/cli@latest init ``` - When prompted for a Cloud ID, press `Enter` to skip. You’ll generate one later if you want to use Tina Cloud. - When prompted “What framework are you using”, choose Other. - When asked where public assets are stored, press `Enter`. After this has finished, you should now have a `.tina` folder in the root of your project and a generated `hello-world.md` file at `content/posts`. 2. Change the `dev` script in `package.json`: * npm package.json ```json { "scripts": { "dev": "astro dev", "dev": "tinacms dev -c \"astro dev\"" } } ``` * pnpm package.json ```json { "scripts": { "dev": "astro dev", "dev": "tinacms dev -c \"astro dev\"" } } ``` * Yarn package.json ```json { "scripts": { "dev": "astro dev", "dev": "tinacms dev -c \"astro dev\"" } } ``` 3. TinaCMS is now set up in local mode. Test this by running the `dev` script, then navigating to `/admin/index.html#/collections/post`. Editing the “Hello, World!” post will update the `content/posts/hello-world.md` file in your project directory. 4. Set up your Tina collections by editing the `schema.collections` property in `.tina/config.ts`. For example, you can add a required “date posted” frontmatter property to our posts: .tina/config.ts ```js import { defineConfig } from "tinacms"; // Your hosting provider likely exposes this as an environment variable const branch = process.env.HEAD || process.env.VERCEL_GIT_COMMIT_REF || "main"; export default defineConfig({ branch, clientId: null, // Get this from tina.io token: null, // Get this from tina.io build: { outputFolder: "admin", publicFolder: "public", }, media: { tina: { mediaRoot: "images", publicFolder: "public", }, }, schema: { collections: [ { name: "posts", label: "Posts", path: "src/content/posts", format: 'mdx', fields: [ { type: "string", name: "title", label: "Title", isTitle: true, required: true, }, { type: "datetime", name: "posted", label: "Date Posted", required: true, }, { type: "rich-text", name: "body", label: "Body", isBody: true, }, ], }, ], }, }); ``` Learn more about Tina collections [in the Tina docs](https://tina.io/docs/reference/collections/). 5. In production, TinaCMS can commit changes directly to your GitHub repository. To set up TinaCMS for production, you can choose to use [Tina Cloud](https://tina.io/docs/tina-cloud/) or self-host the [Tina Data Layer](https://tina.io/docs/self-hosted/overview/). You can [read more about registering for Tina Cloud](https://app.tina.io/register) in the Tina Docs. ## Official Resources [Section titled Official Resources](#official-resources) * [TinaCMS Astro integration guide](https://tina.io/docs/frameworks/astro/). ## Community Resources [Section titled Community Resources](#community-resources) * [Astro Tina Starter with visual editing](https://github.com/dawaltconley/tina-astro) by Jeff See + Dylan Awalt-Conley * [Astro Tina Starter with basic editing](https://github.com/tombennet/astro-tina-starter/tree/main) by Tom Bennet * [Using Astro’s Image Optimization with Tina](https://joschua.io/posts/2023/08/16/how-to-use-astro-assets-with-tina-cms/) ## Themes [Section titled Themes](#themes) * [![](/_astro/resume01.CAukhX1f_183P41.webp) Resume01](https://astro.build/themes/details/resume01/) # Umbraco & Astro > Add content to your Astro project using Umbraco as a CMS [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 [Section titled Integrating with Astro](#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 [Section titled Prerequisites](#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 [Section titled Setting up the Content Delivery API](#setting-up-the-content-delivery-api) To enable the Content Delivery API, update your Umbraco project’s `appsettings.json` file: appsettings.json ```json { "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 [Section titled Fetching Data](#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. src/pages/index.astro ```astro --- const res = await fetch('http://localhost/umbraco/delivery/api/v2/content?filter=contentType:article'); const articles = await res.json(); ---
Astro + Umbraco 🚀
{ articles.items.map((article) => (
{article.name}

{article.properties.articleDate}

)) } ``` Read more about [data fetching in Astro](/en/guides/data-fetching/). ## Building a blog with Umbraco and Astro [Section titled Building a blog with Umbraco and Astro](#building-a-blog-with-umbraco-and-astro) ### Prerequisites [Section titled Prerequisites](#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. * 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 [Section titled Creating blog posts in Umbraco](#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 [Section titled Displaying a list of blog posts in Astro](#displaying-a-list-of-blog-posts-in-astro) Create a `src/layouts/` folder, then add a new file `Layout.astro` with the following code: src/layouts/Layout.astro ```astro --- --- My Blog with Astro and Umbraco

``` 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: src/pages/index.astro ```astro --- import Layout from '../layouts/Layout.astro'; const res = await fetch('http://localhost/umbraco/delivery/api/v2/content?filter=contentType:article'); const articles = await res.json(); ---
Blog Articles
{ articles.items.map((article: any) => (

{article.properties.title}

{article.properties.articleDate}
Read more
)) } ``` ### Generating individual blog posts [Section titled Generating individual blog posts](#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: \[...slug].astro ```astro --- import Layout from '../layouts/Layout.astro'; export async function getStaticPaths() { let data = await fetch("http://localhost/umbraco/delivery/api/v2/content?filter=contentType:article"); let articles = await data.json(); return articles.items.map((article: any) => ({ params: { slug: article.route.path }, props: { article: article }, })); } const { article } = Astro.props; ---
{article.properties.title}

{article.properties.articleDate}

``` 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 [Section titled Publishing your site](#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 [Section titled Local dev, HTTPS and self-signed SSL certificates](#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: .env.development ```sh NODE_TLS_REJECT_UNAUTHORIZED=0 ``` astro.config.mjs ```astro import { defineConfig } from 'astro/config'; import { loadEnv } from "vite"; 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 export default defineConfig({}); ``` 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 [Section titled Official Documentation](#official-documentation) * [Content Delivery API - Umbraco Documentation](https://docs.umbraco.com/umbraco-cms/reference/content-delivery-api) ## Community Resources [Section titled Community Resources](#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) # Headless WordPress & Astro > Add content to your Astro project using WordPress as a CMS [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 [Section titled Integrating with Astro](#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 [Section titled Prerequisites](#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 [Section titled Setting up Credentials](#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 [Section titled Fetching Data](#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: src/pages/index.astro ```astro --- const res = await fetch("https://[YOUR-SITE]/wp-json/wp/v2/posts"); const posts = await res.json(); ---
Astro + WordPress 🚀
{ posts.map((post) => (

)) } ``` 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 [Section titled Building a blog with WordPress and Astro](#building-a-blog-with-wordpress-and-astro) This example fetches data from the public WordPress API of . 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 [Section titled Displaying a list of WordPress posts](#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.) /src/pages/index.astro ```astro --- import Layout from "../layouts/Layout.astro"; let res = await fetch("https://norian.studio/wp-json/wp/v2/dinos"); let posts = await res.json(); ---

List of Dinosaurs
{ posts.map((post) => (

)) }
``` ### Using the WordPress API to generate pages [Section titled Using the WordPress API to generate pages](#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. /src/pages/dinos/\[slug].astro ```astro --- import Layout from '../../layouts/Layout.astro'; 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. export async function getStaticPaths() { let data = await fetch("https://norian.studio/wp-json/wp/v2/dinos"); let posts = await data.json(); return posts.map((post) => ({ params: { slug: post.slug }, props: { post: post }, })); } ---

``` ### Returning embedded resources [Section titled Returning embedded resources](#returning-embedded-resources) The `_embed` query parameter instructs the server to return related (embedded) resources. src/pages/dinos/\[slug].astro ```astro --- 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.) /src/pages/dinos/\[slug].astro ```astro

``` ### Publishing your site [Section titled Publishing your site](#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 [Section titled Community Resources](#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. ## Production Sites [Section titled Production Sites](#production-sites) The following sites use Astro + WordPress in production: * [Dinos!](https://wc-dinos.netlify.app/) by Anindo Neel Dutta — [source code on GitHub](https://github.com/leen-neel/astro-wordpress) ## Themes [Section titled Themes](#themes) * [![](/_astro/astro-wordpress-starter.DWg2-sU7_ZlvAh5.webp) Astro WordPress Starter](https://astro.build/themes/details/astro-wordpress-starter/) # Content collections > Manage your content with type safety. Added in: `astro@2.0.0` Content collections are the best way to manage sets of content in any Astro project. Collections help to organize and query your documents, enable Intellisense and type checking in your editor, and provide automatic TypeScript type-safety for all of your content. Astro v5.0 introduced the Content Layer API for defining and querying content collections. This performant, scalable API provides built-in content loaders for your local collections. For remote content, you can use third-party and community-built loaders or create your own custom loader and pull in your data from any source. Note Projects may continue using the legacy Content Collections API introduced in Astro v2.0. However, we encourage you to [update any existing collections](/en/guides/upgrade-to/v5/#legacy-v20-content-collections-api) when you are able. ## What are Content Collections? [Section titled What are Content Collections?](#what-are-content-collections) You can define a collection from a set of data that is structurally similar. This can be a directory of blog posts, a JSON file of product items, or any data that represents multiple items of the same shape. Collections stored locally in your project or on your filesystem can have entries of Markdown, MDX, Markdoc, YAML, or JSON files: * src/ * … * newsletter/ the “newsletter” collection * week-1.md a collection entry * week-2.md a collection entry * week-3.md a collection entry * authors/ the “author” collection * authors.json a single file containing all collection entries With an appropriate collection loader, you can fetch remote data from any external source, such as a CMS, database, or headless payment system. ## TypeScript configuration for collections [Section titled TypeScript configuration for collections](#typescript-configuration-for-collections) Content collections rely on TypeScript to provide Zod validation, Intellisense and type checking in your editor. If you are not extending one of Astro’s `strict` or `strictest` TypeScript settings, you will need to ensure the following `compilerOptions` are set in your `tsconfig.json`: tsconfig.json ```json { // Included with "astro/tsconfigs/strict" or "astro/tsconfigs/strictest" "extends": "astro/tsconfigs/base", "compilerOptions": { "strictNullChecks": true, // add if using `base` template "allowJs": true // required, and included with all Astro templates } } ``` ## Defining Collections [Section titled Defining Collections](#defining-collections) Individual collections use `defineCollection()` to configure: * a `loader` for a data source (required) * a `schema` for type safety (optional, but highly recommended!) ### The collection config file [Section titled The collection config file](#the-collection-config-file) To define collections, you must create a `src/content.config.ts` file in your project (`.js` and `.mjs` extensions are also supported.) This is a special file that Astro will use to configure your content collections based on the following structure: src/content.config.ts ```ts // 1. Import utilities from `astro:content` import { defineCollection, z } from 'astro:content'; // 2. Import loader(s) import { glob, file } from 'astro/loaders'; // 3. Define your collection(s) const blog = defineCollection({ /* ... / }); const dogs = defineCollection({ / ... */ }); // 4. Export a single `collections` object to register your collection(s) export const collections = { blog, dogs }; ``` ### Defining the collection `loader` [Section titled Defining the collection loader](#defining-the-collection-loader) The Content Layer API allows you to fetch your content (whether stored locally in your project or remotely) and uses a `loader` property to retrieve your data. #### Built-in loaders [Section titled Built-in loaders](#built-in-loaders) Astro provides [two built-in loader functions](/en/reference/content-loader-reference/#built-in-loaders) (`glob()` and `file()`) for fetching your local content, as well as access to the API to construct your own loader and fetch remote data. The [`glob()` loader](/en/reference/content-loader-reference/#glob-loader) creates entries from directories of Markdown, MDX, Markdoc, JSON, or YAML files from anywhere on the filesystem. It accepts 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. Each entry’s `id` will be automatically generated from its file name. Use this loader when you have one file per entry. The [`file()` loader](/en/reference/content-loader-reference/#file-loader) creates multiple entries from a single local file. Each entry in the file must have a unique `id` key property. It accepts a `base` file path to your file and optionally a [`parser` function](#parser-function) for data files it cannot parse automatically. Use this loader when your data file can be parsed as an array of objects. src/content.config.ts ```ts import { defineCollection, z } from 'astro:content'; import { glob, file } from 'astro/loaders'; // Not available with legacy API const blog = defineCollection({ loader: glob({ pattern: "**/.md", base: "./src/data/blog" }), schema: / ... / }); const dogs = defineCollection({ loader: file("src/data/dogs.json"), schema: / ... / }), }); const probes = defineCollection({ // `loader` can accept an array of multiple patterns as well as string patterns // Load all markdown files in the space-probes directory, except for those that start with "voyager-" loader: glob({ pattern: ['.md', '!voyager-'], base: 'src/data/space-probes' }), schema: z.object({ name: z.string(), type: z.enum(['Space Probe', 'Mars Rover', 'Comet Lander']), launch_date: z.date(), status: z.enum(['Active', 'Inactive', 'Decommissioned']), destination: z.string(), operator: z.string(), notable_discoveries: z.array(z.string()), }), }); export const collections = { blog, dogs, probes }; ``` ##### `parser` function [Section titled parser function](#parser-function) The `file()` loader accepts a second argument that defines a `parser` function. This allows you to specify a custom parser (e.g. `toml.parse` or `csv-parse`) to create a collection from a file’s contents. The `file()` loader will automatically detect and parse a single array of objects from JSON and YAML files (based on their file extension) with no need for a `parser` unless you have a [nested JSON document](#nested-json-documents). To use other files, such as `.toml` and `.csv`, you will need a to create a parser function. The following example defines a content collection `dogs` using a `.toml` file: src/data/dogs.toml ```toml [[dogs]] id = "..." age = "..." [[dogs]] id = "..." age = "..." ``` After importing TOML’s parser, you can load the `dogs` collection into your project by passing both a file path and `parser` function to the `file()` loader. A similar process can be used to define a `cats` collection from a `.csv` file: src/content.config.ts ```typescript import { defineCollection } from "astro:content"; import { file } from "astro/loaders"; import { parse as parseToml } from "toml"; import { parse as parseCsv } from "csv-parse/sync"; const dogs = defineCollection({ loader: file("src/data/dogs.toml", { parser: (text) => parseToml(text).dogs }), schema: / ... / }) const cats = defineCollection({ loader: file("src/data/cats.csv", { parser: (text) => parseCsv(text, { columns: true, skipEmptyLines: true })}) }); ``` ###### Nested `.json` documents [Section titled Nested .json documents](#nested-json-documents) The `parser` argument also allows you to load a single collection from a nested JSON document. For example, this JSON file contains multiple collections: src/data/pets.json ```json {"dogs": [{}], "cats": [{}]} ``` You can separate these collections by passing a custom `parser` to the `file()` loader for each collection: src/content.config.ts ```typescript 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 }) }); ``` #### Building a custom loader [Section titled Building a custom loader](#building-a-custom-loader) You can build a custom loader to fetch remote content from any data source, such as a CMS, a database, or an API endpoint. Using a loader to fetch your data will automatically create a collection from your remote data. This gives you all the benefits of local collections, such as collection-specific API helpers such as `getCollection()` and `render()` to query and display your data, as well as schema validation. Tip Find community-built and third-party loaders in the [Astro integrations directory](https://astro.build/integrations/?search=\&categories%5B%5D=loaders). ##### Inline loaders [Section titled Inline loaders](#inline-loaders) You can define a loader inline, inside your collection, as an async function that returns an array of entries. This is useful for loaders that don’t need to manually control how the data is loaded and stored. Whenever the loader is called, it will clear the store and reload all the entries. src/content.config.ts ```ts 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, })); }, schema: / ... */ }); ``` The returned entries are stored in the collection and can be queried using the `getCollection()` and `getEntry()` functions. ##### Loader objects [Section titled Loader objects](#loader-objects) For more control over the loading process, you can use the Content Loader API to create a loader object. For example, with access to the `load` method directly, you can create a loader that allows entries to be updated incrementally or clears the store only when necessary. Similar to creating an Astro integration or Vite plugin, you can [distribute your loader as an NPM package](/en/reference/publish-to-npm/) that others can use in their projects. See the full [Content Loader API](/en/reference/content-loader-reference/) and examples of how to build your own loader. ### Defining the collection schema [Section titled Defining the collection schema](#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. Every frontmatter or data property of your collection entries must be defined using a Zod data type: src/content.config.ts ```ts import { defineCollection, z } from 'astro:content'; import { glob, file } from 'astro/loaders'; // Not available with legacy API 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()), }), }); export const collections = { blog, dogs }; ``` #### Defining datatypes with Zod [Section titled Defining datatypes with Zod](#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 go to query content from inside your project. To use Zod in Astro, import the `z` utility from `"astro:content"`. This is a re-export of the Zod library, and it supports all of the features of Zod. ```ts // Example: A cheatsheet of many common Zod datatypes import { z, defineCollection } from 'astro:content'; defineCollection({ schema: z.object({ isDraft: z.boolean(), title: z.string(), sortOrder: z.number(), image: z.object({ src: z.string(), alt: z.string(), }), author: z.string().default('Anonymous'), language: z.enum(['en', 'es']), tags: z.array(z.string()), footnote: z.string().optional(), // In YAML, dates written without quotes around them are interpreted as Date objects publishDate: z.date(), // e.g. 2024-09-17 // Transform a date string (e.g. "2022-07-08") to a Date object updatedDate: z.string().transform((str) => new Date(str)), authorContact: z.string().email(), canonicalURL: z.string().url(), }) }) ``` See [Zod’s README](https://github.com/colinhacks/zod) for complete documentation on how Zod works and what features are available. ##### Zod schema methods [Section titled Zod schema methods](#zod-schema-methods) All [Zod schema methods](https://zod.dev/?id=schema-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 [Section titled Defining collection references](#defining-collection-references) Collection entries can also “reference” other related entries. With the `reference()` function from the Collections API, 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: src/content.config.ts ```ts import { defineCollection, reference, z } from 'astro:content'; const blog = defineCollection({ loader: glob({ pattern: '**/[^_]*.md', base: "./src/data/blog" }), 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 `slug` relatedPosts: z.array(reference('blog')), }) }); const authors = defineCollection({ loader: glob({ pattern: '**/[^_].json', base: "./src/data/authors" }), schema: z.object({ name: z.string(), portfolio: z.string().url(), }) }); export const collections = { blog, authors }; ``` This example blog post specifies the `id`s of related posts and the `id` of the post author: src/data/blog/welcome.md ```yaml --- title: "Welcome to my blog" author: ben-holmes # references `src/data/authors/ben-holmes.json` relatedPosts: - about-me # references `src/data/blog/about-me.md` - my-year-in-review # references `src/data/blog/my-year-in-review.md` --- ``` ### Defining custom IDs [Section titled Defining custom IDs](#defining-custom-ids) When using the `glob()` loader with Markdown, MDX, Markdoc, or JSON files, every content entry [`id`](/en/reference/modules/astro-content/#id) is automatically generated in an URL-friendly format based on the content filename. The `id` is used to query the entry directly from your collection. It is also useful when creating new pages and URLs from your content. You can override an 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. src/blog/1.md ```md --- title: My Blog Post slug: my-custom-id/supports/slashes --- Your blog post content here. ``` src/categories/1.json ```json { "title": "My Category", "slug": "my-custom-id/supports/slashes", "description": "Your category description here." } ``` ## Querying Collections [Section titled Querying Collections](#querying-collections) Astro provides helper functions to query a 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. ```js import { getCollection, getEntry } from 'astro:content'; // 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'); ``` See the full list of properties returned by the [`CollectionEntry` type](/en/reference/modules/astro-content/#collectionentry). ### Using content in Astro templates [Section titled Using content in Astro templates](#using-content-in-astro-templates) After querying your collections, you can access each entry’s content 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. src/pages/index.astro ```astro --- import { getCollection } from 'astro:content'; const posts = await getCollection('blog'); ---
My posts

{posts.map(post => (
{post.data.title}
))}
``` #### Rendering body content [Section titled Rendering body content](#rendering-body-content) Once queried, you can render Markdown and MDX entries to HTML using the [`render()`](/en/reference/modules/astro-content/#render) function property. Calling this function gives you access to rendered HTML content, including both a `` component and a list of all rendered headings. src/pages/blog/post-1.astro ```astro --- import { getEntry, render } from 'astro:content'; const entry = await getEntry('blog', 'post-1'); if (!entry) { // Handle Error, for example: throw new Error('Could not find blog post 1'); } const { Content, headings } = await render(entry); ---
Published on: {entry.data.published.toDateString()}
``` #### Passing content as props [Section titled Passing content as props](#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. src/components/BlogCard.astro ```astro --- import type { CollectionEntry } from 'astro:content'; interface Props { post: CollectionEntry<'blog'>; } // `post` will match your 'blog' collection schema type const { post } = Astro.props; --- ``` ### Filtering collection queries [Section titled Filtering collection queries](#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: ```js // Example: Filter out content entries with `draft: true` import { getCollection } from 'astro:content'; 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: ```js // Example: Filter out content entries with `draft: true` only when building for production import { getCollection } from 'astro:content'; 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: ```js // Example: Filter entries by sub-directory in the collection import { getCollection } from 'astro:content'; const englishDocsEntries = await getCollection('docs', ({ id }) => { return id.startsWith('en/'); }); ``` ### Accessing referenced data [Section titled Accessing referenced data](#accessing-referenced-data) Any [references defined in your schema](/en/guides/content-collections/#defining-collection-references) must be queried separately after first querying your collection entry. You can use the `getEntry()` function to return a single referenced item, or `getEntries()` to retrieve multiple referenced entries from the returned `data` object. src/pages/blog/welcome.astro ```astro --- import { getEntry, getEntries } from 'astro:content'; const blogPost = await getEntry('blog', 'welcome'); // Resolve a singular reference const author = await getEntry(blogPost.data.author); // Resolve an array of references const relatedPosts = await getEntries(blogPost.data.relatedPosts); ---
{blogPost.data.title}

Author: {author.data.name}

You might also like:
{relatedPosts.map(post => ( {post.data.title} ))} ``` ## Generating Routes from Content [Section titled Generating Routes from Content](#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. 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.slug` in `src/pages/blog/[...slug].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) [Section titled Building for static output (default)](#building-for-static-output-default) If you are building a static website (Astro’s default behavior), use the [`getStaticPaths()`](/en/reference/routing-reference/#getstaticpaths) function to create multiple pages from a single page component (e.g. `src/pages/[slug]`) 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 is passed the entire collection entry as a prop for [use in your page template](#using-content-in-astro-templates). src/pages/posts/\[id].astro ```astro --- import { getCollection, render } from 'astro:content'; // 1. Generate a new path for every collection entry export async function getStaticPaths() { const posts = await getCollection('blog'); 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); ---
{post.data.title}
``` 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. `[...slug]`)](/en/guides/routing/#rest-parameters) in the `.astro` filename for this dynamic routing page. ### Building for server output (SSR) [Section titled Building for server output (SSR)](#building-for-server-output-ssr) If you are building a dynamic website (using Astro’s SSR support), you are not expected to generate any paths ahead of time during the build. Instead, your page should examine the request (using `Astro.request` or `Astro.params`) to find the `slug` on-demand, and then fetch it using [`getEntry()`](/en/reference/modules/astro-content/#getentry). src/pages/posts/\[id].astro ```astro --- import { getEntry, render } from "astro:content"; // 1. Get the slug from the incoming server request const { id } = Astro.params; 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); ---
{post.data.title}
``` 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 pages from your collections for blog features like a list of blog posts, tags pages, and more! ## When to create a collection [Section titled When to create a collection](#when-to-create-a-collection) You can [create a collection](#defining-collections) any time you have a group of related data or content that shares a common structure. Much of the benefit of using collections comes from: * Defining a common data shape to validate that an individual entry is “correct” or “complete”, avoiding errors in production. * Content-focused APIs designed to make querying intuitive (e.g. `getCollection()` instead of `import.meta.glob()`) when importing and rendering content on your pages. * A [Content Loader API](/en/reference/content-loader-reference/) for retrieving your content that provides both built-in loaders and access to the low-level API. There are several third-party and community-built loaders available, and you can build your own custom loader to fetch data from anywhere. * Performance and scalability. The Content Layer API allows data to be cached between builds and is suitable for tens of thousands of content entries. [Define your data](#defining-collections) as a collection when: * You have multiple files or data to organize that share the same overall structure (e.g. blog posts written in Markdown which all have the same frontmatter properties). * You have existing content stored remotely, such as in a CMS, and want to take advantage of the collections helper functions and Content Layer API instead of using `fetch()` or SDKs. * You need to fetch (tens of) thousands of related pieces of data, and need a querying and caching method that handles at scale. ### When not to create a collection [Section titled When not to create a collection](#when-not-to-create-a-collection) Collections provide excellent structure, safety, and organization when you have multiple pieces of content that must share the same properties. Collections may not be your solution if: * You have only one or a small number of different pages. Consider [making individual page components](/en/basics/astro-pages/) such as `src/pages/about.astro` with your content directly instead. * You are displaying files that are not processed by Astro, such as PDFs. Place these static assets in the [`public/` directory](/en/basics/project-structure/#public) of your project instead. * Your data source has its own SDK/client library for imports that is incompatible with or does not offer a content loader and you prefer to use it directly. * You are using APIs that need to be updated in real time. Content collections are only updated at build time, so if you need live data, use other methods of [importing files](/en/guides/imports/#import-statements) or [fetching data](/en/guides/data-fetching/) with [on-demand rendering](/en/guides/on-demand-rendering/). # Data fetching > Learn how to fetch remote data with Astro using the fetch API. `.astro` files can fetch remote data to help you generate your pages. ## `fetch()` in Astro [Section titled fetch() in Astro](#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. ). 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)`. 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 ```astro --- import Contact from '../components/Contact.jsx'; import Location from '../components/Location.astro'; const response = await fetch('https://randomuser.me/api/'); const data = await response.json(); const randomUser = data.results[0]; ---
User

{randomUser.name.first} {randomUser.name.last}
``` 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 [Section titled fetch() in Framework Components](#fetch-in-framework-components) The `fetch()` function is also globally available to any [framework components](/en/guides/framework-components/): src/components/Movies.tsx ```tsx import type { FunctionalComponent } from 'preact'; 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
{JSON.stringify(data)}
; }; export default Movies; ``` ## GraphQL queries [Section titled GraphQL queries](#graphql-queries) Astro can also use `fetch()` to query a GraphQL server with any valid GraphQL query. src/components/Film.astro ```astro --- 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; ---
Fetching information about Star Wars: A New Hope

Title: {film.title}

Year: {film.releaseDate}
``` ## Fetch from a Headless CMS [Section titled Fetch from a Headless CMS](#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 [Section titled Community resources](#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 > How to deploy your Astro site to the web. Ready to build and deploy your Astro site? Follow one of our guides to different deployment services or scroll down for general guidance about deploying an Astro site. ## Deployment Guides [Section titled Deployment Guides](#deployment-guides) * ![](/logos/netlify.svg) ### [Netlify](/en/guides/deploy/netlify/) SSRStatic * ![](/logos/vercel.svg) ### [Vercel](/en/guides/deploy/vercel/) SSRStatic * ![](/logos/deno.svg) ### [Deno Deploy](/en/guides/deploy/deno/) SSRStatic * ![](/logos/github.svg) ### [GitHub Pages](/en/guides/deploy/github/) Static * ![](/logos/gitlab.svg) ### [GitLab Pages](/en/guides/deploy/gitlab/) Static * ![](/logos/cloudflare-pages.svg) ### [Cloudflare Pages](/en/guides/deploy/cloudflare/) SSRStatic * ![](/logos/aws.svg) ### [AWS](/en/guides/deploy/aws/) Static * ![](/logos/flightcontrol.svg) ### [AWS via Flightcontrol](/en/guides/deploy/flightcontrol/) SSRStatic * ![](/logos/sst.svg) ### [AWS via SST](/en/guides/deploy/sst/) SSRStatic * ![](/logos/clever-cloud.svg) ### [Clever Cloud](/en/guides/deploy/clever-cloud/) SSRStatic * ![](/logos/azion.svg) ### [Azion](/en/guides/deploy/azion/) SSRStatic * ![](/logos/google-cloud.svg) ### [Google Cloud](/en/guides/deploy/google-cloud/) SSRStatic * ![](/logos/firebase.svg) ### [Firebase Hosting](/en/guides/deploy/google-firebase/) SSRStatic * ![](/logos/heroku.svg) ### [Heroku](/en/guides/deploy/heroku/) Static * ![](/logos/microsoft-azure.svg) ### [Microsoft Azure](/en/guides/deploy/microsoft-azure/) Static * ![](/logos/buddy.svg) ### [Buddy](/en/guides/deploy/buddy/) Static * ![](/logos/edgio.svg) ### [Edgio](/en/guides/deploy/edgio/) SSRStatic * ![](/logos/fleek.svg) ### [Fleek](/en/guides/deploy/fleek/) Static * ![](/logos/flyio.svg) ### [Fly.io](/en/guides/deploy/flyio/) SSRStatic * ![](/logos/render.svg) ### [Render](/en/guides/deploy/render/) Static * ![](/logos/stormkit.svg) ### [Stormkit](/en/guides/deploy/stormkit/) Static * ![](/logos/surge.svg) ### [Surge](/en/guides/deploy/surge/) Static * ![](/logos/cleavr.svg) ### [Cleavr](/en/guides/deploy/cleavr/) SSRStatic * ![](/logos/kinsta.svg) ### [Kinsta](/en/guides/deploy/kinsta/) SSRStatic * ![](/logos/zeabur.svg) ### [Zeabur](/en/guides/deploy/zeabur/) SSRStatic * ![](/logos/zerops.svg) ### [Zerops](/en/guides/deploy/zerops/) SSRStatic ## Quick Deploy Options [Section titled Quick Deploy Options](#quick-deploy-options) You can build and deploy an Astro site to a number of hosts quickly using either their website’s dashboard UI or a CLI. ### Website UI [Section titled Website UI](#website-ui) A quick way to deploy your website is to connect your Astro project’s online Git repository (e.g. GitHub, GitLab, Bitbucket) to a host provider and take advantage of continuous deployment using Git. These host platforms automatically detect pushes to your Astro project’s source repository, build your site and deploy it to the web at a custom URL or your personal domain. Often, setting up a deployment on these platforms will follow steps something like the following: 1. Add your repository to an online Git provider (e.g. in GitHub, GitLab, Bitbucket) 2. Choose a host that supports continuous deployment (e.g. [Netlify](/en/guides/deploy/netlify/) or [Vercel](/en/guides/deploy/vercel/)) and import your Git repository as a new site/project. Many common hosts will recognize your project as an Astro site, and should choose the appropriate configuration settings to build and deploy your site as shown below. (If not, these settings can be changed.) Deploy settings * Build Command: `astro build` or `npm run build` * Publish directory: `dist` 3. Click “Deploy” and your new website will be created at a unique URL for that host (e.g. `new-astro-site.netlify.app`). The host will be automatically configured to watch your Git provider’s main branch for changes, and to rebuild and republish your site at each new commit. These settings can typically be configured in your host provider’s dashboard UI. ### CLI Deployment [Section titled CLI Deployment](#cli-deployment) Some hosts will have their own command line interface (CLI) you can install globally to your machine using npm. Often, using a CLI to deploy looks something like the following: 1. Install your host’s CLI globally, for example: * npm ```shell npm install --global netlify-cli ``` * pnpm ```shell pnpm add --global netlify-cli ``` * Yarn ```shell yarn global add netlify-cli ``` 2. Run the CLI and follow any instructions for authorization, setup etc. 3. Build your site and deploy to your host Many common hosts will build and deploy your site for you. They will usually recognize your project as an Astro site, and should choose the appropriate configuration settings to build and deploy as shown below. (If not, these settings can be changed.) Deploy settings * Build Command: `astro build` or `npm run build` * Publish directory: `dist` Other hosts will require you to [build your site locally](#building-your-site-locally) and deploy using the command line. ## Building Your Site Locally [Section titled Building Your Site Locally](#building-your-site-locally) Many hosts like Netlify and Vercel will build your site for you and then publish that build output to the web. But, some sites will require you to build locally and then run a deploy command or upload your build output. You may also wish to build locally to preview your site, or to catch any potential errors and warnings in your own environment. Run the command `npm run build` to build your Astro site. * npm ```shell npm run build ``` * pnpm ```shell pnpm run build ``` * Yarn ```shell yarn run build ``` By default, the build output will be placed at `dist/`. This location can be changed using the [`outDir` configuration option](/en/reference/configuration-reference/#outdir). ## Adding an Adapter for on-demand rendering [Section titled Adding an Adapter for on-demand rendering](#adding-an-adapter-for-on-demand-rendering) Note Before deploying your Astro site with [on-demand rendering](/en/guides/on-demand-rendering/) enabled, make sure you have: * Installed the [appropriate adapter](/en/guides/on-demand-rendering/) to your project dependencies (either manually, or using the adapter’s `astro add` command, e.g. `npx astro add netlify`). * [Added the adapter](/en/reference/configuration-reference/#integrations) to your `astro.config.mjs` file’s import and default export when installing manually. (The `astro add` command will take care of this step for you!) # Deploy your Astro Site to AWS > How to deploy your Astro site to the web using 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 [Section titled AWS Amplify](#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. 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. * npm ```yaml version: 1 frontend: phases: preBuild: commands: - npm ci build: commands: - npm run build artifacts: baseDirectory: /dist files: - '**/*' cache: paths: - node_modules/**/* ``` * pnpm ```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/**/* ``` * Yarn ```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. ## S3 static website hosting [Section titled S3 static website hosting](#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): ```plaintext aws s3 cp dist/ s3:/// --recursive ``` 4. Update your bucket policy to allow public access. You can find this setting in the bucket’s Permissions > Bucket policy. ```json { "Version": "2012-10-17", "Statement": [ { "Sid": "PublicReadGetObject", "Effect": "Allow", "Principal": "", "Action": "s3:GetObject", "Resource": "arn:aws:s3:::/" } ] } ``` Caution Do not forget to replace `` 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 [Section titled S3 with CloudFront](#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 [Section titled Continuous deployment with GitHub Actions](#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": [ "", "arn:aws:s3:::/", "arn:aws:s3:::" ] } ] } ``` Caution Do not forget to replace `` and ``. 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. ```yaml name: Deploy Website on: push: branches: - main jobs: deploy: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - 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 [Section titled Community Resources](#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) # Deploy your Astro Site to Azion > How to deploy your Astro site to the web using 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 [Section titled Prerequisites](#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 [Section titled How to Deploy through Azion Console Dashboard](#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 [Section titled How to Deploy a Static Site Using the Azion CLI](#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. ```bash azion login ``` 3. Set Up Your Application: * Use the following commands to initialize and configure your project: ```bash azion init ``` 4. Build Your Astro Project: * Run your build command locally: ```bash azion build ``` 5. Deploy Your Static Files: * Deploy your static files using the Azion CLI: ```bash azion deploy ``` This guide provides an overview of deploying static applications. ## Enabling Local Devlopment Using Azion CLI [Section titled Enabling Local Devlopment Using Azion CLI](#enabling-local-devlopment-using-azion-cli) For the preview to work, you must execute the following command: ```bash azion dev ``` Once you’ve initialized the local development server, the application goes through the `build` process. ```bash 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: ```bash [Azion Bundler] [Server] › ✔ success Function running on port http://localhost:3000 ``` ## Troubleshooting [Section titled Troubleshooting](#troubleshooting) ### Node.js runtime APIs [Section titled Node.js runtime APIs](#nodejs-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 > How to deploy your Astro site to the web using Buddy. You can deploy your Astro project using [Buddy](https://buddy.works/), a CI/CD solution that can build your site and push it to many different deploy targets including FTP servers and cloud hosting providers. Note Buddy itself will not host your site. Instead, it helps you manage the build process and deliver the result to a deploy platform of your choice. ## How to deploy [Section titled How to deploy](#how-to-deploy) 1. [Create a Buddy account](https://buddy.works/sign-up). 2. Create a new project and connect it with a git repository (GitHub, GitLab, BitBucket, any private Git Repository or you can use Buddy Git Hosting). 3. Add a new pipeline. 4. In the newly created pipeline add a [Node.js](https://buddy.works/actions/node-js) action. 5. In this action add: ```bash npm install npm run build ``` 6. Add a deployment action — there are many to choose from, you can browse them in [Buddy’s actions catalog](https://buddy.works/actions). Although their settings can differ, remember to set the Source path to `dist`. 7. Press the Run button. # Deploy your Astro Site with Cleavr > How to deploy your Astro site to your VPS server using Cleavr. You can deploy your Astro project to your own Virtual Private Server (VPS) using [Cleavr](https://cleavr.io/), a server and app deployment management tool. Tip Check out [the Astro guide in Cleavr’s docs](https://docs.cleavr.io/guides/astro)! ## Prerequisites [Section titled Prerequisites](#prerequisites) To get started, you will need: A Cleavr account * A server on your VPS provider using Cleavr ## Add your site [Section titled Add your site](#add-your-site) 1. In Cleavr, navigate to the server you want to add your Astro project to. 2. Select Add Site and fill in the details for your application, such as domain name. 3. For App Type, select ‘NodeJS Static’ or ‘NodeJS SSR’ according to how you are setting up your Astro app. 4. For Static apps, set Artifact Folder to `dist`. 5. For SSR apps: * Set Entry Point to `entry.mjs`. * Set Artifact Folder to `dist/server`. 6. Select Add to add the site to your server. ## Setup and deploy [Section titled Setup and deploy](#setup-and-deploy) 1. Once your new site is added, click Setup and deploy. 2. Select the VC Profile, Repo, and Branch for your Astro Project. 3. Make any additional configurations necessary for your project. 4. Click on the Deployments tab and then click on Deploy. Congratulations, you’ve just deployed your Astro app! # Deploy your Astro Site to Clever Cloud > How to deploy your Astro site to the web on Clever Cloud. [Clever Cloud](https://clever-cloud.com) is a European cloud platform that provides automated, scalable services. ## Project Configuration [Section titled Project Configuration](#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 [Section titled Scripts](#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. package.json ```json "scripts": { "start": "node ./dist/server/entry.mjs --host 0.0.0.0 --port 8080", } ``` ## Deploy Astro from the Console [Section titled Deploy Astro from the Console](#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://developers.clever-cloud.com/doc/addons/) unless you’re using a database or Keycloak. 7. Inject environment variables: * For Node.js, no specific environment variable is needed to deploy Astro if you’re using npm. If you’re using yarn or pnpm, set the following environment variables: - pnpm ```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" ``` - yarn ```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: - npm ```shell CC_POST_BUILD_HOOK="npm run build" CC_PRE_BUILD_HOOK="npm install && npm run astro telemetry disable" CC_WEBROOT="/dist" ``` - pnpm ```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" ``` - yarn ```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. Other Branches To deploy from branches other than `master`, use `git push clever :master`. For example, if you want to deploy your local `main` branch without renaming it, use `git push clever main:master`. ## Official Resources [Section titled Official Resources](#official-resources) * [Clever Cloud documentation for deploying a Node.js application](https://developers.clever-cloud.com/doc/applications/javascript/nodejs/) * [Clever Cloud documentation for deploying Astro as a static application](https://developers.clever-cloud.com/guides/astro/) # Deploy your Astro Site to Cloudflare Pages > How to deploy your Astro site to the web using Cloudflare Pages. You can deploy your Astro project on [Cloudflare Pages](https://pages.cloudflare.com/), a platform for frontend developers to collaborate and deploy static (JAMstack) and SSR websites. This guide includes: * [How to deploy through the Cloudflare Pages Dashboard](#how-to-deploy-a-site-with-git) * [How to deploy using Wrangler, the Cloudflare CLI](#how-to-deploy-a-site-using-wrangler) * [How to deploy an SSR site using `@astrojs/cloudflare`](#how-to-deploy-an-ssr-site) ## Prerequisites [Section titled Prerequisites](#prerequisites) To get started, you will need: * A Cloudflare account. If you don’t already have one, you can create a free Cloudflare account during the process. * Your app code pushed to a [GitHub](https://github.com/) or a [GitLab](https://about.gitlab.com/) repository. ## How to deploy a site with Git [Section titled How to deploy a site with Git](#how-to-deploy-a-site-with-git) 1. Set up a new project on Cloudflare Pages. 2. Push your code to your git repository (GitHub, GitLab). 3. Log in to the Cloudflare dashboard and select your account in Account Home > Compute (Workers) > Workers & Pages > Overview. 4. Select Create application, then the Pages tab and then select the Connect to Git option. 5. Select the git project you want to deploy and click Begin setup 6. Use the following build settings: * Framework preset: `Astro` * Build command: `npm run build` * Build output directory: `dist` 7. Click the Save and Deploy button. ## How to deploy a site using Wrangler [Section titled How to deploy a site using Wrangler](#how-to-deploy-a-site-using-wrangler) 1. Install [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/get-started/). 2. Authenticate Wrangler with your Cloudflare account using `wrangler login`. 3. Run your build command. 4. Deploy using `npx wrangler pages deploy dist`. ```bash # Install Wrangler CLI npm install -g wrangler # Login to Cloudflare account from CLI wrangler login # Run your build command npm run build # Create new deployment npx wrangler pages deploy dist ``` After your assets are uploaded, Wrangler will give you a preview URL to inspect your site. When you log into the Cloudflare Pages dashboard, you will see your new project. ### Enabling Preview locally with Wrangler [Section titled Enabling Preview locally with Wrangler](#enabling-preview-locally-with-wrangler) For the preview to work, you must install `wrangler` ```bash pnpm add wrangler --save-dev ``` It’s then possible to update the preview script to run `wrangler` instead of Astro’s built-in preview command: package.json ```json "preview": "wrangler pages dev ./dist" ``` ## How to deploy an SSR site [Section titled How to deploy an SSR site](#how-to-deploy-an-ssr-site) You can build an Astro SSR site for deployment to Cloudflare Pages using the [`@astrojs/cloudflare` adapter](/en/guides/integrations-guide/cloudflare/). Follow the steps below to set up the adapter. You can then deploy using either of the approaches documented above. ### Quick install [Section titled Quick install](#quick-install) Add the Cloudflare adapter to enable SSR in your Astro project 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. ```bash npx astro add cloudflare ``` ### Manual install [Section titled Manual install](#manual-install) If you prefer to install the adapter manually instead, complete the following two steps: 1. Add the `@astrojs/cloudflare` adapter to your project’s dependencies using your preferred package manager. If you’re using npm or aren’t sure, run this in the terminal: ```bash npm install @astrojs/cloudflare ``` 2. Add the following to your `astro.config.mjs` file: astro.config.mjs ```js import { defineConfig } from 'astro/config'; import cloudflare from '@astrojs/cloudflare'; export default defineConfig({ output: 'server', adapter: cloudflare() }); ``` Read more about [SSR in Astro](/en/guides/on-demand-rendering/). ## Troubleshooting [Section titled Troubleshooting](#troubleshooting) ### Client-side hydration [Section titled Client-side hydration](#client-side-hydration) Client-side hydration may fail as a result of Cloudflare’s Auto Minify setting. If you see `Hydration completed but contains mismatches` in the console, make sure to disable Auto Minify under Cloudflare settings. ### Node.js runtime APIs [Section titled Node.js runtime APIs](#nodejs-runtime-apis) If you are building a project that is using on-demand rendering with [the Cloudflare SSR adapter](/en/guides/integrations-guide/cloudflare/) and the server 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 in the server-side environment is not compatible with the [Cloudflare runtime APIs](https://developers.cloudflare.com/workers/runtime-apis/nodejs/). * If you are directly importing a Node.js runtime API, please refer to the Astro documentation on Cloudflare’s [Node.js compatibility](/en/guides/integrations-guide/cloudflare/#nodejs-compatibility) 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 to Deno > How to deploy your Astro site to the web using Deno. You can deploy a server-side rendered Astro site to [Deno Deploy](https://deno.com/deploy), a distributed system that runs JavaScript, TypeScript, and WebAssembly at the edge, worldwide. This guide includes instructions for deploying to Deno Deploy through GitHub Actions or Deno Deploy’s CLI. ## Requirements [Section titled Requirements](#requirements) This guide assumes you already have [Deno](https://deno.com/) installed. ## Project Configuration [Section titled Project Configuration](#project-configuration) Your Astro project can be deployed to [Deno Deploy](https://deno.com/deploy) as a static site, or as a server-side rendered site (SSR). ### Static Site [Section titled Static 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 Deno Deploy. ### Adapter for SSR [Section titled Adapter for SSR](#adapter-for-ssr) To enable SSR in your Astro project and deploy on Deno Deploy: Add [the Deno adapter](https://github.com/denoland/deno-astro-adapter) to enable SSR in your Astro project 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. ```bash npx astro add deno ``` If you prefer to install the adapter manually instead, complete the following two steps: 1. Install [the `@deno/astro-adapter` adapter](https://github.com/denoland/deno-astro-adapter) to your project’s dependencies using your preferred package manager. If you’re using npm or aren’t sure, run this in the terminal: ```bash npm install @deno/astro-adapter ``` 2. Update your `astro.config.mjs` project configuration file with the changes below. astro.config.mjs ```js import { defineConfig } from 'astro/config'; import deno from '@deno/astro-adapter'; export default defineConfig({ output: 'server', adapter: deno(), }); ``` Next, Update your `preview` script in `package.json` with the change below. package.json ```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. ```bash npm run preview ``` ## How to deploy [Section titled How to deploy](#how-to-deploy) You can deploy to Deno Deploy through GitHub Actions or using Deno Deploy’s CLI (command line interface). ### GitHub Actions Deployment [Section titled GitHub Actions Deployment](#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. Static .github/workflows/deploy.yml ```yaml 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@v4 # Not using npm? Change `npm ci` to `yarn install` or `pnpm i` - name: Install dependencies run: npm ci # Not using npm? Change `npm run build` to `yarn build` or `pnpm 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 ``` * SSR .github/workflows/deploy.yml ```yaml 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@v4 # Not using npm? Change `npm ci` to `yarn install` or `pnpm i` - name: Install dependencies run: npm ci # Not using npm? Change `npm run build` to `yarn build` or `pnpm 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: server/entry.mjs root: dist ``` 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 [Section titled CLI Deployment](#cli-deployment) 1. Install the [Deno Deploy CLI](https://docs.deno.com/deploy/manual/deployctl). ```bash deno install -gArf jsr:@deno/deployctl ``` 2. Run your Astro build step. ```bash npm run build ``` 3. Run `deployctl` to deploy! In the command below, replace `` with your [Personal Access Token](https://dash.deno.com/account#access-tokens) and `` with your Deno Deploy project name. * Static ```bash cd dist && DENO_DEPLOY_TOKEN= deployctl deploy --project= jsr:@std/http/file-server ``` * SSR ```bash DENO_DEPLOY_TOKEN= deployctl deploy --project= --no-static --include=./dist ./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`. * Static package.json ```json { // ... "scripts": { "dev": "astro dev", "start": "astro dev", "build": "astro build", "preview": "astro preview", "deno-deploy": "npm run build && cd dist && deployctl deploy --project= jsr:@std/http/file-server" } } ``` * SSR package.json ```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 --project= --no-static --include=./dist ./dist/server/entry.mjs" } } ``` Then you can use this command to build and deploy your Astro site in one step. ```bash DENO_DEPLOY_TOKEN= npm run deno-deploy ``` # Deploy your Astro Site to Edgio > How to deploy your Astro site to the web using Edgio. You can deploy your Astro project to [Edgio](https://www.edg.io/), an edge and CDN platform to deploy, protect and accelerate websites and APIs. Tip Check out [the Astro guide in Edgio’s docs](https://docs.edg.io/guides/astro)! ## How to deploy [Section titled How to deploy](#how-to-deploy) 1. Install [the Edgio CLI](https://docs.edg.io/guides/cli) globally from the Terminal, if you haven’t already. ```bash npm install -g @edgio/cli ``` 2. Add Edgio to your Astro site ```bash edgio init ``` 3. (Optional) Enable Server Side Rendering After you’ve set up [@astrojs/node with Astro](/en/guides/integrations-guide/node/), specify the server file path in `edgio.config.js` as below: edgio.config.js ```js import { join } from 'path' module.exports = { astro: { // The path of the standalone server that runs Astro SSR. // The dependencies for this file are automatically bundled. appPath: join(process.cwd(), 'dist', 'server', 'entry.mjs'), }, }; ``` 4. Deploy to Edgio ```bash edgio deploy ``` # Deploy your Astro Site to Fleek > How to deploy your Astro site to the web on Fleek. You can use [Fleek](http://fleek.xyz/) to deploy a static Astro site to their edge-optimized decentralized network. This guide gives a complete walkthrough of deploying your Astro site to Fleek using the Fleek UI and CLI. ## Project Configuration [Section titled Project Configuration](#project-configuration) Your Astro project can be deployed to Fleek as a static site. ## How to deploy [Section titled How to deploy](#how-to-deploy) You can deploy to Fleek through the website UI or using Fleek’s CLI (command line interface). ### Platform UI Deployment [Section titled Platform UI Deployment](#platform-ui-deployment) 1. Create a [Fleek](https://app.fleek.xyz) account. 2. Push your code to your online Git repository (GitHub). 3. Import your project into Fleek. 4. Fleek will automatically detect Astro and then you can configure the correct settings. 5. Your application is deployed! ### Fleek CLI [Section titled Fleek CLI](#fleek-cli) 1. Install the Fleek CLI. ```bash # You need to have Nodejs >= 18.18.2 npm install -g @fleek-platform/cli ``` 2. Log in to your Fleek account from your terminal. ```bash fleek login ``` 3. Run the build command to generate the static files. By default, these will be located in the `dist/` directory. ```bash npm run build ``` 4. Initialize your project. This will generate a configuration file. ```bash fleek sites init ``` 5. You will be prompted to either create a new Fleek Site or use an existing one. Give the site a name and select the directory where your project is located. 6. Deploy your site. ```bash fleek sites deploy ``` ## Learn more [Section titled Learn more](#learn-more) [Deploy site from Fleek UI](https://fleek.xyz/docs/platform/deployments/) [Deploy site from Fleek CLI](https://fleek.xyz/docs/cli/hosting/) # Deploy your Astro Site to AWS with Flightcontrol > How to deploy your Astro site to AWS with Flightcontrol You can deploy an Astro site using [Flightcontrol](https://www.flightcontrol.dev?ref=astro), which provides fully-automated deployments to your AWS account. Supports both static and SSR Astro sites. ## How to Deploy [Section titled How to Deploy](#how-to-deploy) 1. Create a Flightcontrol account at [app.flightcontrol.dev/signup](https://app.flightcontrol.dev/signup?ref=astro) 2. Go to [app.flightcontrol.dev/projects/new/1](https://app.flightcontrol.dev/projects/new/1) 3. Connect your GitHub account and select your repo 4. Select your desired “Config Type”: * `GUI` (all config managed through Flightcontrol dashboard) where you will select the `Astro Static` or `Astro SSR` preset * `flightcontrol.json` (“infrastructure as code” option where all config is in your repo) where you will select an Astro example config, then add it to your codebase as `flightcontrol.json` 5. Adjust any configuration as needed 6. Click “Create Project” and complete any required steps (like linking your AWS account). ### SSR Setup [Section titled SSR Setup](#ssr-setup) To deploy with SSR support, make sure you first set up the [`@astrojs/node`](/en/guides/integrations-guide/node/) adapter. Then, follow the steps above, choosing the appropriate configurations for Astro SSR. # Deploy your Astro Site to Fly.io > How to deploy your Astro site to the web using 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 [Section titled Project Configuration](#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 [Section titled Static 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 Fly.io. ### Adapter for SSR [Section titled Adapter for SSR](#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 [Section titled How to deploy](#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. ```bash 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 [Section titled Generating your Astro Dockerfile](#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 [Section titled Official Resources](#official-resources) * Check out [the official Fly.io docs](https://fly.io/docs/js/frameworks/astro/) # Deploy your Astro Site to GitHub Pages > How to deploy your Astro site to the web using GitHub Pages. You can use [GitHub Pages](https://pages.github.com/) to host an Astro website directly from a repository on [GitHub.com](https://github.com/). ## How to deploy [Section titled How to deploy](#how-to-deploy) You can deploy an Astro site to GitHub Pages by using [GitHub Actions](https://github.com/features/actions) to automatically build and deploy your site. To do this, your source code must be hosted on GitHub. Astro maintains the official `withastro/action` to deploy your project with very little configuration. Follow the instructions below to deploy your Astro site to GitHub pages, and see [the package README](https://github.com/withastro/action) if you need more information. ## Configure Astro for GitHub Pages [Section titled Configure Astro for GitHub Pages](#configure-astro-for-github-pages) ### Deploying to a `github.io` URL [Section titled Deploying to a github.io URL](#deploying-to-a-githubio-url) Set the [`site`](/en/reference/configuration-reference/#site) and [`base`](/en/reference/configuration-reference/#base) options in `astro.config.mjs`. astro.config.mjs ```js import { defineConfig } from 'astro/config' export default defineConfig({ site: 'https://astronaut.github.io', base: 'my-repo', }) ``` #### `site` [Section titled site](#site) The value for `site` must be one of the following: * The following URL based on your username: `https://.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://.pages.github.io/` #### `base` [Section titled base](#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. * Your repository is located at `https://github.com//.github.io`. 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: ```astro About ``` See more about [configuring a `base` value](/en/reference/configuration-reference/#base) ### Using GitHub pages with a custom domain [Section titled Using GitHub pages with a custom domain](#using-github-pages-with-a-custom-domain) Set up a custom domain You can set up a custom domain by adding the following `./public/CNAME` file to your project: public/CNAME ```js sub.mydomain.com ``` This will deploy your site at your custom domain instead of `user.github.io`. Don’t forget to also [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). To configure Astro for using GitHub pages with a custom domain, set your domain as the value for `site`. Do not set a value for `base`: astro.config.mjs ```js import { defineConfig } from 'astro/config' export default defineConfig({ site: 'https://example.com', }) ``` ## Configure a GitHub Action [Section titled Configure a GitHub Action](#configure-a-github-action) 1. Create a new file in your project at `.github/workflows/deploy.yml` and paste in the YAML below. deploy.yml ```yaml 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@v4 - name: Install, build, and upload your site uses: withastro/action@v3 # with: # path: . # The root location of your Astro project inside the repository. (optional) # node-version: 20 # The specific version of Node that should be used to build your site. Defaults to 20. (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) 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@v4 ``` Note The astro action takes a few optional inputs. These can be provided by uncommenting the `with:` line and the input you want to use. 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. On GitHub, go to your repository’s Settings tab and find the Pages section of the settings. 3. Choose GitHub Actions as the Source of your site. 4. Commit the new workflow file and push it to GitHub. Your site should now be published! When you push changes to your Astro project’s repository, the GitHub Action will automatically deploy them for you. ## Examples [Section titled Examples](#examples) * [Github Pages Deployment](https://github.com/hkbertoson/github-pages) # Deploy your Astro Site to GitLab Pages > How to deploy your Astro site to the web using 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. Looking for an example? Check out [the official GitLab Pages Astro example project](https://gitlab.com/pages/astro)! ## How to deploy [Section titled How to deploy](#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`. astro.config.mjs ```js import { defineConfig } from 'astro/config'; export default defineConfig({ site: 'https://.gitlab.io', base: '/', outDir: 'public', publicDir: 'static', }); ``` `site` The value for `site` must be one of the following: * The following URL based on your username: `https://.gitlab.io` * The following URL based on your group name: `https://.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: ```astro About ``` 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/`: astro.config.mjs ```js 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/`: .gitignore ```diff # 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: .gitlab-ci.yml ```yaml 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 > How to deploy your Astro site to the web using Google Cloud. [Google Cloud](https://cloud.google.com/) is a full-featured web app hosting platform that can be used to deploy an Astro site. ## How to deploy [Section titled How to deploy](#how-to-deploy) ### Cloud Storage (static only) [Section titled Cloud Storage (static only)](#cloud-storage-static-only) 1. [Create a new GCP project](https://console.cloud.google.com/projectcreate), or select one you already have. 2. Create a new bucket under [Cloud Storage](https://cloud.google.com/storage). 3. Give it a name and the other required settings. 4. Upload your `dist` folder into it or upload using [Cloud Build](https://cloud.google.com/build). 5. Enable public access by adding a new permission to `allUsers` called `Storage Object Viewer`. 6. Edit the website configuration and add `ìndex.html` as the entrypoint and `404.html` as the error page. ### Cloud Run (SSR and static) [Section titled Cloud Run (SSR and static)](#cloud-run-ssr-and-static) Cloud Run is a serverless platform that allows you to run a container without having to manage any infrastructure. It can be used to deploy both static and SSR sites. #### Prepare the Service [Section titled Prepare the Service](#prepare-the-service) 1. [Create a new GCP project](https://console.cloud.google.com/projectcreate), or select one you already have. 2. Make sure the [Cloud Run API](https://console.cloud.google.com/apis/library/run.googleapis.com) is enabled. 3. Create a new service. #### Create Dockerfile & Build the Container [Section titled Create Dockerfile \& Build the Container](#create-dockerfile--build-the-container) Before you can deploy your Astro site to Cloud Run, you need to create a Dockerfile that will be used to build the container. Find more information about [how to use Docker with Astro](/en/recipes/docker/#creating-a-dockerfile) in our recipe section. Once the Dockerfile is created, build it into an image and push it to Google Cloud. There are a few ways to accomplish this: Build locally using Docker: Use the `docker build` command to build the image, `docker tag` to give it a tag, then `docker push` to push it to a registry. In the case of Google Cloud, [`Artifact Registry`](https://cloud.google.com/artifact-registry/docs/docker/pushing-and-pulling) is the easiest option, but you can also use [Docker Hub](https://hub.docker.com/). ```bash # build your container docker build . docker tag SOURCE_IMAGE HOSTNAME/PROJECT-ID/TARGET-IMAGE:TAG # Push your image to a registry docker push HOSTNAME/PROJECT-ID/IMAGE:TAG ``` Change the following values in the commands above to match your project: * `SOURCE_IMAGE`: the local image name or image ID. * `HOSTNAME`: the registry host (`gcr.io`, `eu.gcr.io`, `asia.gcr.io`, `us.gcr.io`, `docker.io`). * `PROJECT`: your Google Cloud project ID. * `TARGET-IMAGE`: the name for the image when it’s stored in the registry. * `TAG` is the version associated with the image. [Read more in the Google Cloud docs.](https://cloud.google.com/artifact-registry/docs/docker/pushing-and-pulling) Using another tool: You can use a CI/CD tool that supports Docker, like [GitHub Actions](https://github.com/marketplace/actions/push-to-gcr-github-action). Build using [Cloud Build](https://cloud.google.com/build): Instead of building the Dockerfile locally, you can instruct Google Cloud to build the image remotely. See the [Google Cloud Build documentation here](https://cloud.google.com/build/docs/build-push-docker-image). #### Deploying the container [Section titled Deploying the container](#deploying-the-container) Deployment can be handled manually in your terminal [using `gcloud`](https://cloud.google.com/run/docs/deploying#service) or automatically using [Cloud Build](https://cloud.google.com/build) or any other CI/CD system. Need public access? Don’t forget to add the permission `Cloud Run Invoker` to the `allUsers` group in the Cloud Run permissions settings! # Deploy your Astro Site to Google’s Firebase Hosting > How to deploy your Astro site to the web using 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/google-firebase/) such as databases, authentication, and storage. ## Project Configuration [Section titled Project Configuration](#project-configuration) Your Astro project can be deployed to Firebase as a static site, or as a server-side rendered site (SSR). ### Static Site [Section titled Static 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 Firebase. ### Adapter for SSR [Section titled Adapter for SSR](#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 [Section titled How to deploy](#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. * npm ```shell npm install firebase-tools ``` * pnpm ```shell pnpm add firebase-tools ``` * Yarn ```shell yarn add firebase-tools ``` 2. Authenticate the Firebase CLI with your Google account. This will open a browser window where you can log in to your Google account. * npm ```shell npx firebase login ``` * pnpm ```shell pnpm exec firebase login ``` * Yarn ```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. * npm ```shell npx firebase experiments:enable webframeworks ``` * pnpm ```shell pnpm exec firebase experiments:enable webframeworks ``` * Yarn ```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. * npm ```shell npx firebase init hosting ``` * pnpm ```shell pnpm exec firebase init hosting ``` * Yarn ```shell yarn firebase init hosting ``` 5. Deploy your site to Firebase Hosting. This will build your Astro site and deploy it to Firebase. * npm ```shell npx firebase deploy --only hosting ``` * pnpm ```shell pnpm exec firebase deploy --only hosting ``` * Yarn ```shell yarn firebase deploy --only hosting ``` # Deploy your Astro Site to Heroku > How to deploy your Astro site to the web using 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. Danger 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 [Section titled How to deploy](#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: ```bash $ heroku login ``` 4. Create a file called `static.json` in the root of your project with the below content: static.json ```json { "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: ```bash # 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: ```bash # publish site $ git push heroku master # opens a browser to view the Dashboard version of Heroku CI $ heroku open ``` # Deploy your Astro Site to Kinsta Application Hosting > How to deploy your Astro site to the web on Kinsta Application Hosting. You can use [Kinsta Application Hosting](https://kinsta.com/application-hosting/) to host an Astro site on their cloud hosting. ## Configuring your Astro project [Section titled Configuring your Astro project](#configuring-your-astro-project) ### Static hosting [Section titled Static hosting](#static-hosting) Looking for an example? Check out [the official Kinsta Application Hosting Starter project for Astro](https://github.com/kinsta/hello-world-astro)! To host your project on Kinsta Application Hosting, you need to: * Include a `name` field in your `package.json`. (This can be anything, and will not affect your deployment.) * Include a `build` script in your `package.json`. (Your Astro project should already include this.) * Install the [`serve`](https://www.npmjs.com/package/serve) package and set the `start` script to `serve dist/`. Here are the necessary lines in your `package.json` file: package.json ```json { "name": "anything", // This is required, but the value does not matter. "scripts": { "dev": "astro dev", "start": "serve dist/", "build": "astro build", "preview": "astro preview", "astro": "astro" }, "dependencies": { "astro": "^2.2.0", "serve": "^14.0.1" }, } ``` ### SSR [Section titled SSR](#ssr) Looking for an example? Check out [the official Kinsta Application Hosting Starter project for Astro SSR](https://github.com/kinsta/hello-world-astro-ssr)! To host your project on Kinsta Application Hosting, you need to: * Include a `name` field in your `package.json`. (This can be anything, and will not affect your deployment.) * Include a `build` script in your `package.json`. (Your Astro project should already include this.) * Install the [`@astrojs/node`](https://www.npmjs.com/package/@astrojs/node) package and set the `start` script to `node ./dist/server/entry.mjs`. * Set the `astro.config.mjs` to use `@astrojs/node` and to use `host: true`. Here are the necessary lines in your `package.json` file: package.json ```json { "name": "anything", // This is required, but the value does not matter. "scripts": { "dev": "astro dev", "start": "node ./dist/server/entry.mjs", "build": "astro build", "preview": "astro preview", "astro": "astro" }, "dependencies": { "astro": "^2.2.0", "@astrojs/node": "^5.1.1" }, } ``` Here are the necessary lines in your `astro.config.mjs` file: astro.config.mjs ```js import { defineConfig } from 'astro/config'; import node from "@astrojs/node"; export default defineConfig({ output: 'server', adapter: node({ mode: "standalone" }), server: { host: true } }); ``` ## How to deploy [Section titled How to deploy](#how-to-deploy) Once your project’s GitHub repository is connected, you can trigger manual deploys to Kinsta Application Hosting in the MyKinsta Admin Panel. You can also set up automatic deployments in your admin panel. ### Configuring a new Kinsta application [Section titled Configuring a new Kinsta application](#configuring-a-new-kinsta-application) 1. Go to the [My Kinsta](https://my.kinsta.com/) admin panel. 2. Go to the Applications tab. 3. Connect your GitHub repository. 4. Press the Add service > Application button. 5. Follow the wizard steps. 6. Your application is deployed. # Deploy your Astro Site to Microsoft Azure > How to deploy your Astro site to the web using Microsoft Azure. [Azure](https://azure.microsoft.com/) is a cloud platform from Microsoft. You can deploy your Astro site with Microsoft Azure’s [Static Web Apps](https://aka.ms/staticwebapps) service. This guide takes you through deploying your Astro site stored in GitHub using Visual Studio Code. Please see Microsoft guides for using an [Azure Pipelines Task](https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/azure-static-web-app-v0?view=azure-pipelines) for other setups. ## Prerequisites [Section titled Prerequisites](#prerequisites) To follow this guide, you will need: * An Azure account and a subscription key. You can create a [free Azure account here](https://azure.microsoft.com/free). * Your app code pushed to [GitHub](https://github.com/). * The [SWA Extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-azurestaticwebapps) in [Visual Studio Code](https://code.visualstudio.com/). ## How to deploy [Section titled How to deploy](#how-to-deploy) 1. Open your project in VS Code. 2. Open the Static Web Apps extension, sign in to Azure, and click the + button to create a new Static Web App. You will be prompted to designate which subscription key to use. 3. Follow the wizard started by the extension to give your app a name, choose a framework preset, and designate the app root (usually `/`) and built file location (use `/dist`). Astro is not listed in the built-in templates in Azure so you will need to select `custom`. The wizard will run and will create a [GitHub Action](https://github.com/features/actions) in the `.github` folder of your repo. (This folder will be automatically created if it does not already exist.) The GitHub Action will deploy your app (you can see its progress in your repo’s Actions tab on GitHub). When successfully completed, you can view your app at the address shown in the SWA Extension’s progress window by clicking the Browse Website button (this will appear after the GitHub Action has run). ## Known Issues [Section titled Known Issues](#known-issues) The GitHub action yaml that is created for you assumes the use of node 14. This means the Astro build fails. To resolve this update your projects package.json file with this snippet. ```plaintext "engines": { "node": ">=18.0.0" }, ``` ## Official Resources [Section titled Official Resources](#official-resources) * [Microsoft Azure Static Web Apps documentation](https://learn.microsoft.com/en-us/azure/static-web-apps/) ## Community Resources [Section titled Community Resources](#community-resources) * [Deploying an Astro Website to Azure Static Web Apps](https://www.blueboxes.co.uk/deploying-an-astro-website-to-azure-static-web-apps) * [Deploying a Static Astro Site to Azure Static Web Apps using GitHub Actions](https://agramont.net/blog/create-static-site-astro-azure-ssg/#automate-deployment-with-github-actions) # Deploy your Astro Site to Netlify > How to deploy your Astro site to the web on 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 [Section titled Project Configuration](#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 [Section titled Static 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 SSR [Section titled Adapter for SSR](#adapter-for-ssr) Add [the Netlify adapter](/en/guides/integrations-guide/netlify/) to enable SSR 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. ```bash npx astro add netlify ``` If you prefer to install the adapter manually instead, complete the following two steps: 1. Install [the `@astrojs/netlify` adapter](/en/guides/integrations-guide/netlify/) to your project’s dependencies using your preferred package manager. If you’re using npm or aren’t sure, run this in the terminal: ```bash npm install @astrojs/netlify ``` 2. Add two new lines to your `astro.config.mjs` project configuration file. astro.config.mjs ```js import { defineConfig } from 'astro/config'; import netlify from '@astrojs/netlify'; export default defineConfig({ output: 'server', adapter: netlify(), }); ``` You can also deploy your project’s Astro middleware using Netlify’s Edge Functions by adding `edgeMiddleware: true` to the Netlify adapter’s configuration: astro.config.mjs ```js import { defineConfig } from 'astro/config'; import netlify from '@astrojs/netlify/functions'; export default defineConfig({ output: 'server', adapter: netlify({ edgeMiddleware: true }), }); ``` To run middleware for pre-rendered pages, set `edgeMiddleware: true`. This allows you to use middleware to implement authentication, redirects, or similar things, while still using static HTML output. ## How to deploy [Section titled How to deploy](#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 SSR Astro sites. ### Website UI Deployment [Section titled Website UI Deployment](#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 [Section titled netlify.toml file](#netlifytoml-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: ```toml [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 [Section titled CLI Deployment](#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 [Section titled Set a Node.js Version](#set-a-nodejs-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 `v18.17.1` or `v20.3.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 [Section titled Using Netlify Functions](#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 [Section titled Examples](#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 to Render > How to deploy your Astro site to the web using Render. You can deploy your Astro project to [Render](https://render.com/), a service to build websites with free TLS certificates, a global CDN, DDoS protection, private networks, and auto deploys from Git. ## How to deploy [Section titled How to deploy](#how-to-deploy) 1. Create a [render.com account](https://dashboard.render.com/) and sign in 2. Click the New + button from your dashboard and select Static Site 3. Connect your [GitHub](https://github.com/) or [GitLab](https://about.gitlab.com/) repository or alternatively enter the public URL of a public repository 4. Give your website a name, select the branch and specify the build command and publish directory * Build Command: `npm run build` * Publish Directory: `dist`, for static sites; `dist/client` if you have any pages rendered on demand. 5. Click the Create Static Site button # Deploy your Astro Site to AWS with SST > How to deploy your Astro site to AWS with SST You can deploy an Astro site to AWS using [SST](https://sst.dev), an open-source framework for deploying modern full-stack applications with SSG and SSR support. You can also use any additional SST components like cron jobs, Buckets, Queues, etc while maintaining type-safety. ## Quickstart [Section titled Quickstart](#quickstart) 1. Create an astro project. 2. Run `npx sst@latest init`. 3. It should detect that you are using Astro and ask you to confirm. 4. Once you’re ready for deployment you can run `npx sst deploy --stage production`. You can also read [the full Astro on AWS with SST tutorial](https://sst.dev/docs/start/aws/astro) that will guide you through the steps. ### SST components [Section titled SST components](#sst-components) To use any [additional SST components](https://sst.dev/docs/), add them to `sst.config.ts`. sst.config.ts ```ts const bucket = new sst.aws.Bucket("MyBucket", { access: "public", }); new sst.aws.Astro("MyWeb", { link: [bucket], }); ``` And then access them in your `.astro` file. ```astro --- import { Resource } from "sst" console.log(Resource.MyBucket.name) --- ``` Consult the [SST docs on linking resources](https://sst.dev/docs/linking) to learn more. If you have any questions, you can [ask in the SST Discord](https://discord.gg/sst). # Deploy your Astro Site to Stormkit > Deploy your Astro site to Stormkit You can deploy your Astro project to [Stormkit](https://stormkit.io/), a deployment platform for static websites, single-page applications (SPAs), and serverless functions. ## How to deploy [Section titled How to deploy](#how-to-deploy) 1. [Log in to Stormkit](https://app.stormkit.io/auth). 2. Using the user interface, import your Astro project from one of the three supported Git providers (GitHub, GitLab, or Bitbucket). 3. Navigate to the project’s production environment in Stormkit or create a new environment if needed. 4. Verify the build command in your [Stormkit configuration](https://stormkit.io/docs/deployments/configuration). By default, Stormkit CI will run `npm run build` but you can specify a custom build command on this page. 5. Click the “Deploy Now” button to deploy your site. Read more in the [Stormkit Documentation](https://stormkit.io/docs). # Deploy your Astro Site to Surge > How to deploy your Astro site to the web using 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 [Section titled How to deploy](#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. ```shell npm run build ``` 3. Deploy to Surge using the CLI. ```shell 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 > How to deploy your Astro site to the web on Vercel. You can use [Vercel](http://vercel.com/) to deploy an Astro site to their global edge network with zero configuration. This guide includes instructions for deploying to Vercel through the website UI or Vercel’s CLI. ## Project Configuration [Section titled Project Configuration](#project-configuration) Your Astro project can be deployed to Vercel as a static site, or as a server-side rendered site (SSR). ### Static Site [Section titled Static 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 Vercel. ### Adapter for SSR [Section titled Adapter for SSR](#adapter-for-ssr) To enable SSR in your Astro project and deploy on Vercel: Add [the Vercel adapter](/en/guides/integrations-guide/vercel/) to enable SSR in your Astro project 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. * npm ```shell npx astro add vercel ``` * pnpm ```shell pnpm astro add vercel ``` * Yarn ```shell yarn astro add vercel ``` If you prefer to install the adapter manually instead, complete the following two steps: 1. Install [the `@astrojs/vercel` adapter](/en/guides/integrations-guide/vercel/) to your project’s dependencies using your preferred package manager. * npm ```shell npm install @astrojs/vercel ``` * pnpm ```shell pnpm add @astrojs/vercel ``` * Yarn ```shell yarn add @astrojs/vercel ``` 2. Add two new lines to your `astro.config.mjs` project configuration file. astro.config.mjs ```js import { defineConfig } from 'astro/config'; import vercel from '@astrojs/vercel'; export default defineConfig({ output: 'server', adapter: vercel(), }); ``` ## How to deploy [Section titled How to deploy](#how-to-deploy) You can deploy to Vercel through the website UI or using Vercel’s CLI (command line interface). The process is the same for both static and SSR Astro sites. ### Website UI Deployment [Section titled Website UI Deployment](#website-ui-deployment) 1. Push your code to your online Git repository (GitHub, GitLab, BitBucket). 2. [Import your project](https://vercel.com/new) into Vercel. 3. Vercel will automatically detect Astro and configure the right settings. 4. Your application is deployed! (e.g. [astro.vercel.app](https://astro.vercel.app/)) After your project has been imported and deployed, all subsequent pushes to branches will generate [Preview Deployments](https://vercel.com/docs/concepts/deployments/preview-deployments), and all changes made to the Production Branch (commonly “main”) will result in a [Production Deployment](https://vercel.com/docs/concepts/deployments/environments#production). Learn more about Vercel’s [Git Integration](https://vercel.com/docs/concepts/git). ### CLI Deployment [Section titled CLI Deployment](#cli-deployment) 1. Install the [Vercel CLI](https://vercel.com/cli) and run `vercel` to deploy. * npm ```shell npm install -g vercel vercel ``` * pnpm ```shell pnpm add -g vercel vercel ``` * Yarn ```shell yarn global add vercel vercel ``` 2. Vercel will automatically detect Astro and configure the right settings. 3. When asked `Want to override the settings? [y/N]`, choose `N`. 4. Your application is deployed! (e.g. [astro.vercel.app](https://astro.vercel.app/)) ### Project config with vercel.json [Section titled Project config with vercel.json](#project-config-with-verceljson) You can use `vercel.json` to override the default behavior of Vercel and to configure additional settings. For example, you may wish to attach headers to HTTP responses from your Deployments. Learn more about [Vercel’s project configuration](https://vercel.com/docs/project-configuration). # Deploy your Astro Site to Zeabur > How to deploy your Astro site to the web on Zeabur. [Zeabur](https://zeabur.com) offers hosting for full-stack web applications. Astro sites can be hosted as both SSR or static output. This guide includes instructions for deploying to Zeabur through the website UI. ## Project Configuration [Section titled Project Configuration](#project-configuration) ### Static Site [Section titled Static Site](#static-site) Astro outputs a static site by default. There is no need for any extra configuration to deploy a static Astro site to Zeabur. ### Adapter for SSR [Section titled Adapter for SSR](#adapter-for-ssr) To enable SSR in your Astro project and deploy on Zeabur: 1. Install [the `@zeabur/astro-adapter` adapter](https://www.npmjs.com/package/@zeabur/astro-adapter) to your project’s dependencies using your preferred package manager. If you’re using npm or aren’t sure, run this in the terminal: ```bash npm install @zeabur/astro-adapter ``` 2. Add two new lines to your `astro.config.mjs` project configuration file. astro.config.mjs ```js import { defineConfig } from 'astro/config'; import zeabur from '@zeabur/astro-adapter/serverless'; export default defineConfig({ output: 'server', adapter: zeabur(), }); ``` ## How to deploy [Section titled How to deploy](#how-to-deploy) You can deploy your Astro site to Zeabur if the project is stored in GitHub. 1. Click `Create new project` in the [Zeabur dashboard](https://dash.zeabur.com). 2. Configure GitHub installation and import the repository. 3. Zeabur will automatically detect that your project is an Astro project and will build it using the `astro build` command. 4. Once the build is complete, you can bind a domain to your site and visit it. After your project has been imported and deployed, all subsequent pushes to branches will generate new builds. Learn more about Zeabur’s [Deployment Guide](https://zeabur.com/docs/get-started/). # Deploy your Astro Site to Zerops > How to deploy your Astro site to the web using 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. 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 [Section titled Astro Static site on Zerops](#astro-static-site-on-zerops) ### Creating a project and a service for Astro Static [Section titled Creating a project and a service for Astro Static](#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: ```yaml # 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 [Section titled Deploying your Astro Static site](#deploying-your-astro-static-site) To tell Zerops how to build and run your site, add a `zerops.yml` to your repository: * npm zerops.yml ```yaml # see https://docs.zerops.io/references/zeropsyml for full reference zerops: - setup: app build: base: nodejs@20 buildCommands: - npm i - npm build deployFiles: - dist/~ run: base: static ``` * pnpm zerops.yml ```yaml # see https://docs.zerops.io/references/zeropsyml for full reference zerops: - setup: app build: base: nodejs@20 buildCommands: - pnpm i - pnpm build deployFiles: - dist/~ run: base: static ``` * Yarn zerops.yml ```yaml # see https://docs.zerops.io/references/zeropsyml 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 [Section titled Astro SSR site on Zerops](#astro-ssr-site-on-zerops) ### Update scripts [Section titled Update scripts](#update-scripts) Update your `start` script to run the server output from the Node adapter. package.json ```json "scripts": { "start": "node ./dist/server/entry.mjs", } ``` ### Creating a project and a service for Astro SSR (Node.js) [Section titled Creating a project and a service for Astro SSR (Node.js)](#creating-a-project-and-a-service-for-astro-ssr-nodejs) 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: ```yaml # 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 [Section titled Deploying your Astro SSR site](#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: * npm zerops.yml ```yaml # see https://docs.zerops.io/references/zeropsyml 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 ``` * pnpm zerops.yml ```yaml # see https://docs.zerops.io/references/zeropsyml 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 ``` * Yarn zerops.yml ```yaml # see https://docs.zerops.io/references/zeropsyml 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) [Section titled Trigger the pipeline using Zerops CLI (zcli)](#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 ``` 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 [Section titled Resources](#resources) ### Official [Section titled Official](#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 [Section titled Community](#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 > A guide to using the developer toolbar in Astro While the dev server is running, Astro includes a development 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 [Section titled Built-in apps](#built-in-apps) ### Astro Menu [Section titled Astro Menu](#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 [Section titled Inspect](#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 [Section titled Audit](#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 [Section titled Settings](#settings) The Settings app allows you to configure options for the development toolbar, such as verbose logging, disabling notifications, and adjusting its placement on your screen. ## Extending the dev toolbar [Section titled Extending the dev toolbar](#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-guide/) according to its own installation instructions. ![](/houston_chef.webp) Related recipe: [Create a dev toolbar app](/en/recipes/making-toolbar-apps/) ## Disabling the dev toolbar [Section titled Disabling the dev toolbar](#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 [Section titled Per-project](#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). astro.config.mjs ```js import { defineConfig } from "astro/config"; export default defineConfig({ devToolbar: { enabled: false } }) ``` To enable the dev toolbar again, remove these lines from your configuration, or set `enabled:true`. ### Per-user [Section titled Per-user](#per-user) To disable the dev toolbar for yourself on a specific project, run the [`astro preferences`](/en/reference/cli-reference/#astro-preferences) command. ```shell 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`: ```shell astro preferences disable --global devToolbar ``` The dev toolbar can later be enabled with: ```shell astro preferences enable devToolbar ``` # E-commerce > An introduction to adding e-commerce options to your Astro site With Astro, you can build several e-commerce options, from checkout links to hosted payment pages to building an entire storefront using a payment service API. ## Payment processing overlays [Section titled Payment processing overlays](#payment-processing-overlays) Some payment processing services (e.g. [Lemon Squeezy](#lemon-squeezy), [Paddle](#paddle)) add a payment form to allow your customer to purchase from your site. These can be hosted overlays or embedded in a page on your site. These may offer some basic customization or site branding, and may be added to your Astro project as scripts, buttons, or external links. ### Lemon Squeezy [Section titled Lemon Squeezy](#lemon-squeezy) [Lemon Squeezy](https://www.lemonsqueezy.com/) is an all-in-one platform for payments and subscriptions with multi-currency support, global tax compliance, PayPal integration and more. It allows you to create and manage digital products and services through your account dashboard and provides product URLs for the checkout process. The basic [Lemon.js JavaScript library](https://docs.lemonsqueezy.com/help/lemonjs/what-is-lemonjs) allows you to sell your Lemon Squeezy products with a checkout link. #### Basic Usage [Section titled Basic Usage](#basic-usage) The following is an example of adding a Lemon Squeezy “Buy now” element to an Astro page. Clicking this link will open a checkout and allow the visitor to complete a single purchase. 1. Add the following ` ``` 2. Create an anchor tag on the page linking to your product URL. Include the class `lemonsqueezy-button` to open a checkout overlay when clicked. src/pages/my-product-page.astro ```html Buy Now ``` #### Lemon.js [Section titled Lemon.js](#lemonjs) Lemon.js also provides additional behavior such as [programmatically opening overlays](https://docs.lemonsqueezy.com/help/lemonjs/opening-overlays) and [handling overlay events](https://docs.lemonsqueezy.com/help/lemonjs/handling-events). Read the [Lemon Squeezy developer getting started guide](https://docs.lemonsqueezy.com/guides/developer-guide) for more information. ### Paddle [Section titled Paddle](#paddle) [Paddle](https://www.paddle.com/) is a billing solution for digital products and services. It handles payments, taxes, and subscription management through an overlay or inline checkout. [Paddle.js](https://developer.paddle.com/paddlejs/overview) is a lightweight JavaScript library that lets you build rich, integrated subscription billing experiences using Paddle. #### Basic Usage [Section titled Basic Usage](#basic-usage-1) The following is an example of adding a Paddle “Buy Now” element to an Astro page. Clicking this link will open a checkout and allow the visitor to complete a single purchase. After your default payment link domain (your own website) is approved by Paddle, you can turn any element on your page into a trigger for a checkout overlay using HTML data attributes. 1. Add the following two ` ``` 2. Turn any element on your page into a Paddle Checkout button by adding the `paddle_button` class: src/pages/my-product-page.astro ```html Buy Now ``` 3. Add a `data-items` attribute to specify your product’s Paddle `priceId` and `quantity`. You can also optionally pass additional [supported HTML data attributes](https://developer.paddle.com/paddlejs/html-data-attributes) to prefill data, handle checkout success, or style your button and checkout overlay: src/pages/my-product-page.astro ```html Buy now ``` #### Paddle.js [Section titled Paddle.js](#paddlejs) Instead of passing HTML data attributes, you can send data to the checkout overlay using JavaScript for passing multiple attributes and even greater customization. You can also create upgrade workflows using an inline checkout. Read more about [using Paddle.js to build an inline checkout](https://developer.paddle.com/build/checkout/build-branded-inline-checkout). ## Full-featured e-commerce solutions [Section titled Full-featured e-commerce solutions](#full-featured-e-commerce-solutions) For more customization over your site’s shopping cart and checkout process, you can connect a more fully-featured financial service provider (e.g. [Snipcart](#snipcart)) to your Astro project. These e-commerce platforms may also integrate with other third-party services for user account management, personalization, inventory and analytics. ### Snipcart [Section titled Snipcart](#snipcart) [Snipcart](https://snipcart.com/) is a powerful, developer-first HTML/JavaScript shopping cart platform. Snipcart also allows you to integrate with third-party services such as shipping providers, enable webhooks for an advanced e-commerce integration between your shopping cart and other systems, choose from several payment gateways (e.g. Stripe, Paypal, and Square), customize email templates, and even provides live testing environments. Tip Want a pre-built Snipcart solution instead? Check out [`astro-snipcart`](https://astro-snipcart.vercel.app/), a fully functional Astro community template including an optional design system, ready for you to integrate with your existing Snipcart account. #### Basic Usage [Section titled Basic Usage](#basic-usage-2) The following is an example of configuring a Snipcart checkout and adding button elements for “Add to cart” and “Check out now” to an Astro page. This will allow your visitors to add products to a cart without being immediately sent to a checkout page. For complete instructions, including setting up your Snipcart store, please see [the Snipcart installation documentation](https://docs.snipcart.com/v3/setup/installation). 1. Add the script [as shown in the Snipcart installation instructions](https://docs.snipcart.com/v3/setup/installation) on your page after the `` element. src/pages/my-product-page.astro ```html ``` 2. Customize `window.SnipcartSettings` with any of the [available Snipcart settings](https://docs.snipcart.com/v3/setup/installation#settings) to control the behavior and appearance of your cart. src/pages/my-product-page.astro ```html ``` 3. Add `class="snipcart-add-item"` to any HTML element, such as a ` ``` 4. Add a Snipcart checkout button with the `snipcart-checkout` class to open the cart and allow guests to complete their purchase with a checkout modal. src/pages/my-product-page.astro ```html ``` #### Snipcart JavaScript SDK [Section titled Snipcart JavaScript SDK](#snipcart-javascript-sdk) The [Snipcart JavaScript SDK](https://docs.snipcart.com/v3/sdk/basics) lets you configure, customize and manage your Snipcart cart programmatically. This allows you to perform actions such as: * Retrieve relevant information about the current Snipcart session and apply certain operations to the cart. * Listen to incoming events and trigger callbacks dynamically. * Listen to state changes and receive a full snapshot of the state of the cart. See the [Snipcart documentation](https://docs.snipcart.com/v3/) for more information about all the options to integrate Snipcart with your Astro Project. #### `astro-snipcart` [Section titled astro-snipcart](#astro-snipcart) There are two `astro-snipcart` community packages that can simplify using Snipcart. * [`@lloydjatkinson/astro-snipcart` Astro template](https://astro-snipcart.vercel.app/): This Astro template includes an optional design system for a complete e-commerce solution out of the box. Learn more on its own extensive documentation site, including [the motivation behind building `astro-snipcart`](https://astro-snipcart.vercel.app/motivation) as providing a convenient, Astro-native way for you to interact with the Snipcart API. * [`@Adammatthiesen/astro-snipcart` integration](https://github.com/Adammatthiesen/astro-snipcart): This integration was heavily inspired by the `astro-snipcart` theme and provides Astro components (or Vue components) that you can add to your existing Astro project for creating products, controlling the cart, and more. See the [full tutorial](https://matthiesen.xyz/blog/getting-started-with-my-astro-snipcart-addon) for more information. ## Community Resources [Section titled Community Resources](#community-resources) * [Hands-On Experience: eCommerce Store with Astro?](https://crystallize.com/blog/building-ecommerce-with-astro) * [Collecting Payments with Stripe using Astro](https://zellwk.com/blog/stripe-astro-recipe/) # Endpoints > Learn how to create endpoints that serve any kind of data 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 [Section titled Static File Endpoints](#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 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. src/pages/builtwith.json.ts ```ts // Outputs: /builtwith.json export async function GET({params, request}) { return new Response( JSON.stringify({ name: 'Astro', url: 'https://astro.build/' }) ) } ``` 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: src/pages/astro-logo.png.ts ```ts export async function GET({ params, request }) { const response = await fetch("https://docs.astro.build/assets/full-logo-light.png"); return new Response(await response.arrayBuffer()); } ``` You can also type your endpoint functions using the `APIRoute` type: ```ts import type { APIRoute } from 'astro'; export const GET: APIRoute = async ({ params, request }) => {...} ``` ### `params` and Dynamic routing [Section titled params and Dynamic routing](#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: src/pages/api/\[id].json.ts ```ts import type { APIRoute } from 'astro'; const usernames = ["Sarah", "Chris", "Yan", "Elian"] export const GET: APIRoute = ({ params, request }) => { const id = params.id; return new Response( JSON.stringify({ name: usernames[id] }) ) } export function getStaticPaths() { return [ { params: { id: "0"} }, { params: { id: "1"} }, { params: { id: "2"} }, { params: { id: "3"} } ] } ``` 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, but because the endpoint is a function and not a component, [props](/en/reference/routing-reference/#data-passing-with-props) aren’t supported. ### `request` [Section titled request](#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. src/pages/request-path.json.ts ```ts import type { APIRoute } from 'astro'; export const GET: APIRoute = ({ params, request }) => { return new Response(JSON.stringify({ path: new URL(request.url).pathname }) ) } ``` ## Server Endpoints (API Routes) [Section titled Server Endpoints (API Routes)](#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`. ![](/houston_chef.webp) Related recipe: [Call endpoints from the server](/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`](https://developer.mozilla.org/en-US/docs/Web/API/Response) object, allowing you to set status codes and headers: src/pages/\[id].json.js ```js import { getProduct } from '../db'; export async function GET({ params }) { const id = params.id; 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" } } ); } ``` 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 create 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: src/pages/astro-logo.png.ts ```ts export async function GET({ params, request }) { const response = await fetch("https://docs.astro.build/assets/full-logo-light.png"); const buffer = Buffer.from(await response.arrayBuffer()); return new Response(buffer, { headers: { "Content-Type": "image/png" }, }); } ``` ### HTTP methods [Section titled HTTP methods](#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). src/pages/methods.json.ts ```ts export const GET: APIRoute = ({ params, request }) => { return new Response(JSON.stringify({ message: "This was a GET!" }) ) } export const POST: APIRoute = ({ request }) => { return new Response(JSON.stringify({ message: "This was a POST!" }) ) } export const DELETE: APIRoute = ({ request }) => { return new Response(JSON.stringify({ message: "This was a DELETE!" }) ) } export const ALL: APIRoute = ({ request }) => { return new Response(JSON.stringify({ message: `This was a ${request.method}!` }) ) } ``` ![](/houston_chef.webp) Related recipes * [Verify a Captcha](/en/recipes/captcha/) * [Build forms with API routes](/en/recipes/build-forms-api/) ### `request` [Section titled request](#request-1) 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: src/pages/test-post.json.ts ```ts export const POST: APIRoute = async ({ request }) => { if (request.headers.get("Content-Type") === "application/json") { const body = await request.json(); const name = body.name; return new Response(JSON.stringify({ message: "Your name was: " + name }), { status: 200 }) } return new Response(null, { status: 400 }); } ``` ### Redirects [Section titled Redirects](#redirects) The endpoint context exports a `redirect()` utility similar to `Astro.redirect`: src/pages/links/\[id].js ```js import { getLinkUrl } from '../db'; export async function GET({ params, redirect }) { const { id } = params; const link = await getLinkUrl(id); if (!link) { return new Response(null, { status: 404, statusText: 'Not found' }); } return redirect(link, 307); } ``` # Using environment variables > Learn how to use environment variables in an Astro project. 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 [Section titled Vite’s built-in support](#vites-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. .env ```ini 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 [Section titled IntelliSense for TypeScript](#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/` and configure `ImportMetaEnv` like this: src/env.d.ts ```ts interface ImportMetaEnv { readonly DB_PASSWORD: string; readonly PUBLIC_POKEAPI: string; // more env variables... } interface ImportMeta { readonly env: ImportMetaEnv; } ``` ## Default environment variables [Section titled Default environment variables](#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`. * `import.meta.env.ASSETS_PREFIX`: The prefix for Astro-generated asset links if the [`build.assetsPrefix` config option](/en/reference/configuration-reference/#buildassetsprefix) is set. This can be used to create asset links not handled by Astro. Use them like any other environment variable. ```ts const isProd = import.meta.env.PROD; const isDev = import.meta.env.DEV; ``` ## Setting environment variables [Section titled Setting environment variables](#setting-environment-variables) ### `.env` files [Section titled .env files](#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. .env ```ini # 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: ```bash # Run the dev server connected to a "staging" API astro dev --mode staging # Build a site that connects to a "production" API with additional debug information astro build --devOutput # Build a site that connects to a "testing" API 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 [Section titled In the Astro config file](#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. astro.config.mjs ```js import { loadEnv } from "vite"; 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. ```sh pnpm add vite --save-dev ``` ### Using the CLI [Section titled Using the CLI](#using-the-cli) You can also add environment variables as you run your project: * npm ```shell PUBLIC_POKEAPI=https://pokeapi.co/api/v2 npm run dev ``` * pnpm ```shell PUBLIC_POKEAPI=https://pokeapi.co/api/v2 pnpm run dev ``` * Yarn ```shell PUBLIC_POKEAPI=https://pokeapi.co/api/v2 yarn run dev ``` ## Getting environment variables [Section titled Getting environment variables](#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. ```js // 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 [Section titled Type safe environment variables](#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 [Section titled Basic Usage](#basic-usage) #### Define your schema [Section titled Define your schema](#define-your-schema) To configure a schema, add the `env.schema` option to your Astro config: astro.config.mjs ```js import { defineConfig } from 'astro/config' export default defineConfig({ env: { schema: { // ... } } }) ``` You can then [register variables as a string, number, enum, or boolean](#data-types) using the `envField` helper. Define the [kind of environment variable](#variable-types) by providing a `context` (client or server) and `access` (secret or public) for each variable, and pass any additional properties such as `optional` or `default` in an object: astro.config.mjs ```js import { defineConfig, envField } from 'astro/config' export default defineConfig({ env: { schema: { API_URL: envField.string({ context: "client", access: "public", optional: true }), PORT: envField.number({ context: "server", access: "public", default: 4321 }), API_SECRET: envField.string({ context: "server", access: "secret" }), } } }) ``` Types will be generated for you when running `astro dev` or `astro build`, but you can run `astro sync` to generate types only. #### Use variables from your schema [Section titled Use variables from your schema](#use-variables-from-your-schema) Import and use your defined variables from the appropriate `/client` or `/server` module: ```astro --- import { API_URL } from "astro:env/client" import { API_SECRET_TOKEN } from "astro:env/server" const data = await fetch(`${API_URL}/users`, { method: "GET", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${API_SECRET_TOKEN}` }, }) --- ``` ### Variable types [Section titled Variable types](#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: ```js 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: ```js 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: ```js import { API_SECRET } from "astro:env/server" ``` By default, secrets are only validated at runtime. You can enable validating private variables 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 [Section titled Data types](#data-types) There are currently four data types supported: strings, numbers, enums, and booleans: ```js import { envField } from "astro/config" 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/configuration-reference/#envschema). ### Retrieving secrets dynamically [Section titled Retrieving secrets dynamically](#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`: ```js import { FOO, // boolean getSecret } from 'astro:env/server' getSecret('FOO') // string | undefined ``` Learn more in [the API reference](/en/reference/modules/astro-env/#getsecret). ### Limitations [Section titled Limitations](#limitations) 1. `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 2. [`@astrojs/cloudflare`](/en/guides/integrations-guide/cloudflare/) is a bit different than other adapters. Environment variables are scoped to the request, unlike Node.js where it’s global. That means you always need to use secrets inside the request scope: src/middleware.ts ```js import { defineMiddleware } from "astro:middleware" import { FOO, getSecret } from "astro:env" console.log(FOO) // undefined console.log(getSecret("FOO")) // undefined export const onRequest = defineMiddleware((context, next) => { console.log(FOO) // boolean console.log(getSecret("FOO")) // string return next() }) ``` # Using custom fonts > Looking to add some custom typefaces to an Astro website? Use Google Fonts with Fontsource or add a font of your choice. This guide will show you how to add web fonts to your project and use them in your components. ## Using a local font file [Section titled Using a local font file](#using-a-local-font-file) This example will demonstrate adding a custom font using the font file `DistantGalaxy.woff`. 1. Add your font file to `public/fonts/`. 2. Add the following `@font-face` statement to your CSS. This could be in a global `.css` file you import, a ` ``` ## Using Fontsource [Section titled Using Fontsource](#using-fontsource) The [Fontsource](https://fontsource.org/) project simplifies using Google Fonts and other open-source fonts. It provides npm modules you can install for the fonts you want to use. 1. Find the font you want to use in [Fontsource’s catalog](https://fontsource.org/). This example will use [Twinkle Star](https://fontsource.org/fonts/twinkle-star). 2. Install the package for your chosen font. * npm ```shell npm install @fontsource/twinkle-star ``` * pnpm ```shell pnpm add @fontsource/twinkle-star ``` * Yarn ```shell yarn add @fontsource/twinkle-star ``` Tip You’ll find the correct package name in the “Quick Installation” section of each font page on Fontsource’s website. It will start with `@fontsource/` or `@fontsource-variable/` followed by the name of the font. 3. Import the font package in the component where you want to use the font. Usually, you will want to do this in a common layout component to make sure the font is available across your site. The import will automatically add the necessary `@font-face` rules needed to set up the font. src/layouts/BaseLayout.astro ```astro --- import '@fontsource/twinkle-star'; --- ``` 4. Use the font’s name as shown in the `body` example on its Fontsource page as the `font-family` value. This will work anywhere you can write CSS in your Astro project. ```css h1 { font-family: "Twinkle Star", cursive; } ``` To optimize your website’s rendering times, you may want to preload fonts that are essential for the initial page display. See the [Fontsource guide to preloading fonts](https://fontsource.org/docs/getting-started/preload) for more information and usage. ## Register fonts in Tailwind [Section titled Register fonts in Tailwind](#register-fonts-in-tailwind) If you are using the [Tailwind integration](/en/guides/integrations-guide/tailwind/), you can use either of the previous methods on this page to install your font, with some modification. You can either add an [`@font-face` statement for a local font](#using-a-local-font-file) or use [Fontsource’s `import` strategy](#using-fontsource) to install your font. To register your font in Tailwind: 1. Follow either of the guides above, but skip the final step of adding `font-family` to your CSS. 2. Add the typeface name to `tailwind.config.mjs`. This example adds `Inter` to the sans-serif font stack, with default fallback fonts from Tailwind CSS. tailwind.config.mjs ```js import defaultTheme from 'tailwindcss/defaultTheme' /** @type {import('tailwindcss').Config} */ export default { content: ['./src/**/.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'], theme: { extend: { fontFamily: { sans: ['Inter', ...defaultTheme.fontFamily.sans], }, }, }, plugins: [], } ``` Now, all sans-serif text (the default with Tailwind) in your project will use your chosen font and the `font-sans` class will also apply the Inter font. See [Tailwind’s docs on adding custom font families](https://tailwindcss.com/docs/font-family#using-custom-values) for more information. ## More resources [Section titled More resources](#more-resources) Learn how web fonts work in [MDN’s web fonts guide](https://developer.mozilla.org/en-US/docs/Learn/CSS/Styling_text/Web_fonts). * Generate CSS for your font with [Font Squirrel’s Webfont Generator](https://www.fontsquirrel.com/tools/webfont-generator). # Front-end frameworks > Build your Astro website with React, Svelte, and more. Build your Astro website without sacrificing your favorite component framework. Create Astro [islands](/en/concepts/islands/) with the UI frameworks of your choice. ## Official front-end framework integrations [Section titled Official front-end framework integrations](#official-front-end-framework-integrations) Astro supports a variety of popular frameworks including [React](https://react.dev/), [Preact](https://preactjs.com/), [Svelte](https://svelte.dev/), [Vue](https://vuejs.org/), [SolidJS](https://www.solidjs.com/), and [AlpineJS](https://alpinejs.dev/) with official integrations. Find even more [community-maintained framework integrations](https://astro.build/integrations/?search=\&categories%5B%5D=frameworks) (e.g. Angular, Qwik, Elm) in our integrations directory. ### Front-end frameworks * ![](/logos/alpine-js.svg) ### [@astrojs/alpinejs](/en/guides/integrations-guide/alpinejs/) * ![](/logos/preact.svg) ### [@astrojs/preact](/en/guides/integrations-guide/preact/) * ![](/logos/react.svg) ### [@astrojs/react](/en/guides/integrations-guide/react/) * ![](/logos/solid.svg) ### [@astrojs/solid⁠-⁠js](/en/guides/integrations-guide/solid-js/) * ![](/logos/svelte.svg) ### [@astrojs/svelte](/en/guides/integrations-guide/svelte/) * ![](/logos/vue.svg) ### [@astrojs/vue](/en/guides/integrations-guide/vue/) ## Installing integrations [Section titled Installing integrations](#installing-integrations) One or several of these Astro integrations can be installed and configured in your project. See the [Integrations Guide](/en/guides/integrations-guide/) for more details on installing and configuring Astro integrations. Tip Want to see an example for the framework of your choice? Visit [astro.new](https://astro.new/latest/frameworks) and select one of the framework templates. ## Using framework components [Section titled Using framework components](#using-framework-components) Use your JavaScript framework components in your Astro pages, layouts and components just like Astro components! All your components can live together in `/src/components`, or can be organized in any way you like. To use a framework component, import it from its relative path in your Astro component script. Then, use the component alongside other components, HTML elements and JSX-like expressions in the component template. src/pages/static-components.astro ```astro --- import MyReactComponent from '../components/MyReactComponent.jsx'; ---
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 [Section titled Hydrating interactive components](#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. src/pages/interactive-components.astro ```astro --- // Example: hydrating framework components in the browser. import InteractiveButton from '../components/InteractiveButton.jsx'; import InteractiveCounter from '../components/InteractiveCounter.jsx'; import InteractiveModal from '../components/InteractiveModal.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. 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 [Section titled Available hydration directives](#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 [Section titled Mixing frameworks](#mixing-frameworks) You can import and render components from multiple frameworks in the same Astro component. src/pages/mixing-frameworks.astro ```astro --- // Example: Mixing multiple framework components on the same page. import MyReactComponent from '../components/MyReactComponent.jsx'; import MySvelteComponent from '../components/MySvelteComponent.svelte'; import MyVueComponent from '../components/MyVueComponent.vue'; ---

``` Caution Only Astro components (`.astro`) can contain components from multiple frameworks. ## Passing props to framework components [Section titled Passing props to framework components](#passing-props-to-framework-components) You can pass props from Astro components to framework components: src/pages/frameworks-props.astro ```astro --- import TodoList from '../components/TodoList.jsx'; import Counter from '../components/Counter.svelte'; ---

``` Passing functions as props You can pass a function as a prop to a framework component, but it only works during server rendering. If you try to use the function in a hydrated component (for example, as an event handler), an error will occur. This is because functions can’t be serialized* (transferred from the server to the client) by Astro. ## Passing children to framework components [Section titled Passing children to framework components](#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 `` element. src/pages/component-children.astro ```astro --- import MyReactSidebar from '../components/MyReactSidebar.jsx'; ---
Here is a sidebar with some text and a button.
``` 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`. src/pages/named-slots.astro ```astro --- import MySidebar from '../components/MySidebar.jsx'; ---
Menu

Here is a sidebar with some text and a button.

Twitter

GitHub

``` src/components/MySidebar.jsx ```jsx export default function MySidebar(props) { return (

{props.title}

{props.children}

{props.socialLinks}

) } ``` For Svelte and Vue these slots can be referenced using a `` element with the `name` attribute. Slot names using `kebab-case` will be preserved. src/components/MySidebar.svelte ```jsx

``` ## Nesting framework components [Section titled Nesting framework components](#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. src/pages/nested-components.astro ```astro --- import MyReactSidebar from '../components/MyReactSidebar.jsx'; import MyReactButton from '../components/MyReactButton.jsx'; import MySvelteButton from '../components/MySvelteButton.svelte'; ---
Here is a sidebar with some text and a button.

``` 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? [Section titled Can I use Astro components inside my framework components?](#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 `` pattern](/en/basics/astro-components/#slots) to pass static content generated by Astro components as children to your framework components inside an `.astro` component. src/pages/astro-children.astro ```astro --- import MyReactComponent from '../components/MyReactComponent.jsx'; import MyAstroComponent from '../components/MyAstroComponent.astro'; --- ``` ## Can I hydrate Astro components? [Section titled Can I hydrate Astro components?](#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 ` ``` ## Generating images with `getImage()` [Section titled Generating images with getImage()](#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 `` and `` components do not currently support, you can use the `getImage()` function to create your own custom `` component. See more in the [`getImage()` reference](/en/reference/modules/astro-assets/#getimage). ![](/houston_chef.webp) Related recipe: [Build a custom image component](/en/recipes/build-custom-img-component/) ## Alt Text [Section titled Alt Text](#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 `` and `` 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 [Section titled Default image service](#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: ```bash pnpm add sharp ``` ### Configure no-op passthrough service [Section titled Configure no-op passthrough service](#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. Deno, Cloudflare), you can configure a no-op image service to allow you to use the `` and `` 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: astro.config.mjs ```js import { defineConfig, passthroughImageService } from 'astro/config'; export default defineConfig({ image: { service: passthroughImageService() } }); ``` ## Asset Caching [Section titled Asset Caching](#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 [Section titled Remote Images](#remote-images-2) 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 [Section titled Revalidation](#revalidation) Added in: `astro@5.1.0` New [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 [Section titled Community Integrations](#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 > Learn how to import different file types into your Astro project. Astro supports most static assets with zero configuration required. You can use the `import` statement anywhere in your project JavaScript (including your Astro frontmatter) and Astro will include a built, optimized copy of that static asset in your final build. `@import` is also supported inside of CSS & ` ``` Similarly, in Astro you can drop in a ` ``` #### Global Styling [Section titled Global Styling](#global-styling) ` ``` #### Pre-processor support [Section titled Pre-processor support](#pre-processor-support) [Astro supports the most popular CSS preprocessors](/en/guides/styling/#css-preprocessors) by installing them as a dev dependency. For example, to use SCSS: ```shell npm install -D sass ``` After doing so, you’re then able to use `.scss` or `.sass` styled without modification from your Vue components. src/layouts/Layout.astro ```astro
Hello, world
``` See more about [Styling in Astro](/en/guides/styling/). ### Nuxt Image Plugin to Astro [Section titled Nuxt Image Plugin to Astro](#nuxt-image-plugin-to-astro) Convert any [Nuxt `` or `` components](https://image.nuxtjs.org/components/nuxt-img) to [Astro’s own image component](/en/guides/images/) in `.astro` or `.mdx` files, or to a [standard HTML ``](/en/guides/images/#images-in-ui-framework-components) or `` tag as appropriate in your Vue components. Astro’s `` component works in `.astro` and `.mdx` files only. See a [full list of its component attributes](/en/reference/modules/astro-assets/#image-properties) and note that several will differ from Nuxt’s attributes. src/pages/index.astro ```astro --- import { Image } from 'astro:assets'; import rocket from '../assets/rocket.png'; --- ``` In Vue (`.vue`) components within your Astro app, use standard JSX image syntax (``). Astro will not optimize these images, but you can install and use NPM packages for more flexibility. You can learn more about [using images in Astro](/en/guides/images/) in the Images Guide. ## Guided example: See the steps! [Section titled Guided example: See the steps!](#guided-example-see-the-steps) Here is an example of Nuxt Pokédex data fetch converted to Astro. `pages/index.vue` fetches and displays a list of the first 151 Pokémon using [the REST PokéAPI](https://pokeapi.co/). Here’s how to recreate that in `src/pages/index.astro`, replacing `asyncData()` with `fetch()`. 1. Identify the `

Hello, World!

{title}

Register

Sign in

Welcome {user.displayName}

Add a new friend

Edit {friend.name}

{friend.name}

Friends

Current Time

Register

Sign in

Welcome {email}

Sign in

{rows[0].title}

{item.name} - ${item.price}

{fields.headline}

{post.title}

{item.fields.title}

My Blog

{post.title}

{title}

{post?.title}

{post.title}

{catalogue.name}

{data.title}

{data.title}

{article.title}

No Content found

My news site

{article.title}

{title}

{post.title}

{post.title}

{post.title}

{post.title}

{post.title}

{post.node.title}

{post.title}

Astro

{post.title}

{post.data.title}

Blog posts

{blogPost.elements.title.value}

{blogPost.elements.title.value}

Astro + PayloadCMS 🚀

Blog posts list:

My blog site

{article.title}

Astro + Statamic 🚀

Astro + Statamic 🚀

{blok.title}

{blok.title}

{article.attributes.title}

{article.attributes.title}

Astro + Umbraco 🚀

{article.name}

Blog Articles

{article.properties.title}

{article.properties.title}

Astro + WordPress 🚀

List of Dinosaurs

My posts

{blogPost.data.title}

You might also like:

{post.data.title}

{post.data.title}

User

{randomUser.name.first} {randomUser.name.last}

Fetching information about Star Wars: A New Hope

Title: {film.title}

Use React components directly in Astro!

Menu

{title}

{resource}: {id}

{title}

Page {page.currentPage}

Page {page.currentPage}

Title

Hello