@sntlr/registry-shell 1.0.0

package/dist/config-loader.js

@@ -0,0 +1,140 @@
+/**
+ * Loads the user's `registry-shell.config.ts` at server boot. Uses `jiti` so
+ * the user doesn't need a build step or TS tooling of their own — the shell
+ * parses TS on the fly.
+ *
+ * Called once at Next.js server startup (see src/next-app/registry.config.ts).
+ * The returned `ResolvedShellConfig` contains absolute paths and defaults
+ * applied.
+ */
+import "server-only";
+import path from "node:path";
+import fs from "node:fs";
+import { createJiti } from "jiti";
+// `skipBlocks`, `globalCss`, and `buildOutput` are excluded from the
+// "must have a default" shape: skipBlocks is always an array (empty
+// default); globalCss is purely opt-in; buildOutput is read by the CLI
+// directly (with its own `.next` default) and doesn't flow through the
+// server-side resolver.
+const DEFAULT_PATHS = {
+    components: "components/ui",
+    blocks: "registry/new-york/blocks",
+    previews: "components/previews/index.ts",
+    docs: "content/docs",
+    registryJson: "public/r",
+    a11y: "public/a11y",
+    tests: "public/tests",
+    props: "public/props",
+    skipBlocks: [],
+};
+const DEFAULT_BRANDING = {
+    siteName: "UI Registry",
+    shortName: "UI",
+    siteUrl: "",
+    logoAlt: "UI",
+    faviconDark: "/favicon_dark.svg",
+    faviconLight: "/favicon_light.svg",
+    faviconIco: "/favicon.ico",
+};
+/**
+ * Read env vars set by the CLI, load the config file, resolve paths. Returns
+ * `null` when no config is set (shell-only dev mode) — the Next app falls
+ * back to built-in shell docs.
+ */
+export function loadResolvedConfig() {
+    const configPath = process.env.USER_CONFIG_PATH;
+    const root = process.env.USER_REGISTRY_ROOT;
+    if (!configPath || !root)
+        return null;
+    if (!fs.existsSync(configPath)) {
+        throw new Error(`[registry-shell] Config file not found: ${configPath}. ` +
+            `Check USER_CONFIG_PATH.`);
+    }
+    const jiti = createJiti(import.meta.url, { interopDefault: true });
+    const loaded = jiti(configPath);
+    const config = extractDefault(loaded);
+    if (!config?.branding) {
+        throw new Error(`[registry-shell] Invalid config at ${configPath}: missing required \`branding\`.`);
+    }
+    if (config.multilocale && !config.defaultLocale) {
+        throw new Error(`[registry-shell] Invalid config at ${configPath}: \`multilocale\` is true but \`defaultLocale\` is missing.`);
+    }
+    const rootAbs = path.resolve(root);
+    const cfgPaths = config.paths ?? {};
+    return {
+        root: rootAbs,
+        configPath,
+        branding: applyBrandingDefaults(config.branding),
+        paths: {
+            components: path.resolve(rootAbs, cfgPaths.components ?? DEFAULT_PATHS.components),
+            blocks: path.resolve(rootAbs, cfgPaths.blocks ?? DEFAULT_PATHS.blocks),
+            previews: path.resolve(rootAbs, cfgPaths.previews ?? DEFAULT_PATHS.previews),
+            docs: path.resolve(rootAbs, cfgPaths.docs ?? DEFAULT_PATHS.docs),
+            registryJson: path.resolve(rootAbs, cfgPaths.registryJson ?? DEFAULT_PATHS.registryJson),
+            a11y: path.resolve(rootAbs, cfgPaths.a11y ?? DEFAULT_PATHS.a11y),
+            tests: path.resolve(rootAbs, cfgPaths.tests ?? DEFAULT_PATHS.tests),
+            props: path.resolve(rootAbs, cfgPaths.props ?? DEFAULT_PATHS.props),
+            skipBlocks: new Set(cfgPaths.skipBlocks ?? []),
+            globalCss: cfgPaths.globalCss ? path.resolve(rootAbs, cfgPaths.globalCss) : null,
+        },
+        homePage: config.homePage ? path.resolve(rootAbs, config.homePage) : null,
+        adapter: config.adapter ? path.resolve(rootAbs, config.adapter) : null,
+        extraTranslations: config.extraTranslations ?? {},
+        multilocale: Boolean(config.multilocale),
+        defaultLocale: config.defaultLocale ?? "",
+        locales: resolveLocales(rootAbs, cfgPaths.docs ?? DEFAULT_PATHS.docs, config),
+    };
+}
+/**
+ * Resolve the locale list for the locale toggle. In single-locale mode we
+ * return an empty array (the toggle hides itself). In multilocale mode we
+ * use the explicit `locales` config if present, otherwise auto-scan
+ * subfolders under `paths.docs`.
+ */
+function resolveLocales(rootAbs, docsRel, config) {
+    if (!config.multilocale)
+        return [];
+    if (config.locales && config.locales.length > 0)
+        return [...config.locales];
+    const docsAbs = path.resolve(rootAbs, docsRel);
+    if (!fs.existsSync(docsAbs))
+        return config.defaultLocale ? [config.defaultLocale] : [];
+    const found = fs
+        .readdirSync(docsAbs, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .map((d) => d.name);
+    // Put the default locale first so the toggle cycles predictably.
+    if (config.defaultLocale && found.includes(config.defaultLocale)) {
+        return [config.defaultLocale, ...found.filter((l) => l !== config.defaultLocale)];
+    }
+    return found;
+}
+function extractDefault(loaded) {
+    if (loaded && typeof loaded === "object" && "default" in loaded) {
+        return loaded.default;
+    }
+    return loaded;
+}
+function applyBrandingDefaults(b) {
+    return {
+        siteName: b.siteName,
+        shortName: b.shortName,
+        siteUrl: b.siteUrl ?? "",
+        description: b.description ?? "",
+        ogImage: b.ogImage ?? "",
+        twitterHandle: b.twitterHandle ?? "",
+        github: b.github
+            ? {
+                owner: b.github.owner,
+                repo: b.github.repo,
+                label: b.github.label ?? "Github",
+                showStars: b.github.showStars ?? true,
+            }
+            : { owner: "", repo: "", label: "", showStars: false },
+        logoAlt: b.logoAlt ?? b.siteName,
+        faviconDark: b.faviconDark ?? DEFAULT_BRANDING.faviconDark,
+        faviconLight: b.faviconLight ?? DEFAULT_BRANDING.faviconLight,
+        faviconIco: b.faviconIco ?? DEFAULT_BRANDING.faviconIco,
+    };
+}
+//# sourceMappingURL=config-loader.js.map

package/dist/define-config.d.ts

@@ -0,0 +1,188 @@
+/**
+ * `defineConfig` — the single entry point registry builders use.
+ *
+ * ```ts
+ * // registry-shell.config.ts
+ * import { defineConfig } from "@sntlr/registry-shell"
+ *
+ * export default defineConfig({
+ *   branding: { siteName: "My UI", shortName: "UI", ... },
+ *   // paths/homePage/adapter are optional
+ * })
+ * ```
+ */
+export interface GithubConfig {
+    /** GitHub org or user that owns the repo. */
+    owner: string;
+    /** Repo name. */
+    repo: string;
+    /** Button label in the header. Default: `"Github"`. */
+    label?: string;
+    /**
+     * Show the public star count (fetched server-side, revalidated hourly).
+     * Default: `true`.
+     */
+    showStars?: boolean;
+}
+export interface BrandingConfig {
+    /** Full product name, e.g. "My UI". Used in HTML title. */
+    siteName: string;
+    /** Short breadcrumb label, e.g. "UI". */
+    shortName: string;
+    /** Canonical URL of the deployed registry, e.g. "https://ui.example.com". */
+    siteUrl?: string;
+    /** SEO meta description. Shown in search results + social cards. */
+    description?: string;
+    /** Path/URL to a 1200×630 Open Graph image. Relative to `siteUrl` if no scheme. */
+    ogImage?: string;
+    /** Twitter handle (without `@`) for Twitter card attribution. */
+    twitterHandle?: string;
+    /**
+     * Optional. Adds a GitHub link button to the header. Omit to hide the
+     * button entirely (default).
+     */
+    github?: GithubConfig;
+    /** Accessible alt text for the logo image. Default: siteName. */
+    logoAlt?: string;
+    /** Public path to the dark-theme SVG favicon. */
+    faviconDark?: string;
+    /** Public path to the light-theme SVG favicon. */
+    faviconLight?: string;
+    /** Public path to a fallback `.ico` favicon. */
+    faviconIco?: string;
+}
+/**
+ * Filesystem locations the default adapter scans. All paths are relative to
+ * the config file's directory. Any path can be omitted to use the default.
+ */
+export interface ShellPaths {
+    /** Component source files. Default: "components/ui". */
+    components?: string;
+    /** Block directories (each block is a folder). Default: "registry/new-york/blocks". */
+    blocks?: string;
+    /** Preview index file. Default: "components/previews/index.ts" (or .tsx). */
+    previews?: string;
+    /** Doc MDX files. Default: "content/docs". */
+    docs?: string;
+    /** Built registry JSON files (served at /r/[name].json). Default: "public/r". */
+    registryJson?: string;
+    /** A11y JSON files (served at /a11y/[name].json). Default: "public/a11y". */
+    a11y?: string;
+    /** Test JSON files (served at /tests/[name].json). Default: "public/tests". */
+    tests?: string;
+    /** Props JSON files (served at /props/[name].json). Default: "public/props". */
+    props?: string;
+    /** Block names to omit from navigation (e.g. example blocks). */
+    skipBlocks?: string[];
+    /**
+     * Optional. Path to a `.css` file the shell imports AFTER its own
+     * globals. Use this for brand fonts (`@font-face`), token overrides
+     * (redefine `--primary` etc. on `:root` / `.dark`), extra `@source`
+     * directives, or any custom utilities.
+     *
+     * Imported at the very end of the shell's `globals.css` so your `:root`
+     * declarations win the cascade against the shell's defaults.
+     *
+     * Example: `globalCss: "./styles/theme.css"`.
+     */
+    globalCss?: string;
+    /**
+     * Optional. Directory (relative to the config file) where
+     * `registry-shell build` writes Next's build output, and where
+     * `registry-shell start` reads it back from. Default: `.next`.
+     *
+     * Override only if `.next` collides with something else in your
+     * project. Most Next.js hosts (Vercel, Netlify, self-hosted)
+     * auto-detect `.next` — if you change this, update your host's
+     * "Output Directory" setting to match.
+     */
+    buildOutput?: string;
+}
+/**
+ * Advanced: point at a custom adapter module. The module must default-export
+ * a factory `(resolved: ResolvedShellConfig) => RegistryAdapter`. When unset,
+ * the shell uses its built-in convention-based adapter.
+ */
+export type CustomAdapterSpec = string;
+export interface ShellConfig {
+    /**
+     * Required. Displayed in shell chrome.
+     */
+    branding: BrandingConfig;
+    /**
+     * When `true`, docs are organized under per-locale subfolders
+     * (e.g. `content/docs/en/foo.mdx`, `content/docs/fr/foo.mdx`) and each
+     * subfolder name is treated as a locale code. Requires `defaultLocale`.
+     *
+     * When `false` (default), docs live directly under `paths.docs` and
+     * locale variants use the file-extension convention `{slug}.{locale}.mdx`
+     * alongside the canonical `{slug}.mdx`.
+     */
+    multilocale?: boolean;
+    /**
+     * Required when `multilocale` is `true`. Locale code (e.g. `"en"`) of the
+     * subfolder containing the canonical doc set. Other locales are optional
+     * translations and fall back to this one when a slug is missing.
+     */
+    defaultLocale?: string;
+    /**
+     * Optional in multilocale mode. Explicit list of locale codes the shell
+     * should offer in its locale toggle (e.g. `["en", "fr", "ja"]`). When
+     * unset, the shell auto-discovers locales by scanning subfolders under
+     * `paths.docs`.
+     *
+     * Ignored in single-locale mode (the toggle is hidden).
+     */
+    locales?: string[];
+    /**
+     * Optional. Override filesystem layout. Defaults match the sntlr-registry
+     * convention.
+     */
+    paths?: ShellPaths;
+    /**
+     * Optional. Path to a custom homepage module, relative to config dir.
+     * The module must default-export a React component accepting
+     * `{ firstDocSlug?: string }` props.
+     */
+    homePage?: string;
+    /**
+     * Optional. Locale → key → value dictionaries merged into the shell's
+     * built-in i18n table. Use for marketing copy referenced by a custom
+     * homepage.
+     */
+    extraTranslations?: Record<string, Record<string, string>>;
+    /**
+     * Optional. Path to a custom adapter module. See `CustomAdapterSpec`.
+     */
+    adapter?: CustomAdapterSpec;
+    /**
+     * Optional. Pin the dev/start server to a specific port. Falls through to
+     * Next.js's default (3000, auto-incrementing if in use) when unset.
+     */
+    port?: number;
+    /**
+     * Optional. Extra npm package names the shell's Next.js build should
+     * transpile. Use this when your registry depends on another workspace
+     * package (e.g. a shared components library) whose TSX files should be
+     * compiled the same way as your own.
+     *
+     * Forwarded to Next's `transpilePackages`. The shell itself
+     * (`@sntlr/registry-shell`) is always transpiled regardless.
+     */
+    transpilePackages?: string[];
+    /**
+     * Optional. Template the shell uses to render the install command in the
+     * component "Install" tab. Supported placeholders:
+     *   - `{name}`    — the component/block slug (e.g. `"button"`)
+     *   - `{siteUrl}` — `branding.siteUrl` (trailing slash stripped)
+     *
+     * Default: `"npx shadcn@latest add {siteUrl}/r/{name}.json"`. Set to an
+     * empty string to hide the install line entirely.
+     */
+    installCommandTemplate?: string;
+}
+/**
+ * Identity function with type inference — users call this purely for editor
+ * support. No runtime validation here; the shell validates at boot time.
+ */
+export declare function defineConfig(config: ShellConfig): ShellConfig;

package/dist/define-config.js

@@ -0,0 +1,21 @@
+/**
+ * `defineConfig` — the single entry point registry builders use.
+ *
+ * ```ts
+ * // registry-shell.config.ts
+ * import { defineConfig } from "@sntlr/registry-shell"
+ *
+ * export default defineConfig({
+ *   branding: { siteName: "My UI", shortName: "UI", ... },
+ *   // paths/homePage/adapter are optional
+ * })
+ * ```
+ */
+/**
+ * Identity function with type inference — users call this purely for editor
+ * support. No runtime validation here; the shell validates at boot time.
+ */
+export function defineConfig(config) {
+    return config;
+}
+//# sourceMappingURL=define-config.js.map

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @sntlr/registry-shell — public API.
+ *
+ * Registry builders import `defineConfig` from here into their
+ * `registry-shell.config.ts`. Custom-adapter authors also import
+ * `ResolvedShellConfig` to type their factory's argument.
+ */
+export { defineConfig } from "./define-config.js";
+export type { ShellConfig, BrandingConfig, GithubConfig, ShellPaths, CustomAdapterSpec, } from "./define-config.js";
+export type { ResolvedShellConfig } from "./config-loader.js";
+export type { AdapterOverrides } from "./adapter/custom.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @sntlr/registry-shell — public API.
+ *
+ * Registry builders import `defineConfig` from here into their
+ * `registry-shell.config.ts`. Custom-adapter authors also import
+ * `ResolvedShellConfig` to type their factory's argument.
+ */
+export { defineConfig } from "./define-config.js";
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,124 @@
+{
+  "name": "@sntlr/registry-shell",
+  "version": "1.0.0",
+  "description": "Generic Next.js viewer for component registries. Drop a registry-shell.config.ts into your registry and get a full docs/components/blocks site on localhost:3000.",
+  "keywords": [
+    "shadcn",
+    "registry",
+    "components",
+    "ui",
+    "next",
+    "nextjs",
+    "docs",
+    "shell"
+  ],
+  "license": "MIT",
+  "author": "Scintillar",
+  "homepage": "https://github.com/scintillar-com/registry-shell#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scintillar-com/registry-shell.git"
+  },
+  "bugs": {
+    "url": "https://github.com/scintillar-com/registry-shell/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "registry-shell": "./dist/cli/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./shell/*": "./src/next-app/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/adapter",
+    "dist/cli",
+    "dist/config-loader.js",
+    "dist/config-loader.d.ts",
+    "dist/define-config.js",
+    "dist/define-config.d.ts",
+    "dist/index.js",
+    "dist/index.d.ts",
+    "src/adapter",
+    "src/cli",
+    "src/config-loader.ts",
+    "src/define-config.ts",
+    "src/index.ts",
+    "src/next-app/app",
+    "src/next-app/components",
+    "src/next-app/fallback",
+    "src/next-app/hooks",
+    "src/next-app/lib",
+    "src/next-app/public",
+    "src/next-app/next.config.ts",
+    "src/next-app/next-env.d.ts",
+    "src/next-app/postcss.config.mjs",
+    "src/next-app/registry.config.ts",
+    "src/next-app/tsconfig.json",
+    "src/next-app/user-aliases.d.ts",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.18"
+  },
+  "packageManager": "pnpm@10.28.0",
+  "scripts": {
+    "dev:shell": "node dist/cli/index.js dev",
+    "build": "tsc -p tsconfig.cli.json",
+    "build:cli": "tsc -p tsconfig.cli.json",
+    "prepack": "tsc -p tsconfig.cli.json",
+    "lint": "eslint . --max-warnings 0",
+    "test": "vitest run",
+    "test:smoke": "pnpm build && playwright test"
+  },
+  "dependencies": {
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@tailwindcss/postcss": "^4.1.0",
+    "@tailwindcss/typography": "^0.5.19",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "cross-env": "^7.0.3",
+    "date-fns": "^4.1.0",
+    "gray-matter": "^4.0.3",
+    "input-otp": "^1.4.2",
+    "jiti": "^2.4.2",
+    "lucide-react": "^0.503.0",
+    "next": "^15.5.14",
+    "next-mdx-remote": "^6.0.0",
+    "next-themes": "^0.4.6",
+    "radix-ui": "^1.4.3",
+    "react": "^19.1.0",
+    "react-day-picker": "^9.14.0",
+    "react-dom": "^19.1.0",
+    "remark-gfm": "^4.0.1",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.3.1",
+    "tailwindcss": "^4.1.0",
+    "tw-animate-css": "^1.3.6",
+    "yaml": "^2.8.3",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.3.5",
+    "@playwright/test": "^1.59.1",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "eslint": "^9.39.4",
+    "eslint-config-next": "^15.5.15",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.3"
+  }
+}

package/src/adapter/custom.ts

@@ -0,0 +1,90 @@
+/**
+ * Custom adapter loader.
+ *
+ * When a user's `registry-shell.config.ts` sets `adapter: "./my-adapter"`, the
+ * shell calls `loadCustomAdapterOverrides(resolved)` to resolve that module
+ * and extract method overrides. The overrides are then shallow-merged on top
+ * of the default convention-based adapter's methods.
+ *
+ * The user's module should default-export one of:
+ *   • A factory `(resolved) => Partial<AdapterMethods>` — preferred. Gets the
+ *     resolved config so it can build paths against `resolved.paths`, decide
+ *     based on `resolved.root`, etc.
+ *   • A plain `Partial<AdapterMethods>` object — also accepted for simple
+ *     static overrides that don't need the resolved config.
+ *
+ * Only the methods a user supplies are taken; any method they omit falls
+ * through to the built-in default. That means you can override just
+ * `getAllComponents` to serve from a database and keep convention-based
+ * doc/registry-item loading for the rest.
+ *
+ * Loaded via jiti so the user can write the adapter in TypeScript without
+ * their own build step — same approach we use for the config file itself.
+ */
+import "server-only"
+import { createJiti } from "jiti"
+import type { ResolvedShellConfig } from "../config-loader.js"
+
+/**
+ * Shape of what a custom adapter module may override. Mirrors the public
+ * methods on RegistryAdapter (defined inside next-app/lib) minus the fields
+ * that are wired via other mechanisms (previewLoader via `@user/previews`
+ * alias, branding from config, homePage via `@user/homepage` alias).
+ *
+ * Typed with `unknown` args on the server side — the Next app re-applies
+ * its stricter RegistryAdapter types when consuming this.
+ */
+export interface AdapterOverrides {
+  getAllComponents?: () => unknown[]
+  getAllDocs?: () => unknown[]
+  getDocBySlug?: (slug: string, locale?: string) => unknown | null
+  getDocAllLocales?: (slug: string) => Record<string, string>
+  getComponentSource?: (name: string) => string | null
+  getRegistryItem?: (name: string) => Promise<unknown | null>
+  getA11yData?: (name: string) => Promise<unknown | null>
+  getTestData?: (name: string) => Promise<unknown | null>
+  getPropsData?: (name: string) => Promise<unknown | null>
+  extraTranslations?: Record<string, Record<string, string>>
+}
+
+type AdapterFactory = (resolved: ResolvedShellConfig) => AdapterOverrides
+
+export function loadCustomAdapterOverrides(
+  resolved: ResolvedShellConfig,
+): AdapterOverrides {
+  if (!resolved.adapter) return {}
+
+  const jiti = createJiti(import.meta.url, { interopDefault: true })
+  let loaded: unknown
+  try {
+    loaded = jiti(resolved.adapter)
+  } catch (err) {
+    throw new Error(
+      `[registry-shell] Failed to load custom adapter at ${resolved.adapter}: ` +
+        (err instanceof Error ? err.message : String(err)),
+    )
+  }
+
+  const extracted =
+    loaded && typeof loaded === "object" && "default" in loaded
+      ? (loaded as { default: unknown }).default
+      : loaded
+
+  if (typeof extracted === "function") {
+    const overrides = (extracted as AdapterFactory)(resolved)
+    if (!overrides || typeof overrides !== "object") {
+      throw new Error(
+        `[registry-shell] Custom adapter factory at ${resolved.adapter} did not return an object.`,
+      )
+    }
+    return overrides
+  }
+
+  if (extracted && typeof extracted === "object") {
+    return extracted as AdapterOverrides
+  }
+
+  throw new Error(
+    `[registry-shell] Custom adapter at ${resolved.adapter} must default-export a factory function or an object.`,
+  )
+}