@django-stack/cli 0.3.0 → 0.5.0

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

@@ -0,0 +1,70 @@
+import "./globals.css";
+import { Image, RichText } from "@django-stack/react";
+import { linkHref } from "@django-stack/utils";
+import type { Metadata } from "next";
+import { NavLink } from "@/components/NavLink";
+import { getContent, previewToken, SITE_URL } from "@/lib/api";
+
+export function generateMetadata(): Metadata {
+  return {
+    metadataBase: new URL(SITE_URL),
+    icons: { icon: { url: "/favicon.svg", type: "image/svg+xml" } },
+  };
+}
+
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+  const content = await getContent();
+  const [settings, mainMenu, footerMenu, preview] = await Promise.all([
+    content.getSiteSettings(),
+    content.getMenu("main"),
+    content.getMenu("footer"),
+    previewToken(),
+  ]);
+  return (
+    <html lang="en">
+      <body>
+        {preview !== null ? (
+          <div className="preview-banner">
+            Preview: drafts are shown. <a href="/preview/exit">Leave preview</a>
+          </div>
+        ) : null}
+        <header className="site-header">
+          <div className="container bar">
+            <a className="brand" href="/">
+              {settings?.logo ? (
+                <Image media={settings.logo} size="thumbnail" alt={settings.site_name} eager />
+              ) : (
+                settings?.site_name
+              )}
+            </a>
+            <nav aria-label="Main">
+              {(mainMenu?.items ?? []).map((item) => (
+                <NavLink key={item.id} href={linkHref(item)}>
+                  {item.value.label}
+                </NavLink>
+              ))}
+            </nav>
+          </div>
+        </header>
+        <main>{children}</main>
+        <footer className="site-footer">
+          <div className="container bar muted">
+            <RichText html={settings?.footer_text} className="footer-text" />
+            <nav aria-label="Footer">
+              {(footerMenu?.items ?? []).map((item) => (
+                <a key={item.id} href={linkHref(item)}>
+                  {item.value.label}
+                </a>
+              ))}
+              {Object.entries(settings?.social_links ?? {}).map(([name, url]) => (
+                <a key={name} href={url} rel="me">
+                  {name}
+                </a>
+              ))}
+            </nav>
+          </div>
+        </footer>
+      </body>
+    </html>
+  );
+}

package/templates/frontend-next/src/app/not-found.tsx

@@ -0,0 +1,15 @@
+import Link from "next/link";
+
+export const metadata = { title: "Page not found" };
+
+export default function NotFound() {
+  return (
+    <section className="narrow">
+      <h1>Page not found</h1>
+      <p>The page you are looking for does not exist or has moved.</p>
+      <p>
+        <Link href="/">Go to the home page</Link>
+      </p>
+    </section>
+  );
+}

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

@@ -0,0 +1,35 @@
+import { Blocks } from "@django-stack/react";
+import type { Metadata } from "next";
+import { PostList } from "@/components/PostList";
+import { getContent, pageMetadata } from "@/lib/api";
+
+async function load() {
+  const content = await getContent();
+  const settings = await content.getSiteSettings();
+  return { settings, home: await content.getHomePage(settings), content };
+}
+
+export async function generateMetadata(): Promise<Metadata> {
+  const { home } = await load();
+  return pageMetadata(home, "/");
+}
+
+export default async function Home() {
+  const { settings, home, content } = await load();
+  if (home) {
+    return (
+      <article className="narrow">
+        <h1>{home.title}</h1>
+        <Blocks blocks={home.body} />
+      </article>
+    );
+  }
+  const posts = await content.getPosts({ limit: 9 });
+  return (
+    <section className="container">
+      <h1>{settings?.site_name ?? "Latest posts"}</h1>
+      {settings?.tagline ? <p className="muted">{settings.tagline}</p> : null}
+      <PostList result={posts} base="/" />
+    </section>
+  );
+}

package/templates/frontend-next/src/app/preview/exit/route.ts

@@ -0,0 +1,3 @@
+import { exitPreviewHandler } from "@django-stack/next";
+
+export const GET = exitPreviewHandler();

package/templates/frontend-next/src/app/preview/route.ts

@@ -0,0 +1,4 @@
+import { previewHandler } from "@django-stack/next";
+
+/** Opens a page with drafts shown: the admin's Preview button links here. */
+export const GET = previewHandler();

package/templates/frontend-next/src/app/revalidate/route.ts

@@ -0,0 +1,8 @@
+import { revalidateHandler } from "@django-stack/next";
+
+/**
+ * Django calls this after editors change content (REVALIDATE_URL), signed
+ * with REVALIDATE_SECRET. It expires the cached API responses, so the next
+ * visit renders the new content.
+ */
+export const POST = revalidateHandler();

package/templates/frontend-next/src/app/robots.txt/route.ts

