feat: Add official Astro frontend template

Open
#493 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
25/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Stale
Tech stack
tailwindcss, typescript
Domain
cloud, frontend

Research direction

Start with the proposed templates/astro-frontend/ tree and the API helper src/lib/sonicjs.ts, which calls /api/collections/blog-posts/content. Run a local SonicJS backend, then check that the helper's responses match the shapes the issue assumes. Done means the blog listing and post pages render real content from that API. The open questions (separate package or CLI integration, SSG vs SSR) need a maintainer decision before the work can start.

Written by the indexing model from the issue text.

Description

area: developer-experience enhancement priority: P2

Summary

Add an official Astro frontend template that integrates with SonicJS, providing developers with a ready-to-use frontend starter that pairs with the existing backend starter template.

Motivation

Current State
  • SonicJS is a headless CMS - it provides a REST API but no frontend
  • The current create-sonicjs CLI only offers a backend starter template
  • Users must build their own frontend from scratch
  • No pre-built examples of how to consume the SonicJS API
Why Astro?

Astro is an excellent match for SonicJS:

Feature Astro SonicJS Synergy
Target Use Case Content-driven sites Headless CMS Perfect pairing
Performance Focus Zero JS by default Edge-first on Workers Both optimized for speed
Cloudflare Deploy First-class support Built for Workers Full Cloudflare stack
Content Model Works with any CMS Exposes REST API Standard integration

Astro stats that matter:

  • 63% of Astro sites achieve good Core Web Vitals (vs 27% for Next.js)
  • Purpose-built for blogs, docs, marketing sites - SonicJS's sweet spot
  • Server-first rendering reduces JavaScript overhead
  • Built-in content collections with TypeScript safety

Proposed Template Structure

templates/astro-frontend/
├── astro.config.mjs          # Astro + Cloudflare adapter config
├── package.json
├── tsconfig.json
├── wrangler.toml             # Cloudflare Pages deployment
├── .env.example              # SONICJS_API_URL config
├── public/
│   └── favicon.svg
└── src/
    ├── components/
    │   ├── Header.astro
    │   ├── Footer.astro
    │   ├── PostCard.astro
    │   └── Pagination.astro
    ├── layouts/
    │   ├── BaseLayout.astro
    │   └── PostLayout.astro
    ├── lib/
    │   └── sonicjs.ts        # SonicJS API client helper
    ├── pages/
    │   ├── index.astro       # Homepage with latest posts
    │   ├── blog/
    │   │   ├── index.astro   # Blog listing with pagination
    │   │   └── [slug].astro  # Individual post page
    │   └── 404.astro
    └── styles/
        └── global.css        # Minimal Tailwind styles

Key Implementation Details

1. SonicJS API Client (src/lib/sonicjs.ts)
const API_BASE = import.meta.env.SONICJS_API_URL || 'http://localhost:8787';

export interface SonicJSContent {
  id: string;
  title: string;
  slug: string;
  status: string;
  collectionId: string;
  data: Record<string, any>;
  created_at: number;
  updated_at: number;
}

export interface SonicJSResponse<T> {
  data: T;
  meta: {
    count: number;
    cache: { hit: boolean; source: string };
  };
}

export async function getPublishedPosts(limit = 10, offset = 0) {
  const filter = encodeURIComponent(JSON.stringify({
    and: [{ field: 'status', operator: 'equals', value: 'published' }]
  }));
  
  const res = await fetch(
    `${API_BASE}/api/collections/blog-posts/content?where=${filter}&limit=${limit}&offset=${offset}`
  );
  
  return res.json() as Promise<SonicJSResponse<SonicJSContent[]>>;
}

export async function getPostBySlug(slug: string) {
  const filter = encodeURIComponent(JSON.stringify({
    and: [{ field: 'data.slug', operator: 'equals', value: slug }]
  }));
  
  const res = await fetch(
    `${API_BASE}/api/collections/blog-posts/content?where=${filter}&limit=1`
  );
  
  const { data } = await res.json() as SonicJSResponse<SonicJSContent[]>;
  return data[0] || null;
}
2. Blog Listing Page (src/pages/blog/index.astro)
---
import { getPublishedPosts } from '../../lib/sonicjs';
import BaseLayout from '../../layouts/BaseLayout.astro';
import PostCard from '../../components/PostCard.astro';

const { data: posts, meta } = await getPublishedPosts(10);
---

<BaseLayout title="Blog">
  <h1>Blog Posts</h1>
  <div class="post-grid">
    {posts.map(post => <PostCard post={post} />)}
  </div>
</BaseLayout>
3. Dynamic Post Page (src/pages/blog/[slug].astro)
---
import { getPublishedPosts, getPostBySlug } from '../../lib/sonicjs';
import PostLayout from '../../layouts/PostLayout.astro';

export async function getStaticPaths() {
  const { data: posts } = await getPublishedPosts(1000);
  return posts.map(post => ({
    params: { slug: post.data.slug },
    props: { post }
  }));
}

const { post } = Astro.props;
---

<PostLayout title={post.title}>
  <article>
    <h1>{post.title}</h1>
    <time>{new Date(post.created_at).toLocaleDateString()}</time>
    <div set:html={post.data.content} />
  </article>
</PostLayout>
4. Cloudflare Deployment (wrangler.toml)
name = "my-sonicjs-frontend"
compatibility_date = "2024-01-01"
pages_build_output_dir = "./dist"

[vars]
SONICJS_API_URL = "https://your-sonicjs-api.workers.dev"

Integration with create-sonicjs CLI

The CLI could be updated to offer template selection:

$ npx create-sonicjs my-project

? What would you like to create?
  ❯ Backend only (SonicJS CMS)
    Frontend only (Astro)
    Full-stack (Backend + Astro frontend)

Features Included

  • Homepage with latest blog posts
  • Blog listing page with pagination
  • Individual blog post pages with dynamic routing
  • Responsive design with Tailwind CSS
  • SEO meta tags and Open Graph support
  • RSS feed generation
  • Sitemap generation
  • 404 page
  • Type-safe SonicJS API client
  • Environment-based API URL configuration
  • Cloudflare Pages deployment ready
  • Image optimization for media from SonicJS

Future Considerations

  1. Additional templates: Portfolio, docs site, e-commerce storefront
  2. SSR mode: For dynamic content that can't be statically generated
  3. Preview mode: Draft content preview with authentication
  4. Image component: Wrapper for SonicJS media with Cloudflare Images optimization

Related


Would love feedback on:

  1. Should this be a separate npm package (create-sonicjs-astro) or integrated into create-sonicjs?
  2. What additional pages/features should be included in the template?
  3. Should we support both static (SSG) and server-rendered (SSR) modes?
Dominant language
TypeScript
Stars
1.8k
Forks
219
Avg merge
2d 21h
Merged PRs (30d)
67

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from SonicJs-Org/sonicjs

All issues in SonicJs-Org/sonicjs

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.