@django-stack/cli 0.2.0 → 0.4.0

package/templates/frontend-nuxt/src/composables/useContent.ts

@@ -0,0 +1,27 @@
+import type { NitroFetchRequest } from "nitropack";
+
+/**
+ * Content from a route in server/routes/_content. When it is not found, a
+ * redirect that editors manage in the admin is followed; otherwise the error
+ * page shows with the status, such as 404.
+ */
+export async function useContent<R extends NitroFetchRequest>(url: R, query?: () => Record<string, unknown>) {
+  const nuxtApp = useNuxtApp();
+  const route = useRoute();
+  const result = await useFetch(url, { query: computed(() => query?.() ?? {}) });
+  const error = result.error.value;
+  if (error) {
+    const statusCode = error.statusCode ?? 500;
+    if (statusCode === 404) {
+      const target = await $fetch("/_content/redirect", { query: { path: route.path } }).catch(() => null);
+      if (target) {
+        await nuxtApp.runWithContext(() =>
+          navigateTo(target.new_path, { redirectCode: target.permanent ? 301 : 302 }),
+        );
+        return result;
+      }
+    }
+    throw createError({ statusCode, statusMessage: error.statusMessage, fatal: true });
+  }
+  return result;
+}

package/templates/frontend-nuxt/src/composables/useLayoutContent.ts

@@ -0,0 +1,4 @@
+/** The site settings, the menus and whether drafts are shown, for every page. */
+export function useLayoutContent() {
+  return useFetch("/_content/layout", { key: "layout", dedupe: "defer" });
+}

package/templates/frontend-nuxt/src/composables/usePageSeo.ts

@@ -0,0 +1,33 @@
+import { type SeoInput, seo } from "@django-stack/utils";
+import type { MaybeRefOrGetter } from "vue";
+
+/**
+ * The title, description, canonical URL, Open Graph and Twitter tags of a
+ * page. It awaits nothing, so call it anywhere in `<script setup>`.
+ */
+export function usePageSeo(
+  page: MaybeRefOrGetter<SeoInput | null | undefined>,
+  type?: "website" | "article",
+) {
+  const route = useRoute();
+  // The layout loads the same data under the same key: this does not fetch again.
+  const { data: layout } = useLayoutContent();
+  const meta = computed(() =>
+    seo({
+      page: toValue(page),
+      settings: layout.value?.settings ?? null,
+      siteUrl: layout.value?.siteUrl ?? "",
+      path: route.path,
+      type,
+    }),
+  );
+  useHead(() => ({
+    title: meta.value.title,
+    link: [{ rel: "canonical", href: meta.value.canonical }],
+    meta: [
+      ...(meta.value.description ? [{ name: "description", content: meta.value.description }] : []),
+      ...Object.entries(meta.value.openGraph).map(([property, content]) => ({ property, content })),
+      ...Object.entries(meta.value.twitter).map(([name, content]) => ({ name, content })),
+    ],
+  }));
+}

package/templates/frontend-nuxt/src/error.vue

@@ -0,0 +1,23 @@
+<script setup lang="ts">
+import type { NuxtError } from "#app";
+
+const props = defineProps<{ error: NuxtError }>();
+const notFound = computed(() => props.error.statusCode === 404);
+useHead({ title: notFound.value ? "Page not found" : "Something went wrong" });
+</script>
+
+<template>
+  <NuxtLayout>
+    <section class="narrow">
+      <template v-if="notFound">
+        <h1>Page not found</h1>
+        <p>The page you are looking for does not exist or has moved.</p>
+      </template>
+      <template v-else>
+        <h1>Something went wrong</h1>
+        <p>The page could not be shown. Try again in a moment.</p>
+      </template>
+      <p><a href="/">Go to the home page</a></p>
+    </section>
+  </NuxtLayout>
+</template>

package/templates/frontend-nuxt/src/layouts/default.vue

