@ayezee/astro-cms

AyeZee CMS integration for Astro with automatic data fetching, form handling, validation, and analytics.

Features

• 🚀 Automatic Data Fetching - Fetches CMS data during build time
• 📊 Analytics Integration - Auto-inject Umami analytics from dashboard settings
• 📦 Type-Safe - Full TypeScript support with proper types
• 🔄 Build-Time Caching - No runtime API calls needed
• ✅ Form Validation - Client-side and server-side validation support
• 🔒 Turnstile Integration - Built-in Cloudflare Turnstile support
• 🎨 Zero Config - Works with environment variables

Installation

npm install @ayezee/astro-cms

Quick Start

1. Add Environment Variables

Create a .env file in your project root:

PUBLIC_CMS_DOMAIN=http://localhost:3000
PUBLIC_PROJECT_SLUG=your-project-slug
PUBLIC_AYEZEE_API_KEY=AZ_your_api_key_here

2. Add Integration to Astro Config

// astro.config.mjs
import { defineConfig } from 'astro/config';
import { ayezeeCms } from '@ayezee/astro-cms/integration';

export default defineConfig({
  integrations: [ayezeeCms()],
});

3. Use CMS Data in Your Pages

---
// src/pages/index.astro
import { initCmsHelper, getModuleData } from '@ayezee/astro-cms';
import cmsData from '../data/cms-cache.json';

// Initialize the helper (only needed once)
initCmsHelper(cmsData);

// Get your data
const testimonials = getModuleData('testimonials');
---

<div>
  {testimonials.map((item) => (
    <div>
      <h3>{item.data.name}</h3>
      <p>{item.data.message}</p>
    </div>
  ))}
</div>

API Reference

Integration Options

ayezeeCms({
  // CMS domain (defaults to PUBLIC_CMS_DOMAIN env var)
  cmsDomain?: string;

  // Project slug (defaults to PUBLIC_PROJECT_SLUG env var)
  projectSlug?: string;

  // Output directory for cache (defaults to 'src/data')
  outputDir?: string;

  // Cache file name (defaults to 'cms-cache.json')
  cacheFileName?: string;

  // Skip build if fetch fails (defaults to false)
  skipOnError?: boolean;

  // Enable automatic Umami analytics injection (defaults to true)
  enableAnalytics?: boolean;
});

Helper Functions

Module Retrieval

import {
  getModule,
  getModuleByLabel,
  getModuleBySlug,
  getModules,
  getModulesByCategory,
  getModulesByDataType,
} from '@ayezee/astro-cms';

// Get by instance key
const module = getModule('contact_form-123');

// Get by label (case-insensitive)
const module = getModuleByLabel('Contact Form');

// Get by slug
const module = getModuleBySlug('contact-form');

// Get all modules
const allModules = getModules();

// Get by category
const formModules = getModulesByCategory('forms');

// Get by type
const collections = getModulesByDataType('collection');

Data Retrieval

import {
  getModuleData,
  getModuleDataByLabel,
  getModuleDataBySlug,
} from '@ayezee/astro-cms';

// Get data by instance key
const data = getModuleData('testimonials-123');

// Get data by label
const data = getModuleDataByLabel('Testimonials');

// Get data by slug
const data = getModuleDataBySlug('testimonials');

Form Configuration

import { getFormConfig, getTurnstileConfig } from '@ayezee/astro-cms';

// Get complete form configuration
const config = getFormConfig('Contact Form');
// Returns: { module, turnstile, apiUrl, apiKey }

// Get just Turnstile config
const turnstile = getTurnstileConfig('Contact Form');
// Returns: { enabled: boolean, siteKey: string | null }

Project & Cache Info

import { getProject, getCacheInfo } from '@ayezee/astro-cms';

// Get project details
const project = getProject();
// Returns: { id, slug, name, domain }

// Get cache metadata
const info = getCacheInfo();
// Returns: { fetchedAt, version, moduleCount }

Analytics

import {
  getAnalyticsConfig,
  isAnalyticsEnabled,
  getAnalyticsWebsiteId,
} from '@ayezee/astro-cms';

// Get full analytics configuration
const analytics = getAnalyticsConfig();
// Returns: { websiteId: string, baseUrl: string } | null

// Check if analytics is enabled
const enabled = isAnalyticsEnabled();
// Returns: boolean

// Get just the website ID
const websiteId = getAnalyticsWebsiteId();
// Returns: string | null

TypeScript Support

The package exports all necessary types:

import type {
  CachedModule,
  ModuleField,
  ModuleDataItem,
  ValidationRules,
  CMSCache,
} from '@ayezee/astro-cms';

Analytics Integration

The integration automatically injects Umami analytics if configured in your AyeZee Dashboard.

How It Works

1. Configure in Dashboard: Set up Umami analytics in your project settings at /admin/projects/{slug}/settings?tab=analytics
2. Automatic Injection: The integration fetches your analytics config and automatically injects the Umami tracking script
3. Zero Configuration: No need to manually add script tags or manage website IDs

Analytics Configuration

Analytics is enabled by default. The script will only be injected if you've configured Umami in the dashboard.

To disable automatic analytics injection:

// astro.config.mjs
export default defineConfig({
  integrations: [
    ayezeeCms({
      enableAnalytics: false, // Disable automatic Umami script injection
    }),
  ],
});

Manual Analytics Setup

If you need more control over when/where the analytics script loads, you can disable auto-injection and add it manually:

---
import { getAnalyticsConfig } from '@ayezee/astro-cms';
import cmsData from '../data/cms-cache.json';

const analytics = cmsData.analytics;
---

{analytics && (
  <script
    defer
    src={`${analytics.baseUrl}/script.js`}
    data-website-id={analytics.websiteId}
  ></script>
)}

Advanced Usage

Custom Cache Location

// astro.config.mjs
export default defineConfig({
  integrations: [
    ayezeeCms({
      outputDir: 'src/custom/location',
      cacheFileName: 'my-cache.json',
    }),
  ],
});

Skip Build on Error

Useful for CI/CD when CMS might be temporarily unavailable:

export default defineConfig({
  integrations: [
    ayezeeCms({
      skipOnError: process.env.NODE_ENV === 'development',
    }),
  ],
});

Runtime Configuration

Override environment variables programmatically:

export default defineConfig({
  integrations: [
    ayezeeCms({
      cmsDomain: 'https://cms.example.com',
      projectSlug: 'my-project',
    }),
  ],
});

How It Works

1. Build Time: The integration fetches all CMS data during astro build or astro dev
2. Caching: Data is saved to src/data/cms-cache.json
3. Runtime: Helper functions read from the cached file (no API calls!)
4. Type Safety: Full TypeScript support with generated types

License

MIT © AyeZee Web Designs