@goodfellow-cms/next 0.3.0 → 0.4.0

package/README.md

@@ -1,12 +1,12 @@
 # @goodfellow-cms/next
 
-Goodfellow pages and the admin panel in a Next.js App Router site, exported as static files. Links use `next/link` and images `next/image`.
+Goodfellow pages and the admin panel in a Next.js App Router site, exported as static files, or with a server of its own that publishes for editors who sign in with the site's own sign-in (`@goodfellow-cms/next/server`). Links use `next/link` and images `next/image`.
 
 Start from the Next.js starter: `npm create goodfellow@latest my-site -- --template next`.
 
 [Goodfellow](https://github.com/goodfellow-cms/goodfellow-cms) is a website builder for people who aren't developers, with no server or database: pages are files in your own GitHub or GitLab repository, edited in a visual editor built on [Puck](https://puckeditor.com). To start a new site, run `npm create goodfellow@latest my-site`. See the [documentation](https://goodfellow-cms.github.io/goodfellow-cms/) for everything else.
 
-More in the docs: [Next.js](https://goodfellow-cms.github.io/goodfellow-cms/docs/nextjs).
+More in the docs: [Next.js](https://goodfellow-cms.github.io/goodfellow-cms/docs/nextjs) and [Full-stack Next.js sites](https://goodfellow-cms.github.io/goodfellow-cms/docs/full-stack-nextjs).
 
 ## License
 

package/bin/goodfellow-next.js

@@ -2,13 +2,32 @@
 // After `next build`: `goodfellow-next finish out` fixes the export's prefetch files on Windows,
 // writes the calendar files of collections of events and the pages at redirects' old addresses, and the search index for sites with a search block. `index` only writes the index.
 // `goodfellow-next update` updates Goodfellow, as `goodfellow update` does for other sites.
+// `goodfellow-next content link|copy [folder]` puts a content repository's files in place, for a site whose
+// content is kept in a repository of its own.
+import { rm } from "node:fs/promises";
+import { relative } from "node:path";
 import { parseArgs } from "node:util";
 import { formatUpdateResult } from "@goodfellow-cms/core";
-import { update } from "@goodfellow-cms/core/node";
-import { writeSearchIndex } from "@goodfellow-cms/core/search-index";
-import { fixSegmentFiles, writeCalendarFiles, writeRedirectFiles } from "@goodfellow-cms/next/export";
+import { ContentRepositoryError, setUpContentRepository, update } from "@goodfellow-cms/core/node";
+import { writePagesSearchIndex, writeSearchIndex } from "@goodfellow-cms/core/search-index";
+import { builtPages, fixSegmentFiles, writeCalendarFiles, writeRedirectFiles } from "@goodfellow-cms/next/export";
 
 const [command, dir = "out"] = process.argv.slice(2);
+// A full-stack site (withGoodfellow(config, { server: true })): Next.js serves its pages and sends redirects
+// itself, so the calendar files and the search index are written into public/, which `next start` and hosts
+// serve as static files, as they are for an export.
+if (command === "finish" && dir === "--server") {
+  await rm("public/calendars", { recursive: true, force: true });
+  const calendars = await writeCalendarFiles("public");
+  if (calendars > 0) console.log(`Wrote ${calendars} calendar files, in public/calendars`);
+  const indexed = await writePagesSearchIndex(await builtPages(), "public/pagefind");
+  console.log(
+    indexed === undefined
+      ? "No page has a search block, so there's nothing to index"
+      : `Indexed ${indexed} pages for search, in public/pagefind`,
+  );
+  process.exit(0);
+}
 if (command === "update") {
   const { values } = parseArgs({
     args: process.argv.slice(3),
@@ -19,19 +38,45 @@ if (command === "update") {
   console.log(formatUpdateResult(result));
   process.exit(result.state === "failed" ? 1 : 0);
 }
+if (command === "content") {
+  const [action, from] = process.argv.slice(3);
+  if (action === "link" || action === "copy") {
+    try {
+      const folder =
+        relative(process.cwd(), await setUpContentRepository(".", { from, copy: action === "copy" })) || ".";
+      console.log(
+        action === "copy"
+          ? `Copied content/ and public/media/ from ${folder}`
+          : `Linked content/ and public/media/ to ${folder}, so the site's content is the content repository's`,
+      );
+      process.exit(0);
+    } catch (error) {
+      if (!(error instanceof ContentRepositoryError)) throw error;
+      console.error(error.message);
+      process.exit(1);
+    }
+  }
+}
 if (command !== "finish" && command !== "index") {
   console.error(
     [
       "Usage: goodfellow-next finish [folder]",
+      "       goodfellow-next finish --server",
       "       goodfellow-next index [folder]",
       "       goodfellow-next update [--to fixes|automatic|latest|<release>] [--publish]",
+      "       goodfellow-next content link|copy [folder]",
       "",
       "finish  Gets the exported site in folder (default: out) ready to publish: puts the files",
       "        Next.js uses to load pages ahead where browsers look for them, writes calendar files",
       "        for collections of events and pages that send visitors on from old addresses, and",
-      "        indexes it for search.",
+      "        indexes it for search. With --server, for a full-stack site, writes the calendar",
+      "        files into public/calendars and indexes the pages next build rendered into",
+      "        public/pagefind instead.",
       "index   Only indexes the exported site for its search block.",
       "update  Updates Goodfellow, and blocks from its registry, if the site still builds.",
+      "content For a site whose content is kept in a repository of its own: links content/ and",
+      "        public/media/ to the content repository in folder (default: content-repository),",
+      "        or copies them from it, as builds do.",
     ].join("\n"),
   );
   process.exit(1);

package/dist/admin.d.ts

@@ -10,12 +10,19 @@ export interface GoodfellowAdminProps {
   siteUrl?: string;
   /** Replaces any of the admin panel's text, for rewording or translation. */
   strings?: Partial<Strings>;
+  /**
+   * On a full-stack site, the address of its `goodfellowApi()` route, such as
+   * `/api/goodfellow`, without the base path. Editors then sign in with the
+   * site's own sign-in, and its server publishes for them. `next dev` still
+   * saves to the files on disk.
+   */
+  server?: string;
 }
 /**
  * The admin panel, for a Next.js site's `app/admin/page.tsx`, which must be a
  * Client Component (`"use client"`) that imports the site's config.
  * In `next dev` it saves to the files on disk; on the live site, editors sign
- * in to the config's git backend.
+ * in to the config's git backend, or on a full-stack site (`server`), with the site's own sign-in.
  */
-export declare function GoodfellowAdmin({ config, siteUrl, strings }: GoodfellowAdminProps): import("react").JSX.Element | null;
+export declare function GoodfellowAdmin({ config, siteUrl, strings, server }: GoodfellowAdminProps): import("react").JSX.Element | null;
 //#endregion

package/dist/admin.js

@@ -40,9 +40,9 @@ async function setUp(siteUrl) {
 * The admin panel, for a Next.js site's `app/admin/page.tsx`, which must be a
 * Client Component (`"use client"`) that imports the site's config.
 * In `next dev` it saves to the files on disk; on the live site, editors sign
-* in to the config's git backend.
+* in to the config's git backend, or on a full-stack site (`server`), with the site's own sign-in.
 */
-function GoodfellowAdmin({ config, siteUrl = `${BASE_PATH}/`, strings }) {
+function GoodfellowAdmin({ config, siteUrl = `${BASE_PATH}/`, strings, server }) {
 	const [setup, setSetup] = useState(null);
 	useEffect(() => {
 		let current = true;
@@ -64,6 +64,7 @@ function GoodfellowAdmin({ config, siteUrl = `${BASE_PATH}/`, strings }) {
 			store: setup.store,
 			registry: `${BASE_PATH}/__goodfellow/api/registry/{name}.json`
 		},
+		...server && { server: `${BASE_PATH}${server}` },
 		preview: {
 			stylesheets: setup.stylesheets,
 			themeCss: theme_css_default,

package/dist/config.d.ts

@@ -3,6 +3,13 @@ import { NextConfig } from "next";
 export interface GoodfellowNextOptions {
   /** The site's folder, holding `content/` and `public/media/`. Defaults to the folder Next.js runs in. */
   root?: string;
+  /**
+   * For a full-stack site, with a server of its own: builds it for `next start`
+   * or a host that runs Next.js, rather than as static files, and includes
+   * `content/` and `public/media/` with its server, which reads them for pages
+   * built on request and calendar files.
+   */
+  server?: boolean;
 }
 /**
  * Sets up Next.js for a Goodfellow site, in `next.config.ts`:
@@ -16,6 +23,8 @@ export interface GoodfellowNextOptions {
  * - Serves images as they are unless the site sets an image loader, since static files can't be optimized on request.
  * - Adds the site's redirects (Site Settings → Redirects) ahead of the site's own, for hosts that
  *   send them, such as Vercel. Others get the pages `goodfellow-next finish` writes at old addresses.
+ * - With `{ server: true }`, builds a full-stack site for a server instead of as static
+ *   files: see `goodfellowApi()` in `@goodfellow-cms/next/server`.
  * - In `next dev`, runs the admin panel's local backend, so publishing saves to
  *   the files on disk. It's never part of a build.
  * - In `next dev`, turns off React's debug channel (`experimental.reactDebugChannel`)

package/dist/config.js

@@ -1,5 +1,5 @@
 import { CALENDARS_DIR, allPages, loadSiteContent, normalizeBase, redirectFrom, redirectProblems } from "@goodfellow-cms/core";
-import { DEV_API_PREFIX, fileSystemSource, handleDevApi, isLocalOrigin, localFileStore, localRegistryDir } from "@goodfellow-cms/core/node";
+import { DEV_API_PREFIX, contentRepositoryProblem, fileSystemSource, handleDevApi, isLocalOrigin, localFileStore, localRegistryDir } from "@goodfellow-cms/core/node";
 import { createServer } from "node:http";
 import { resolve } from "node:path";
 //#region src/config.ts
@@ -91,6 +91,8 @@ async function siteRedirects(root) {
 * - Serves images as they are unless the site sets an image loader, since static files can't be optimized on request.
 * - Adds the site's redirects (Site Settings → Redirects) ahead of the site's own, for hosts that
 *   send them, such as Vercel. Others get the pages `goodfellow-next finish` writes at old addresses.
+* - With `{ server: true }`, builds a full-stack site for a server instead of as static
+*   files: see `goodfellowApi()` in `@goodfellow-cms/next/server`.
 * - In `next dev`, runs the admin panel's local backend, so publishing saves to
 *   the files on disk. It's never part of a build.
 * - In `next dev`, turns off React's debug channel (`experimental.reactDebugChannel`)
@@ -101,6 +103,8 @@ function withGoodfellow(nextConfig = {}, options = {}) {
 	const root = resolve(options.root ?? process.cwd());
 	const basePath = nextBasePath(nextConfig.basePath ?? process.env.GOODFELLOW_BASE);
 	return async (phase) => {
+		const problem = contentRepositoryProblem(root);
+		if (problem) throw new Error(problem);
 		const config = {
 			trailingSlash: true,
 			...nextConfig,
@@ -111,6 +115,19 @@ function withGoodfellow(nextConfig = {}, options = {}) {
 				GOODFELLOW_BASE_PATH: basePath
 			}
 		};
+		if (phase !== PHASE_DEVELOPMENT_SERVER && options.server) return {
+			...config,
+			images: nextConfig.images,
+			outputFileTracingIncludes: {
+				...nextConfig.outputFileTracingIncludes,
+				"/**": [
+					...nextConfig.outputFileTracingIncludes?.["/**"] ?? [],
+					"./content/**/*",
+					"./public/media/**/*"
+				]
+			},
+			redirects: async () => [...await siteRedirects(root), ...await nextConfig.redirects?.() ?? []]
+		};
 		if (phase !== PHASE_DEVELOPMENT_SERVER) return {
 			output: "export",
 			...config,

package/dist/export.d.ts

@@ -19,4 +19,16 @@ export declare function writeRedirectFiles(outDir: string, root?: string): Promi
  * prefetch is "not found". Returns how many files it moved; none elsewhere.
  */
 export declare function fixSegmentFiles(outDir: string): Promise<number>;
+/** A page `next build` rendered ahead: its address on the site, and its HTML. */
+export interface BuiltPage {
+  url: string;
+  html: string;
+}
+/**
+ * The pages `next build` rendered ahead for a full-stack site (`withGoodfellow(config,
+ * { server: true })`), at their addresses on the site, without its base path, as the
+ * Search block looks them up. Next.js lists them in `.next/prerender-manifest.json`
+ * and keeps their HTML in `.next/server/app/`. The admin panel and Next.js's own pages are left out.
+ */
+export declare function builtPages(root?: string): Promise<BuiltPage[]>;
 //#endregion

package/dist/export.js

@@ -88,5 +88,28 @@ async function fixSegmentFiles(outDir) {
 	await visit(outDir);
 	return moved;
 }
+/**
+* The pages `next build` rendered ahead for a full-stack site (`withGoodfellow(config,
+* { server: true })`), at their addresses on the site, without its base path, as the
+* Search block looks them up. Next.js lists them in `.next/prerender-manifest.json`
+* and keeps their HTML in `.next/server/app/`. The admin panel and Next.js's own pages are left out.
+*/
+async function builtPages(root = process.cwd()) {
+	const next = join(resolve(root), ".next");
+	const manifest = JSON.parse(await readFile(join(next, "prerender-manifest.json"), "utf8"));
+	const trailingSlash = JSON.parse(await readFile(join(next, "required-server-files.json"), "utf8")).config?.trailingSlash === true;
+	const pages = [];
+	for (const route of Object.keys(manifest.routes ?? {})) {
+		if (route.startsWith("/_") || route === "/admin" || route.startsWith("/admin/")) continue;
+		const file = join(next, "server/app", `${route === "/" ? "/index" : route}.html`);
+		if (!await exists(file)) continue;
+		const url = route === "/" ? "/" : trailingSlash ? `${route}/` : route;
+		pages.push({
+			url,
+			html: await readFile(file, "utf8")
+		});
+	}
+	return pages;
+}
 //#endregion
-export { fixSegmentFiles, writeCalendarFiles, writeRedirectFiles };
+export { builtPages, fixSegmentFiles, writeCalendarFiles, writeRedirectFiles };

package/dist/server.d.ts

@@ -0,0 +1,57 @@
+import { GoodfellowConfig } from "@goodfellow-cms/core";
+import { AppApiOptions } from "@goodfellow-cms/core/node";
+import { ServerKeys } from "@goodfellow-cms/ai";
+//#region src/server.d.ts
+/** The environment variable the server's token is read from, unless `goodfellowApi({ token })` gives one. */
+export declare const GIT_TOKEN_VARIABLE = "GOODFELLOW_GIT_TOKEN";
+export interface GoodfellowApiOptions {
+  /** The site's `goodfellow.config.tsx`, whose `backend` says where the site is stored. */
+  config: GoodfellowConfig;
+  /**
+   * A token that can read and publish to the site's repository, such as a
+   * fine-grained GitHub token or a GitLab project access token. It never
+   * reaches a browser. Defaults to the `GOODFELLOW_GIT_TOKEN` environment variable.
+   */
+  token?: string | (() => Promise<string>);
+  /**
+   * Who's signed in, from the site's own sign-in (such as Better Auth's
+   * `auth.api.getSession({ headers: request.headers })`): their name, email
+   * address and role, or `null` if nobody is, or `false` if they may not edit.
+   */
+  authorize: AppApiOptions["authorize"];
+  /** Where the admin panel sends people to sign in, such as `/sign-in?next=/admin/`. */
+  signIn: string;
+  /** Where the admin panel's Sign out button goes, if the site has an address for it. */
+  signOut?: string;
+  /**
+   * Keys for AI services, such as `{ anthropic: process.env.ANTHROPIC_API_KEY }`,
+   * so the AI assistant's requests go through the server and editors need no
+   * keys of their own. Services without a key are left out.
+   */
+  ai?: ServerKeys;
+  /** Told about failures editors only hear about as "something went wrong". Defaults to `console.error`. */
+  onError?: (error: unknown) => void;
+}
+/** The route parameters of a catch-all route named `[...path]`. */
+interface RouteContext {
+  params: Promise<{
+    path?: string[];
+  }>;
+}
+/**
+ * The admin panel's API on a full-stack Next.js site, for
+ * `app/api/goodfellow/[...path]/route.ts`:
+ *
+ * ```ts
+ * export const { GET, POST } = goodfellowApi({ config, authorize, signIn: "/sign-in" });
+ * ```
+ *
+ * The admin panel (`<GoodfellowAdmin server="/api/goodfellow" />`) reads and
+ * publishes through it, and the server reaches the repository with its own
+ * token, naming each editor as the author of what they publish.
+ */
+export declare function goodfellowApi(options: GoodfellowApiOptions): {
+  GET: (request: Request, context: RouteContext) => Promise<Response>;
+  POST: (request: Request, context: RouteContext) => Promise<Response>;
+};
+//#endregion

package/dist/server.js

@@ -0,0 +1,45 @@
+import { appApi } from "@goodfellow-cms/core/node";
+import { aiServer } from "@goodfellow-cms/ai";
+//#region src/server.ts
+/** The environment variable the server's token is read from, unless `goodfellowApi({ token })` gives one. */
+const GIT_TOKEN_VARIABLE = "GOODFELLOW_GIT_TOKEN";
+/**
+* The admin panel's API on a full-stack Next.js site, for
+* `app/api/goodfellow/[...path]/route.ts`:
+*
+* ```ts
+* export const { GET, POST } = goodfellowApi({ config, authorize, signIn: "/sign-in" });
+* ```
+*
+* The admin panel (`<GoodfellowAdmin server="/api/goodfellow" />`) reads and
+* publishes through it, and the server reaches the repository with its own
+* token, naming each editor as the author of what they publish.
+*/
+function goodfellowApi(options) {
+	let api;
+	function handler() {
+		if (api) return api;
+		const { backend } = options.config;
+		if (!backend?.server) throw new Error("goodfellowApi() needs the config's `backend`, such as github({ repo }) or gitlab({ project }).");
+		const token = options.token || process.env["GOODFELLOW_GIT_TOKEN"] || (() => {
+			throw new Error(`goodfellowApi() needs a token: set GOODFELLOW_GIT_TOKEN, or pass \`token\`.`);
+		})();
+		const ai = options.ai && aiServer(options.ai);
+		api = appApi({
+			git: backend.server({ token }),
+			authorize: options.authorize,
+			signIn: options.signIn,
+			...options.signOut && { signOut: options.signOut },
+			...ai && ai.services.length > 0 && { ai },
+			...options.onError && { onError: options.onError }
+		});
+		return api;
+	}
+	const route = async (request, context) => handler()(request, ((await context.params).path ?? []).join("/"));
+	return {
+		GET: route,
+		POST: route
+	};
+}
+//#endregion
+export { GIT_TOKEN_VARIABLE, goodfellowApi };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodfellow-cms/next",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Goodfellow pages and the admin panel in a Next.js site.",
   "keywords": [
     "goodfellow",
@@ -43,6 +43,11 @@
       "import": "./dist/export.js",
       "default": "./dist/export.js"
     },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "default": "./dist/server.js"
+    },
     "./package.json": "./package.json"
   },
   "bin": {
@@ -53,15 +58,16 @@
     "dist"
   ],
   "dependencies": {
-    "@goodfellow-cms/core": "0.3.0",
-    "@goodfellow-cms/react": "0.3.0"
+    "@goodfellow-cms/ai": "0.4.0",
+    "@goodfellow-cms/react": "0.4.0",
+    "@goodfellow-cms/core": "0.4.0"
   },
   "peerDependencies": {
     "@puckeditor/core": "0.23.0",
     "next": "^16.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@goodfellow-cms/admin": "0.3.0"
+    "@goodfellow-cms/admin": "0.4.0"
   },
   "devDependencies": {
     "@puckeditor/core": "0.23.0",
@@ -71,7 +77,9 @@
     "next": "16.3.8",
     "react": "19.3.0",
     "react-dom": "19.3.0",
-    "@goodfellow-cms/admin": "0.3.0"
+    "@goodfellow-cms/admin": "0.4.0",
+    "@goodfellow-cms/github": "0.4.0",
+    "@goodfellow-cms/gitlab": "0.4.0"
   },
   "engines": {
     "node": ">=22"