@django-stack/cli 0.3.0 → 0.4.0

package/templates/frontend-next/src/lib/headless.ts

@@ -0,0 +1,344 @@
+// Generated by django-headless from the OpenAPI schema of the API. Do not edit this file:
+// run `headless generate` again when the exposed models change.
+
+export interface ContentAuthor {
+  id: number;
+  name: string;
+  slug: string;
+  bio: string;
+  avatar: string | null;
+}
+
+export interface ContentCategory {
+  id: number;
+  name: string;
+  slug: string;
+  description: string;
+}
+
+export interface ContentFormSubmission {
+  id: number;
+  name: string;
+  /** Format: email. */
+  email: string;
+  message: string;
+  /** Format: date-time. */
+  created_at: string;
+}
+
+export interface ContentFormSubmissionInput {
+  name: string;
+  /** Format: email. */
+  email: string;
+  message: string;
+}
+
+export interface ContentMenu {
+  id: number;
+  name: string;
+  /** The frontend asks for a menu by this name, such as main. */
+  slug: string;
+  items: { [key: string]: unknown };
+}
+
+export interface ContentPage {
+  id: number;
+  status: "draft" | "published";
+  /** Leave empty to publish right away. A future date schedules the publication. Format: date-time. */
+  published_at: string | null;
+  seo_title: string;
+  seo_description: string;
+  title: string;
+  slug: string;
+  path: string;
+  body: { [key: string]: unknown };
+  order: number;
+  /** Shown when the page is shared; 1200 × 630 works best. */
+  share_image: string | null;
+  parent: number | null;
+  is_published: boolean;
+}
+
+export interface ContentPost {
+  id: number;
+  status: "draft" | "published";
+  /** Leave empty to publish right away. A future date schedules the publication. Format: date-time. */
+  published_at: string | null;
+  seo_title: string;
+  seo_description: string;
+  title: string;
+  slug: string;
+  /** A short summary for lists and search results. */
+  excerpt: string;
+  body: { [key: string]: unknown };
+  /** Shown when the page is shared; 1200 × 630 works best. */
+  share_image: string | null;
+  cover: string | null;
+  author: number | null;
+  categories: number[];
+  tags: number[];
+  is_published: boolean;
+}
+
+export interface ContentRedirect {
+  id: number;
+  /** Such as /old-page, without the domain. */
+  old_path: string;
+  /** A path on the site or a full URL. */
+  new_path: string;
+  /** 301 when on, 302 when off. */
+  permanent: boolean;
+}
+
+export interface ContentSiteSettings {
+  id: number;
+  site_name: string;
+  tagline: string;
+  seo_description: string;
+  /** Such as {"Mastodon": "https://..."}. */
+  social_links: { [key: string]: unknown };
+  footer_text: string;
+  logo: string | null;
+  /** The page shown at /. Without one, the home page lists the latest posts. */
+  home_page: number | null;
+  /** The default image for social sharing. */
+  share_image: string | null;
+}
+
+export interface ContentStudioMediaLibraryMedia {
+  /** Format: uuid. */
+  id: string;
+  name: string;
+  /** Describes a picture for screen readers */
+  alt_text: string;
+  type: "image" | "video" | "audio" | "file";
+  /** Format: binary. */
+  file: string;
+  /** Read from the file, such as an image's width and height. */
+  metadata: { [key: string]: unknown };
+  /** Set by editors for some types of media, such as a focal point. */
+  properties: { [key: string]: unknown };
+}
+
+export interface ContentTag {
+  id: number;
+  name: string;
+  slug: string;
+}
+
+export type Models = {
+  "content.author": {
+    item: ContentAuthor;
+    input: never;
+    id: number;
+    filters: {
+      posts: number;
+      id: number;
+      name: string;
+      slug: string;
+      bio: string;
+      avatar: string;
+    };
+    lookups: {
+      slug: string;
+    };
+    expandable: {
+      posts: { model: "content.post"; many: true; nullable: false };
+      avatar: { model: "content_studio_media_library.media"; many: false; nullable: true };
+    };
+    readOnly: true;
+    singleton: false;
+    paginated: true;
+  };
+  "content.category": {
+    item: ContentCategory;
+    input: never;
+    id: number;
+    filters: {
+      posts: number;
+      id: number;
+      name: string;
+      slug: string;
+      description: string;
+    };
+    lookups: {
+      slug: string;
+    };
+    expandable: {
+      posts: { model: "content.post"; many: true; nullable: false };
+    };
+    readOnly: true;
+    singleton: false;
+    paginated: true;
+  };
+  "content.formsubmission": {
+    item: ContentFormSubmission;
+    input: ContentFormSubmissionInput;
+    id: number;
+    filters: {
+      id: number;
+      name: string;
+      email: string;
+      message: string;
+      created_at: string | Date;
+    };
+    lookups: {};
+    expandable: {};
+    readOnly: false;
+    singleton: false;
+    paginated: true;
+  };
+  "content.menu": {
+    item: ContentMenu;
+    input: never;
+    id: number;
+    filters: {
+      id: number;
+      name: string;
+      slug: string;
+      items: string;
+    };
+    lookups: {
+      slug: string;
+    };
+    expandable: {};
+    readOnly: true;
+    singleton: false;
+    paginated: true;
+  };
+  "content.page": {
+    item: ContentPage;
+    input: never;
+    id: number;
+    filters: {
+      children: number;
+      id: number;
+      status: "draft" | "published";
+      published_at: string | Date;
+      seo_title: string;
+      seo_description: string;
+      share_image: string;
+      title: string;
+      slug: string;
+      parent: number;
+      path: string;
+      body: string;
+      order: number;
+    };
+    lookups: {};
+    expandable: {
+      children: { model: "content.page"; many: true; nullable: false };
+      share_image: { model: "content_studio_media_library.media"; many: false; nullable: true };
+      parent: { model: "content.page"; many: false; nullable: true };
+    };
+    readOnly: true;
+    singleton: false;
+    paginated: true;
+  };
+  "content.post": {
+    item: ContentPost;
+    input: never;
+    id: number;
+    filters: {
+      id: number;
+      status: "draft" | "published";
+      published_at: string | Date;
+      seo_title: string;
+      seo_description: string;
+      share_image: string;
+      title: string;
+      slug: string;
+      excerpt: string;
+      cover: string;
+      body: string;
+      author: number;
+      categories: number;
+      tags: number;
+    };
+    lookups: {
+      slug: string;
+    };
+    expandable: {
+      share_image: { model: "content_studio_media_library.media"; many: false; nullable: true };
+      cover: { model: "content_studio_media_library.media"; many: false; nullable: true };
+      author: { model: "content.author"; many: false; nullable: true };
+      categories: { model: "content.category"; many: true; nullable: false };
+      tags: { model: "content.tag"; many: true; nullable: false };
+    };
+    readOnly: true;
+    singleton: false;
+    paginated: true;
+  };
+  "content.redirect": {
+    item: ContentRedirect;
+    input: never;
+    id: number;
+    filters: {
+      id: number;
+      old_path: string;
+      new_path: string;
+      permanent: boolean;
+    };
+    lookups: {
+      old_path: string;
+    };
+    expandable: {};
+    readOnly: true;
+    singleton: false;
+    paginated: true;
+  };
+  "content.sitesettings": {
+    item: ContentSiteSettings;
+    input: never;
+    id: string | number;
+    filters: {};
+    lookups: {};
+    expandable: {
+      logo: { model: "content_studio_media_library.media"; many: false; nullable: true };
+      home_page: { model: "content.page"; many: false; nullable: true };
+      share_image: { model: "content_studio_media_library.media"; many: false; nullable: true };
+    };
+    readOnly: true;
+    singleton: true;
+    paginated: true;
+  };
+  "content.tag": {
+    item: ContentTag;
+    input: never;
+    id: number;
+    filters: {
+      posts: number;
+      id: number;
+      name: string;
+      slug: string;
+    };
+    lookups: {
+      slug: string;
+    };
+    expandable: {
+      posts: { model: "content.post"; many: true; nullable: false };
+    };
+    readOnly: true;
+    singleton: false;
+    paginated: true;
+  };
+  "content_studio_media_library.media": {
+    item: ContentStudioMediaLibraryMedia;
+    input: never;
+    id: string;
+    filters: {
+      id: string;
+      file: string;
+      name: string;
+      alt_text: string;
+      metadata: string;
+      properties: string;
+      type: "image" | "video" | "audio" | "file";
+    };
+    lookups: {};
+    expandable: {};
+    readOnly: true;
+    singleton: false;
+    paginated: true;
+  };
+};