@@ -0,0 +1,13 @@
+import { connection } from "next/server";
+import { SITE_URL } from "@/lib/api";
+
+export async function GET() {
+  // Rendered on request: SITE_URL is set when the container starts.
+  await connection();
+  return new Response(
+    `User-agent: *\nDisallow: /admin/\nDisallow: /preview\n\nSitemap: ${SITE_URL}/sitemap.xml\n`,
+    {
+      headers: { "Content-Type": "text/plain; charset=utf-8" },
+    },
+  );
+}

package/templates/frontend-next/src/app/rss.xml/route.ts

@@ -0,0 +1,19 @@
+import { getContent, SITE_URL } from "@/lib/api";
+import { rssFeed } from "@/lib/rss";
+
+export async function GET() {
+  const content = await getContent();
+  const [settings, posts] = await Promise.all([content.getSiteSettings(), content.getPosts({ limit: 20 })]);
+  const body = rssFeed({
+    title: settings?.site_name ?? "Blog",
+    description: settings?.seo_description || settings?.tagline || "",
+    site: SITE_URL,
+    items: posts.data.map((post) => ({
+      title: post.title,
+      link: `/blog/${post.slug}`,
+      description: post.excerpt,
+      pubDate: post.published_at ? new Date(post.published_at) : null,
+    })),
+  });
+  return new Response(body, { headers: { "Content-Type": "application/rss+xml; charset=utf-8" } });
+}

package/templates/frontend-next/src/app/sitemap.xml/route.ts

@@ -0,0 +1,28 @@
+import { getContent, SITE_URL } from "@/lib/api";
+
+export async function GET() {
+  const content = await getContent();
+  const [pages, posts, settings] = await Promise.all([
+    content.getAllPages(),
+    content.getAllPosts(),
+    content.getSiteSettings(),
+  ]);
+  const urls = [
+    { loc: "/", lastmod: null },
+    { loc: "/blog", lastmod: null },
+    ...pages
+      .filter((page) => page.id !== settings?.home_page)
+      .map((page) => ({ loc: `/${page.path}`, lastmod: page.published_at })),
+    ...posts.map((post) => ({ loc: `/blog/${post.slug}`, lastmod: post.published_at })),
+  ];
+  const body = `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${urls
+  .map(
+    ({ loc, lastmod }) =>
+      `  <url><loc>${SITE_URL}${loc}</loc>${lastmod ? `<lastmod>${lastmod.slice(0, 10)}</lastmod>` : ""}</url>`,
+  )
+  .join("\n")}
+</urlset>`;
+  return new Response(body, { headers: { "Content-Type": "application/xml; charset=utf-8" } });
+}

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

@@ -0,0 +1,29 @@
+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, tag: await (await getContent()).getTag(slug) };
+}
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { slug, tag } = await load(params);
+  return tag ? pageMetadata({ title: `#${tag.name}` }, `/tag/${slug}`) : {};
+}
+
+export default async function Tag({ params, searchParams }: Props) {
+  const { slug, tag } = await load(params);
+  if (!tag) return notFoundOrRedirect(`/tag/${slug}`);
+  const page = pageNumber((await searchParams).page);
+  const result = await (await getContent()).getPosts({ tag: slug, page, limit: 9 });
+  return (
+    <section className="container">
+      <p className="muted">Tag</p>
+      <h1>#{tag.name}</h1>
+      <PostList result={result} base={`/tag/${slug}`} />
+    </section>
+  );
+}

package/templates/frontend-next/src/components/ContactForm.tsx

@@ -0,0 +1,55 @@
+"use client";
+
+/**
+ * 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.
+ */
+import { type FormEvent, useState } from "react";
+
+export function ContactForm() {
+  const [status, setStatus] = useState("");
+  const [sending, setSending] = useState(false);
+
+  async function submit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    const form = event.currentTarget;
+    setSending(true);
+    setStatus("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();
+      setStatus("Thank you, your message was sent.");
+    } catch (error) {
+      setStatus(error instanceof Error ? error.message : String(error));
+    } finally {
+      setSending(false);
+    }
+  }
+
+  return (
+    <form className="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} />
+      </label>
+      <button className="button" type="submit" disabled={sending}>
+        Send
+      </button>
+      <p className="status" role="status" aria-live="polite">
+        {status}
+      </p>
+    </form>
+  );
+}

package/templates/frontend-next/src/components/NavLink.tsx

@@ -0,0 +1,15 @@
+"use client";
+
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+
+/** A menu link, marked as the current page when the visitor is on it or below it. */
+export function NavLink({ href, children }: { href: string; children: React.ReactNode }) {
+  const path = usePathname();
+  const current = href === path || (href !== "/" && path.startsWith(`${href}/`));
+  return (
+    <Link href={href} aria-current={current ? "page" : undefined}>
+      {children}
+    </Link>
+  );
+}

package/templates/frontend-next/src/components/PostCard.tsx

