@django-stack/cli 0.3.0 → 0.4.0

package/templates/base/SECURITY.md

@@ -9,4 +9,4 @@ Problems in the packages it is built on go to their projects:
 - Django Headless: https://github.com/dwarsbit/django-headless/security
 - Django Content Studio: https://github.com/dwarsbit/django-content-studio/security
 - Django: https://www.djangoproject.com/security/
-- Astro: https://github.com/withastro/astro/security
+- {{frontend_label}}: {{frontend_security}}

package/templates/base/gitignore

@@ -10,7 +10,13 @@ backend/db.sqlite3
 __pycache__/
 *.pyc
 frontend/dist/
+frontend/build/
 frontend/.astro/
+frontend/.svelte-kit/
+frontend/.nuxt/
+frontend/.output/
+frontend/.next/
+frontend/next-env.d.ts
 .DS_Store
 backend/backups/
 backend/huey-stats.db*

package/templates/base/package.json

@@ -1,7 +1,7 @@
 {
   "name": "{{project_name}}",
   "private": true,
-  "description": "{{project_name}}: Django, Django Headless, Content Studio and Astro, created with DjangoStack.",
+  "description": "{{project_name}}: Django, Django Headless, Content Studio and {{frontend_label}}, created with DjangoStack.",
   "scripts": {
     "dev": "docker compose up --build",
     "start": "docker compose up --build --detach",

package/templates/frontend-astro/AGENTS.md

@@ -0,0 +1,43 @@
+# The Astro frontend
+
+Astro renders the site on the server (`output: "server"`, Node adapter).
+The project's `AGENTS.md` describes the whole project; this file describes
+the frontend.
+
+## Layout
+
+```
+src/pages/             routes: /, /[...slug], /blog, /blog/[slug], /category/[slug], /tag/[slug], sitemap.xml, rss.xml, robots.txt, /preview, /revalidate
+src/layouts/Base.astro the page shell: head, menus, footer, preview banner
+src/components/        Blocks.astro maps block types to components in components/blocks/
+src/lib/api.ts         getContent(): content helpers with the read-only key, drafts in preview
+src/lib/cache.ts       the in-memory page cache that /revalidate empties
+src/lib/headless.ts    generated API types; do not edit, run `npm run generate:types`
+src/middleware.ts      page cache, editor-managed redirects, security headers
+astro.config.mjs       server output, Content-Security-Policy, the dev proxy to Django
+```
+
+## Read a content model
+
+```astro
+---
+// src/pages/events.astro
+import { getClient } from "../lib/api";
+
+const events = await getClient(Astro.cookies).model("content.event").list();
+---
+```
+
+## Render a block type
+
+Add a component in `src/components/blocks/` that takes a `block` prop, and
+map the block's type to it in `src/components/Blocks.astro`.
+
+## Commands
+
+Run them in the `frontend` container (`docker compose exec frontend <command>`):
+
+| Task | Command |
+|------|---------|
+| Type-check | `npm run check` |
+| Test | `npm test` |

package/templates/frontend-astro/package.json

@@ -16,7 +16,7 @@
     "@astrojs/node": "^11.1.9",
     "@astrojs/rss": "^4.0.19",
     "@django-headless/client": "^1.1.1",
-    "@django-stack/utils": "^0.3.0",
+    "@django-stack/utils": "^0.4.0",
     "astro": "^7.4.5"
   },
   "devDependencies": {

package/templates/frontend-astro/template.json

@@ -0,0 +1,5 @@
+{
+  "label": "Astro",
+  "url": "https://astro.build",
+  "security": "https://github.com/withastro/astro/security"
+}

package/templates/frontend-next/.dockerignore

@@ -0,0 +1,3 @@
+node_modules
+.next
+.env

package/templates/frontend-next/AGENTS.md

@@ -0,0 +1,59 @@
+# The Next.js frontend
+
+Next.js renders the site on the server with the App Router. Content is
+loaded in server components and route handlers only, through `src/lib/api.ts`,
+so the API key stays on the server. The project's `AGENTS.md` describes the
+whole project; this file describes the frontend.
+
+## Layout
+
+```
+src/app/                 routes: /, /[...path], /blog, /blog/[slug], /category/[slug], /tag/[slug], sitemap.xml, rss.xml, robots.txt, /preview, /revalidate
+src/app/layout.tsx       the page shell: menus, footer, preview banner
+src/components/          the post list, the menu links and the contact form
+src/lib/api.ts           getContent(): content helpers with the read-only key, drafts in preview; pageMetadata()
+src/lib/headless.ts      generated API types; do not edit, run `npm run generate:types`
+src/proxy.ts             Content-Security-Policy with a nonce, security headers, the dev proxy to Django
+next.config.ts           standalone output, the in-memory data cache
+```
+
+Blocks, rich text and images come from `@django-stack/react`; the
+`/preview` and `/revalidate` handlers, the metadata and the
+Content-Security-Policy from `@django-stack/next`.
+
+API responses are kept in Next's data cache with the tag `content` for
+`CACHE_TTL` seconds (default 300). `/revalidate` expires the tag when
+editors publish. Previews and the dev server skip the cache.
+
+## Read a content model
+
+```tsx
+// src/app/events/page.tsx
+import { getClient } from "@/lib/api";
+
+export default async function Events() {
+  const events = await (await getClient()).model("content.event").list();
+  return <ul>{events.data.map((event) => <li key={event.id}>{event.title}</li>)}</ul>;
+}
+```
+
+`src/lib/api.ts` imports `server-only`: a client component (`"use client"`)
+that imports it fails the build.
+
+## Render a block type
+
+Add a component that takes a `block` prop, and pass it to `Blocks` by the
+block's type:
+
+```tsx
+<Blocks blocks={page.body} components={{ gallery: Gallery }} />
+```
+
+## Commands
+
+Run them in the `frontend` container (`docker compose exec frontend <command>`):
+
+| Task | Command |
+|------|---------|
+| Type-check | `npm run check` |
+| Test | `npm test` |

package/templates/frontend-next/Dockerfile

@@ -0,0 +1,32 @@
+# syntax=docker/dockerfile:1
+
+# The frontend image. The `dev` target runs the Next dev server with the
+# source mounted; `prod` builds the site and runs Next's standalone server.
+FROM node:22-alpine AS base
+WORKDIR /app
+ENV NEXT_TELEMETRY_DISABLED=1
+
+FROM base AS deps
+COPY package.json package-lock.json* ./
+COPY vendor/ vendor/
+RUN --mount=type=cache,target=/root/.npm \
+    if [ -f package-lock.json ]; then npm ci; else npm install; fi
+
+FROM deps AS dev
+EXPOSE 3000
+CMD ["npm", "run", "dev"]
+
+FROM deps AS build
+COPY . .
+RUN npm run build
+
+FROM base AS prod
+ENV NODE_ENV=production HOSTNAME=0.0.0.0 PORT=3000
+COPY --from=build --chown=node:node /app/.next/standalone ./
+COPY --from=build --chown=node:node /app/.next/static ./.next/static
+COPY --from=build --chown=node:node /app/public ./public
+USER node
+EXPOSE 3000
+HEALTHCHECK --interval=10s --timeout=5s --start-period=20s --retries=5 \
+    CMD wget -qO- http://127.0.0.1:3000/robots.txt > /dev/null || exit 1
+CMD ["node", "server.js"]

package/templates/frontend-next/next.config.ts

@@ -0,0 +1,19 @@
+import type { NextConfig } from "next";
+
+const config: NextConfig = {
+  // A self-contained server in .next/standalone, for a small production image.
+  output: "standalone",
+  // Django's paths end in a slash; the dev proxy in src/proxy.ts passes them on as they are.
+  skipTrailingSlashRedirect: true,
+  // Django calls /revalidate at http://frontend:3000 on the Compose network.
+  allowedDevOrigins: ["frontend"],
+  poweredByHeader: false,
+  experimental: {
+    // The data cache stays in memory: the production container's file system is read-only.
+    isrFlushToDisk: false,
+    // Media uploads in the admin pass through the dev proxy.
+    proxyClientMaxBodySize: "100mb",
+  },
+};
+
+export default config;

package/templates/frontend-next/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "{{project_name}}-frontend",
+  "private": true,
+  "type": "module",
+  "version": "0.1.0",
+  "scripts": {
+    "dev": "next dev --hostname 0.0.0.0 --port 3000",
+    "build": "next build",
+    "start": "next start --hostname 0.0.0.0 --port 3000",
+    "check": "next typegen && tsc --noEmit",
+    "test": "vitest run",
+    "generate:types": "headless generate --url \"${API_URL:-http://localhost:8000/api}/schema\" --out src/lib/headless.ts"
+  },
+  "dependencies": {
+    "@django-headless/client": "^1.1.1",
+    "@django-stack/next": "^0.4.0",
+    "@django-stack/react": "^0.4.0",
+    "@django-stack/utils": "^0.4.0",
+    "next": "^16.4.4",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "server-only": "^0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.7",
+    "typescript": "~6.0.3",
+    "vitest": "^5.1.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/templates/frontend-next/public/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="6" fill="#0c4b33"/><path d="M8 9h10a6 6 0 0 1 0 12h-4v3H8z" fill="#44b78b"/><path d="M14 13h4a2 2 0 0 1 0 4h-4z" fill="#0c4b33"/></svg>

package/templates/frontend-next/src/app/[...path]/page.tsx

@@ -0,0 +1,28 @@
+import { Blocks } from "@django-stack/react";
+import type { Metadata } from "next";
+import { ContactForm } from "@/components/ContactForm";
+import { getContent, notFoundOrRedirect, pageMetadata } from "@/lib/api";
+
+type Props = { params: Promise<{ path: string[] }> };
+
+async function load(params: Props["params"]) {
+  const path = (await params).path.join("/");
+  return { path, page: await (await getContent()).getPage(path) };
+}
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { path, page } = await load(params);
+  return page ? pageMetadata(page, `/${path}`) : {};
+}
+
+export default async function ContentPage({ params }: Props) {
+  const { path, page } = await load(params);
+  if (!page) return notFoundOrRedirect(`/${path}`);
+  return (
+    <article className="narrow">
+      <h1>{page.title}</h1>
+      <Blocks blocks={page.body} />
+      {page.path === "contact" ? <ContactForm /> : null}
+    </article>
+  );
+}

package/templates/frontend-next/src/app/blog/[slug]/page.tsx

@@ -0,0 +1,60 @@
+import { Blocks, Image } from "@django-stack/react";
+import type { Author, Taxonomy } from "@django-stack/utils";
+import type { Metadata } from "next";
+import Link from "next/link";
+import { getContent, notFoundOrRedirect, pageMetadata } from "@/lib/api";
+
+type Props = { params: Promise<{ slug: string }> };
+
+async function load(params: Props["params"]) {
+  const { slug } = await params;
+  return { slug, post: await (await getContent()).getPost(slug) };
+}
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { slug, post } = await load(params);
+  return post ? pageMetadata(post, `/blog/${slug}`, "article") : {};
+}
+
+export default async function BlogPost({ params }: Props) {
+  const { slug, post } = await load(params);
+  if (!post) return notFoundOrRedirect(`/blog/${slug}`);
+  const author = typeof post.author === "object" ? (post.author as Author | null) : null;
+  const categories = post.categories.filter((item): item is Taxonomy => typeof item === "object");
+  const tags = post.tags.filter((item): item is Taxonomy => typeof item === "object");
+  const date = post.published_at ? new Date(post.published_at) : null;
+  return (
+    <article className="narrow">
+      <p className="muted">
+        {date ? (
+          <time dateTime={date.toISOString()}>{date.toLocaleDateString("en", { dateStyle: "long" })}</time>
+        ) : null}
+        {author ? <span> · {author.name}</span> : null}
+        {categories.map((category) => (
+          <span key={category.slug}>
+            {" · "}
+            <Link href={`/category/${category.slug}`}>{category.name}</Link>
+          </span>
+        ))}
+      </p>
+      <h1>{post.title}</h1>
+      <Image
+        media={post.cover}
+        size="content"
+        sizes="(min-width: 48rem) 44rem, 100vw"
+        className="post-cover"
+        eager
+      />
+      <Blocks blocks={post.body} />
+      {tags.length > 0 ? (
+        <p className="tags">
+          {tags.map((tag) => (
+            <Link key={tag.slug} href={`/tag/${tag.slug}`}>
+              #{tag.name}
+            </Link>
+          ))}
+        </p>
+      ) : null}
+    </article>
+  );
+}

package/templates/frontend-next/src/app/blog/page.tsx

@@ -0,0 +1,20 @@
+import type { Metadata } from "next";
+import { PostList } from "@/components/PostList";
+import { getContent, pageMetadata, pageNumber } from "@/lib/api";
+
+type Props = { searchParams: Promise<{ page?: string }> };
+
+export function generateMetadata(): Promise<Metadata> {
+  return pageMetadata({ title: "Blog" }, "/blog");
+}
+
+export default async function Blog({ searchParams }: Props) {
+  const page = pageNumber((await searchParams).page);
+  const result = await (await getContent()).getPosts({ page, limit: 9 });
+  return (
+    <section className="container">
+      <h1>Blog</h1>
+      <PostList result={result} base="/blog" />
+    </section>
+  );
+}

package/templates/frontend-next/src/app/category/[slug]/page.tsx

@@ -0,0 +1,34 @@
+import type { Metadata } from "next";
+import { PostList } from "@/components/PostList";
+import { getContent, notFoundOrRedirect, pageMetadata, pageNumber } from "@/lib/api";
+
+type Props = { params: Promise<{ slug: string }>; searchParams: Promise<{ page?: string }> };
+
+async function load(params: Props["params"]) {
+  const { slug } = await params;
+  return { slug, category: await (await getContent()).getCategory(slug) };
+}
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { slug, category } = await load(params);
+  if (!category) return {};
+  return pageMetadata(
+    { title: category.name, seo_description: category.description ?? "" },
+    `/category/${slug}`,
+  );
+}
+
+export default async function Category({ params, searchParams }: Props) {
+  const { slug, category } = await load(params);
+  if (!category) return notFoundOrRedirect(`/category/${slug}`);
+  const page = pageNumber((await searchParams).page);
+  const result = await (await getContent()).getPosts({ category: slug, page, limit: 9 });
+  return (
+    <section className="container">
+      <p className="muted">Category</p>
+      <h1>{category.name}</h1>
+      {category.description ? <p>{category.description}</p> : null}
+      <PostList result={result} base={`/category/${slug}`} />
+    </section>
+  );
+}

