Skip to content
Conloca CMS

Getting Started

Conloca CMS can be added to any Astro project. You install two packages, add the integration to your Astro config, define your visual components, and start editing pages in the browser.

This guide walks you through adding Conloca CMS to an Astro project. By the end, you will have a working visual editor at /__cms where you can create and edit pages.

Prerequisites

Before starting, you need:

  • Bun installed (v1.0+)
  • An existing Astro project with SSR enabled, or a new one created with bun create astro@latest
  • Basic familiarity with Astro — see the Astro docs if you are new

Installation

Install the required packages:

bun add @conloca/astro-cms @astrojs/react @astrojs/node react react-dom
PackagePurpose
@conloca/astro-cmsAstro integration — injects CMS routes, API handler, and admin UI
@astrojs/reactReact support for Astro — required because the Puck visual editor is a React application
@astrojs/nodeNode.js SSR adapter — the CMS API needs a server runtime
react, react-domReact peer dependencies

Configuration

Open your astro.config.mjs and add the Conloca integration:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
import { conlocaCMS } from '@conloca/astro-cms/node';
import react from '@astrojs/react';

export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
  integrations: [
    react(),
    conlocaCMS({
      contentRoot: './content',
      puckConfigPath: './src/puck.config.tsx',
    }),
  ],
});
OptionDescription
contentRootDirectory where Conloca stores content files (VXJSON format). Created automatically on first use.
puckConfigPathPath to your Puck component configuration file (see next step).

Create Your First Puck Config

The Puck config defines the components available in the visual editor. Create a minimal config with a single Heading component:

// src/puck.config.tsx
import type { Config } from '@puckeditor/core';

const config: Config = {
  components: {
    Heading: {
      fields: {
        text: { type: 'text' },
      },
      defaultProps: {
        text: 'Hello, World!',
      },
      render: ({ text }) => <h1>{text}</h1>,
    },
  },
};

export default config;

This registers a Heading component with a single text field. You can add as many components as your site needs — see the Creating Custom Blocks guide for more advanced patterns.

Create the Content Directory

Create the directory where Conloca will store your content:

mkdir -p content

Conloca uses this directory to store content as VXJSON files — a JSON format with content-last field ordering for fast metadata indexing and deterministic ETags. Crash-safe writes are handled separately at runtime via temp file + atomic rename. You do not need to create any files manually; the CMS creates them when you save content.

Start Development

Start the Astro dev server:

bun run dev

Navigate to http://localhost:4321/__cms in your browser. You will see the Conloca CMS dashboard.

Create Your First Page

  1. Click New Page in the CMS dashboard.
  2. Enter a title (e.g., “Home”) and a pathname (e.g., /).
  3. The Puck visual editor opens. Drag the Heading component from the left panel onto the canvas.
  4. Edit the heading text in the right panel.
  5. Click Save. The save indicator in the top bar confirms the content was written to disk.
  6. Open http://localhost:4321/ in a new tab to see your page rendered with the heading you just created.

Your content is now stored in the content/ directory as VXJSON files. These files are plain JSON that you can commit to version control alongside your code.

Next Steps

You now have a working Conloca CMS installation. Here is where to go next: