nextpluggable 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,289 @@
+# NextPluggable
+
+WordPress-style plugins for Next.js. Add one package to a site and its owner gets a
+dashboard where they connect GitHub repositories that hold plugins, then install,
+configure, update and remove those plugins themselves: no developer, no rebuild, no
+redeploy.
+
+Plugins are full features, not UI snippets. One plugin can add server-rendered pages
+that search engines index, HTTP endpoints, stored data, widgets in the site's layout,
+a settings form, and its own screens inside the dashboard.
+
+> **Status: working prototype.** Everything described here is
+> implemented and covered by tests in this repository. See [Limits](#limits) before
+> relying on it, and [docs/research.md](https://github.com/rohittp0/NextPluggable/blob/main/docs/research.md) for why it is built this way.
+
+**Documentation: <https://rohittp0.github.io/NextPluggable/>.** Each guide also exists
+as Markdown written for coding agents: give yours
+[`integrate.md`](https://rohittp0.github.io/NextPluggable/integrate.md) to add
+NextPluggable to a site, or
+[`build.md`](https://rohittp0.github.io/NextPluggable/build.md) to write plugins.
+
+## What the site owner does
+
+1. Opens `/admin/plugins` and signs in.
+2. Pastes the address of a GitHub repository under **Sources**. For a private
+   repository, the dashboard walks them through creating a read-only access token.
+3. Picks a plugin under **Add plugins**. A confirmation lists, in plain language, what
+   it adds and what it is allowed to do.
+4. The plugin is live about a second later. Its settings are an ordinary form; the
+   address of each page it adds can be changed; it can be paused, updated or removed
+   with one click.
+
+## What the developer does, once
+
+```bash
+npm install nextpluggable
+npx nextpluggable init
+```
+
+`init` adds four small files to an App Router project and never overwrites existing
+ones:
+
+| File | Purpose |
+|---|---|
+| `lib/nextpluggable.ts` | Settings: sign-in, storage, site name |
+| `app/admin/plugins/[[...np]]/page.tsx` | The dashboard |
+| `app/api/nextpluggable/[...np]/route.ts` | The dashboard's API, plugin files, and plugins' own endpoints |
+| `app/[...slug]/page.tsx` | Serves the pages plugins add. Your own routes always win; unknown addresses still get your 404 page. Optional page caching is two commented lines in this file |
+
+It also writes a generated dashboard password and secret to `.env.local`.
+
+If the site already has a root catch-all route, `init` leaves it alone. Serve plugin
+pages from it yourself: render `<np.PluginPage params={params} />` where your own lookup
+finds nothing, or, when that route never returns a 404 (a landing page for any address,
+say), ask first:
+
+```tsx
+if (await np.hasPluginPage(`/${segments.join('/')}`)) return <np.PluginPage params={params} />;
+```
+
+Optionally, mark places in your layout that plugins may fill:
+
+```tsx
+import { np } from '@/lib/nextpluggable';
+
+<nav>
+  …
+  <np.Slot name="header.actions" />
+</nav>
+…
+<np.Slot name="body.end" />
+```
+
+### Settings
+
+```ts
+import { createNextPluggable, customAuth, upstashStorage } from 'nextpluggable';
+
+export const np = createNextPluggable({
+  siteName: 'Harbor Lending',
+  // Who may use the dashboard. Default: one password from NEXTPLUGGABLE_PASSWORD.
+  auth: customAuth({
+    getUser: async (request) => {
+      const session = await getSessionSomehow(request); // Auth.js, Clerk, your own…
+      return session?.role === 'admin' ? { id: session.userId, name: session.name } : null;
+    },
+    loginUrl: '/login',
+  }),
+  // Where data lives. Default: a .nextpluggable folder.
+  storage: upstashStorage(),
+});
+```
+
+| Storage | Use it when |
+|---|---|
+| `fileStorage()` (default) | Local development, or one long-running server with a disk. Set `NEXTPLUGGABLE_DATA_DIR` to choose the folder |
+| `postgresStorage({ query })` | You already have Postgres. Pass your client's query function, e.g. `(text, params) => pool.query(text, params)` |
+| `upstashStorage()` | Serverless hosts such as Vercel. Reads `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` |
+| `memoryStorage()` | Tests |
+
+| Environment variable | Meaning |
+|---|---|
+| `NEXTPLUGGABLE_PASSWORD` | Dashboard password (when using the default sign-in) |
+| `NEXTPLUGGABLE_SECRET` | Signs sessions and encrypts stored secrets. Required in production |
+| `NEXT_PUBLIC_SITE_URL` | Public address of the site, used for canonical links |
+| `NEXTPLUGGABLE_GITHUB_TOKEN` | Optional token used for every GitHub source that has none of its own; also lifts GitHub's limit of 60 requests an hour |
+
+## Writing plugins
+
+A plugin is a folder with a manifest, React components and optional server code:
+
+```
+my-plugin/
+  plugin.json      what it adds, its settings form, what it may do
+  src/client.tsx   React components: pages, layout widgets, dashboard screens
+  src/server.ts    page loaders (data + SEO metadata) and HTTP endpoints
+  dist/            built output, committed
+```
+
+```bash
+npm install --save-dev @nextpluggable/plugin esbuild
+npx nextpluggable-plugin build
+```
+
+A repository can hold one plugin at its root, or several listed in a root
+`nextpluggable.json`. Hosts install straight from the repository at an exact commit.
+The full guide is in [docs/build.md](https://github.com/rohittp0/NextPluggable/blob/main/docs/build.md).
+
+This repository is itself a plugin source with two reference plugins:
+
+| Plugin | Shows |
+|---|---|
+| [EMI Calculator](https://github.com/rohittp0/NextPluggable/tree/main/plugins/emi-calculator) | A standalone tool: one server-rendered, interactive page with a dozen settings. 5 kB of JavaScript |
+| [Enquiry Form](https://github.com/rohittp0/NextPluggable/tree/main/plugins/enquiry-form) | A full-stack feature: a page, a public endpoint with validation, stored data, a floating button on every page, an inbox inside the dashboard, and an encrypted webhook setting |
+
+## How it works
+
+- **Loading.** A plugin ships prebuilt bundles that leave React to the host. When a
+  plugin page is requested, the site server-renders the plugin's component inside the
+  page using its own React, then the browser loads the same bundle as a normal script
+  and hydrates. Plugin code is never part of the site's build.
+- **SEO.** Plugin pages are real server-rendered HTML, complete for search engines by
+  default: their own title, description, canonical link, Open Graph and Twitter tags,
+  structured data, and an entry in the sitemap (`np.sitemap()`). A plugin can say more;
+  it never has to say anything. Addresses no plugin owns return a real 404.
+- **Speed and cost.** Sharing the site's React keeps plugin bundles small (the EMI
+  calculator is 5 kB). A plugin's stylesheet is written into the page and its script
+  loads without blocking, so a widget on every page adds no request the browser waits
+  for. By default plugin pages are rendered on each request, which is
+  always correct. They can instead be cached like static pages and refreshed the moment
+  anything changes in the dashboard; see [Caching plugin pages](#caching-plugin-pages).
+- **Safety net.** A plugin that crashes while rendering is contained: a broken widget
+  disappears and a broken page shows a short message, while the rest of the site, and
+  the dashboard needed to remove it, keep working. A plugin that fails to start is not
+  installed, and a failed update leaves the working version in place.
+
+## Caching plugin pages
+
+Uncommenting two lines in the generated `app/[...slug]/page.tsx` makes Next.js render
+each plugin page once and serve it from its cache until something changes in the
+dashboard:
+
+```ts
+export const generateStaticParams = async () => [];
+export const revalidate = 3600;
+```
+
+This is the cheapest way to run, and worth doing on sites that are mostly public
+content. Two things to know first, both measured on Next.js 16.4:
+
+- **Your root layout must not read `cookies()` or `headers()` on the server.** If it
+  does, cached plugin pages and unknown addresses fail with a 500 error in production
+  builds. It does not show up in `next dev`, so check with `next build && next start`.
+- **Next.js stores the address of the request that first generated a cached page,
+  query string included, in that page's inline data**, and serves it to later
+  visitors. This is how Next.js caches any on-demand page, not something specific to
+  plugins. If links to your site can carry private values in the query string, leave
+  caching off.
+
+Do not use `export const dynamic = 'force-static'` for this route: with it, a
+component that reads the query string has the first visitor's value rendered into the
+page everyone receives.
+
+Whatever the mode, plugin components never render the query string on the server: the
+SDK only makes it available in the browser.
+
+## Security
+
+- **Plugins are trusted code.** A plugin's server code runs inside your site and can do
+  anything your site can, exactly like a WordPress plugin or an npm package. There is
+  no sandbox yet. Connect only sources you trust.
+- What protects you today: only sources the owner connects are used; every install is
+  pinned to an exact commit; every file is checked against the fingerprint recorded
+  when the plugin was built; the install dialog states what the plugin does.
+- The dashboard requires a sign-in for everything. Sessions are signed, http-only
+  cookies. Writes are protected against cross-site request forgery. Repeated wrong
+  passwords are slowed down.
+- Access tokens and secret settings are encrypted at rest and never sent back to the
+  browser. Settings marked server-only never reach public pages.
+- Folder-based sources (for plugin development) are off in production.
+
+## Limits
+
+- **Next.js Cache Components mode is not supported yet.** With `cacheComponents: true`
+  the build fails. This is the first item on the roadmap because Next.js plans to make
+  that mode the default in version 17.
+- **Node.js runtime only**, 20.16 or newer. It does not run on Cloudflare Workers or
+  other runtimes that forbid evaluating code.
+- **Serverless hosts need a database adapter**; the default file storage needs a disk.
+- **Several server instances:** a dashboard change reaches the other instances'
+  in-memory plugin list within about five seconds, and cached pages rely on your host
+  propagating Next.js revalidation. This has been tested on a single instance only.
+- **Do not put a `loading.tsx` above the catch-all route** while it is uncached (the
+  default). Next.js would start streaming before the plugin lookup finishes, and
+  unknown addresses would return 200 with `noindex` instead of a 404. With caching
+  switched on they return a real 404 either way.
+- **Plugins cannot read the query string on the server.** Pages that vary for search
+  engines should use address segments (`/shop/page/2`); filters and searches read the
+  query in the browser.
+- **Plugin UI is React**, and plugins cannot use Next.js-only features such as server
+  components or server actions.
+- **Plugin storage is a simple key-value store**: fine for settings, messages and small
+  catalogues, not yet for large or heavily queried data.
+
+## Roadmap
+
+1. Cache Components support.
+2. One-click GitHub connection for private repositories (a GitHub App created from the
+   dashboard) in place of pasted tokens.
+3. Sandboxed execution of plugin server code, with the permissions list enforced.
+4. A shopping cart reference plugin, and richer storage (collections with queries).
+5. A second host adapter (Astro) on the same plugin format.
+
+## Repository
+
+| Path | Contents |
+|---|---|
+| `packages/nextpluggable` | The package sites install: dashboard, sign-in, storage, GitHub sources, installer, runtime |
+| `packages/plugin` | `@nextpluggable/plugin`: the SDK and build tool for plugin authors |
+| `plugins/` | Reference plugins, with their built `dist/` committed |
+| `e2e/` | Browser test of the whole owner journey against a mock GitHub API, and the small Next.js site (`e2e/site`) it runs against |
+| `docs/` | The documentation site, served by GitHub Pages: the guides ([integrate](https://github.com/rohittp0/NextPluggable/blob/main/docs/integrate.md), [build plugins](https://github.com/rohittp0/NextPluggable/blob/main/docs/build.md)) and [research and decisions](https://github.com/rohittp0/NextPluggable/blob/main/docs/research.md) |
+| `scripts/` | The release version script and the documentation site generator |
+
+### Checks
+
+```bash
+pnpm build        # packages, then plugins
+pnpm typecheck
+pnpm test         # unit tests; set TEST_POSTGRES_URL to include the Postgres adapter
+pnpm e2e          # browser test, run twice (pages uncached, then cached); needs Playwright with Chromium
+```
+
+Rebuilding the plugins must leave `plugins/*/dist` unchanged: builds are reproducible,
+and the committed output is what sites install.
+
+### Documentation site
+
+GitHub Pages serves the `docs/` folder as it is. The guides are written once, as
+`docs/integrate.md` and `docs/build.md`: those files are what coding agents read, and
+`pnpm docs:build` renders them to the HTML pages people read. Commit the generated
+pages with the Markdown change; `pnpm test` fails when they are out of date. Changes
+under `docs/` do not publish a release.
+
+### Releases
+
+Every merge to `main` publishes `nextpluggable` and `@nextpluggable/plugin` to npm
+under one shared version ([`release.yml`](.github/workflows/release.yml)), tags the
+commit and creates a GitHub release. The patch number goes up by one each time. For a
+minor or major release, set the new version in both `packages/*/package.json` files in
+the pull request; it is published as it is, and patch releases continue from there.
+
+No npm token is stored in the repository. npm lets the workflow publish because each
+package names it as its [trusted publisher](https://docs.npmjs.com/trusted-publishers),
+which can only be set up once a package exists. So there is a one-time setup:
+
+1. Publish the first version by hand, signed in to npm as yourself:
+
+   ```bash
+   pnpm install && pnpm build
+   (cd packages/plugin && pnpm publish --access public --no-git-checks)
+   (cd packages/nextpluggable && pnpm publish --access public --no-git-checks)
+   ```
+
+2. On npmjs.com, open each package's settings and add a trusted publisher: GitHub
+   Actions, user `rohittp0`, repository `NextPluggable`, workflow `release.yml`, with
+   `npm publish` allowed.
+3. Merge to `main` within two days. npm drops a trusted publisher that has not
+   published by then.

package/dist/api/handler.js

@@ -85,7 +85,7 @@ async function serveAsset(cfg, pluginId, hash, name) {
     return new Response(body, {
         headers: {
             'content-type': asset.type,
-            'cache-control': 'public, max-age=31536000, immutable',
+            'cache-control': 'public, max-age=31536000, s-maxage=31536000, immutable',
             'x-content-type-options': 'nosniff',
         },
     });

package/dist/cli.js

@@ -66,6 +66,10 @@ export default np.PluginPage;
     }
     if (['tsx', 'jsx', 'js'].some((ext) => existsSync(path.join(appDir, `loading.${ext}`))))
         result.notes.push('Your app has a root loading file. While plugin pages are uncached (the default), it makes addresses that do not exist return "200 OK" with a noindex tag instead of a 404. To get real 404s, switch on caching in the catch-all route (see the comment in that file) or move the loading file into a route group.');
+    const sitemap = ['ts', 'tsx', 'js', 'jsx'].map((ext) => path.join(appDir, `sitemap.${ext}`)).find((f) => existsSync(f));
+    result.notes.push(sitemap
+        ? `List plugin pages in your sitemap: add \`...(await np.sitemap())\` to the entries ${rel(sitemap)} returns.`
+        : 'Your site has no sitemap. To list plugin pages for search engines, create app/sitemap.ts that returns `await np.sitemap()` along with your own pages.');
     // Secrets for local development.
     const envFile = path.join(root, '.env.local');
     const env = existsSync(envFile) ? await readFile(envFile, 'utf8') : '';

package/dist/config.d.ts

@@ -25,6 +25,12 @@ export interface NextPluggableConfig {
     allowLocalSources?: boolean;
     /** How long the list of installed plugins is cached in memory per server instance. Default 5000 (0 in development). */
     cacheTtlMs?: number;
+    /**
+     * Write small plugin stylesheets into the page instead of linking to them, so a plugin
+     * never adds a request the browser must wait for. Default true. Set false on sites
+     * whose Content Security Policy forbids inline styles.
+     */
+    inlineStyles?: boolean;
 }
 export interface ResolvedConfig {
     auth: AuthAdapter;
@@ -34,6 +40,9 @@ export interface ResolvedConfig {
     apiPath: string;
     siteUrl: string;
     siteName: string;
+    /** The site name only when the developer set one: used where a placeholder would be wrong (sharing previews, structured data). */
+    publicSiteName: string | undefined;
+    inlineStyles: boolean;
     githubApiUrl: string;
     githubToken: string | undefined;
     allowLocalSources: boolean;

package/dist/config.js

@@ -45,6 +45,8 @@ export function resolveConfig(config) {
             apiPath: cleanPath(config.apiPath ?? '/api/nextpluggable', 'apiPath'),
             siteUrl: (config.siteUrl ?? defaultSiteUrl()).replace(/\/+$/, ''),
             siteName: config.siteName ?? 'Your site',
+            publicSiteName: config.siteName?.trim() || undefined,
+            inlineStyles: config.inlineStyles ?? true,
             githubApiUrl: (config.github?.apiUrl ?? process.env.NEXTPLUGGABLE_GITHUB_API_URL ?? 'https://api.github.com').replace(/\/+$/, ''),
             githubToken: config.github?.token ?? process.env.NEXTPLUGGABLE_GITHUB_TOKEN ?? undefined,
             allowLocalSources: config.allowLocalSources ?? (!production || process.env.NEXTPLUGGABLE_ALLOW_LOCAL_SOURCES === '1'),

package/dist/core/runtime.d.ts

@@ -18,6 +18,8 @@ export interface ClientAssets {
     moduleKey: string;
     scriptSrc: string;
     styleHref?: string;
+    /** The stylesheet itself, when it is small enough to be written into the page. */
+    styleCss?: string;
 }
 /**
  * Make a plugin's client bundle available to the SSR pass of this process and

package/dist/core/runtime.js

@@ -118,6 +118,8 @@ export async function loadServer(cfg, install) {
     cache.set(key, server);
     return server;
 }
+/** Larger stylesheets are linked: inlining them would bloat every page that shows the plugin. */
+const INLINE_STYLE_MAX_BYTES = 32_000;
 /**
  * Make a plugin's client bundle available to the SSR pass of this process and
  * return the URLs the browser loads it from.
@@ -137,10 +139,13 @@ export async function prepareClient(cfg, install) {
                 ssr.delete(k);
         ssr.set(moduleKey, code);
     }
+    const style = install.files.style;
+    const styleCss = style && cfg.inlineStyles && style.bytes <= INLINE_STYLE_MAX_BYTES ? ((await getFile(cfg.storage, install.id, 'style', style.sha256)) ?? undefined) : undefined;
     return {
         moduleKey,
         scriptSrc: assetUrl(cfg, install.id, client.sha256, 'client.js'),
-        styleHref: install.files.style ? assetUrl(cfg, install.id, install.files.style.sha256, 'style.css') : undefined,
+        styleHref: style ? assetUrl(cfg, install.id, style.sha256, 'style.css') : undefined,
+        styleCss,
     };
 }
 export async function runPageLoader(cfg, install, pageId, input) {

package/dist/core/sitemap.d.ts

@@ -0,0 +1,12 @@
+import type { ResolvedConfig } from '../config.js';
+export interface PluginSitemapEntry {
+    url: string;
+    lastModified?: Date;
+}
+/**
+ * Every address that switched-on plugins serve and that search engines may index, for
+ * the site's sitemap. Never throws: a plugin that fails while listing its pages keeps
+ * what it had listed so far, and a storage outage yields an empty list rather than a
+ * broken sitemap.
+ */
+export declare function pluginSitemap(cfg: ResolvedConfig): Promise<PluginSitemapEntry[]>;

package/dist/core/sitemap.js

@@ -0,0 +1,83 @@
+import { isStaticPath } from '@nextpluggable/plugin/manifest';
+import { effectivePaths, findPage, normalizePathname } from './routes.js';
+import { loadServer, pluginContext, runPageLoader } from './runtime.js';
+import { getInstalledPlugins } from './state.js';
+/** A plugin may list this many addresses; a sitemap file holds 50,000 in all. */
+const MAX_PER_PLUGIN = 10_000;
+const toDate = (value) => {
+    if (typeof value !== 'string' && !(value instanceof Date))
+        return undefined;
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? undefined : date;
+};
+async function entriesOf(cfg, install, add) {
+    const paths = effectivePaths(install);
+    const updated = toDate(install.updatedAt);
+    // Pages with a fixed address. The loader decides whether the page exists and may be indexed.
+    for (const page of install.manifest.pages ?? []) {
+        const address = paths[page.id];
+        if (!isStaticPath(address))
+            continue;
+        const result = await runPageLoader(cfg, install, page.id, { path: address, params: {} });
+        if (result.notFound || result.redirect || result.metadata?.noindex)
+            continue;
+        const canonical = result.metadata?.canonical;
+        // A page that names another address as the real one is not listed under its own.
+        if (canonical && new URL(canonical, `${cfg.siteUrl}/`).pathname !== address)
+            continue;
+        add(address, toDate(result.metadata?.modifiedTime) ?? updated);
+    }
+    // Pages with parameters: only the plugin knows which addresses exist.
+    const server = await loadServer(cfg, install);
+    if (typeof server?.sitemap !== 'function')
+        return;
+    const listed = await server.sitemap(pluginContext(cfg, install));
+    if (!Array.isArray(listed))
+        return;
+    const own = { [install.id]: install };
+    for (const entry of listed.slice(0, MAX_PER_PLUGIN)) {
+        const raw = typeof entry === 'string' ? entry : entry?.path;
+        if (typeof raw !== 'string' || !raw.startsWith('/'))
+            continue;
+        const address = normalizePathname(raw);
+        // A plugin can only add addresses of its own pages.
+        if (!findPage(own, address))
+            continue;
+        add(address, typeof entry === 'string' ? undefined : toDate(entry.lastModified));
+    }
+}
+/**
+ * Every address that switched-on plugins serve and that search engines may index, for
+ * the site's sitemap. Never throws: a plugin that fails while listing its pages keeps
+ * what it had listed so far, and a storage outage yields an empty list rather than a
+ * broken sitemap.
+ */
+export async function pluginSitemap(cfg) {
+    const out = new Map();
+    try {
+        for (const install of Object.values(await getInstalledPlugins(cfg))) {
+            if (!install.enabled)
+                continue;
+            try {
+                await entriesOf(cfg, install, (address, lastModified) => {
+                    let url;
+                    try {
+                        url = new URL(address, `${cfg.siteUrl}/`).toString();
+                    }
+                    catch {
+                        return;
+                    }
+                    if (!out.has(url))
+                        out.set(url, lastModified ? { url, lastModified } : { url });
+                });
+            }
+            catch (e) {
+                console.error(`[nextpluggable] Plugin "${install.id}" could not list all of its pages for the sitemap:`, e);
+            }
+        }
+    }
+    catch (e) {
+        console.error('[nextpluggable] Plugin pages could not be listed for the sitemap:', e);
+    }
+    return [...out.values()];
+}

package/dist/dashboard/ui.js

@@ -84,7 +84,7 @@ export function SettingInput(props) {
             control = (_jsxs("select", { ...common, value: value ?? '', onChange: (e) => onChange(e.target.value || undefined), children: [!field.required || value === undefined ? _jsx("option", { value: "", children: "Choose\u2026" }) : null, field.options?.map((o) => (_jsx("option", { value: o.value, children: o.label }, o.value)))] }));
             break;
         case 'color':
-            control = (_jsxs("span", { className: "np-color", children: [_jsx("input", { type: "color", "aria-label": `${field.label} picker`, value: /^#[0-9a-f]{6}$/i.test(String(value)) ? String(value) : '#000000', onChange: (e) => onChange(e.target.value) }), _jsx("input", { ...common, style: { maxWidth: 140 }, value: value ?? '', placeholder: "#2563eb", onChange: (e) => onChange(e.target.value) })] }));
+            control = (_jsxs("span", { className: "np-color", children: [_jsx("input", { type: "color", "aria-label": `${field.label} picker`, value: /^#[0-9a-f]{6}$/i.test(String(value)) ? String(value) : '#000000', onChange: (e) => onChange(e.target.value) }), _jsx("input", { ...common, style: { maxWidth: 140 }, value: value ?? '', placeholder: field.placeholder ?? '#2563eb', onChange: (e) => onChange(e.target.value) })] }));
             break;
         case 'secret':
             control = (_jsx("input", { ...common, type: "password", autoComplete: "new-password", value: value ?? '', placeholder: props.secretSet ? 'Saved. Type to replace it' : field.placeholder, onChange: (e) => onChange(e.target.value === '' ? undefined : e.target.value) }));

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export type { AdminUser, AuthAdapter } from './auth/types.js';
 export type { StorageAdapter } from './storage/types.js';
 export type { PluginPageProps } from './next/plugin-page.js';
 export type { SlotProps } from './next/slot.js';
+export type { PluginSitemapEntry } from './core/sitemap.js';
 export { passwordAuth, type PasswordAuthOptions } from './auth/password.js';
 export { customAuth, type CustomAuthOptions } from './auth/custom.js';
 export { fileStorage, type FileStorageOptions } from './storage/file.js';
@@ -28,12 +29,18 @@ export declare function createNextPluggable(config?: NextPluggableConfig): {
     dashboardMetadata: import("next").Metadata;
     /** Page for the root catch-all `app/[...slug]/page.tsx`: serves pages added by plugins. */
     PluginPage: (props: import("./index.js").PluginPageProps) => Promise<import("react").ReactNode>;
-    generatePluginMetadata: (props: import("./index.js").PluginPageProps) => Promise<import("next").Metadata>;
+    generatePluginMetadata: (props: import("./index.js").PluginPageProps, parent?: import("next").ResolvingMetadata) => Promise<import("next").Metadata>;
     /**
      * `await np.hasPluginPage('/some/address')`: does a plugin serve a page there? Use it in a
      * catch-all route of your own to decide whether to render `PluginPage` or your own content.
      */
     hasPluginPage: (pathname: string) => Promise<boolean>;
+    /**
+     * `await np.sitemap()`: the address of every page that switched-on plugins serve and
+     * search engines may index, as `{ url, lastModified? }`. Add them to `app/sitemap.ts`.
+     * Never throws.
+     */
+    sitemap: () => Promise<import("./index.js").PluginSitemapEntry[]>;
     /** `<Slot name="…" />` — a place in your layout that plugins can fill. */
     Slot: ({ name }: import("./index.js").SlotProps) => Promise<import("react").ReactNode>;
 };

package/dist/index.js

@@ -1,6 +1,7 @@
 import { revalidatePath } from 'next/cache';
 import { createHandler } from './api/handler.js';
 import { resolveConfig } from './config.js';
+import { pluginSitemap } from './core/sitemap.js';
 import { createDashboardPage, dashboardMetadata } from './next/dashboard-page.js';
 import { createPluginPage } from './next/plugin-page.js';
 import { createSlot } from './next/slot.js';
@@ -21,6 +22,7 @@ export function createNextPluggable(config = {}) {
         onSiteChange() {
             try {
                 revalidatePath('/', 'layout');
+                revalidatePath('/sitemap.xml');
             }
             catch (e) {
                 console.warn('[nextpluggable] Could not refresh cached pages:', e);
@@ -42,6 +44,21 @@ export function createNextPluggable(config = {}) {
          * catch-all route of your own to decide whether to render `PluginPage` or your own content.
          */
         hasPluginPage,
+        /**
+         * `await np.sitemap()`: the address of every page that switched-on plugins serve and
+         * search engines may index, as `{ url, lastModified? }`. Add them to `app/sitemap.ts`.
+         * Never throws.
+         */
+        sitemap: async () => {
+            try {
+                return await pluginSitemap(getConfig());
+            }
+            catch (e) {
+                // Setup that is not finished (no secret yet) must not break the site's sitemap.
+                console.error('[nextpluggable] Plugin pages could not be listed for the sitemap:', e);
+                return [];
+            }
+        },
         /** `<Slot name="…" />` — a place in your layout that plugins can fill. */
         Slot: createSlot(getConfig),
     };

package/dist/next/plugin-page.d.ts

@@ -1,4 +1,4 @@
-import type { Metadata } from 'next';
+import type { Metadata, ResolvingMetadata } from 'next';
 import { type ReactNode } from 'react';
 import type { PluginInfo } from '@nextpluggable/plugin';
 import type { ResolvedConfig } from '../config.js';
@@ -10,7 +10,7 @@ export interface PluginPageProps {
 export declare function pluginInfo(cfg: ResolvedConfig, install: InstallRecord, page?: PluginInfo['page']): PluginInfo;
 export declare function createPluginPage(getConfig: () => ResolvedConfig): {
     PluginPage: (props: PluginPageProps) => Promise<ReactNode>;
-    generatePluginMetadata: (props: PluginPageProps) => Promise<Metadata>;
+    generatePluginMetadata: (props: PluginPageProps, parent?: ResolvingMetadata) => Promise<Metadata>;
     hasPluginPage: (pathname: string) => Promise<boolean>;
 };
 export {};

package/dist/next/plugin-page.js

@@ -6,6 +6,8 @@ import { effectivePaths, findPage, normalizePathname } from '../core/routes.js';
 import { prepareClient, publicConfig, runPageLoader } from '../core/runtime.js';
 import { getInstalledPlugins, invalidateInstalledPlugins } from '../core/state.js';
 import { PluginGoneError } from '../errors.js';
+import { pageJsonLd, pageMetadata, pageSeo } from './seo.js';
+import { PluginStyle } from './style.js';
 /** The pathname a catch-all route was called with, whatever the segment is named. */
 async function pathnameOf(params) {
     const values = Object.values(await params);
@@ -49,31 +51,18 @@ export function createPluginPage(getConfig) {
     // Only `params` is read, never the query string, cookies or headers, so this
     // route can be statically cached as well as rendered per request.
     const resolveRequest = async (props) => run(await pathnameOf(props.params));
-    async function generatePluginMetadata(props) {
+    /**
+     * Metadata for the plugin page at the requested address. Pass Next.js's second
+     * `generateMetadata` argument through as `parent`, so a page without a sharing
+     * image of its own keeps the site's.
+     */
+    async function generatePluginMetadata(props, parent) {
         const loaded = await resolveRequest(props);
         if (!loaded || loaded.result.notFound || loaded.result.redirect)
             return {};
         const cfg = getConfig();
-        const meta = loaded.result.metadata ?? {};
-        const title = meta.title ?? loaded.match.page.title;
-        const description = meta.description ?? loaded.match.page.description;
-        const absolute = (value) => {
-            try {
-                return new URL(value, cfg.siteUrl).toString();
-            }
-            catch {
-                return undefined;
-            }
-        };
-        const canonical = absolute(meta.canonical ?? loaded.pathname);
-        const image = meta.image ? absolute(meta.image) : undefined;
-        return {
-            title,
-            description,
-            alternates: canonical ? { canonical } : undefined,
-            openGraph: { title, description, url: canonical, type: 'website', images: image ? [image] : undefined },
-            robots: meta.noindex ? { index: false, follow: false } : undefined,
-        };
+        const inherited = parent ? await Promise.resolve(parent).catch(() => null) : null;
+        return pageMetadata(cfg, pageSeo(cfg, loaded.match.install, loaded.match.page, loaded.pathname, loaded.result), inherited);
     }
     /**
      * Server component for a root catch-all route. Renders the plugin page that
@@ -87,8 +76,8 @@ export function createPluginPage(getConfig) {
         if (result.redirect)
             redirect(result.redirect);
         const cfg = getConfig();
-        const jsonLd = result.jsonLd ? (Array.isArray(result.jsonLd) ? result.jsonLd : [result.jsonLd]) : [];
-        return (_jsxs(_Fragment, { children: [assets.styleHref ? _jsx("link", { rel: "stylesheet", href: assets.styleHref, precedence: "nextpluggable" }) : null, jsonLd.map((item, i) => (_jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: JSON.stringify(item).replace(/</g, '\\u003c') } }, i))), _jsx(PluginIsland, { moduleKey: assets.moduleKey, src: assets.scriptSrc, component: match.page.component, info: pluginInfo(cfg, match.install, { id: match.page.id, path: pathname, params: match.params }), config: publicConfig(match.install), props: { data: result.data ?? {}, params: match.params }, errorFallback: _jsx("p", { style: { padding: '48px 16px', textAlign: 'center' }, children: "This page could not be displayed. Please try again later." }) })] }));
+        const jsonLd = pageJsonLd(cfg, pageSeo(cfg, match.install, match.page, pathname, result), result);
+        return (_jsxs(_Fragment, { children: [_jsx(PluginStyle, { assets: assets }), jsonLd.map((item, i) => (_jsx("script", { type: "application/ld+json", dangerouslySetInnerHTML: { __html: JSON.stringify(item).replace(/</g, '\\u003c') } }, i))), _jsx(PluginIsland, { moduleKey: assets.moduleKey, src: assets.scriptSrc, component: match.page.component, info: pluginInfo(cfg, match.install, { id: match.page.id, path: pathname, params: match.params }), config: publicConfig(match.install), props: { data: result.data ?? {}, params: match.params }, errorFallback: _jsx("p", { style: { padding: '48px 16px', textAlign: 'center' }, children: "This page could not be displayed. Please try again later." }) })] }));
     }
     /**
      * Whether an installed, switched-on plugin serves a page at this address. For sites

package/dist/next/seo.d.ts

@@ -0,0 +1,32 @@
+/**
+ * What a plugin page tells search engines and sharing previews. A plugin may say
+ * as little as nothing: every gap is filled here, so a page is complete by default.
+ */
+import type { Metadata, ResolvedMetadata } from 'next';
+import type { PluginPage } from '@nextpluggable/plugin/manifest';
+import type { PageResult } from '@nextpluggable/plugin/server';
+import type { ResolvedConfig } from '../config.js';
+import type { InstallRecord } from '../core/types.js';
+export interface PageSeo {
+    title: string;
+    /** Never empty: the loader's, else the page's, else the plugin's, else the title. */
+    description: string;
+    canonical?: string;
+    image?: string;
+    imageAlt: string;
+    type: 'website' | 'article';
+    publishedTime?: string;
+    modifiedTime?: string;
+    noindex: boolean;
+}
+/** An absolute URL on this site, or undefined when the value cannot be one. */
+export declare function absoluteUrl(cfg: Pick<ResolvedConfig, 'siteUrl'>, value: string): string | undefined;
+export declare function pageSeo(cfg: Pick<ResolvedConfig, 'siteUrl'>, install: InstallRecord, page: PluginPage, pathname: string, result: PageResult): PageSeo;
+/**
+ * Next.js metadata for the page. `inherited` is what the layouts above already
+ * declared: a page that brings no image of its own keeps the site's sharing image,
+ * site name and Twitter account, but never the site's title or description.
+ */
+export declare function pageMetadata(cfg: Pick<ResolvedConfig, 'publicSiteName'>, seo: PageSeo, inherited?: ResolvedMetadata | null): Metadata;
+/** Structured data for the page: the plugin's own, or a plain description of the page when it gives none. */
+export declare function pageJsonLd(cfg: Pick<ResolvedConfig, 'siteUrl' | 'publicSiteName'>, seo: PageSeo, result: PageResult): Record<string, unknown>[];

package/dist/next/seo.js

@@ -0,0 +1,86 @@
+const clean = (value) => {
+    if (typeof value !== 'string')
+        return undefined;
+    const text = value.replace(/\s+/g, ' ').trim();
+    return text || undefined;
+};
+/** An absolute URL on this site, or undefined when the value cannot be one. */
+export function absoluteUrl(cfg, value) {
+    try {
+        return new URL(value, `${cfg.siteUrl}/`).toString();
+    }
+    catch {
+        return undefined;
+    }
+}
+export function pageSeo(cfg, install, page, pathname, result) {
+    const meta = result.metadata ?? {};
+    const title = clean(meta.title) ?? page.title;
+    const image = clean(meta.image);
+    return {
+        title,
+        description: clean(meta.description) ?? clean(page.description) ?? clean(install.manifest.description) ?? title,
+        canonical: absoluteUrl(cfg, clean(meta.canonical) ?? pathname),
+        image: image ? absoluteUrl(cfg, image) : undefined,
+        imageAlt: clean(meta.imageAlt) ?? title,
+        type: meta.type === 'article' ? 'article' : 'website',
+        publishedTime: clean(meta.publishedTime),
+        modifiedTime: clean(meta.modifiedTime),
+        noindex: meta.noindex === true,
+    };
+}
+/**
+ * Next.js metadata for the page. `inherited` is what the layouts above already
+ * declared: a page that brings no image of its own keeps the site's sharing image,
+ * site name and Twitter account, but never the site's title or description.
+ */
+export function pageMetadata(cfg, seo, inherited) {
+    const og = inherited?.openGraph;
+    const tw = inherited?.twitter;
+    const ownImage = seo.image ? [{ url: seo.image, alt: seo.imageAlt }] : undefined;
+    // "player" and "app" cards need fields a page cannot supply.
+    const inheritedCard = tw?.card === 'summary' || tw?.card === 'summary_large_image' ? tw.card : undefined;
+    return {
+        title: seo.title,
+        description: seo.description,
+        alternates: seo.canonical ? { canonical: seo.canonical } : undefined,
+        openGraph: {
+            type: seo.type,
+            title: seo.title,
+            description: seo.description,
+            url: seo.canonical,
+            siteName: og?.siteName ?? cfg.publicSiteName,
+            locale: og?.locale,
+            images: ownImage ?? og?.images,
+            ...(seo.type === 'article' ? { publishedTime: seo.publishedTime, modifiedTime: seo.modifiedTime } : {}),
+        },
+        twitter: {
+            card: ownImage ? 'summary_large_image' : (inheritedCard ?? 'summary'),
+            title: seo.title,
+            description: seo.description,
+            site: tw?.site ?? undefined,
+            creator: tw?.creator ?? undefined,
+            images: ownImage ?? tw?.images,
+        },
+        robots: seo.noindex ? { index: false, follow: false } : undefined,
+    };
+}
+/** Structured data for the page: the plugin's own, or a plain description of the page when it gives none. */
+export function pageJsonLd(cfg, seo, result) {
+    if (result.jsonLd)
+        return Array.isArray(result.jsonLd) ? result.jsonLd : [result.jsonLd];
+    if (seo.noindex)
+        return [];
+    return [
+        {
+            '@context': 'https://schema.org',
+            '@type': 'WebPage',
+            name: seo.title,
+            description: seo.description,
+            ...(seo.canonical ? { url: seo.canonical } : {}),
+            ...(seo.image ? { image: seo.image } : {}),
+            ...(seo.modifiedTime ? { dateModified: seo.modifiedTime } : {}),
+            ...(cfg.publicSiteName ? { isPartOf: { '@type': 'WebSite', name: cfg.publicSiteName, url: cfg.siteUrl } } : {}),
+        },
+    ];
+}

package/dist/next/slot.js

@@ -5,6 +5,7 @@ import { prepareClient, publicConfig } from '../core/runtime.js';
 import { getInstalledPlugins } from '../core/state.js';
 import { PluginGoneError } from '../errors.js';
 import { pluginInfo } from './plugin-page.js';
+import { PluginStyle } from './style.js';
 export function createSlot(getConfig) {
     /**
      * A place in the site's layout where installed plugins may render something
@@ -29,7 +30,7 @@ export function createSlot(getConfig) {
                 });
                 if (!assets)
                     return null;
-                return (_jsxs(Fragment, { children: [assets.styleHref ? _jsx("link", { rel: "stylesheet", href: assets.styleHref, precedence: "nextpluggable" }) : null, _jsx(PluginIsland, { moduleKey: assets.moduleKey, src: assets.scriptSrc, component: slot.component, info: pluginInfo(cfg, install), config: publicConfig(install) })] }, `${install.id}:${slot.component}`));
+                return (_jsxs(Fragment, { children: [_jsx(PluginStyle, { assets: assets }), _jsx(PluginIsland, { moduleKey: assets.moduleKey, src: assets.scriptSrc, component: slot.component, info: pluginInfo(cfg, install), config: publicConfig(install) })] }, `${install.id}:${slot.component}`));
             }));
             return _jsx(_Fragment, { children: rendered });
         }

package/dist/next/style.d.ts

@@ -0,0 +1,10 @@
+import type { ReactNode } from 'react';
+import type { ClientAssets } from '../core/runtime.js';
+/**
+ * A plugin's CSS. Small stylesheets are written into the page itself, so a plugin
+ * never adds a request the browser must wait for before it can paint. React keeps
+ * one copy per page however many of the plugin's components are on it.
+ */
+export declare function PluginStyle({ assets }: {
+    assets: ClientAssets;
+}): ReactNode;

package/dist/next/style.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * A plugin's CSS. Small stylesheets are written into the page itself, so a plugin
+ * never adds a request the browser must wait for before it can paint. React keeps
+ * one copy per page however many of the plugin's components are on it.
+ */
+export function PluginStyle({ assets }) {
+    if (!assets.styleHref)
+        return null;
+    if (assets.styleCss !== undefined)
+        return (_jsx("style", { href: assets.styleHref, precedence: "nextpluggable", children: assets.styleCss }));
+    return _jsx("link", { rel: "stylesheet", href: assets.styleHref, precedence: "nextpluggable" });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nextpluggable",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "WordPress-style plugins for Next.js: a dashboard where site owners install full-featured plugins from GitHub repositories, with no rebuild.",
   "repository": {
     "type": "git",
@@ -30,7 +30,7 @@
     "bin"
   ],
   "dependencies": {
-    "@nextpluggable/plugin": "0.1.0"
+    "@nextpluggable/plugin": "0.1.1"
   },
   "peerDependencies": {
     "next": ">=15.0.0",