package/templates/frontend-next/src/app/error.tsx

@@ -0,0 +1,13 @@
+"use client";
+
+export default function ErrorPage() {
+  return (
+    <section className="narrow">
+      <h1>Something went wrong</h1>
+      <p>The page could not be shown. Try again in a moment.</p>
+      <p>
+        <a href="/">Go to the home page</a>
+      </p>
+    </section>
+  );
+}

package/templates/frontend-next/src/app/globals.css

@@ -0,0 +1,250 @@
+/* A small, plain stylesheet: replace it with your own design. */
+:root {
+  --color-bg: #ffffff;
+  --color-text: #1d2420;
+  --color-muted: #5b6862;
+  --color-line: #e3e8e4;
+  --color-accent: #0c4b33;
+  --color-accent-soft: #e8f3ee;
+  --font-body: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  --width: 72rem;
+  --width-text: 44rem;
+  color-scheme: light dark;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-bg: #111614;
+    --color-text: #e6ebe8;
+    --color-muted: #a1aba6;
+    --color-line: #2a322e;
+    --color-accent: #6fcf9f;
+    --color-accent-soft: #1b2a23;
+  }
+}
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  background: var(--color-bg);
+  color: var(--color-text);
+  font-family: var(--font-body);
+  line-height: 1.6;
+}
+
+a {
+  color: var(--color-accent);
+}
+
+img {
+  max-width: 100%;
+  height: auto;
+}
+
+.container {
+  width: min(100% - 2rem, var(--width));
+  margin-inline: auto;
+}
+
+.narrow {
+  width: min(100% - 2rem, var(--width-text));
+  margin-inline: auto;
+}
+
+.muted {
+  color: var(--color-muted);
+}
+
+.prose h2,
+.prose h3 {
+  line-height: 1.25;
+  margin-top: 2em;
+}
+
+.prose blockquote {
+  margin: 2rem 0;
+  padding-left: 1.25rem;
+  border-left: 4px solid var(--color-accent);
+}
+
+.button {
+  display: inline-block;
+  padding: 0.6rem 1.2rem;
+  border-radius: 0.5rem;
+  background: var(--color-accent);
+  color: var(--color-bg);
+  font-weight: 600;
+  text-decoration: none;
+  border: 0;
+  cursor: pointer;
+  font-family: inherit;
+  font-size: inherit;
+}
+
+.grid {
+  display: grid;
+  gap: 2rem;
+  grid-template-columns: repeat(auto-fill, minmax(18rem, 1fr));
+}
+
+.preview-banner {
+  background: #fde68a;
+  color: #422006;
+  padding: 0.5rem 1rem;
+  text-align: center;
+  font-size: 0.9rem;
+}
+
+/* Blocks, from @django-stack/react. */
+.block-image {
+  margin: 2rem 0;
+}
+
+.block-image img {
+  border-radius: 0.5rem;
+}
+
+.block-image figcaption {
+  font-size: 0.9rem;
+  margin-top: 0.5rem;
+}
+
+.cta {
+  margin: 2.5rem 0;
+  padding: 2rem;
+  border-radius: 0.75rem;
+  background: var(--color-accent-soft);
+}
+
+.cta h2 {
+  margin-top: 0;
+}
+
+/* The page shell. */
+.site-header {
+  border-bottom: 1px solid var(--color-line);
+}
+
+.bar {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 1rem;
+  align-items: center;
+  justify-content: space-between;
+  padding-block: 1rem;
+}
+
+.brand {
+  font-weight: 700;
+  font-size: 1.2rem;
+  color: inherit;
+  text-decoration: none;
+}
+
+.brand img {
+  height: 2.5rem;
+  width: auto;
+}
+
+.bar nav {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 1.25rem;
+}
+
+.bar nav a {
+  text-decoration: none;
+}
+
+.bar nav a[aria-current="page"] {
+  font-weight: 600;
+  text-decoration: underline;
+}
+
+main {
+  min-height: 70vh;
+  padding-block: 2rem 4rem;
+}
+
+.site-footer {
+  border-top: 1px solid var(--color-line);
+  font-size: 0.9rem;
+}
+
+.site-footer .footer-text p {
+  margin: 0;
+}
+
+/* Posts. */
+.card h3 {
+  margin: 0.75rem 0 0.25rem;
+  line-height: 1.3;
+}
+
+.card h3 a {
+  color: inherit;
+  text-decoration: none;
+}
+
+.card .cover {
+  width: 100%;
+  aspect-ratio: 16 / 10;
+  object-fit: cover;
+  border-radius: 0.5rem;
+}
+
+.card .meta {
+  font-size: 0.9rem;
+  margin: 0;
+}
+
+.pagination {
+  display: flex;
+  gap: 1.5rem;
+  justify-content: center;
+  margin: 3rem 0;
+}
+
+.post-cover {
+  width: 100%;
+  border-radius: 0.75rem;
+}
+
+.tags {
+  display: flex;
+  gap: 1rem;
+  margin-top: 3rem;
+}
+
+/* The contact form. */
+.contact-form {
+  display: grid;
+  gap: 1rem;
+  max-width: 32rem;
+  margin-top: 2rem;
+}
+
+.contact-form label {
+  display: grid;
+  gap: 0.25rem;
+  font-weight: 600;
+}
+
+.contact-form input,
+.contact-form textarea {
+  font: inherit;
+  padding: 0.5rem 0.75rem;
+  border: 1px solid var(--color-line);
+  border-radius: 0.375rem;
+  background: transparent;
+  color: inherit;
+}
+
+.contact-form button {
+  justify-self: start;
+}