@@ -0,0 +1,25 @@
+import { Image } from "@django-stack/react";
+import type { Author, Post } from "@django-stack/utils";
+import Link from "next/link";
+
+export function PostCard({ post }: { post: Post }) {
+  const author = typeof post.author === "object" ? (post.author as Author | null) : null;
+  const date = post.published_at ? new Date(post.published_at) : null;
+  return (
+    <article className="card">
+      <Link href={`/blog/${post.slug}`}>
+        <Image media={post.cover} size="card" sizes="(min-width: 40rem) 22rem, 100vw" className="cover" />
+      </Link>
+      <h3>
+        <Link href={`/blog/${post.slug}`}>{post.title}</Link>
+      </h3>
+      <p className="muted meta">
+        {date ? (
+          <time dateTime={date.toISOString()}>{date.toLocaleDateString("en", { dateStyle: "medium" })}</time>
+        ) : null}
+        {author ? <span> · {author.name}</span> : null}
+      </p>
+      {post.excerpt ? <p>{post.excerpt}</p> : null}
+    </article>
+  );
+}

package/templates/frontend-next/src/components/PostList.tsx

@@ -0,0 +1,28 @@
+import type { Paginated, Post } from "@django-stack/utils";
+import Link from "next/link";
+import { PostCard } from "./PostCard";
+
+/** A page of posts, with links to the newer and older pages. `base` is the URL of the list. */
+export function PostList({ result, base }: { result: Paginated<Post>; base: string }) {
+  const { current, pages } = result.pagination;
+  const pageUrl = (page: number) => (page === 1 ? base : `${base}?page=${page}`);
+  return (
+    <>
+      {result.data.length === 0 ? <p className="muted">No posts yet.</p> : null}
+      <div className="grid">
+        {result.data.map((post) => (
+          <PostCard key={post.id} post={post} />
+        ))}
+      </div>
+      {pages > 1 ? (
+        <nav className="pagination" aria-label="Pages">
+          {current > 1 ? <Link href={pageUrl(current - 1)}>← Newer</Link> : null}
+          <span className="muted">
+            Page {current} of {pages}
+          </span>
+          {current < pages ? <Link href={pageUrl(current + 1)}>Older →</Link> : null}
+        </nav>
+      ) : null}
+    </>
+  );
+}

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

@@ -0,0 +1,71 @@
+/**
+ * Content access for server components and route handlers. Server-side only:
+ * the API key is read from API_READ_KEY, and `server-only` fails the build
+ * if a client component imports this module.
+ */
+import "server-only";
+
+import { contentFetchInit, PREVIEW_COOKIE, toMetadata } from "@django-stack/next";
+import { createClient, createContent, type SeoInput, seo } from "@django-stack/utils";
+import type { Metadata } from "next";
+import { cookies } from "next/headers";
+import { notFound, permanentRedirect, redirect } from "next/navigation";
+import type { Models } from "./headless";
+
+export { PREVIEW_COOKIE };
+
+export const SITE_URL = (process.env.SITE_URL ?? "http://localhost:3000").replace(/\/$/, "");
+
+/** The preview token, when the visitor opened a preview link. */
+export async function previewToken(): Promise<string | null> {
+  return (await cookies()).get(PREVIEW_COOKIE)?.value ?? null;
+}
+
+/**
+ * The typed Django Headless client, for queries the content helpers do not
+ * cover. Its responses are cached until Django calls /revalidate, except in
+ * preview and in development.
+ */
+export async function getClient() {
+  const token = await previewToken();
+  return createClient<Models>({
+    previewToken: token,
+    init: contentFetchInit({ preview: token !== null || process.env.NODE_ENV === "development" }),
+  });
+}
+
+/** The content helpers, with drafts when the visitor is in preview. */
+export async function getContent() {
+  return createContent(await getClient());
+}
+
+/** The page number of a list, from ?page=. */
+export function pageNumber(page: string | string[] | undefined): number {
+  return Math.max(1, Number(Array.isArray(page) ? page[0] : page) || 1);
+}
+
+/**
+ * For a path that does not exist: follows a redirect editors manage in the
+ * admin, or shows the not-found page.
+ */
+export async function notFoundOrRedirect(path: string): Promise<never> {
+  const target = await (await getContent()).resolveRedirect(path).catch(() => null);
+  if (target) (target.permanent ? permanentRedirect : redirect)(target.new_path);
+  notFound();
+}
+
+/**
+ * The metadata of a page: title, description, canonical URL and share image,
+ * with the site settings as the fallback. `path` is the page's path.
+ */
+export async function pageMetadata(
+  page: SeoInput | null | undefined,
+  path: string,
+  type: "website" | "article" = "website",
+): Promise<Metadata> {
+  const settings = await (await getContent()).getSiteSettings();
+  const metadata = toMetadata(seo({ page, settings, siteUrl: SITE_URL, path, type }));
+  // Next replaces the layout's alternates with the page's, so the feed is listed here.
+  const feed = [{ url: "/rss.xml", title: settings?.site_name ?? "RSS" }];
+  return { ...metadata, alternates: { ...metadata.alternates, types: { "application/rss+xml": feed } } };
+}