Getting Started

**Referenced Files in This Document** - [README.md](file://README.md) - [package.json](file://package.json) - [.eleventy.js](file://.eleventy.js) - [src/admin/config.yml](file://src/admin/config.yml) - [worker.js](file://worker.js) - [wrangler.jsonc](file://wrangler.jsonc) - [cloudflare-pages.toml](file://cloudflare-pages.toml) - [netlify.toml](file://netlify.toml)

Table of Contents

  1. Introduction
  2. Prerequisites
  3. Installation
  4. Development Workflow
  5. Quick Start Commands
  6. Environment Differences
  7. Troubleshooting
  8. Project Structure Overview
  9. Next Steps

Introduction

Ace Strategies Prime is a modern, serverless communication platform built with Eleventy, Cloudflare Workers, Sveltia CMS, and Pagefind. This platform serves as both a public website and an IAA (Invest Australia Alliance) member portal, featuring content management capabilities powered by Git-based CMS.

The platform combines static site generation with serverless computing to deliver fast, secure, and scalable web experiences. It leverages Cloudflare Workers for member authentication, API endpoints, and dynamic content while maintaining excellent SEO through static HTML generation.

Prerequisites

Before setting up the Ace Strategies Prime platform, ensure you have the following prerequisites installed:

Node.js and npm Requirements

  • Node.js: Version 18 or higher (required)
  • npm: Version 9 or higher (recommended)

Cloudflare Workers CLI

  • Wrangler CLI: Install and authenticate with your Cloudflare account
  • Authentication command: wrangler login

Optional: TinaCMS (Local Development Only)

  • TinaCMS CLI: Only required if you need to rebuild TinaCMS admin files locally
  • Used for npm run build:cms script

Verification Commands

# Check Node.js version
node --version

# Check npm version  
npm --version

# Verify Wrangler installation
wrangler --version

Section sources

  • [README.md:47-53](file://README.md#L47-L53)
  • [package.json:22-24](file://package.json#L22-L24)

Installation

Follow these step-by-step instructions to set up the development environment:

Step 1: Clone and Navigate

# Clone the repository
git clone https://github.com/kamirostami-lab/aces-prime.git
cd aces-prime

Step 2: Install Dependencies

# Install all project dependencies
npm install

Step 3: Configure Cloudflare Workers (First-Time Setup)

# 1. Authenticate with Cloudflare
wrangler login

# 2. Create KV namespaces for member authentication
wrangler kv namespace create MEMBER_EMAILS
wrangler kv namespace create MAGIC_TOKENS

# 3. Add the returned namespace IDs to wrangler.jsonc
# (See wrangler.jsonc comments for instructions)

# 4. Set required secrets
wrangler secret put SESSION_SECRET
wrangler secret put RESEND_API_KEY
wrangler secret put GOOGLE_SHEETS_ID
wrangler secret put GOOGLE_SHEETS_API_KEY

Step 4: Configure Sveltia CMS

The CMS configuration is managed through src/admin/config.yml. This YAML file defines:

  • Content collections (News, Cases, Team, Knowledge Base, etc.)
  • Field definitions for each collection
  • Media upload locations
  • GitHub repository integration

Section sources

  • [README.md:523-548](file://README.md#L523-L548)
  • [src/admin/config.yml:1-10](file://src/admin/config.yml#L1-L10)

Development Workflow

The Ace Strategies Prime platform uses a dual-development approach combining Eleventy for static site generation with Sveltia CMS for content management.

Local Development Modes

Basic Development (Eleventy Only)

# Start Eleventy development server
npm start
# → http://localhost:8080

CMS Development (Eleventy + Sveltia)

# Start development with Sveltia CMS
npm run dev:cms
# → http://localhost:8080 (site)
# → http://localhost:4001 (CMS admin)

Development Features

Live Reload

Both development modes support automatic browser refresh when content changes:

  • Eleventy watches src/assets/css/, src/assets/js/, and src/_data/ directories
  • Changes trigger immediate rebuild and refresh

Content Management

Sveltia CMS provides:

  • Real-time content editing interface
  • Git-backed content storage
  • Media management for images and documents
  • Multi-collection content organization

Section sources

  • [.eleventy.js:19-22](file://.eleventy.js#L19-L22)
  • [package.json:8-9](file://package.json#L8-L9)

Quick Start Commands

Basic Development

# Install dependencies
npm install

# Start local development server
npm start

CMS Development

# Start development with Sveltia CMS
npm run dev:cms

Production Builds

# Build for production
npm run build

# Preview production build locally
npm run preview

# Deploy to Cloudflare Workers
npm run deploy

Clean Operations

# Clean build output
npm run clean

Section sources

  • [README.md:56-76](file://README.md#L56-L76)
  • [package.json:5-12](file://package.json#L5-L12)

Environment Differences

Local Development Environment

  • Port 8080: Eleventy static site server
  • Port 4001: Sveltia CMS admin interface (when using dev:cms)
  • Live reload: Automatic browser refresh on content changes
  • Development mode: No HTML minification or production optimizations
  • Debugging: Full console logging and development tools

Production Environment

  • Static site generation: Eleventy builds complete HTML files
  • Pagefind integration: Client-side search index generation
  • HTML minification: Production-optimized HTML compression
  • Asset optimization: CSS and JavaScript minification
  • Cloudflare Workers: Serverless runtime for member authentication and APIs

Build Process Flow

flowchart TD
Start([Source Files]) --> Eleventy[Eleventy Build]
Eleventy --> Site[_site/ Output]
Site --> Pagefind[Pagefind Index]
Pagefind --> Production[Production Ready]
Production --> Workers[Cloudflare Workers]
Workers --> Deploy[Deployed Site]
subgraph "Development Mode"
DevStart[Local Server] --> DevLive[Live Reload]
DevLive --> DevEdit[Content Editing]
end
subgraph "Production Mode"
ProdBuild[Build Process] --> ProdOpt[Optimizations]
ProdOpt --> ProdDeploy[Deployment]
end

Diagram sources

  • [package.json:6-7](file://package.json#L6-L7)
  • [.eleventy.js:242-261](file://.eleventy.js#L242-L261)

Section sources

  • [README.md:556-586](file://README.md#L556-L586)
  • [.eleventy.js:267-283](file://.eleventy.js#L267-L283)

Troubleshooting

Common Setup Issues

Node.js Version Problems

Issue: ERR_REQUIRE_ESM or compatibility errors Solution: Ensure Node.js 18+ is installed

node --version
# Should output 18.x or higher

Wrangler Authentication Issues

Issue: wrangler login fails or authentication timeout Solution:

# Re-authenticate
wrangler logout
wrangler login

# Verify authentication
wrangler whoami

Missing Environment Variables

Issue: Member authentication fails or polling API errors Solution: Set required secrets in Cloudflare

# Required secrets
wrangler secret put SESSION_SECRET
wrangler secret put RESEND_API_KEY  
wrangler secret put GOOGLE_SHEETS_ID
wrangler secret put GOOGLE_SHEETS_API_KEY

CMS Authentication Problems

Issue: Sveltia CMS login failures Solution: Verify GitHub OAuth configuration in src/admin/config.yml

  • Check repository name and branch
  • Ensure GitHub App permissions are correct

Port Conflicts

Issue: Ports 8080 or 4001 already in use Solution: Change ports in development scripts or stop conflicting processes

# Check for processes using ports
lsof -i :8080
lsof -i :4001

# Kill conflicting processes
kill -9 $(lsof -t -i :8080)

Build Failures

Issue: npm run build fails during Pagefind indexing Solution:

# Clean build artifacts
npm run clean

# Reinstall dependencies
npm install

# Try build again
npm run build

Section sources

  • [README.md:497-520](file://README.md#L497-L520)
  • [README.md:656-664](file://README.md#L656-L664)

Project Structure Overview

The Ace Strategies Prime platform follows a well-organized structure designed for scalability and maintainability:

graph TB
subgraph "Source Directory (src/)"
Data["_data/ - Global data files"]
Includes["_includes/ - Templates and macros"]
Content["content/ - Markdown collections"]
Assets["assets/ - Static assets"]
Admin["admin/ - CMS configuration"]
Templates["Templates - Nunjucks files"]
end
subgraph "Platform Components"
Eleventy[".eleventy.js - Configuration"]
Worker["worker.js - Cloudflare Worker"]
Config["wrangler.jsonc - Deployment config"]
Package["package.json - Scripts & deps"]
end
subgraph "Build Output (_site/)"
Static["Static HTML files"]
AssetsOut["Optimized assets"]
Search["Pagefind search index"]
CMSOut["CMS admin interface"]
end
Data --> Eleventy
Includes --> Eleventy
Content --> Eleventy
Assets --> Eleventy
Eleventy --> Static
Worker --> Static
Static --> AssetsOut
Static --> Search
Static --> CMSOut

Diagram sources

  • [README.md:80-156](file://README.md#L80-L156)
  • [.eleventy.js:267-283](file://.eleventy.js#L267-L283)

Key Directories and Files

Configuration Files

  • .eleventy.js: Eleventy configuration and custom filters
  • wrangler.jsonc: Cloudflare Workers deployment settings
  • package.json: NPM scripts and dependency management

Content Management

  • src/admin/config.yml: Sveltia CMS schema and field definitions
  • src/_data/: Global data files available to all templates
  • src/content/: Markdown collections organized by content type

Static Assets

  • src/assets/css/: Modular CSS architecture
  • src/assets/js/: Client-side JavaScript modules
  • src/assets/repository/images/: Media storage for uploads

Section sources

  • [README.md:80-156](file://README.md#L80-L156)

Next Steps

Getting Started Checklist

  1. ✅ Verify Node.js 18+ installation
  2. ✅ Install project dependencies (npm install)
  3. ✅ Authenticate with Cloudflare (wrangler login)
  4. ✅ Configure required secrets
  5. ✅ Start development server (npm start)

Learning Resources

  • Eleventy Documentation: Learn templating, collections, and transforms
  • Cloudflare Workers: Explore serverless functions and KV storage
  • Sveltia CMS: Master content editing and Git-based publishing
  • Pagefind: Understand client-side search implementation

Contributing Guidelines

  • Follow the existing code structure and naming conventions
  • Test changes in both development and production modes
  • Verify CMS functionality with real content updates
  • Monitor build performance and optimize asset loading

Deployment Pipeline

The platform supports multiple deployment targets:

  • Cloudflare Workers: Primary production deployment
  • Netlify: Alternative hosting option
  • Manual Preview: Local production testing via Wrangler

Section sources

  • [README.md:556-586](file://README.md#L556-L586)
  • [cloudflare-pages.toml:1-17](file://cloudflare-pages.toml#L1-L17)
  • [netlify.toml:1-26](file://netlify.toml#L1-L26)