Umbraco & Astro
هذا المحتوى لا يتوفر بلغتك بعد.
Umbraco CMS 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 AstroIn this section you will use Umbraco’s native Content Delivery API to provide content to your Astro project.
Prerequisites
Section titled PrerequisitesTo get started, you will need to have the following:
- An Astro project - If you don’t have an Astro project yet, our Installation guide will get you up and running in no time.
- An Umbraco (v12+) project - If you don’t have an Umbraco project yet, please see this Installation guide.
Setting up the Content Delivery API
Section titled Setting up the Content Delivery APITo enable the Content Delivery API, update your Umbraco project’s appsettings.json
file:
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 for more information.
Fetching Data
Section titled Fetching DataUse 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.
Building a blog with Umbraco and Astro
Section titled Building a blog with Umbraco and AstroPrerequisites
Section titled Prerequisites-
An Astro project - If you don’t have an Astro project yet, our Installation guide will get you up and running in no time.
-
An Umbraco project (v12+) with the Content Delivery API enabled - Follow this Installation guide to create a new project.
Creating blog posts in Umbraco
Section titled Creating blog posts in UmbracoFrom the Umbraco backoffice, create a Document Type for a simple blog article called ‘Article’.
-
Configure your ‘Article’ Document Type with the following properties:
- Title (DataType: Textstring)
- Article Date (DataType: Date Picker)
- Content (DataType: Richtext Editor)
-
Toggle “Allow as root” to
true
on the ‘Article’ document type. -
From the “Content” section in the Umbraco backoffice, create and publish your first blog post. Repeat the process as many times as you like.
For more information, watch a video guide on creating Document Types.
Displaying a list of blog posts in Astro
Section titled Displaying a list of blog posts in AstroCreate a src/layouts/
folder, then add a new file Layout.astro
with the following code:
Your project should now contain the following files:
Directorysrc/
Directorylayouts/
- Layout.astro
Directorypages/
- 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:
Generating individual blog posts
Section titled Generating individual blog postsCreate the file [...slug].astro
at the root of the /pages/
directory. This file will be used to generate the individual blog pages dynamically.
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:
Your project should now contain the following files:
Directorysrc/
Directorylayouts/
- Layout.astro
Directorypages/
- 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 siteTo deploy your site visit our deployment guides 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 certificatesIf 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:
This method is described in more detail in this blog post showing how to configure your project for self-signed certificates, with an accompanying repo.
Official Documentation
Section titled Official DocumentationCommunity Resources
Section titled Community Resources- Astro-nomically Performant Websites using the Content Delivery API - Louis Richardson
- Generating a TypeScript OpenAPI client from Umbraco’s Content Delivery API - Rick Butterfield
- Jamstack For Free With Azure And CloudFlare - Kenn Jacobsen
- Quick n’ dirty blog with Astro and Umbraco - Kenn Jacobsen