@@ -0,0 +1,99 @@
+<script setup lang="ts">
+import { Image, RichText } from "@django-stack/vue";
+import { linkHref } from "@django-stack/utils";
+
+const { data } = await useLayoutContent();
+const route = useRoute();
+const isCurrent = (href: string) => href === route.path || (href !== "/" && route.path.startsWith(`${href}/`));
+
+useHead(() => ({
+  link: [
+    { rel: "alternate", type: "application/rss+xml", title: data.value?.settings?.site_name ?? "RSS", href: "/rss.xml" },
+  ],
+}));
+</script>
+
+<template>
+  <div v-if="data?.preview" class="preview-banner">
+    Preview: drafts are shown. <a href="/preview/exit">Leave preview</a>
+  </div>
+  <header class="site-header">
+    <div class="container bar">
+      <NuxtLink class="brand" to="/">
+        <Image v-if="data?.settings?.logo" :media="data.settings.logo" size="thumbnail" :alt="data.settings.site_name" eager />
+        <template v-else>{{ data?.settings?.site_name }}</template>
+      </NuxtLink>
+      <nav aria-label="Main">
+        <NuxtLink
+          v-for="item in data?.mainMenu?.items ?? []"
+          :key="item.id"
+          :to="linkHref(item)"
+          :aria-current="isCurrent(linkHref(item)) ? 'page' : undefined"
+        >
+          {{ item.value.label }}
+        </NuxtLink>
+      </nav>
+    </div>
+  </header>
+  <main>
+    <slot />
+  </main>
+  <footer class="site-footer">
+    <div class="container bar muted">
+      <RichText :html="data?.settings?.footer_text" class="footer-text" />
+      <nav aria-label="Footer">
+        <NuxtLink v-for="item in data?.footerMenu?.items ?? []" :key="item.id" :to="linkHref(item)">
+          {{ item.value.label }}
+        </NuxtLink>
+        <a v-for="(url, name) in data?.settings?.social_links ?? {}" :key="name" :href="url" rel="me">{{ name }}</a>
+      </nav>
+    </div>
+  </footer>
+</template>
+
+<style scoped>
+.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 :deep(img) {
+  height: 2.5rem;
+  width: auto;
+}
+nav {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 1.25rem;
+}
+nav a {
+  text-decoration: none;
+}
+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 :deep(.footer-text p) {
+  margin: 0;
+}
+</style>

package/templates/frontend-nuxt/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-nuxt/src/pages/[...path].vue

@@ -0,0 +1,16 @@
+<script setup lang="ts">
+import { Blocks } from "@django-stack/vue";
+
+const route = useRoute();
+const path = computed(() => ([] as string[]).concat(route.params.path ?? []).join("/"));
+const { data: page } = await useContent("/_content/page", () => ({ path: path.value }));
+usePageSeo(page);
+</script>
+
+<template>
+  <article v-if="page" class="narrow">
+    <h1>{{ page.title }}</h1>
+    <Blocks :blocks="page.body" />
+    <ContactForm v-if="page.path === 'contact'" />
+  </article>
+</template>

package/templates/frontend-nuxt/src/pages/blog/[slug].vue

@@ -0,0 +1,43 @@
+<script setup lang="ts">
+import { Blocks, Image } from "@django-stack/vue";
+import type { Author, Taxonomy } from "@django-stack/utils";
+
+const route = useRoute();
+const { data: post } = await useContent(`/_content/post/${route.params.slug}`);
+usePageSeo(post, "article");
+
+const author = computed(() => (typeof post.value?.author === "object" ? (post.value.author as Author | null) : null));
+const categories = computed(() => (post.value?.categories ?? []).filter((item): item is Taxonomy => typeof item === "object"));
+const tags = computed(() => (post.value?.tags ?? []).filter((item): item is Taxonomy => typeof item === "object"));
+const date = computed(() => (post.value?.published_at ? new Date(post.value.published_at) : null));
+</script>
+
+<template>
+  <article v-if="post" class="narrow">
+    <p class="muted">
+      <time v-if="date" :datetime="date.toISOString()">{{ date.toLocaleDateString("en", { dateStyle: "long" }) }}</time>
+      <span v-if="author"> · {{ author.name }}</span>
+      <span v-for="category in categories" :key="category.slug">
+        · <NuxtLink :to="`/category/${category.slug}`">{{ category.name }}</NuxtLink>
+      </span>
+    </p>
+    <h1>{{ post.title }}</h1>
+    <Image :media="post.cover" size="content" sizes="(min-width: 48rem) 44rem, 100vw" class="cover" eager />
+    <Blocks :blocks="post.body" />
+    <p v-if="tags.length > 0" class="tags">
+      <NuxtLink v-for="tag in tags" :key="tag.slug" :to="`/tag/${tag.slug}`">#{{ tag.name }}</NuxtLink>
+    </p>
+  </article>
+</template>
+
+<style scoped>
+article :deep(.cover) {
+  width: 100%;
+  border-radius: 0.75rem;
+}
+.tags {
+  display: flex;
+  gap: 1rem;
+  margin-top: 3rem;
+}
+</style>

