feat: Add official Astro frontend template

Aperta
#493 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
25/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Ferma
Stack tecnologico
tailwindcss, typescript
Ambito
cloud, frontend

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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?
Lingua principale
TypeScript
Stelle
1.8k
Fork
219
Merge medio
2g 21h
PR unite (30g)
67

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di SonicJs-Org/sonicjs

Tutte le issue di SonicJs-Org/sonicjs

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.