nextpluggable 0.0.0-stage → 0.1.1

package/dist/cli.js

@@ -0,0 +1,123 @@
+/**
+ * `npx nextpluggable init` — wire NextPluggable into an existing Next.js (App Router) site.
+ * Creates four small files and never overwrites anything that already exists.
+ */
+import { randomBytes } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { appendFile, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+const importPath = (fromFile, toFile) => {
+    const rel = path.relative(path.dirname(fromFile), toFile).split(path.sep).join('/').replace(/\.(t|j)sx?$/, '');
+    return rel.startsWith('.') ? rel : `./${rel}`;
+};
+export async function init(projectDir) {
+    const root = path.resolve(projectDir);
+    const result = { created: [], skipped: [], notes: [] };
+    const appDir = ['app', 'src/app'].map((d) => path.join(root, d)).find((d) => existsSync(d));
+    if (!appDir)
+        throw new Error('No "app" directory found. NextPluggable needs a Next.js project that uses the App Router (run this in the project root).');
+    const ts = existsSync(path.join(root, 'tsconfig.json'));
+    const x = ts ? 'ts' : 'js';
+    const libFile = path.join(path.dirname(appDir), 'lib', `nextpluggable.${x}`);
+    const rel = (file) => path.relative(root, file).split(path.sep).join('/');
+    async function create(file, content) {
+        if (existsSync(file))
+            return void result.skipped.push(rel(file));
+        await mkdir(path.dirname(file), { recursive: true });
+        await writeFile(file, content);
+        result.created.push(rel(file));
+    }
+    await create(libFile, `import { createNextPluggable } from 'nextpluggable';
+
+// Sign-in: one password, read from NEXTPLUGGABLE_PASSWORD. To use your site's own
+// login instead, pass \`auth: customAuth({ getUser })\`.
+// Data: a .nextpluggable folder next to your project. On serverless hosts
+// (Vercel, Netlify) pass a database instead, e.g. \`storage: upstashStorage()\`.
+export const np = createNextPluggable({
+  siteName: 'My site',
+});
+`);
+    const apiRoute = path.join(appDir, 'api', 'nextpluggable', '[...np]', `route.${x}`);
+    await create(apiRoute, `import { np } from '${importPath(apiRoute, libFile)}';\n\nexport const { GET, POST, PUT, PATCH, DELETE } = np.handlers;\n`);
+    const dashboard = path.join(appDir, 'admin', 'plugins', '[[...np]]', `page.${x}x`);
+    await create(dashboard, `import { np } from '${importPath(dashboard, libFile)}';\n\nexport const metadata = np.dashboardMetadata;\nexport default np.DashboardPage;\n`);
+    // A root catch-all is where plugin pages are served. If the site already has one, it must be merged by hand.
+    const existingCatchAll = (await readdir(appDir, { withFileTypes: true })).find((e) => e.isDirectory() && /^\[\[?\.\.\..+\]\]?$/.test(e.name));
+    if (existingCatchAll) {
+        result.notes.push(`Your site already has a catch-all route (${rel(path.join(appDir, existingCatchAll.name))}). To serve plugin pages from it, render \`<np.PluginPage params={params} />\` there when your own lookup finds nothing, or ask \`await np.hasPluginPage(pathname)\` first if that route never returns a 404.`);
+    }
+    else {
+        const catchAll = path.join(appDir, '[...slug]', `page.${x}x`);
+        await create(catchAll, `import { np } from '${importPath(catchAll, libFile)}';
+
+// Addresses your own routes don't handle land here. Installed plugins answer
+// for the pages they add; everything else gets your normal 404 page.
+export const generateMetadata = np.generatePluginMetadata;
+export default np.PluginPage;
+
+// Faster and cheaper: uncomment the next two lines to cache plugin pages like
+// static pages. The dashboard refreshes the cache whenever a plugin changes.
+// Only do this if nothing in your root layout reads cookies() or headers() on
+// the server: with caching on, such a layout makes these pages fail with a
+// 500 error in production builds (it will not show up in \`next dev\`).
+// export const generateStaticParams = async () => [];
+// export const revalidate = 3600;
+`);
+    }
+    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') : '';
+    const additions = [];
+    if (!/^NEXTPLUGGABLE_PASSWORD=/m.test(env)) {
+        result.password = randomBytes(9).toString('base64url');
+        additions.push(`NEXTPLUGGABLE_PASSWORD=${result.password}`);
+    }
+    if (!/^NEXTPLUGGABLE_SECRET=/m.test(env))
+        additions.push(`NEXTPLUGGABLE_SECRET=${randomBytes(32).toString('base64url')}`);
+    if (additions.length) {
+        await appendFile(envFile, `${env && !env.endsWith('\n') ? '\n' : ''}\n# NextPluggable (plugin dashboard)\n${additions.join('\n')}\n`);
+        result.created.push('.env.local (added NextPluggable settings)');
+    }
+    const gitignore = path.join(root, '.gitignore');
+    if (existsSync(gitignore)) {
+        const current = await readFile(gitignore, 'utf8');
+        if (!/^\/?\.nextpluggable\/?$/m.test(current))
+            await appendFile(gitignore, `${current.endsWith('\n') ? '' : '\n'}\n# NextPluggable local data\n.nextpluggable/\n`);
+        if (!/^\.env(\.local|\*|\.\*)?$/m.test(current))
+            result.notes.push('Make sure .env.local is not committed: it now holds your dashboard password.');
+    }
+    return result;
+}
+const HELP = `nextpluggable — WordPress-style plugins for Next.js
+
+Usage:
+  npx nextpluggable init [dir]    Add the dashboard, API route and plugin page route to a Next.js site
+`;
+export async function main() {
+    const [command, dir] = process.argv.slice(2);
+    if (command !== 'init') {
+        console.log(HELP);
+        return command && command !== 'help' && command !== '--help' ? 1 : 0;
+    }
+    const result = await init(dir ?? '.');
+    for (const f of result.created)
+        console.log(`  created  ${f}`);
+    for (const f of result.skipped)
+        console.log(`  kept     ${f} (already exists)`);
+    console.log(`
+Next steps
+  1. Start your site and open /admin/plugins${result.password ? `\n     Dashboard password: ${result.password}  (saved in .env.local)` : ''}
+  2. Optional: add <np.Slot name="header.actions" />, <np.Slot name="footer" /> and
+     <np.Slot name="body.end" /> to your root layout so plugins can add buttons and widgets there.
+  3. Before going live, set NEXTPLUGGABLE_PASSWORD and NEXTPLUGGABLE_SECRET on your host,
+     and choose a storage adapter if the host has no persistent disk.`);
+    for (const note of result.notes)
+        console.log(`\nNote: ${note}`);
+    return 0;
+}

package/dist/client/host-runtime.d.ts

@@ -0,0 +1,9 @@
+import * as React from 'react';
+import type { HostRuntime, PluginApi, PluginInfo } from '@nextpluggable/plugin';
+export interface PluginRuntimeValue {
+    info: PluginInfo;
+    config: Record<string, unknown>;
+}
+export declare const PluginRuntimeContext: React.Context<PluginRuntimeValue | null>;
+export declare function createPluginApi(apiBase: string): PluginApi;
+export declare const hostRuntime: HostRuntime;

package/dist/client/host-runtime.js

@@ -0,0 +1,71 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The host's implementation of `@nextpluggable/plugin`. Plugin bundles keep that
+ * module external; when they `require` it they receive this object, so every
+ * plugin shares the site's React, router and context.
+ */
+import NextLink from 'next/link';
+import { usePathname, useRouter, useSearchParams } from 'next/navigation';
+import * as React from 'react';
+export const PluginRuntimeContext = React.createContext(null);
+function useRuntime() {
+    const value = React.useContext(PluginRuntimeContext);
+    if (!value)
+        throw new Error('Plugin hooks can only be used inside a plugin component.');
+    return value;
+}
+export function createPluginApi(apiBase) {
+    return (path, init = {}) => {
+        const { json, headers, ...rest } = init;
+        const h = new Headers(headers);
+        h.set('x-nextpluggable', '1');
+        if (json !== undefined)
+            h.set('content-type', 'application/json');
+        return fetch(`${apiBase}${path.startsWith('/') ? path : `/${path}`}`, {
+            credentials: 'same-origin',
+            ...rest,
+            headers: h,
+            body: json !== undefined ? JSON.stringify(json) : rest.body,
+        });
+    };
+}
+const subscribeToNothing = () => () => { };
+export const hostRuntime = {
+    usePluginConfig() {
+        return useRuntime().config;
+    },
+    usePlugin() {
+        return useRuntime().info;
+    },
+    usePluginApi() {
+        const { apiBase } = useRuntime().info;
+        return React.useMemo(() => createPluginApi(apiBase), [apiBase]);
+    },
+    useNavigation() {
+        const router = useRouter();
+        const pathname = usePathname();
+        return React.useMemo(() => ({
+            pathname,
+            push: (href) => router.push(href),
+            replace: (href) => router.replace(href),
+            back: () => router.back(),
+        }), [router, pathname]);
+    },
+    useQuery() {
+        // The query string must never reach server-rendered HTML: plugin pages may be cached and
+        // served to every visitor, and a query can carry private values. So it is not read on the
+        // server at all, stays empty while the browser hydrates (to match that HTML), and becomes
+        // available on the first update after.
+        // eslint-disable-next-line react-hooks/rules-of-hooks -- the branch is fixed per environment
+        const live = typeof window === 'undefined' ? null : useSearchParams();
+        const hydrated = React.useSyncExternalStore(subscribeToNothing, () => true, () => false);
+        const search = hydrated && live ? live.toString() : '';
+        return React.useMemo(() => new URLSearchParams(search), [search]);
+    },
+    Link(props) {
+        return _jsx(NextLink, { ...props });
+    },
+};
+// Also reachable through the published SDK module, in case a plugin bundled it by mistake.
+globalThis[Symbol.for('nextpluggable.host-runtime')] = hostRuntime;

package/dist/client/island.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Renders a component from a plugin bundle that was not part of this site's build.
+ *
+ * Server (SSR pass): the bundle's source was placed in process memory by the
+ * server component that rendered us; it is evaluated here with THIS module
+ * graph's React, so the plugin renders into the same tree as the rest of the page.
+ *
+ * Browser: the same bundle arrives as a <script>, registers itself, and is
+ * given the browser's React. `use()` suspends until it has, and React keeps the
+ * server-rendered HTML in place and hydrates it once the module is ready.
+ */
+import * as React from 'react';
+import * as jsxRuntime from 'react/jsx-runtime';
+import type { PluginInfo } from '@nextpluggable/plugin';
+export interface PluginIslandProps {
+    moduleKey: string;
+    src: string;
+    /** Name of the export to render. */
+    component: string;
+    info: PluginInfo;
+    config: Record<string, unknown>;
+    props?: Record<string, unknown>;
+    /** Shown if the plugin crashes. Slots default to nothing so a broken widget never breaks the page around it. */
+    errorFallback?: React.ReactNode;
+    /** Shown while the bundle loads on client-side navigation. */
+    loadingFallback?: React.ReactNode;
+}
+export declare function PluginIsland(p: PluginIslandProps): jsxRuntime.JSX.Element;

package/dist/client/island.js

@@ -0,0 +1,177 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Renders a component from a plugin bundle that was not part of this site's build.
+ *
+ * Server (SSR pass): the bundle's source was placed in process memory by the
+ * server component that rendered us; it is evaluated here with THIS module
+ * graph's React, so the plugin renders into the same tree as the rest of the page.
+ *
+ * Browser: the same bundle arrives as a <script>, registers itself, and is
+ * given the browser's React. `use()` suspends until it has, and React keeps the
+ * server-rendered HTML in place and hydrates it once the module is ready.
+ */
+import * as React from 'react';
+import * as ReactDOM from 'react-dom';
+import * as jsxRuntime from 'react/jsx-runtime';
+import { hostRuntime, PluginRuntimeContext } from './host-runtime.js';
+import { ClientOnly, createGuardedRuntime } from './ssr-guard.js';
+const shared = {
+    react: React,
+    'react/jsx-runtime': jsxRuntime,
+    'react-dom': ReactDOM,
+    '@nextpluggable/plugin': hostRuntime,
+};
+function hostRequire(name) {
+    if (name in shared)
+        return shared[name];
+    throw new Error(`A plugin tried to load "${name}", which this site does not provide. Bundle it into the plugin instead.`);
+}
+function instantiate(factory, require = hostRequire) {
+    const module = { exports: {} };
+    factory(require, module, module.exports);
+    return module.exports;
+}
+/** Server only: the crash guard each plugin bundle was instantiated with. */
+const guards = new Map();
+function settled(value) {
+    const p = Promise.resolve(value);
+    p.status = 'fulfilled';
+    p.value = value;
+    return p;
+}
+function failed(reason) {
+    const p = Promise.reject(reason);
+    p.catch(() => { });
+    p.status = 'rejected';
+    p.reason = reason;
+    return p;
+}
+const modules = new Map();
+const pending = new Map();
+const LOAD_TIMEOUT_MS = 20_000;
+function register(key, factory) {
+    const waiter = pending.get(key);
+    pending.delete(key);
+    try {
+        const mod = instantiate(factory);
+        if (waiter)
+            waiter.resolve(mod);
+        else
+            modules.set(key, settled(mod));
+    }
+    catch (e) {
+        if (waiter)
+            waiter.reject(e);
+        else
+            modules.set(key, failed(e));
+    }
+}
+if (typeof window !== 'undefined') {
+    // Bundles that arrived before this module ran queued themselves; later ones call straight in.
+    const w = window;
+    const queued = Array.isArray(w.__NP_Q__) ? w.__NP_Q__ : [];
+    w.__NP_Q__ = { push: (entry) => register(entry[0], entry[1]) };
+    for (const entry of queued)
+        register(entry[0], entry[1]);
+}
+function loadModule(key, src) {
+    const existing = modules.get(key);
+    if (existing)
+        return existing;
+    let tracked;
+    if (typeof window === 'undefined') {
+        const state = globalThis[Symbol.for('nextpluggable.state')];
+        const code = state?.ssrCode?.get(key);
+        // Keep only the newest build of each plugin in memory.
+        const prefix = `${key.split('@')[0]}@`;
+        for (const k of modules.keys())
+            if (k.startsWith(prefix))
+                (modules.delete(k), guards.delete(k));
+        try {
+            if (code === undefined)
+                throw new Error(`Plugin bundle ${key} was not prepared for server rendering.`);
+            // On the server the plugin is given a React that contains its crashes (see ssr-guard).
+            const guarded = createGuardedRuntime(`Plugin "${key.split('@')[0]}"`);
+            guards.set(key, guarded);
+            const guardedRequire = (name) => (name === 'react' ? guarded.react : name === 'react/jsx-runtime' ? guarded.jsxRuntime : hostRequire(name));
+            tracked = settled(instantiate(new Function('require', 'module', 'exports', `${code}\n//# sourceURL=nextpluggable-plugin:///${key}/client.js`), guardedRequire));
+        }
+        catch (e) {
+            console.error(`[nextpluggable] Plugin bundle ${key} could not be loaded on the server and was left out of the page:`, e);
+            tracked = failed(e);
+        }
+    }
+    else {
+        tracked = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                pending.delete(key);
+                reject(new Error(`Timed out loading plugin bundle ${key}.`));
+            }, LOAD_TIMEOUT_MS);
+            pending.set(key, {
+                resolve: (m) => {
+                    clearTimeout(timer);
+                    resolve(m);
+                },
+                reject: (e) => {
+                    clearTimeout(timer);
+                    reject(e);
+                },
+            });
+            if (!document.querySelector(`script[src="${CSS.escape(src)}"]`)) {
+                const script = document.createElement('script');
+                script.src = src;
+                script.async = true;
+                script.onerror = () => {
+                    clearTimeout(timer);
+                    pending.delete(key);
+                    reject(new Error(`Could not load plugin bundle ${key}.`));
+                };
+                document.head.appendChild(script);
+            }
+        });
+        tracked.then((value) => {
+            tracked.status = 'fulfilled';
+            tracked.value = value;
+        }, (reason) => {
+            tracked.status = 'rejected';
+            tracked.reason = reason;
+        });
+    }
+    modules.set(key, tracked);
+    return tracked;
+}
+function Loaded(props) {
+    const tracked = loadModule(props.moduleKey, props.src);
+    if (typeof window === 'undefined') {
+        // A bundle that failed to load must not fail the page: leave it to the browser, where the error boundary handles it.
+        const Component = tracked.status === 'fulfilled' ? tracked.value?.[props.component] : undefined;
+        if (typeof Component !== 'function')
+            return _jsx(ClientOnly, {});
+        const Guarded = (guards.get(props.moduleKey)?.guard(Component) ?? Component);
+        return _jsx(Guarded, { ...props.componentProps });
+    }
+    const mod = React.use(tracked);
+    const Component = mod[props.component];
+    if (typeof Component !== 'function')
+        throw new Error(`Plugin bundle ${props.moduleKey} does not export "${props.component}".`);
+    return _jsx(Component, { ...props.componentProps });
+}
+class Boundary extends React.Component {
+    state = { failed: false };
+    static getDerivedStateFromError() {
+        return { failed: true };
+    }
+    componentDidCatch(error) {
+        console.error(`[nextpluggable] ${this.props.label} failed to render:`, error);
+    }
+    render() {
+        return this.state.failed ? this.props.fallback : this.props.children;
+    }
+}
+export function PluginIsland(p) {
+    // Start fetching the bundle as early as possible; during SSR this emits an async <script> in the document head.
+    ReactDOM.preinit(p.src, { as: 'script' });
+    const value = React.useMemo(() => ({ info: p.info, config: p.config }), [p.info, p.config]);
+    return (_jsx(PluginRuntimeContext.Provider, { value: value, children: _jsx(Boundary, { fallback: p.errorFallback ?? null, label: `Plugin "${p.info.id}"`, children: _jsx(React.Suspense, { fallback: p.loadingFallback ?? null, children: _jsx(Loaded, { moduleKey: p.moduleKey, src: p.src, component: p.component, componentProps: p.props ?? {} }) }) }) }));
+}