package/templates/frontend-next/src/lib/rss.ts

@@ -0,0 +1,44 @@
+/** An RSS 2.0 feed. */
+
+export interface FeedItem {
+  title: string;
+  /** A path on the site, such as /blog/hello-world. */
+  link: string;
+  description?: string | null;
+  pubDate?: Date | null;
+}
+
+const escapeXml = (text: string) =>
+  text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+
+export function rssFeed(feed: {
+  title: string;
+  description: string;
+  site: string;
+  items: FeedItem[];
+}): string {
+  const items = feed.items.map((item) => {
+    const url = escapeXml(new URL(item.link, `${feed.site}/`).href);
+    return [
+      "    <item>",
+      `      <title>${escapeXml(item.title)}</title>`,
+      `      <link>${url}</link>`,
+      `      <guid isPermaLink="true">${url}</guid>`,
+      item.description ? `      <description>${escapeXml(item.description)}</description>` : "",
+      item.pubDate ? `      <pubDate>${item.pubDate.toUTCString()}</pubDate>` : "",
+      "    </item>",
+    ]
+      .filter(Boolean)
+      .join("\n");
+  });
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0">
+  <channel>
+    <title>${escapeXml(feed.title)}</title>
+    <description>${escapeXml(feed.description)}</description>
+    <link>${escapeXml(`${feed.site}/`)}</link>
+${items.join("\n")}
+  </channel>
+</rss>
+`;
+}

package/templates/frontend-next/src/proxy.ts

@@ -0,0 +1,34 @@
+import { contentSecurityPolicy, mediaOrigins, PREVIEW_COOKIE, SECURITY_HEADERS } from "@django-stack/next";
+import { type NextRequest, NextResponse } from "next/server";
+
+const dev = process.env.NODE_ENV === "development";
+
+// Django's paths. The reverse proxy sends them to Django in production; in
+// development, this proxy does, so the site and the admin share an origin.
+const BACKEND_PATHS = /^\/(admin|api|media|static)(\/|$)/;
+const backend = process.env.BACKEND_INTERNAL_URL ?? "http://localhost:8000";
+const media = mediaOrigins();
+
+export function proxy(request: NextRequest) {
+  const { pathname, search } = request.nextUrl;
+  if (dev && BACKEND_PATHS.test(pathname)) {
+    return NextResponse.rewrite(new URL(pathname + search, backend));
+  }
+
+  // A fresh nonce for every page: Next adds it to the scripts it renders.
+  const nonce = Buffer.from(crypto.randomUUID()).toString("base64");
+  const policy = contentSecurityPolicy({ nonce, mediaOrigins: media, dev });
+  const headers = new Headers(request.headers);
+  headers.set("Content-Security-Policy", policy);
+
+  const response = NextResponse.next({ request: { headers } });
+  response.headers.set("Content-Security-Policy", policy);
+  for (const [name, value] of Object.entries(SECURITY_HEADERS)) response.headers.set(name, value);
+  if (request.cookies.has(PREVIEW_COOKIE)) response.headers.set("Cache-Control", "private, no-store");
+  return response;
+}
+
+export const config = {
+  // Every path but Next's own files and the favicon.
+  matcher: ["/((?!_next/static|_next/image|favicon.svg).*)"],
+};

package/templates/frontend-next/template.json

@@ -0,0 +1,5 @@
+{
+  "label": "Next.js",
+  "url": "https://nextjs.org",
+  "security": "https://github.com/vercel/next.js/security"
+}

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

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+import { rssFeed } from "../src/lib/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-next/tsconfig.json

@@ -0,0 +1,42 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": [
+        "./src/*"
+      ]
+    },
+    "esModuleInterop": true
+  },
+  "include": [
+    "next-env.d.ts",
+    "src",
+    "test",
+    "*.ts",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

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

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

package/templates/frontend-nuxt/.dockerignore

@@ -0,0 +1,4 @@
+node_modules
+.nuxt
+.output
+.env

package/templates/frontend-nuxt/AGENTS.md

@@ -0,0 +1,64 @@
+# The Nuxt frontend
+
+Nuxt renders the site on the server (Nitro's `node-server` preset). Pages
+never call Django: they load content with `useFetch` from the server routes
+in `server/routes/_content/`, which hold the read-only API key, so the key
+never reaches the browser. The project's `AGENTS.md` describes the whole
+project; this file describes the frontend.
+
+## Layout
+
+```
+src/pages/                   routes: /, /[...path], /blog, /blog/[slug], /category/[slug], /tag/[slug]
+src/layouts/default.vue      the page shell: menus, footer, preview banner
+src/components/              the post list and the contact form
+src/composables/             useContent() loads from server/routes/_content and follows redirects; usePageSeo() sets the SEO tags
+src/lib/headless.ts          generated API types; do not edit, run `npm run generate:types`
+server/routes/_content/      the content the pages load, cached in memory
+server/routes/               sitemap.xml, rss.xml, robots.txt, /preview, /revalidate
+server/utils/content.ts      getContent(): content helpers with the read-only key, drafts in preview
+server/utils/cache.ts        the in-memory cache that /revalidate empties
+server/plugins/              the media origins in the Content-Security-Policy
+nuxt.config.ts               security headers (nuxt-security), the dev proxy to Django
+```
+
+Blocks, rich text and images come from `@django-stack/vue`.
+
+## Read a content model
+
+Add a server route, then load it in a page:
+
+```ts
+// server/routes/_content/events.get.ts
+export default defineEventHandler((event) =>
+  cachedContent(event, () => getClient(event).model("content.event").list()),
+);
+```
+
+```vue
+<!-- src/pages/events.vue -->
+<script setup lang="ts">
+const { data: events } = await useContent("/_content/events");
+</script>
+```
+
+Never call `getClient()` or `getContent()` outside `server/`, and never
+put a route in `server/api/`: Django owns `/api`.
+
+## Render a block type
+
+Add a component in `src/components/blocks/` that takes a `block` prop, and
+pass it to `Blocks` by the block's type:
+
+```vue
+<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-nuxt/Dockerfile

@@ -0,0 +1,32 @@
+# syntax=docker/dockerfile:1
+
+# The frontend image. The `dev` target runs the Nuxt dev server with the
+# source mounted; `prod` builds the site and runs the Node server.
+FROM node:22-alpine AS base
+WORKDIR /app
+ENV NUXT_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 --ignore-scripts; else npm install --ignore-scripts; fi
+
+FROM deps AS dev
+EXPOSE 3000
+CMD ["npm", "run", "dev"]
+
+FROM deps AS build
+COPY . .
+RUN npm run build
+
+# The build output holds the server and the packages it needs: no
+# node_modules in the image.
+FROM base AS prod
+ENV NODE_ENV=production HOST=0.0.0.0 PORT=3000
+COPY --from=build --chown=node:node /app/.output ./.output
+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", ".output/server/index.mjs"]

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

@@ -0,0 +1,69 @@
+// The Django backend: the frontend container reaches it on the Compose network.
+const backend = process.env.BACKEND_INTERNAL_URL ?? "http://localhost:8000";
+
+export default defineNuxtConfig({
+  compatibilityDate: "2026-11-01",
+  srcDir: "src/",
+  modules: ["nuxt-security"],
+  css: ["~/assets/main.css"],
+  telemetry: false,
+  devtools: { enabled: false },
+  app: {
+    head: {
+      htmlAttrs: { lang: "en" },
+      link: [{ rel: "icon", href: "/favicon.svg", type: "image/svg+xml" }],
+    },
+  },
+  devServer: { host: "0.0.0.0", port: 3000 },
+  vite: {
+    // Django calls /revalidate at http://frontend:3000 on the Compose network.
+    server: { allowedHosts: ["frontend"] },
+  },
+  nitro: {
+    // A Node server: pages render on request, so a publish shows within seconds.
+    preset: "node-server",
+  },
+  // In development, serve Django's paths from the same origin as the site,
+  // like the reverse proxy does in production.
+  $development: {
+    routeRules: Object.fromEntries(
+      ["/admin", "/api", "/media", "/static"].map((path) => [
+        `${path}/**`,
+        { proxy: `${backend}${path}/**` },
+      ]),
+    ),
+  },
+  // Security headers, with a Content-Security-Policy on every page in
+  // production: scripts and styles only from this site, with a nonce for
+  // the ones Nuxt inlines. server/plugins/media-origins.ts adds the origin
+  // of the media files.
+  security: {
+    nonce: true,
+    rateLimiter: false,
+    xssValidator: false,
+    headers: {
+      contentSecurityPolicy:
+        process.env.NODE_ENV === "production"
+          ? {
+              "default-src": ["'self'"],
+              "script-src": ["'self'", "'nonce-{{nonce}}'", "'strict-dynamic'"],
+              "style-src": ["'self'", "'nonce-{{nonce}}'"],
+              // Inline style attributes, such as the focal point of an image.
+              "style-src-attr": ["'unsafe-inline'"],
+              "img-src": ["'self'", "data:"],
+              "media-src": ["'self'"],
+              "font-src": ["'self'"],
+              "connect-src": ["'self'"],
+              "base-uri": ["'self'"],
+              "form-action": ["'self'"],
+              "frame-ancestors": ["'none'"],
+              "object-src": ["'none'"],
+              "upgrade-insecure-requests": false,
+            }
+          : false,
+      // Media may come from another origin (S3 or a CDN) without CORP headers.
+      crossOriginEmbedderPolicy: false,
+      permissionsPolicy: { camera: [], microphone: [], geolocation: [] },
+    },
+  },
+});