package/templates/frontend-nuxt/src/pages/blog/index.vue

@@ -0,0 +1,12 @@
+<script setup lang="ts">
+const route = useRoute();
+const { data: result } = await useContent("/_content/posts", () => ({ page: route.query.page }));
+usePageSeo({ title: "Blog" });
+</script>
+
+<template>
+  <section class="container">
+    <h1>Blog</h1>
+    <PostList v-if="result" :result="result" base="/blog" />
+  </section>
+</template>

package/templates/frontend-nuxt/src/pages/category/[slug].vue

@@ -0,0 +1,14 @@
+<script setup lang="ts">
+const route = useRoute();
+const { data } = await useContent(`/_content/category/${route.params.slug}`, () => ({ page: route.query.page }));
+usePageSeo(() => ({ title: data.value?.category.name, seo_description: data.value?.category.description ?? "" }));
+</script>
+
+<template>
+  <section v-if="data" class="container">
+    <p class="muted">Category</p>
+    <h1>{{ data.category.name }}</h1>
+    <p v-if="data.category.description">{{ data.category.description }}</p>
+    <PostList :result="data.result" :base="`/category/${data.category.slug}`" />
+  </section>
+</template>

package/templates/frontend-nuxt/src/pages/index.vue

@@ -0,0 +1,18 @@
+<script setup lang="ts">
+import { Blocks } from "@django-stack/vue";
+
+const { data } = await useContent("/_content/home");
+usePageSeo(() => data.value?.home);
+</script>
+
+<template>
+  <article v-if="data?.home" class="narrow">
+    <h1>{{ data.home.title }}</h1>
+    <Blocks :blocks="data.home.body" />
+  </article>
+  <section v-else class="container">
+    <h1>{{ data?.settings?.site_name ?? "Latest posts" }}</h1>
+    <p v-if="data?.settings?.tagline" class="muted">{{ data.settings.tagline }}</p>
+    <PostList v-if="data?.posts" :result="data.posts" base="/" />
+  </section>
+</template>

package/templates/frontend-nuxt/src/pages/tag/[slug].vue

@@ -0,0 +1,13 @@
+<script setup lang="ts">
+const route = useRoute();
+const { data } = await useContent(`/_content/tag/${route.params.slug}`, () => ({ page: route.query.page }));
+usePageSeo(() => ({ title: `#${data.value?.tag.name}` }));
+</script>
+
+<template>
+  <section v-if="data" class="container">
+    <p class="muted">Tag</p>
+    <h1>#{{ data.tag.name }}</h1>
+    <PostList :result="data.result" :base="`/tag/${data.tag.slug}`" />
+  </section>
+</template>

package/templates/frontend-nuxt/template.json

@@ -0,0 +1,5 @@
+{
+  "label": "Nuxt",
+  "url": "https://nuxt.com",
+  "security": "https://github.com/nuxt/nuxt/security"
+}

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

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { cached, getCached, purgeAll } from "../server/utils/cache";
+
+describe("content cache", () => {
+  it("stores, serves and purges content", async () => {
+    purgeAll();
+    expect(getCached("/_content/page?path=about")).toBeUndefined();
+    let loads = 0;
+    const load = async () => {
+      loads += 1;
+      return { title: "About" };
+    };
+    expect(await cached("/_content/page?path=about", load)).toEqual({ title: "About" });
+    expect(await cached("/_content/page?path=about", load)).toEqual({ title: "About" });
+    expect(loads).toBe(1);
+
+    expect(purgeAll()).toBe(1);
+    expect(getCached("/_content/page?path=about")).toBeUndefined();
+  });
+});