feat: Add official Astro frontend template
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
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
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-sonicjsCLI 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
- Additional templates: Portfolio, docs site, e-commerce storefront
- SSR mode: For dynamic content that can't be statically generated
- Preview mode: Draft content preview with authentication
- Image component: Wrapper for SonicJS media with Cloudflare Images optimization
Related
- Astro docs: https://astro.build
- Astro CMS integrations: https://docs.astro.build/en/guides/cms/
- Astro Cloudflare deployment: https://docs.astro.build/en/guides/deploy/cloudflare/
Would love feedback on:
- Should this be a separate npm package (
create-sonicjs-astro) or integrated intocreate-sonicjs? - What additional pages/features should be included in the template?
- 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
- Ships a Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from SonicJs-Org/sonicjs
-
bug(admin/users): server error returns bare alert HTML causing black-shape visual artifactPossibly taken @lane711 claimed this today. Openbug
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
SonicJs-Org/sonicjs#1211 ·
Maintainers usually reply within 1 day
-
area: api bug priority: P2
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
SonicJs-Org/sonicjs#1200 ·
Maintainers usually reply within 1 day
-
ResendProvider cannot send on Workers: unbound `fetch` stored as an instance property throws "Illegal invocation"Possibly taken @lane711 claimed this 23 days ago. Openarea: email bug priority: P1
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
SonicJs-Org/sonicjs#1099 ·
Maintainers usually reply within 1 day
-
Email plugin settings are never read: loadDbEmailSettings queries a v2 `plugins` table that does not exist in v3Possibly taken @lane711 claimed this 23 days ago. Openarea: email bug priority: P1
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
SonicJs-Org/sonicjs#1098 ·
Maintainers usually reply within 1 day
-
area: documentation bug documentation priority: P2
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
SonicJs-Org/sonicjs#1012 ·
Maintainers usually reply within 1 day
All issues in SonicJs-Org/sonicjs
Similar issues
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 62/100
AloisSeckar/elrh-cosca#36 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 73/100
cursor/community-plugins#572 ·
Maintainers usually reply within 1 day
-
[Plugin] calendarOpen
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
MUKE-coder/grit#228 ·
-
bug status:needs-triage
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
dongdongbh/Mindwtr#1587 ·
Maintainers usually reply within 1 day