@apostrophecms/apostrophe-astro

- Astro integration for ApostropheCMS
- About Astro
- Bringing ApostropheCMS and Astro together
- Installation
- Security
- Configuration (Astro)
- Options
- aposHost (mandatory)
- widgetsMapping (mandatory)
- templatesMapping (mandatory)
- onBeforeWidgetRender (optional)
- viewTransitionWorkaround (optional)
- includeResponseHeaders
- excludeRequestHeaders
- forwardHeaders (deprecated)
- Mapping Apostrophe templates to Astro components
- Mapping Apostrophe widgets to Astro components
- [Creating the [...slug.astro] component and fetching Apostrophe data](#creating-the-slugastro-component-and-fetching-apostrophe-data)
- Creating Astro page components
- Creating Astro widget components
- Accessing image and URLs
- What to change in your Apostrophe project
- Starting up your combined project
- Logging in
- Redirections
- 404 Not Found
- Reserved routes
- What about widget players?
- aposSetQueryParameter: working with query parameters
- What about Vue, React, SvelteJS, etc.?
- A note on production use
- Debugging
- Widget Render Hook
- Enabling the render-area option to ApostropheCMS REST APIs
- Enabling the @apostrophecms/layout-widget in an existing project
- Backend updates
- Frontend updates
- Conclusion
- Acknowledgements

Astro integration for ApostropheCMS

This module integrates ApostropheCMS into your Astro application.

About Astro

Astro provides a "universal bridge" to run modern frontend frameworks like React, Vue,
and SvelteJS on the server side, as well as a straightforward, JSX-like template
language of its own to meld everything together.

Bringing ApostropheCMS and Astro together

The intent of this integration is to let Apostrophe manage content, handle routing of URLs and fetch content,
and let Astro take the responsibility for the rendering of pages
and any associated logic using your framework(s) of choice like React, Vue.js,
Svelte, etc. (see the Astro integrations page for more).

This module also brings the ApostropheCMS Admin UI in your Astro application, so you can manage your site exactly as if you were in a "normal" Apostrophe instance.

When you use this module, you will have two projects:

1. An Astro project. This is where you write your templates and frontend code.

2. An Apostrophe project. This is where you define your page types, widget types
and other content types with their schemas and other customizations.

This kind of dual-project CMS integration is typical for Astro.

The best way to keep everything consistent is to build these in frontend and backend subdirectories of the same git repository.

To get you started quickly, we recommend one of our official Astro starter kits:

* apostrophecms/starter-kit-astro-essentials is best for a clean start with as little extra code as possible.
* apostrophecms/starter-kit-astro-apollo is a full-fledged project with a blog, a design system and other nice touches.
* apostrophecms/starter-kit-astro-apollo-pro is great for those who expect to use our Pro features right away, but keep in mind you can add those modules to any project later.

> 💡 These combined Astro + Apostrophe projects are best launched by forking the repository, not using our CLI. Follow the links to see how to fork these projects and get started on your own.

You can also adapt your own existing ApostropheCMS project as explained below.

> Note that this module, @apostrophecms/apostrophe-astro, is meant to be installed as a dependency of your Astro project,
> not your Apostrophe project.

This module is currently designed for use with Astro's output: 'server' setting (SSR mode), so that you can edit your content
directly on the page. Support for export as a static site is under consideration for the future.

Installation

If you did not fork the sample projects above, you will need to install this
module into your Astro project. Install this module in your
Astro project, not your ApostropheCMS project:

``shell
cd my-astro-project
npm install @apostrophecms/apostrophe-astro
`

Astro 3.x and 4.x are both supported.

Security

You must set the APOS_EXTERNAL_FRONT_KEY environment variable to a secret
value when running your Astro project, and also set the same variable to the same value when running your Apostrophe application.
This ensures that other sites on the web cannot fetch excessive amounts of
information from ApostropheCMS without your permission.

Configuration (Astro)

Since this is an Astro integration, you will need to add it to your Astro project's astro.config.mjs file.
Here is a working astro.config.mjs file for a project with an Apostrophe CMS backend.

`js
import { defineConfig } from 'astro/config';
import apostrophe from '@apostrophecms/apostrophe-astro';

// For production. You can use other adapters that support
// output: 'server'
import node from '@astrojs/node';

export default defineConfig({
output: 'server',
adapter: node({
mode: 'standalone'
}),
integrations: [
apostrophe({
aposHost: 'http://localhost:3000',
widgetsMapping: './src/widgets',
templatesMapping: './src/templates',
onBeforeWidgetRender: './src/hooks/before-widget-render.js', // Optional
viewTransitionWorkaround: false,
includeResponseHeaders: [
'content-security-policy',
'strict-transport-security',
'x-frame-options',
'referrer-policy',
'cache-control'
],
excludeRequestHeaders: [
// For single-site setups or hosting on multiple servers, block the host header
'host'
]
proxyRoutes: [
// Custom URLs that should be proxied to Apostrophe.
// Note that all of /api/v1 is already proxied, so
// this is usually unnecessary
]
})
],
vite: {
ssr: {
// Do not externalize the @apostrophecms/apostrophe-astro plugin, we need
// to be able to use virtual: URLs there
noExternal: [ '@apostrophecms/apostrophe-astro' ],
}
}
});
`

Options

$3

This option is the base URL of your Apostrophe instance. It must contain the
port number if testing locally and/or communicating directly with another instance
on the same server in a small production deployment. This option can be overriden
at runtime with the APOS_HOST environment variable.

During development it defaults automatically to: http://localhost:3000

$3

The file in your project that contains the mapping between Apostrophe widget types and your Astro components (see below).

$3

The file in your project that contains the mapping between Apostrophe templates and your Astro templates (see below).

$3

Path to a hook function that runs before rendering widgets in edit mode. See Widget Render Hook for details.

$3

If set to true, Apostrophe will refresh its admin UI JavaScript on
every page transition, to ensure compatibility with Astro
view transitions.
If you are not using this feature of Astro, you can omit this flag to
improve performance for editors. Ordinary website visitors are
not impacted in any case. We are seeking an alternative solution to
eliminate this option.

$3

An array of HTTP headers that you want to include from Apostrophe to the final response sent to the browser - useful if you want to use an Apostrophe module like @apostrophecms/security-headers and want to keep those headers as configured in Apostrophe and to preserve Apostrophe's caching headers.

At the present time, Astro is not compatible with the nonce property of content-security-policy script-src value. So this is automatically removed with that integration. The rest of the CSP header remains unchanged.

$3

An array of HTTP headers that you want to prevent from being forwarded from the browser to Apostrophe. This is particularly useful in single-site setups where you want to block the host header to allow Astro and Apostrophe to run on different hostnames.

By default, all headers are forwarded except those specified in this array.

$3

This option has been replaced by includeResponseHeaders which provides clearer naming for its purpose. If both options are provided, includeResponseHeaders takes precedence. forwardHeaders will be removed in a future version.

$3

Since the front end of our project is entirely Astro, we'll need to create Astro components corresponding to each
template that Apostrophe would normally render with Nunjucks.

Create your template mapping in src/templates/index.js file.
As shown above, this file path must then be added to your astro.config.mjs file,
in the templatesMapping option of the apostrophe integration.

`js
// src/templates/index.js
import HomePage from './HomePage.astro';
import DefaultPage from './DefaultPage.astro';
import BlogIndexPage from './BlogIndexPage.astro';
import BlogShowPage from './BlogShowPage.astro';
import NotFoundPage from './NotFoundPage.astro';

const templateComponents = {
'@apostrophecms/home-page': HomePage,
'default-page': DefaultPage,
'@apostrophecms/blog-page:index': BlogIndexPage,
'@apostrophecms/blog-page:show': BlogShowPage,
'@apostrophecms/page:notFound': NotFoundPage
};

export default templateComponents;
`

#### How Apostrophe template names work

For ordinary page templates, like the home page or a typical "default" page type
in an Apostrophe project, you can just specify the Apostrophe module name.

For special templates like notFound, and for modules that serve more than one
template, you'll need to specify the complete name. For instance, Apostrophe's
@apostrophecms/blog module contains an @apostrophecms/blog-page page type
that renders an index template when viewing the main page of the blog, and
a show template when viewing a single blog post (a "permalink" page).

If you don't specify the template name, :page is assumed, which is just right
for ordinary page types.

For the "404 Not Found" page, use @apostrophecms/page:notFound, which is
the standard name for this template in ApostropheCMS.

#### Special template names

The integration comes with two additional special template names that can be mapped to Astro templates.
You should not add a module name to these special names:

* apos-fetch-error: served when Apostrophe generates a 500-class error. The integration will set Astro's response status to 500.
* apos-no-template: served when there is no mapping corresponding to the Apostrophe page type for this page.

See below for an example Astro template for the @apostrophe-cms/home-page type. But first,
let's look at widgets.

$3

Similar to Astro page components, Astro widget components replace Apostrophe's usual
widget rendering.

Create your template mapping in a file in your application, for example in a
src/widgets/index.js file. This file path must then be added to your astro.config.mjs file,
in the widgetsMapping option of the apostrophe integration, as seen above.

`js
// src/widgets/index.js

import RichTextWidget from './RichTextWidget.astro';
import ImageWidget from './ImageWidget.astro';
import VideoWidget from './VideoWidget.astro';
import LayoutWidget from '@apostrophecms/apostrophe-astro/widgets/LayoutWidget.astro';
import LayoutColumnWidget from '@apostrophecms/apostrophe-astro/widgets/LayoutColumnWidget.astro';

const widgetComponents = {
// Standard widgets, but we must provide our own Astro components for them
'@apostrophecms/rich-text': RichTextWidget,
'@apostrophecms/image': ImageWidget,
'@apostrophecms/video': VideoWidget,
'@apostrophecms/layout': LayoutWidget,
'@apostrophecms/layout-column': LayoutColumnWidget
};

export default widgetComponents;
`

> Note that even basic widget types like @apostrophecms/image do need an Astro
template in your project. This integration does not currently ship with built-in
Astro templates for all of the common Apostrophe widgets. However, all of the starter kits referenced in this document include all the necessary code for the most common core widgets.

Note that the Apostrophe widget name (on the left) is the name of your widget module without
the -widget part.

> [!TIP]
> The @apostrophecms/layout-widget needs some extra configuration and addition to areas in your ApostropheCMS project. You can read more in the documentation.

The naming of your Astro widget templates is up to you. The above convention is just
a suggestion.

$3

Since Apostrophe is responsible for managing URLs to content, including creating new content and pages
on the fly, you will only need one top-level Astro page component: the [...slug].astro route.

The integration comes with an aposPageFetch method that can be used to automatically
fetch the relevant data for the current URL.

Your [...slug].astro component should look like this:

`js
---
import aposPageFetch from '@apostrophecms/apostrophe-astro/lib/aposPageFetch.js';
import AposLayout from '@apostrophecms/apostrophe-astro/components/layouts/AposLayout.astro';
import AposTemplate from '@apostrophecms/apostrophe-astro/components/AposTemplate.astro';

const aposData = await aposPageFetch(Astro.request);
const bodyClass = myclass;

if (aposData.redirect) {
return Astro.redirect(aposData.url, aposData.status);
}
if (aposData.notFound) {
Astro.response.status = 404;
}
---








`

Thanks to the aposPageFetch call, the aposData object will then contain all of
the information normally provided by data in an ApostropheCMS Nunjucks template.
This includes, but is not limited to:

* page: the page document for the current URL, if any
* piece: the piece document when on a "show page" for a piece page type
* pieces: an array of pieces when on an "index page" for a piece page type
* user: information about the currently logged-in user
* global: the ApostropheCMS global document e.g. global settings, editable global
headers and footers, etc.
* query: the req.query object, giving access to query parameters in the URL.

Any other data that your custom Apostrophe code attaches to req.data is also
available here.

#### Understanding AposLayout

This integration comes with a full managed global layout, replacing the outerLayout.html
used in Nunjucks page templates.

In your [...slug].astro file, use the AposLayout component built into this
integration to leverage the global layout.

To override any aspect of the global layout, take advantage of the following Astro slots,
which are closely related to what ApostropheCMS offers in Nunjucks:

* startHead: slot in the very beginning of the
* standardHead: slot in the middle of , just after