Getting Started with Astro and BCMS

This guide will take you through integrating BCMS with an Astro project. Let’s get started!

To set up a simple Astro blog with BCMS quickly, use the following command:

npx @thebcms/cli create astro starter simple-blog

Follow the on-screen prompts.

This command will:

Initialize a new BCMS project
Add sample content for you
Scaffold an Astro project locally
Set up an .env file and configure the project with BCMS settings

Once it’s ready, simply run:

npm install
npm run dev

For a detailed, step-by-step setup, read on below:

Open your BCMS project

Go to https://app.thebcms.com. Make sure you have some entries in your BCMS project to fetch and display in Astro. For example, create a template called Blog and add a media property called Cover Image.

Create a Blog Entry

Create a new blog entry with the title My First Blog, add a cover image, and write some content (e.g., lorem ipsum).

Create an API Key

Navigate to Administration > Settings > API Keys. Create a new API key, and leave the page open for the next steps. Ensure the key has permission to access entries from the Blog template.

Create an Astro Project

Open your terminal and create a new Astro project using the following command:

npm create astro@latest

Now you can initialize React suport for Astro project:

npx astro add react

Install BCMS Packages

Run the following command to install BCMS-related packages:

npm i --save @thebcms/cli @thebcms/client @thebcms/components-react

Update package.json

Modify the scripts section in package.json as follows:

  "scripts": {
  "dev": "bcms pull types lng ts && astro dev",
  "start": "bcms pull types lng ts && astro dev",
  "build": "bcms pull types lng ts && astro check && astro build",
  "preview": "bcms pull types lng ts && astro preview",
  "astro": "astro"
},

The bcms pull types lng ts command starts the BCMS CLI and pulls types from BCMS, saving them in /bcms/types/. These types work for both JavaScript and TypeScript.

Create bcms.config.cjs

In the root of your project, create a file called bcms.config.cjs and add the following configuration:

module.exports = {
    client: {
        orgId: "YOUR_PROJECT_ORG_ID",
        instanceId: "YOUR_PROJECT_INSTANCE_ID",
        apiKey: {
            id: "API_KEY_ID",
            secret: "API_KEY_SECRET",
        },
    },
};

All the information for this configuration can be found on the API key page you created earlier.

Create .env

Place your API key and project information in .env file:

BCMS_ORG_ID=
BCMS_INSTANCE_ID=
BCMS_API_KEY_ID=
BCMS_API_KEY_SECRET=

Initialize BCMS Client

In the /src directory, create a new file called bcms.ts. Inside, initialize the BCMS client:

import { Client } from '@thebcms/client';

export const bcms = new Client(
  import.meta.env.BCMS_ORG_ID || '',
  import.meta.env.BCMS_INSTANCE_ID || '',
  {
    id: import.meta.env.BCMS_API_KEY_ID || '',
    secret: import.meta.env.BCMS_API_KEY_SECRET || '',
  },
  {
    injectSvg: true,
  }
);

Fetch and Display Data

In /src/pages/bcms-tutorial.astro, fetch data from the BCMS project and display it on the page:

---
import { bcms } from '../bcms';
import type { BlogEntry } from '../../bcms/types/ts';
import { BCMSContentManager, BCMSImage } from '@thebcms/components-react';

const blogs = (await bcms.entry.getAll('blog')) as BlogEntry[];
const bcmsConfig = bcms.getConfig();
---

<main>
  <div class="flex flex-col gap-4">
    {
      blogs.map((blog, blogIdx) => {
        if (!blog.meta.en || !blog.content.en) {
          return '';
        }
        return (
          <div class="flex flex-col gap-8">
            <h1 class="mb-10 text-3xl">{blog.meta.en.title}</h1>
            <BCMSImage
              className="w-full h-60 object-cover"
              media={blog.meta.en.cover_image}
              clientConfig={bcmsConfig}
            />
            <BCMSContentManager items={blog.content.en} />
          </div>
        );
      })
    }
  </div>
</main>

That's it — happy coding!

PreviousNuxt.js