Quick Start Guide

This guide teaches you how to integrate an Astro website with dotCMS and use the Universal Visual Editor to manage content rendered in the Astro application.

Overview

DotCMS integrates with Astro to support all of DotCMS's features:

✓ Build pages using the Universal Visual Editor (UVE)
✓ Edit content directly on your website with real-time previews
✓ Preview pages before publishing with full-website previews
✓ Model content with DotCMS's content types system
✓ Fetch and display DotCMS content using the REST API or GraphQL
✓ Write content in multiple languages with localization support

Prerequisites

DotCMS websites use @dotcms/client, @dotcms/react, and @dotcms/next.
Node.js & npm/yarn: Ensure you have Node.js and npm installed.
Basic Knowledge: Familiarity with Astro fundamentals and REST/API concepts.

Step 1: Access the dotCMS Backend and Generate an API Access Token

Before creating your Astro application, access the demo.dotcms.com instance and generate an API Access Token for the Admin User:

Access the dotCMS demo instance:
- https://demo.dotcms.com/dotAdmin
- UN: admin@dotcms.com / PW: admin
- Note: The demo instance is reset twice per day
Create an API Access Token: Navigate to Settings > Users, select the Admin User and click the API Access Tokens tab. Click the Request New Token button and create the new token. This will be used in the Astro application.

Step 2: Create Your Astro Application

Use the official dotCMS Astro sample site as a template to create your Astro application locally. Navigate to the directory you want to install the Astro application in and run the command below, this will create an Astro application based on the dotCMS sample.

npm create astro@latest -- --template dotcms/core/examples/astro

Follow the Astro setup steps after the example is pulled. This creates an Astro application that uses localhost :4321 to render in your browser.

Configure Your Connection to dotCMS

Open the Astro project in your code editor at the root, find the file .env.local.example and rename it to .env.local. This file will contain the environment variables for the demo.dotcms.com instance.

Open the .env.local file and update the following environment variables:

PUBLIC_DOTCMS_AUTH_TOKEN: This is the API Access Token you generated for the Admin user in the demo.dotcms.com instance in Step 1 above.
PUBLIC_DOTCMS_HOST: This is the URL for the demo.dotcms.com instance: https://demo.dotcms.com
PUBLIC_DOTCMS_SITE_ID: This is the Site ID for the website you will be managing in the dotcms instance. Instructions on finding this ID are below

To find your Site ID:

Go to Settings > Sites in your dotCMS instance
Select the desired Site (A modal should open)
Go to the History Tab
Copy the Identifier that appears at the top of the tab

Run the dotCMS Astro application locally

Run the dotCMS Astro example locally to see it in our browser. Navigate to the root directory of your Astro application (e.g. intergalactic-inclination) and execute the following:

npm install
npm run dev

Your terminal will output the following, and when you navigate to localhost:4321 on your browser, you’ll see the dotCMS Astro example application running.

Step 3: Universal Visual Editor

The DotCMS Universal Visual Editor (UVE) provides a seamless editing experience directly on your Astro website.

Key features:

In-context editing: Edit content directly on your website
Drag-and-drop interface: Easily arrange components on the page
Component library: Access all your custom React components
Responsive design tools: Preview and edit for different screen sizes
Multi-language support: Edit content in different languages
Workflow integration: Submit changes for approval within the editor

Enabling the Universal Visual Editor

Now, we need to configure the Universal Visual Editor application within the demo.dotcms.com instance for it to recognize the local Astro application and render it in the UVE inside the demo.dotcms.com back end.

In the demo.dotcms.com instance, navigate to Settings > Apps and click on “UVE - Universal Visual Editor”
Click the plus button at the right of demo.dotcms.com, which represents dotCMS’ Demo site the Astro application is based on.
In the Configuration field, add the following JSON object, which contains the URL for your local Astro application:

{ "config":
  [
    {
      "pattern": ".*",
      "url": "http://localhost:4321",
    }
  ]
}

Now, click Save and navigate to Site > Pages > Home to check out the Astro application integrated with dotCMS!

Editing Content in the Universal Visual Editor

Let’s edit the “Home” page.

Inline text edit

Navigate to Site > Pages > Home if you are not already there. With the Home page open in the UVE, click into the Banner title “Explore the World” and tab over to the end then add ‘of Code', then click out of the banner area. The change will auto save and there will be a message flash at the top that it saved.
Click on the dropdown at the top left of the screen that says ‘Draft’ and select ‘Published’, the screen will refresh to the currently published version, which will not show the change you just made as it is not published yet.
Now select ‘Preview’ from the same dropdown, the screen will show you the draft version you are working on in Preview mode (without the edit controls) so you can see what your change looks like.
Now select ‘Draft’ from the same dropdown to get back to the edit mode.

Drag and Drop Content to the page

Click on the ‘X’ icon at the top right of the Explore the World of Code Banner to remove the banner, click ‘Accept’. You will now see an empty container on the page.
Click on the Banner folder in the right hand panel to open up the set of Banners available to place on the page.
Select the ‘Summer is Here!’ banner (or any other banner) and drag it into the empty box on the page. The new banner will render and the page will be saved.

Adjust Layout of the page and add content

Click on the Layout tool in the right side panel
Drag a ‘Row’ from the Row tool located in the top right of the page and drop it below the first box, then grab an additional three ‘Boxes’ and put them in the new row next to the existing box, resize them all to be equal widths within the new row
Click the Content tool in the right side panel to go back to the page content, you will see the four empty containers
Let’s fill them up with Products! Click on the Product content type on the right hand panel (you may need to use the search at the top right to find the Product content type) and drag over a couple of products into the empty slots
Click the ‘Draft’ button on the top left of the screen, this will bring up a short menu, select ‘Preview’ to check out how the page will look without all the controls of Edit mode
Click back to Draft to get back to the Editing screen
Click the Blue ‘Publish’ button on the top right of the screen
Now refresh the browser window that has the Astro application running (localhost:4321), and you will see the changes you made from the back end

You are now up and running with inline editing and preview of an Astro application inside dotCMS in less than 10 minutes!

Learn more

DotCMS Content Types

DotCMS REST API

Universal Visual Editor

Blog Post - How to Integrate Your Astro App with dotCMS Using the JavaScript SDK