@django-stack/cli 0.3.0 → 0.5.0

package/templates/frontend-nuxt/test/rss.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+import { rssFeed } from "../server/utils/rss";
+
+describe("RSS feed", () => {
+  it("lists the posts with absolute links, escaped", () => {
+    const xml = rssFeed({
+      title: "News & notes",
+      description: "",
+      site: "https://example.com",
+      items: [{ title: "<Hello>", link: "/blog/hello", pubDate: new Date("2026-01-02T03:04:05Z") }],
+    });
+    expect(xml).toContain("<title>News &amp; notes</title>");
+    expect(xml).toContain("<title>&lt;Hello&gt;</title>");
+    expect(xml).toContain("<link>https://example.com/blog/hello</link>");
+    expect(xml).toContain("<pubDate>Fri, 02 Jan 2026 03:04:05 GMT</pubDate>");
+  });
+});

package/templates/frontend-nuxt/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./.nuxt/tsconfig.app.json" },
+    { "path": "./.nuxt/tsconfig.server.json" },
+    { "path": "./.nuxt/tsconfig.shared.json" },
+    { "path": "./.nuxt/tsconfig.node.json" }
+  ]
+}

package/templates/frontend-nuxt/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["test/**/*.test.ts"],
+  },
+});

package/templates/frontend-sveltekit/.dockerignore

@@ -0,0 +1,4 @@
+node_modules
+build
+.svelte-kit
+.env

package/templates/frontend-sveltekit/AGENTS.md

