dotCMS logodotCMS logo

Astro Quick Start Guide

Astro Quick Start Guide
getting startedastro

This guide teaches you how to integrate an Astro website with dotCMS and use the Universal Visual Editor (UVE) to manage the layout and rendering of content.

Overview

dotCMS integrates with Astro to support a wide assortment of features. We'll be focusing on:

  • Creating and authenticating an Astro front end for use with the dotCMS back end

  • Configuring your site to integrate with the Universal Visual Editor (UVE)

  • Editing page layout and content with the UVE

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: 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 http://localhost:4321 to render in your browser.

Step 2: Configure and Run

Generate an API Token

Before creating your Angular application, access the demo.dotcms.com instance (or your local instance) and generate an API Access Token for the Admin User:

  • If accessing the dotCMS demo instance:

  • Create an API Access Token: 

    • Navigate to Settings > Users

    • Select the Admin User

    • Click the API Access Tokens tab

    • Click the Request New Token button.

Configure the Connection to dotCMS

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

Open the .env 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 dotCMS instance, such as https://demo.dotcms.com or http://localhost:8082.

  • PUBLIC_DOTCMS_SITE_ID: (Optional for a single-site instance.) This can be either the Site ID or Site key for the website you will be managing in the dotCMS instance.

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 http://localhost:4321 on your browser, you’ll see the dotCMS Astro example application running.

Astro Output.png

🎉 Congratulations! The application is running. Now, let's complete the integration by getting the editor involved.

Step 3: Universal Visual Editor

The dotCMS Universal Visual Editor (UVE) provides a seamless editing experience directly on your Astro website. This editor offers a powerful way to build pages, with features including, but not limited to:

  • In-context editing: Edit content directly on your website

  • Drag-and-drop interface: Easily arrange components on the page

  • Responsive design tools: Preview and edit for different screen sizes

Enabling the Universal Visual Editor

Now, we need to configure the Universal Visual Editor application within your dotCMS instance. This will allow it to recognize the Angular application and render it in the UVE.

  • In dotCMS, navigate to Settings > Apps and click on “UVE - Universal Visual Editor”

  • Click the plus button at the right of the site we're integrating (i.e., demo.dotcms.com).

  • In the Configuration field, add the following JSON object, which contains the URL for your local Astro application:

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

Click Save.

Now, navigate to Site > Pages > Home to check out the Angular application integrated with dotCMS!

Editing Content in the Universal Visual Editor

Let’s edit the “Home” page.

Drag and Drop Content to the page

  • Navigate to Site > Pages > Home if you are not already there.  With the Home page open in the UVE, 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.

  • 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.

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