create-goodfellow 0.0.0-stage → 0.1.0

package/templates/next/.gitlab-ci.yml

@@ -0,0 +1,18 @@
+# Builds the site and publishes it with GitLab Pages whenever the default
+# branch changes (including every Publish in the admin panel). For nightly
+# rebuilds, add a schedule under Build → Pipeline schedules. See README.md.
+pages:
+  image: node:22
+  cache:
+    key:
+      files: [package-lock.json]
+    paths: [.npm/, .next/cache/]
+  script:
+    - npm ci --cache .npm --prefer-offline
+    # Pages may serve the site from a subfolder, such as https://group.gitlab.io/site/.
+    - export GOODFELLOW_BASE="$(node -e 'console.log(new URL(process.env.CI_PAGES_URL).pathname)')"
+    - npx next build
+  pages:
+    publish: out
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

package/templates/next/README.md

@@ -0,0 +1,120 @@
+# My site
+
+A website built with [Goodfellow](https://github.com/chartung17/goodfellow-cms) and [Next.js](https://nextjs.org). Pages are files in `content/`, edited in the admin panel at `/admin`, and built into static files that a free host serves.
+
+## Working on the site
+
+<!-- goodfellow-repository -->
+> **In the Goodfellow repository**, this folder is part of a pnpm workspace, so `npm install` doesn't work here. From the repository's root, run `pnpm install` and `pnpm build` (get pnpm with `corepack enable`, or `npm install -g pnpm`), then `pnpm dev` in this folder. The `npm` commands below are for a site of your own, created with `npm create goodfellow`, which leaves this note out.
+<!-- /goodfellow-repository -->
+
+```sh
+npm install
+npm run dev      # site at http://localhost:4321, admin panel at http://localhost:4321/admin
+npm run build    # builds the site into out/
+```
+
+On your own computer, the admin panel saves straight to the files in `content/`. To see the built site as a host would serve it, serve `out/` with any static server, such as `npx serve out`.
+
+The News page and its stories are an example of a collection: a group of similar items that share one page design. Change it or delete it under **Collections** in the admin panel.
+
+## How it fits together
+
+| File | What it does |
+|---|---|
+| `goodfellow.config.tsx` | The site's blocks and where it's stored, shared by its pages and the admin panel |
+| `app/(site)/layout.tsx` | The site's header and footer, shown once around every page, so they stay as they are when moving between pages |
+| `app/(site)/[[...path]]/page.tsx` | Every page in `content/`, rendered as Server Components. Links between pages use `next/link`, and images `next/image`. |
+| `app/not-found.tsx` | The site's "Page not found" page, `content/pages/404.json` |
+| `app/admin/page.tsx` | The admin panel |
+| `app/admin/demo-content.json/route.ts` | For a [demo](https://github.com/chartung17/goodfellow-cms#demo-mode) (`demo: true` in the config), the copy of the content its admin panel starts from |
+| `app/site.css` | The site's styles: Tailwind, the theme, and the custom CSS from the admin panel |
+| `app/layout.tsx`, `app/sitemap.ts`, `app/robots.ts` | The page around everything, and files for search engines |
+| `next.config.ts` | `withGoodfellow()` builds static files, serves the site from a subfolder when the host needs it, and runs the admin panel's local backend in `next dev` |
+
+Your own Next.js pages can go beside these, in `app/`, and import from the project root as `@/`, such as `@/lib/site`.
+
+More blocks, such as an FAQ, tabs and a pricing table, can be added on the admin panel's **Blocks** screen, which publishes their code into `blocks/installed/` and the shadcn components they use into `components/ui/`. See [Blocks from block registries](https://github.com/chartung17/goodfellow-cms#blocks-from-block-registries).
+
+Blocks are React components in `blocks/`, added to the editor in `goodfellow.config.tsx`. For links and images, use `SiteLink` and `SiteImage` from `@goodfellow-cms/react` rather than `<a>` and `<img>`, so they follow the site's address and use `next/link` and `next/image`. Read the site's settings, menus and collections with `useSite()`.
+
+Interactive parts of a block go in a Client Component: a file starting with `"use client"`, which can use any React hooks and runs in the browser. Pass it plain values and content such as `children`, not functions. `useSite()` works there too.
+
+Images are served as they are. To resize them and convert them to modern formats, set a [custom image loader](https://nextjs.org/docs/app/api-reference/components/image#loader) for a service such as Cloudinary under `images` in `withGoodfellow({ ... })`.
+
+## Putting the site online
+
+Setup takes four steps. It's done once, usually by whoever set up the site.
+
+### 1. Store the site on GitHub or GitLab
+
+Create a repository and push this folder to it, including `package-lock.json`.
+
+### 2. Tell Goodfellow where the site is stored
+
+If you gave the repository when creating the site with `npm create goodfellow`, this is already done. Otherwise, in `goodfellow.config.tsx`, uncomment one `backend` line and its `import`, and fill in your repository:
+
+```tsx
+import { github } from "@goodfellow-cms/github";
+
+export default defineConfig({
+  blocks,
+  categories,
+  backend: github({ repo: "your-name/your-site" }),
+});
+```
+
+Until a backend is set, the admin panel on the live site only says it isn't set up yet. If the live site is built from a branch other than the repository's default branch, add `branch: "name"`.
+
+Also set the site's address under **Site settings → General → Site address**, including any subfolder (such as `https://your-name.github.io/your-site`). It's used for the sitemap and for link previews.
+
+### 3. Choose a host
+
+Each host's free plan has its own rules about business use. If the site is for a business, sells anything, shows ads, or is built or looked after by someone who's paid for it, check those rules first. As of October 2026, GitHub Pages and Vercel's free plan don't allow most of these, and GitLab Pages has no rule against them that we know of. See [Commercial sites](https://github.com/chartung17/goodfellow-cms#requirements-and-limits) in Goodfellow's README.
+
+**GitHub Pages** (free for public repositories; not for online businesses or shops)
+
+1. In the repository on GitHub, go to **Settings → Pages** and set **Source** to **GitHub Actions**.
+2. Push. `.github/workflows/deploy.yml` builds and publishes the site on every change and once a night. If your main branch isn't called `main`, change it in that file.
+
+**GitLab Pages** (free, including for private projects; no rule against business sites that we know of)
+
+1. Push. `.gitlab-ci.yml` builds and publishes the site on every change to the default branch.
+2. For nightly rebuilds, add a schedule under **Build → Pipeline schedules**.
+3. The site's address is under **Deploy → Pages**.
+
+**Vercel** (works with GitHub and GitLab; the free plan is for non-commercial sites only)
+
+1. Import the repository in Vercel, which recognizes it as a Next.js site.
+2. For nightly rebuilds, create a deploy hook under **Settings → Git → Deploy Hooks**, and call it from a scheduled GitHub Action or GitLab pipeline schedule.
+
+Delete the setup files for the hosts you don't use.
+
+### 4. Set up sign-in
+
+**GitHub:** nothing to set up. Editors sign in at `/admin` with an access token. The admin panel links to GitHub's token page with the right permissions already chosen. On that page, under **Repository access**, choose **Only select repositories** and pick the site.
+
+- Editors who are collaborators on someone else's personal repository can't use that kind of token. They can use the "broader token" link instead. Alternatively, move the repository into a free GitHub organization and make editors members.
+
+**GitLab:** editors can sign in with an access token straight away. For one-click **Sign in with GitLab**, register the admin panel with GitLab once:
+
+1. Go to your profile's **Preferences → Applications** (or the group's **Settings → Applications**) and add an application.
+2. Set:
+   - **Redirect URI:** the admin panel's address with a trailing slash, such as `https://your-site.example/admin/`.
+   - **Confidential:** leave this **off**.
+   - **Scopes:** `api`.
+3. Copy the **Application ID** into the config: `gitlab({ project: "your-name/your-site", clientId: "…" })`.
+
+Every editor needs permission to change the repository: on GitHub, write access; on GitLab, the Developer role or higher.
+
+## Images and files
+
+Upload images and files on the admin panel's **Media** screen, or with the **Choose image** button wherever an image goes. They're saved in `public/media/`, and large photos are made web-sized automatically.
+
+## Writing with AI
+
+The admin panel's **AI** tab can draft pages, rewrite blocks and fill in news stories. Each editor picks an AI service there. Claude and some others need the editor's own API key and charge for use; there are free options, including copying the request into a chat app such as Claude.ai. To offer only some services, or to turn the assistant off, see `ai` in [Goodfellow's README](https://github.com/chartung17/goodfellow-cms#ai-services).
+
+## Publishing
+
+Each **Publish** in the admin panel saves its changes as one commit to the main branch, which starts a new build. The admin panel shows when the live site has been updated, usually within a minute or two. If someone else changed the same page in the meantime, publishing stops and explains what happened, instead of overwriting their work.

package/templates/next/_gitignore

@@ -0,0 +1,5 @@
+node_modules/
+.next/
+out/
+next-env.d.ts
+*.tsbuildinfo

package/templates/next/app/(site)/[[...path]]/page.tsx

@@ -0,0 +1,8 @@
+import { site } from "@/lib/site";
+import "@/app/site.css";
+
+// Builds every page in content/. Other addresses show "Page not found": a static host has no file for
+// them, and in `next dev` the page isn't found. (`dynamicParams` stays on, so `next dev` shows new pages at once.)
+export const generateStaticParams = site.generateStaticParams;
+export const generateMetadata = site.generateMetadata;
+export default site.Page;

package/templates/next/app/(site)/layout.tsx

@@ -0,0 +1,5 @@
+import { site } from "@/lib/site";
+import "@/app/site.css";
+
+// The site's header and footer, shown once around every page, so they stay as they are when moving between pages.
+export default site.Layout;

package/templates/next/app/admin/demo-content.json/route.ts

@@ -0,0 +1,5 @@
+import { site } from "@/lib/site";
+
+// The copy of the site's content a demo's admin panel starts from, when the config sets `demo`.
+export const dynamic = "force-static";
+export const GET = site.demoContent;

package/templates/next/app/admin/layout.tsx

@@ -0,0 +1,8 @@
+import type { Metadata } from "next";
+import type { ReactNode } from "react";
+
+export const metadata: Metadata = { title: "Site admin", robots: { index: false } };
+
+export default function AdminLayout({ children }: { children: ReactNode }) {
+  return children;
+}

package/templates/next/app/admin/page.tsx

@@ -0,0 +1,8 @@
+"use client";
+
+import { GoodfellowAdmin } from "@goodfellow-cms/next/admin";
+import config from "@/goodfellow.config";
+
+export default function AdminPage() {
+  return <GoodfellowAdmin config={config} />;
+}

package/templates/next/app/layout.tsx

@@ -0,0 +1,11 @@
+import { loadSite } from "@goodfellow-cms/next";
+import type { ReactNode } from "react";
+
+export default async function RootLayout({ children }: { children: ReactNode }) {
+  const { settings } = await loadSite();
+  return (
+    <html lang={settings.language}>
+      <body>{children}</body>
+    </html>
+  );
+}

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

@@ -0,0 +1,4 @@
+import { site } from "@/lib/site";
+import "@/app/site.css";
+
+export default site.NotFound;

package/templates/next/app/robots.ts

@@ -0,0 +1,4 @@
+import { site } from "@/lib/site";
+
+export const dynamic = "force-static";
+export default site.robots;

package/templates/next/app/site.css

@@ -0,0 +1,11 @@
+/* The site's styles, used by its pages but not the admin panel. */
+@import "tailwindcss";
+/* Animations for blocks installed from block registries, such as an FAQ's opening answers. */
+@import "tw-animate-css";
+@import "@goodfellow-cms/react/theme.css";
+@import "@goodfellow-cms/blocks/styles.css";
+/* Site-wide CSS written in the admin panel. */
+@import "../content/styles/custom.css";
+
+/* Lets Tailwind find class names typed into the editor. */
+@source "../content";

package/templates/next/app/sitemap.ts

@@ -0,0 +1,4 @@
+import { site } from "@/lib/site";
+
+export const dynamic = "force-static";
+export default site.sitemap;

package/templates/next/blocks/installed/index.ts

@@ -0,0 +1,7 @@
+// Written by the admin panel when blocks are installed or removed. Don't edit it by hand.
+import type { ComponentConfig, Config } from "@puckeditor/core";
+
+// biome-ignore lint/suspicious/noExplicitAny: blocks have arbitrary props
+export const installedBlocks: Record<string, ComponentConfig<any>> = {};
+
+export const installedCategories: NonNullable<Config["categories"]> = {};

package/templates/next/components.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "app/site.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "registries": {
+    "@goodfellow": "https://cdn.jsdelivr.net/npm/@goodfellow-cms/registry@latest/r/{name}.json"
+  }
+}

package/templates/next/content/collections/news/_collection.json

@@ -0,0 +1,113 @@
+{
+  "version": 1,
+  "entryName": "News story",
+  "fields": [
+    {
+      "type": "text",
+      "label": "Title",
+      "name": "title",
+      "required": true
+    },
+    {
+      "type": "date",
+      "label": "Date",
+      "name": "date",
+      "required": true
+    },
+    {
+      "type": "textarea",
+      "hint": "One or two sentences, shown in lists of news.",
+      "label": "Summary",
+      "name": "summary"
+    },
+    {
+      "type": "image",
+      "label": "Image",
+      "name": "image"
+    },
+    {
+      "type": "richtext",
+      "label": "Text",
+      "name": "text"
+    }
+  ],
+  "name": "News",
+  "path": "/news/{slug}",
+  "sort": {
+    "field": "date",
+    "order": "desc"
+  },
+  "template": {
+    "content": [
+      {
+        "type": "Section",
+        "props": {
+          "id": "Section-news",
+          "background": "none",
+          "backgroundImage": "",
+          "className": "",
+          "content": [
+            {
+              "type": "EntryField",
+              "props": {
+                "id": "EntryField-date",
+                "className": "",
+                "field": "date",
+                "style": "small"
+              }
+            },
+            {
+              "type": "EntryField",
+              "props": {
+                "id": "EntryField-title",
+                "className": "mt-2",
+                "field": "title",
+                "style": "title"
+              }
+            },
+            {
+              "type": "EntryField",
+              "props": {
+                "id": "EntryField-image",
+                "className": "mt-8",
+                "field": "image",
+                "style": "text"
+              }
+            },
+            {
+              "type": "EntryField",
+              "props": {
+                "id": "EntryField-text",
+                "className": "mt-8",
+                "field": "text",
+                "style": "text"
+              }
+            },
+            {
+              "type": "Button",
+              "props": {
+                "id": "Button-news",
+                "className": "mt-10",
+                "href": "/news",
+                "label": "All news",
+                "newTab": false,
+                "size": "md",
+                "variant": "outline"
+              }
+            }
+          ],
+          "padding": "lg",
+          "width": "narrow"
+        }
+      }
+    ],
+    "root": {
+      "props": {
+        "className": "",
+        "description": "{summary}",
+        "image": "{image}",
+        "title": "{title}"
+      }
+    }
+  }
+}

package/templates/next/content/collections/news/open-house.json

@@ -0,0 +1,9 @@
+{
+  "version": 1,
+  "fields": {
+    "date": "2026-09-20",
+    "summary": "Drop in any time between 10 and 2 to meet everyone.",
+    "text": "<p>Everyone is welcome. Refreshments will be served.</p>",
+    "title": "Open house this Saturday"
+  }
+}

package/templates/next/content/collections/news/welcome.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "fields": {
+    "date": "2026-10-01",
+    "image": "/media/placeholder.svg",
+    "summary": "Our new site is easier to keep up to date, so you'll always find the latest news here.",
+    "text": "<p>This is a news story. Add your own on the <strong>Collections</strong> screen of the admin panel, and they'll appear on the news page in date order.</p>",
+    "title": "Welcome to our new website"
+  }
+}

package/templates/next/content/layout/footer.json

@@ -0,0 +1,55 @@
+{
+  "version": 1,
+  "data": {
+    "content": [
+      {
+        "type": "Section",
+        "props": {
+          "id": "Section-footer",
+          "background": "muted",
+          "backgroundImage": "",
+          "className": "",
+          "content": [
+            {
+              "type": "Flex",
+              "props": {
+                "id": "Flex-footer",
+                "align": "center",
+                "className": "",
+                "direction": "row",
+                "gap": "md",
+                "items": [
+                  {
+                    "type": "Text",
+                    "props": {
+                      "id": "Text-footer",
+                      "align": "left",
+                      "className": "text-sm text-muted-foreground",
+                      "content": "<p>© My site. Built with Goodfellow.</p>"
+                    }
+                  },
+                  {
+                    "type": "Menu",
+                    "props": {
+                      "id": "Menu-footer",
+                      "className": "text-sm",
+                      "menu": "footer",
+                      "orientation": "horizontal"
+                    }
+                  }
+                ],
+                "justify": "between",
+                "wrap": true
+              }
+            }
+          ],
+          "padding": "sm",
+          "width": "wide"
+        }
+      }
+    ],
+    "root": {
+      "props": {}
+    }
+  }
+}

package/templates/next/content/layout/header.json

@@ -0,0 +1,54 @@
+{
+  "version": 1,
+  "data": {
+    "content": [
+      {
+        "type": "Section",
+        "props": {
+          "id": "Section-header",
+          "background": "none",
+          "backgroundImage": "",
+          "className": "",
+          "content": [
+            {
+              "type": "Flex",
+              "props": {
+                "id": "Flex-header",
+                "align": "center",
+                "className": "",
+                "direction": "row",
+                "gap": "md",
+                "items": [
+                  {
+                    "type": "SiteBrand",
+                    "props": {
+                      "id": "SiteBrand-header",
+                      "className": "",
+                      "show": "both"
+                    }
+                  },
+                  {
+                    "type": "Menu",
+                    "props": {
+                      "id": "Menu-main",
+                      "className": "",
+                      "menu": "main",
+                      "orientation": "horizontal"
+                    }
+                  }
+                ],
+                "justify": "between",
+                "wrap": true
+              }
+            }
+          ],
+          "padding": "sm",
+          "width": "wide"
+        }
+      }
+    ],
+    "root": {
+      "props": {}
+    }
+  }
+}

package/templates/next/content/menus.json

@@ -0,0 +1,25 @@
+{
+  "version": 1,
+  "menus": {
+    "footer": [
+      {
+        "href": "/about",
+        "label": "About"
+      }
+    ],
+    "main": [
+      {
+        "href": "/",
+        "label": "Home"
+      },
+      {
+        "href": "/about",
+        "label": "About"
+      },
+      {
+        "href": "/news",
+        "label": "News"
+      }
+    ]
+  }
+}

package/templates/next/content/pages/404.json

@@ -0,0 +1,73 @@
+{
+  "version": 1,
+  "data": {
+    "content": [
+      {
+        "type": "Section",
+        "props": {
+          "id": "Section-not-found",
+          "background": "none",
+          "backgroundImage": "",
+          "className": "",
+          "content": [
+            {
+              "type": "Heading",
+              "props": {
+                "id": "Heading-not-found",
+                "align": "center",
+                "className": "",
+                "level": "h1",
+                "text": "Page not found"
+              }
+            },
+            {
+              "type": "Text",
+              "props": {
+                "id": "Text-not-found",
+                "align": "center",
+                "className": "mt-4 text-muted-foreground",
+                "content": "<p>The page you're looking for doesn't exist or has moved.</p>"
+              }
+            },
+            {
+              "type": "Flex",
+              "props": {
+                "id": "Flex-not-found",
+                "align": "center",
+                "className": "mt-8",
+                "direction": "row",
+                "gap": "md",
+                "items": [
+                  {
+                    "type": "Button",
+                    "props": {
+                      "id": "Button-home",
+                      "className": "",
+                      "href": "/",
+                      "label": "Go to the home page",
+                      "newTab": false,
+                      "size": "md",
+                      "variant": "primary"
+                    }
+                  }
+                ],
+                "justify": "center",
+                "wrap": true
+              }
+            }
+          ],
+          "padding": "lg",
+          "width": "narrow"
+        }
+      }
+    ],
+    "root": {
+      "props": {
+        "className": "",
+        "description": "",
+        "image": "",
+        "title": "Page not found"
+      }
+    }
+  }
+}