package/dist/client/ssr-guard.d.ts

@@ -0,0 +1,11 @@
+import * as React from 'react';
+import * as jsxRuntime from 'react/jsx-runtime';
+/** Renders nothing in the browser; on the server it hands the enclosing Suspense boundary over to client rendering. */
+export declare const ClientOnly: React.ComponentType<{}>;
+export interface GuardedRuntime {
+    /** Wrap one component type. */
+    guard<T>(type: T): T;
+    react: typeof React;
+    jsxRuntime: typeof jsxRuntime;
+}
+export declare function createGuardedRuntime(label: string): GuardedRuntime;

package/dist/client/ssr-guard.js

@@ -0,0 +1,100 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Keeps a crashing plugin from failing the server render of the page around it.
+ *
+ * React has no error boundaries on the server: a component that throws there
+ * fails the nearest Suspense boundary, and for statically cached pages Next.js
+ * then (rightly) refuses to produce the page at all. A widget in the site's
+ * layout would take every page down with it.
+ *
+ * Plugins get React from the host, so on the server the host hands them a
+ * React whose element factories wrap every plugin function component in a
+ * try/catch. When one throws, it is replaced by a client-only placeholder:
+ * the page is produced without that plugin's HTML and the browser renders the
+ * plugin itself. If it throws there too, the island's error boundary shows the
+ * fallback; if it only failed on the server (say, it read `window` while
+ * rendering), it simply works.
+ */
+import dynamic from 'next/dynamic';
+import * as React from 'react';
+import * as jsxRuntime from 'react/jsx-runtime';
+/** Renders nothing in the browser; on the server it hands the enclosing Suspense boundary over to client rendering. */
+export const ClientOnly = dynamic(() => Promise.resolve({ default: () => null }), { ssr: false });
+const MEMO = Symbol.for('react.memo');
+const FORWARD_REF = Symbol.for('react.forward_ref');
+/** Things components throw on purpose: suspending (a promise, or React's own marker) and framework control flow. */
+function isControlFlow(e) {
+    if (e === null || typeof e !== 'object')
+        return false;
+    const x = e;
+    return typeof x.then === 'function' || typeof x.digest === 'string' || (typeof x.message === 'string' && x.message.startsWith('Suspense Exception'));
+}
+export function createGuardedRuntime(label) {
+    const wrapped = new WeakMap();
+    let reported = false;
+    const crashed = (error) => {
+        if (!reported) {
+            reported = true;
+            console.error(`[nextpluggable] ${label} crashed while rendering on the server and was left out of the page:`, error);
+        }
+        return _jsx(ClientOnly, {});
+    };
+    function guard(type) {
+        if (type === null || (typeof type !== 'function' && typeof type !== 'object'))
+            return type;
+        const hit = wrapped.get(type);
+        if (hit)
+            return hit;
+        let result = type;
+        const t = type;
+        if (typeof type === 'function') {
+            // Class components cannot be called directly; they stay as they are.
+            if (!t.prototype?.isReactComponent) {
+                const component = type;
+                const Guarded = (props) => {
+                    try {
+                        return component(props);
+                    }
+                    catch (e) {
+                        if (isControlFlow(e))
+                            throw e;
+                        return crashed(e);
+                    }
+                };
+                Guarded.displayName = t.displayName ?? t.name;
+                result = Guarded;
+            }
+        }
+        else if (t.$$typeof === MEMO) {
+            const inner = guard(t.type);
+            if (inner !== t.type)
+                result = React.memo(inner, t.compare);
+        }
+        else if (t.$$typeof === FORWARD_REF) {
+            const render = t.render;
+            result = React.forwardRef((props, ref) => {
+                try {
+                    return render(props, ref);
+                }
+                catch (e) {
+                    if (isControlFlow(e))
+                        throw e;
+                    return crashed(e);
+                }
+            });
+        }
+        wrapped.set(type, result);
+        return result;
+    }
+    const jsx = jsxRuntime;
+    return {
+        guard,
+        react: { ...React, createElement: (type, ...rest) => React.createElement(guard(type), ...rest) },
+        jsxRuntime: {
+            ...jsxRuntime,
+            jsx: (type, ...rest) => jsx.jsx(guard(type), ...rest),
+            jsxs: (type, ...rest) => jsx.jsxs(guard(type), ...rest),
+        },
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,55 @@
+import type { AuthAdapter } from './auth/types.js';
+import type { StorageAdapter } from './storage/types.js';
+export interface NextPluggableConfig {
+    /** Who may use the dashboard. Default: `passwordAuth()` reading `NEXTPLUGGABLE_PASSWORD`. */
+    auth?: AuthAdapter;
+    /** Where data lives. Default: `fileStorage()` (a `.nextpluggable` folder). */
+    storage?: StorageAdapter;
+    /** Signs sessions and encrypts stored secrets. Default: `NEXTPLUGGABLE_SECRET`. Required in production. */
+    secret?: string;
+    /** URL path of the dashboard. Must match where you put the dashboard page. Default `/admin/plugins`. */
+    dashboardPath?: string;
+    /** URL path of the API route. Must match where you put the route handler. Default `/api/nextpluggable`. */
+    apiPath?: string;
+    /** Public origin of the site, e.g. `https://example.com`. Default: `NEXT_PUBLIC_SITE_URL`, then the host's own URL. */
+    siteUrl?: string;
+    /** Shown in the dashboard header. */
+    siteName?: string;
+    github?: {
+        /** API base, for GitHub Enterprise. Default `https://api.github.com`. */
+        apiUrl?: string;
+        /** A token used for every GitHub source that has none of its own. Default: `NEXTPLUGGABLE_GITHUB_TOKEN`. */
+        token?: string;
+    };
+    /** Allow plugin sources that are folders on the server. Default: only outside production, or when `NEXTPLUGGABLE_ALLOW_LOCAL_SOURCES=1`. */
+    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;
+    storage: StorageAdapter;
+    secret: string;
+    dashboardPath: string;
+    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;
+    cacheTtlMs: number;
+}
+/**
+ * Settings are resolved lazily (on first use, not at import) so that `next build`
+ * succeeds in environments where runtime secrets are not present.
+ */
+export declare function resolveConfig(config: NextPluggableConfig): () => ResolvedConfig;

package/dist/config.js

@@ -0,0 +1,57 @@
+import { passwordAuth } from './auth/password.js';
+import { warnOnce } from './globals.js';
+import { fileStorage } from './storage/file.js';
+function cleanPath(value, name) {
+    const p = `/${value}`.replace(/\/{2,}/g, '/').replace(/\/+$/, '');
+    if (!/^(\/[A-Za-z0-9._~-]+)+$/.test(p))
+        throw new Error(`[nextpluggable] "${name}" must be a URL path like "/admin/plugins" (got ${JSON.stringify(value)}).`);
+    return p;
+}
+function defaultSiteUrl() {
+    const explicit = process.env.NEXT_PUBLIC_SITE_URL ?? process.env.SITE_URL;
+    if (explicit)
+        return explicit;
+    if (process.env.VERCEL_PROJECT_PRODUCTION_URL)
+        return `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}`;
+    if (process.env.VERCEL_URL)
+        return `https://${process.env.VERCEL_URL}`;
+    return `http://localhost:${process.env.PORT ?? 3000}`;
+}
+/**
+ * Settings are resolved lazily (on first use, not at import) so that `next build`
+ * succeeds in environments where runtime secrets are not present.
+ */
+export function resolveConfig(config) {
+    let resolved;
+    return () => {
+        if (resolved)
+            return resolved;
+        const production = process.env.NODE_ENV === 'production';
+        let secret = config.secret ?? process.env.NEXTPLUGGABLE_SECRET;
+        if (!secret) {
+            if (production)
+                throw new Error('[nextpluggable] NEXTPLUGGABLE_SECRET is not set. Add a long random value to your environment (for example the output of `openssl rand -base64 32`).');
+            warnOnce('dev-secret', 'NEXTPLUGGABLE_SECRET is not set; using an insecure development secret.');
+            secret = 'nextpluggable-insecure-development-secret';
+        }
+        else if (secret.length < 16) {
+            throw new Error('[nextpluggable] NEXTPLUGGABLE_SECRET is too short. Use at least 16 characters.');
+        }
+        resolved = {
+            auth: config.auth ?? passwordAuth(),
+            storage: config.storage ?? fileStorage(),
+            secret,
+            dashboardPath: cleanPath(config.dashboardPath ?? '/admin/plugins', 'dashboardPath'),
+            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'),
+            cacheTtlMs: config.cacheTtlMs ?? (production ? 5000 : 0),
+        };
+        return resolved;
+    };
+}

package/dist/core/installer.d.ts

@@ -0,0 +1,30 @@
+import type { PluginManifest } from '@nextpluggable/plugin/manifest';
+import type { ResolvedConfig } from '../config.js';
+import type { Catalog, InstallRecord, SourceRecord } from './types.js';
+/** True while a required setting has no value — the plugin stays paused until the owner fills it in. */
+export declare function needsSetup(manifest: PluginManifest, config: InstallRecord['config']): boolean;
+export declare function addSource(cfg: ResolvedConfig, input: {
+    url?: unknown;
+    token?: unknown;
+}): Promise<SourceRecord>;
+export declare function refreshSource(cfg: ResolvedConfig, source: SourceRecord): Promise<Catalog>;
+/** Refresh every source; one failing source does not stop the others. */
+export declare function refreshAllSources(cfg: ResolvedConfig): Promise<{
+    label: string;
+    message: string;
+}[]>;
+export declare function removeSource(cfg: ResolvedConfig, sourceId: string): Promise<void>;
+export declare function installPlugin(cfg: ResolvedConfig, input: {
+    sourceId?: unknown;
+    path?: unknown;
+}): Promise<InstallRecord>;
+export declare function updatePlugin(cfg: ResolvedConfig, pluginId: string): Promise<InstallRecord>;
+export interface PluginPatch {
+    enabled?: unknown;
+    config?: unknown;
+    paths?: unknown;
+}
+export declare function changePlugin(cfg: ResolvedConfig, pluginId: string, patch: PluginPatch): Promise<InstallRecord>;
+export declare function uninstallPlugin(cfg: ResolvedConfig, pluginId: string, options?: {
+    deleteData?: boolean;
+}): Promise<void>;