@@ -0,0 +1,53 @@
+# The SvelteKit frontend
+
+SvelteKit renders the site on the server (`@sveltejs/adapter-node`). Content
+is loaded in `+page.server.ts` and `+layout.server.ts` only, so the API key
+stays on the server. The project's `AGENTS.md` describes the whole project;
+this file describes the frontend.
+
+## Layout
+
+```
+src/routes/                  routes: /, /[...path], /blog, /blog/[slug], /category/[slug], /tag/[slug], sitemap.xml, rss.xml, robots.txt, /preview, /revalidate
+src/routes/+layout.svelte    the page shell: SEO tags, menus, footer, preview banner
+src/lib/components/          the post list and the contact form
+src/lib/server/api.ts        getContent(): content helpers with the read-only key, drafts in preview
+src/lib/server/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/hooks.server.ts          page cache, editor-managed redirects, security headers
+vite.config.ts               SvelteKit's options (Node adapter, Content-Security-Policy) and the dev proxy to Django
+```
+
+Blocks, rich text, images and SEO tags come from `@django-stack/svelte`.
+
+## Read a content model
+
+```ts
+// src/routes/events/+page.server.ts
+import { getClient } from "#lib/server/api.ts";
+import type { PageServerLoad } from "./$types";
+
+export const load: PageServerLoad = async ({ cookies }) => ({
+  events: await getClient(cookies).model("content.event").list(),
+});
+```
+
+Never import `#lib/server` from a component or a universal `+page.ts`.
+
+## Render a block type
+
+Add a component in `src/lib/components/blocks/` that takes a `block` prop,
+and pass it to `Blocks` by the block's type:
+
+```svelte
+<Blocks blocks={data.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-sveltekit/Dockerfile

@@ -0,0 +1,32 @@
+# syntax=docker/dockerfile:1
+
+# The frontend image. The `dev` target runs the Vite dev server with the
+# source mounted; `prod` builds the site and runs the Node server.
+FROM node:22-alpine AS base
+WORKDIR /app
+
+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 && npm prune --omit=dev
+
+FROM base AS prod
+# The proxy in front sets X-Forwarded-Proto, so links and cookies use https.
+ENV NODE_ENV=production HOST=0.0.0.0 PORT=3000 PROTOCOL_HEADER=x-forwarded-proto
+COPY --from=build --chown=node:node /app/node_modules ./node_modules
+COPY --from=build --chown=node:node /app/build ./build
+COPY --from=build --chown=node:node /app/package.json ./package.json
+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", "build"]

package/templates/frontend-sveltekit/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "{{project_name}}-frontend",
+  "private": true,
+  "type": "module",
+  "version": "0.1.0",
+  "imports": {
+    "#lib": "./src/lib",
+    "#lib/*": "./src/lib/*"
+  },
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "start": "node build",
+    "preview": "vite preview",
+    "prepare": "svelte-kit sync || echo ''",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "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/svelte": "^0.5.0",
+    "@django-stack/utils": "^0.5.0"
+  },
+  "devDependencies": {
+    "@sveltejs/adapter-node": "^6.0.1",
+    "@sveltejs/kit": "^3.1.1",
+    "@sveltejs/vite-plugin-svelte": "^7.3.1",
+    "@types/node": "^22.20.5",
+    "svelte": "^5.57.3",
+    "svelte-check": "^4.7.8",
+    "typescript": "~6.0.3",
+    "vite": "^8.3.5",
+    "vitest": "^5.1.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/templates/frontend-sveltekit/src/app.css

@@ -0,0 +1,126 @@
+/* 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/svelte. */
+.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;
+}

package/templates/frontend-sveltekit/src/app.d.ts

@@ -0,0 +1,12 @@
+// See https://svelte.dev/docs/kit/types#app.d.ts
+import type { SeoInput } from "@django-stack/utils";
+
+declare global {
+  namespace App {
+    interface PageData {
+      /** The page's title, description and share image, for the SEO tags in the layout. */
+      seo?: SeoInput | null;
+      seoType?: "website" | "article";
+    }
+  }
+}

package/templates/frontend-sveltekit/src/app.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="icon" href="%sveltekit.assets%/favicon.svg" type="image/svg+xml" />
+    %sveltekit.head%
+  </head>
+  <body data-sveltekit-preload-data="hover">
+    <div style="display: contents">%sveltekit.body%</div>
+  </body>
+</html>

package/templates/frontend-sveltekit/src/hooks.server.ts

@@ -0,0 +1,70 @@
+import { redirect } from "@sveltejs/kit";
+import type { Handle } from "@sveltejs/kit/hooks";
+import { getContent, PREVIEW_COOKIE } from "#lib/server/api.ts";
+import { getCached, store } from "#lib/server/cache.ts";
+import { dev } from "$app/env";
+
+const SECURITY_HEADERS: Record<string, string> = {
+  "X-Content-Type-Options": "nosniff",
+  "Referrer-Policy": "strict-origin-when-cross-origin",
+  "X-Frame-Options": "DENY",
+  "Permissions-Policy": "camera=(), microphone=(), geolocation=()",
+};
+
+const CACHEABLE = /^(text\/html|application\/json|application\/xml|application\/rss\+xml|text\/plain)/;
+
+// Where media files come from when they are not on this site: S3 or a CDN.
+const MEDIA_ORIGINS = (process.env.MEDIA_ORIGINS ?? "")
+  .split(",")
+  .map((value) => {
+    try {
+      return new URL(value.trim()).origin;
+    } catch {
+      return "";
+    }
+  })
+  .filter(Boolean)
+  .map((origin) => ` ${origin}`)
+  .join("");
+const MEDIA_DIRECTIVES = `img-src 'self' data:${MEDIA_ORIGINS}; media-src 'self'${MEDIA_ORIGINS}`;
+
+export const handle: Handle = async ({ event, resolve }) => {
+  const { request, url, cookies } = event;
+  const preview = cookies.get(PREVIEW_COOKIE) !== undefined;
+  const cacheable = request.method === "GET" && !preview && !dev && !url.pathname.startsWith("/_app/");
+  const key = url.pathname + url.search;
+
+  if (cacheable) {
+    const hit = getCached(key);
+    if (hit) return hit;
+  }
+
+  let response = await resolve(event);
+
+  // Redirects that editors manage in the admin, for paths that do not exist.
+  if (response.status === 404 && request.method === "GET") {
+    const target = await getContent(cookies)
+      .resolveRedirect(url.pathname)
+      .catch(() => null);
+    if (target) redirect(target.permanent ? 301 : 302, target.new_path);
+  }
+
+  // A copy with headers that can be changed.
+  response = new Response(response.body, response);
+  for (const [name, value] of Object.entries(SECURITY_HEADERS)) {
+    if (!response.headers.has(name)) response.headers.set(name, value);
+  }
+  // Images and video may come from the media origins. SvelteKit builds the
+  // policy while it renders, so the directives are added to its header.
+  const csp = response.headers.get("Content-Security-Policy");
+  if (csp && !csp.includes("img-src")) {
+    response.headers.set("Content-Security-Policy", `${csp.trim().replace(/;$/, "")}; ${MEDIA_DIRECTIVES};`);
+  }
+  if (preview) response.headers.set("Cache-Control", "private, no-store");
+
+  const type = response.headers.get("Content-Type") ?? "";
+  if (cacheable && response.status === 200 && CACHEABLE.test(type)) {
+    response = await store(key, response);
+  }
+  return response;
+};

package/templates/frontend-sveltekit/src/lib/components/ContactForm.svelte

@@ -0,0 +1,65 @@
+<!--
+  The contact form. It posts to Django's public create route for form
+  submissions (PUBLIC_CREATE in backend/config/settings.py), which is rate
+  limited per IP address. Submissions appear in the admin.
+-->
+<script lang="ts">
+  let status = $state("");
+  let sending = $state(false);
+
+  async function submit(event: SubmitEvent) {
+    event.preventDefault();
+    const form = event.currentTarget as HTMLFormElement;
+    sending = true;
+    status = "Sending…";
+    try {
+      const response = await fetch("/api/content.formsubmission", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(Object.fromEntries(new FormData(form))),
+      });
+      if (response.status === 429) throw new Error("Too many messages; try again in a minute.");
+      if (!response.ok) throw new Error("The message could not be sent. Check the fields and try again.");
+      form.reset();
+      status = "Thank you, your message was sent.";
+    } catch (error) {
+      status = error instanceof Error ? error.message : String(error);
+    } finally {
+      sending = false;
+    }
+  }
+</script>
+
+<form class="contact-form" onsubmit={submit}>
+  <label>Name <input name="name" required maxlength="200" autocomplete="name" /></label>
+  <label>Email <input name="email" type="email" required autocomplete="email" /></label>
+  <label>Message <textarea name="message" required maxlength="5000" rows="6"></textarea></label>
+  <button class="button" type="submit" disabled={sending}>Send</button>
+  <p class="status" role="status" aria-live="polite">{status}</p>
+</form>
+
+<style>
+  .contact-form {
+    display: grid;
+    gap: 1rem;
+    max-width: 32rem;
+    margin-top: 2rem;
+  }
+  label {
+    display: grid;
+    gap: 0.25rem;
+    font-weight: 600;
+  }
+  input,
+  textarea {
+    font: inherit;
+    padding: 0.5rem 0.75rem;
+    border: 1px solid var(--color-line);
+    border-radius: 0.375rem;
+    background: transparent;
+    color: inherit;
+  }
+  button {
+    justify-self: start;
+  }
+</style>

package/templates/frontend-sveltekit/src/lib/components/PostCard.svelte

@@ -0,0 +1,41 @@
+<script lang="ts">
+  import { Image } from "@django-stack/svelte";
+  import type { Author, Post } from "@django-stack/utils";
+
+  let { post }: { post: Post } = $props();
+  const author = $derived(typeof post.author === "object" ? (post.author as Author | null) : null);
+  const date = $derived(post.published_at ? new Date(post.published_at) : null);
+</script>
+
+<article class="card">
+  <a href="/blog/{post.slug}">
+    <Image media={post.cover} size="card" sizes="(min-width: 40rem) 22rem, 100vw" class="cover" />
+  </a>
+  <h3><a href="/blog/{post.slug}">{post.title}</a></h3>
+  <p class="muted meta">
+    {#if date}<time datetime={date.toISOString()}>{date.toLocaleDateString("en", { dateStyle: "medium" })}</time>{/if}
+    {#if author}<span> · {author.name}</span>{/if}
+  </p>
+  {#if post.excerpt}<p>{post.excerpt}</p>{/if}
+</article>
+
+<style>
+  .card h3 {
+    margin: 0.75rem 0 0.25rem;
+    line-height: 1.3;
+  }
+  .card h3 a {
+    color: inherit;
+    text-decoration: none;
+  }
+  .card :global(.cover) {
+    width: 100%;
+    aspect-ratio: 16 / 10;
+    object-fit: cover;
+    border-radius: 0.5rem;
+  }
+  .meta {
+    font-size: 0.9rem;
+    margin: 0;
+  }
+</style>

package/templates/frontend-sveltekit/src/lib/components/PostList.svelte

@@ -0,0 +1,39 @@
+<script lang="ts">
+  import type { Paginated, Post } from "@django-stack/utils";
+  import PostCard from "./PostCard.svelte";
+
+  interface Props {
+    result: Paginated<Post>;
+    /** The URL of the list, without the page parameter. */
+    base: string;
+  }
+
+  let { result, base }: Props = $props();
+  const { current, pages } = $derived(result.pagination);
+  const pageUrl = (page: number) => (page === 1 ? base : `${base}?page=${page}`);
+</script>
+
+{#if result.data.length === 0}
+  <p class="muted">No posts yet.</p>
+{/if}
+<div class="grid">
+  {#each result.data as post (post.id)}
+    <PostCard {post} />
+  {/each}
+</div>
+{#if pages > 1}
+  <nav class="pagination" aria-label="Pages">
+    {#if current > 1}<a href={pageUrl(current - 1)}>← Newer</a>{/if}
+    <span class="muted">Page {current} of {pages}</span>
+    {#if current < pages}<a href={pageUrl(current + 1)}>Older →</a>{/if}
+  </nav>
+{/if}
+
+<style>
+  .pagination {
+    display: flex;
+    gap: 1.5rem;
+    justify-content: center;
+    margin: 3rem 0;
+  }
+</style>