Skip to content

The Open Standard for Generative UI

feat(cli): select a backend framework at scaffold time (#964)

AB6d3e23f55d48
diff --git a/packages/openui-cli/package.json b/packages/openui-cli/package.json
index 16563a9a7..1b7ecc344 100644
--- a/packages/openui-cli/package.json
+++ b/packages/openui-cli/package.json
@@ -1,6 +1,6 @@
{
"name": "@openuidev/cli",
- "version": "0.2.10",
+ "version": "0.2.11",
"description": "CLI for OpenUI — scaffold generative UI chat apps and generate LLM system prompts from component libraries",
"bin": {
"openui": "dist/index.js"
diff --git a/packages/openui-cli/src/commands/create-app.ts b/packages/openui-cli/src/commands/create-app.ts
index 66f10c093..e7392a653 100644
--- a/packages/openui-cli/src/commands/create-app.ts
+++ b/packages/openui-cli/src/commands/create-app.ts
@@ -4,13 +4,14 @@ import * as path from "node:path";
import { resolveCloudApiKey, THESYS_KEYS_URL } from "../auth/mint";
import { aiSetupFromTemplate, createFunnelProps } from "../lib/create-telemetry";
-import type { CreateAppOptions, EnvResult, TemplateName } from "../lib/create-types";
+import type { CreateAppOptions, EnvResult, OverlayName, TemplateName } from "../lib/create-types";
import {
resolveInstallPackageManager,
type PackageManagerName,
} from "../lib/detect-package-manager";
import { runDevCommand } from "../lib/dev-server";
import { runSkillInstall, shouldInstallSkill } from "../lib/install-skill";
+import { applyOverlay, OVERLAYS_DIR, resolveOverlay, type OverlayManifest } from "../lib/overlays";
import { runCommand } from "../lib/process-runner";
import { resolveArgs } from "../lib/resolve-args";
import { resolveAvailableTarget } from "../lib/target-dir";
@@ -21,8 +22,9 @@ function shouldCopyTemplatePath(templateDir: string, src: string): boolean {
const rel = path.relative(templateDir, src);
if (!rel) return true;
const top = rel.split(path.sep)[0] ?? "";
- // never copy install/build artifacts that may sit in a template dir
- return !["node_modules", ".next", ".turbo", "dist"].includes(top);
+ // Copy the base template only; selected backend overlays are applied later.
+ // Also exclude install/build artifacts that may sit in a template directory.
+ return ![OVERLAYS_DIR, "node_modules", ".next", ".turbo", "dist"].includes(top);
}
function restoreDotfiles(projectDir: string) {
@@ -44,7 +46,21 @@ function buildAppId(name: string): string {
return `${slug}-${Math.random().toString(36).slice(2, 8)}`;
}
-function rewritePackageJson(projectDir: string, name: string, packageManager: PackageManagerName) {
+function requiredApiKeyEnv(template: TemplateName): "THESYS_API_KEY" | "OPENAI_API_KEY" {
+ return template === "openui-cloud" ? "THESYS_API_KEY" : "OPENAI_API_KEY";
+}
+
+/** Match npm/pnpm install: keep dependency keys alphabetically sorted. */
+function sortPackageRecord<T>(record: Record<string, T>): Record<string, T> {
+ return Object.fromEntries(Object.entries(record).sort(([a], [b]) => a.localeCompare(b)));
+}
+
+function rewritePackageJson(
+ projectDir: string,
+ name: string,
+ packageManager: PackageManagerName,
+ overlayPackageJson?: OverlayManifest["packageJson"],
+) {
// package.json: set the project name and de-vendor monorepo-local deps
// (workspace:* / file: / catalog:) to the published "latest". link: deps are
// rewritten to an absolute file: path so locally-linked packages (e.g.
@@ -54,12 +70,24 @@ function rewritePackageJson(projectDir: string, name: string, packageManager: Pa
const pkgPath = path.join(projectDir, "package.json");
const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8")) as {
name: string;
+ scripts?: Record<string, string>;
dependencies?: Record<string, string>;
devDependencies?: Record<string, string>;
pnpm?: unknown;
};
pkg.name = name;
if (packageManager !== "pnpm") delete pkg.pnpm;
+
+ if (overlayPackageJson) {
+ pkg.dependencies ??= {};
+ for (const dependency of overlayPackageJson.removeDependencies ?? []) {
+ delete pkg.dependencies[dependency];
+ }
+ Object.assign(pkg.dependencies, overlayPackageJson.dependencies ?? {});
+ Object.assign((pkg.devDependencies ??= {}), overlayPackageJson.devDependencies ?? {});
+ Object.assign((pkg.scripts ??= {}), overlayPackageJson.scripts ?? {});
+ }
+
for (const section of ["dependencies", "devDependencies"] as const) {
const deps = pkg[section];
if (!deps) continue;
@@ -78,6 +106,9 @@ function rewritePackageJson(projectDir: string, name: string, packageManager: Pa
// can't resolve standalone — pin them to the published "latest".
if (/^(workspace:|file:|catalog:)/.test(v)) deps[key] = "latest";
}
+ // Object.assign appends overlay packages at the end; re-sort so the
+ // scaffolded package.json matches what `npm install` / `pnpm add` write.
+ pkg[section] = sortPackageRecord(deps);
}
fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
@@ -117,6 +148,7 @@ export async function runCreateApp(options: CreateAppOptions): Promise<void> {
interactive,
has_name_arg: Boolean(options.name),
has_template_arg: Boolean(options.template),
+ has_backend_framework_arg: Boolean(options.backendFramework),
has_api_key_arg: Boolean(options.apiKey),
has_auth_arg: Boolean(options.auth),
no_install: Boolean(options.noInstall),
@@ -151,13 +183,48 @@ export async function runCreateApp(options: CreateAppOptions): Promise<void> {
);
}
const template: TemplateName = options.template ?? "openui-cloud";
+
+ const frameworkArgs = await resolveArgs(
+ {
+ backendFramework:
+ options.backendFramework || !interactive
+ ? { value: options.backendFramework ?? "default" }
+ : {
+ prompt: {
+ type: "select",
+ message: "Choose your backend framework",
+ choices: [
+ {
+ value: "default",
+ name: "Default — minimal SDK route",
+ },
+ { value: "vercel-ai-sdk", name: "Vercel AI SDK" },
+ { value: "langgraph", name: "LangGraph" },
+ ],
+ },
+ required: true,
+ },
+ },
+ interactive,
+ );
+ const backendFramework = (frameworkArgs as { backendFramework: OverlayName }).backendFramework;
+
const aiSetup = aiSetupFromTemplate(template);
- telemetry.register({ template, ai_setup: aiSetup });
+ telemetry.register({ template, ai_setup: aiSetup, backend_framework: backendFramework });
telemetry.capture("cli_ai_setup_selected", {
...createFunnelProps("ai_setup_selected"),
template,
ai_setup: aiSetup,
});
+ telemetry.capture("cli_backend_framework_selected", {
+ ...createFunnelProps("backend_framework_selected"),
+ backend_framework: backendFramework,
+ backend_framework_source: options.backendFramework
+ ? "flag"
+ : interactive
+ ? "prompt"
+ : "default",
+ });
const templateDir = path.join(__dirname, "..", "templates", template);
if (!fs.existsSync(templateDir)) {
@@ -168,6 +235,7 @@ export async function runCreateApp(options: CreateAppOptions): Promise<void> {
"TEMPLATE_MISSING",
);
}
+ const overlay = resolveOverlay(templateDir, backendFramework);
telemetry.capture("cli_env_resolution_started", {
...createFunnelProps("env_resolution_started"),
@@ -186,6 +254,9 @@ export async function runCreateApp(options: CreateAppOptions): Promise<void> {
});
const immediateResolution = resolveImmediate(options.immediate, options.noInstall, interactive);
+ const apiKeyEnv = requiredApiKeyEnv(template);
+ const apiKeyAvailable = envResult.envWritten || Boolean(process.env[apiKeyEnv]?.trim());
+ const devStartBlockedByMissingApiKey = immediateResolution.immediate && !apiKeyAvailable;
telemetry.capture("cli_immediate_selected", {
immediate: immediateResolution.immediate,
dependency_install_requested: immediateResolution.installDependencies,
@@ -204,16 +275,20 @@ export async function runCreateApp(options: CreateAppOptions): Promise<void> {
filter: (src) => shouldCopyTemplatePath(templateDir, src),
});
restoreDotfiles(targetDir);
- rewritePackageJson(targetDir, name, packageManager.name);
- // npm ci requires the copied package-lock; other managers resolve from package.json.
+ applyOverlay(targetDir, overlay);
+ rewritePackageJson(targetDir, name, packageManager.name, overlay?.manifest.packageJson);
+ // npm ci needs package-lock.json. Keep it for npm scaffolds (base template or
+ // a backend overlay that ships its own). Other managers resolve from package.json.
if (packageManager.name !== "npm") {
fs.rmSync(path.join(targetDir, "package-lock.json"), { force: true });
}
// The Cloud template ships pnpm's lock/workspace files for reproducible pnpm
- // installs and native-build policy. They are irrelevant to npm/yarn/bun and
- // can confuse workspace-root detection, so keep them only for pnpm scaffolds.
- if (packageManager.name !== "pnpm") {
+ // installs and native-build policy. A framework changes dependencies, so
+ // regenerate its lock; non-pnpm scaffolds do not need either pnpm file.
+ if (packageManager.name !== "pnpm" || backendFramework !== "default") {
fs.rmSync(path.join(targetDir, "pnpm-lock.yaml"), { force: true });
+ }
+ if (packageManager.name !== "pnpm") {
fs.rmSync(path.join(targetDir, "pnpm-workspace.yaml"), { force: true });
}
} catch (err) {
@@ -314,7 +389,25 @@ export async function runCreateApp(options: CreateAppOptions): Promise<void> {
}
}
- const installCmd = packageManager.installCmd;
+ // Framework scaffolds without an npm lock must resolve ranges against the
+ // registry (`npm install`). When a backend overlay ships package-lock.json,
+ // keep the normal `npm ci` path. --prefer-offline is only safe for `npm ci`,
+ // where the lockfile pins exact versions and cache hits are content-addressed;
+ // bare `npm install` can fail with ETARGET on a stale packument cache.
+ const frameworkInstall = backendFramework !== "default";
+ const hasNpmLock = fs.existsSync(path.join(targetDir, "package-lock.json"));
+ const installCmd =
+ frameworkInstall && packageManager.name === "npm" && !hasNpmLock
+ ? "npm install --no-audit --no-fund --progress=false"
+ : frameworkInstall && packageManager.name === "pnpm"
+ ? "pnpm install --no-frozen-lockfile"
+ : packageManager.installCmd;
+ const installArgs =
+ frameworkInstall && packageManager.name === "npm" && !hasNpmLock
+ ? ["install", "--no-audit", "--no-fund", "--progress=false"]
+ : frameworkInstall && packageManager.name === "pnpm"
+ ? ["install", "--no-frozen-lockfile"]
+ : packageManager.installArgs;
let dependencyInstalled = false;
if (!immediateResolution.installDependencies) {
@@ -329,11 +422,7 @@ export async function runCreateApp(options: CreateAppOptions): Promise<void> {
template,
ai_setup: aiSetup,
});
- const installResult = await runCommand(
- packageManager.runCmd,
- packageManager.installArgs,
- targetDir,
- );
+ const installResult = await runCommand(packageManager.runCmd, installArgs, targetDir);
if (!installResult.error && installResult.status === 0) {
dependencyInstalled = true;
telemetry.capture("cli_dependency_install_succeeded", {
@@ -380,7 +469,8 @@ export async function runCreateApp(options: CreateAppOptions): Promise<void> {
}
const devCmd = packageManager.runCmd;
- const startDev = immediateResolution.immediate && dependencyInstalled;
+ const startDev =
+ immediateResolution.immediate && dependencyInstalled && !devStartBlockedByMissingApiKey;
telemetry.capture("cli_create_succeeded", {
...createFunnelProps("create_succeeded"),
@@ -396,14 +486,34 @@ export async function runCreateApp(options: CreateAppOptions): Promise<void> {
name,
devCmd,
template,
+ backendGettingStarted: overlay?.manifest.gettingStarted,
skillInstalled,
envWritten: envResult.envWritten,
startDev,
+ devStartBlockedByMissingApiKey,
installCmd,
dependencyInstalled,
}),
);
+ if (devStartBlockedByMissingApiKey) {
+ telemetry.capture("cli_dev_command_skipped", {
+ skip_reason: "missing_api_key",
+ required_env: apiKeyEnv,
+ });
+ const keyHint =
+ apiKeyEnv === "THESYS_API_KEY"
+ ? `Get a key at ${THESYS_KEYS_URL}, then add:\n\n ${apiKeyEnv}=…\n\nto ${name}/.env`
+ : `Add your key to ${name}/.env:\n\n ${apiKeyEnv}=…`;
+ console.error(
+ `\nSkipped starting the development server — ${apiKeyEnv} is missing.\n\n` +
+ `${keyHint}\n\n` +
+ `Then run:\n\n> cd ${name}\n> ${devCmd} run dev\n`,
+ );
+ process.exitCode = 1;
+ return;
+ }
+
if (!startDev) {
telemetry.capture("cli_dev_command_skipped", {
skip_reason: options.noInstall ? "dependencies_not_installed" : "not_immediate",
@@ -488,8 +598,7 @@ async function writeEnv(targetDir: string, result: EnvResult, appId?: string): P
await fs.promises.writeFile(path.join(targetDir, ".env"), content);
}
-async function resolveChatEnv(interactive: boolean): Promise<EnvResult> {
- if (!interactive) return { envWritten: false };
+async function promptForProviderKey(): Promise<string | null> {
try {
const { input } = await import("@inquirer/prompts");
const apiKey = (
@@ -497,8 +606,7 @@ async function resolveChatEnv(interactive: boolean): Promise<EnvResult> {
message: "Enter your OpenAI-compatible provider API key (leave blank to skip):",
})
).trim();
- if (!apiKey) return { envWritten: false };
- return { envWritten: true, envContent: `OPENAI_API_KEY=${apiKey}\n` };
+ return apiKey || null;
} catch (error) {
const { ExitPromptError } = await import("@inquirer/core");
if (error instanceof ExitPromptError) {
@@ -508,6 +616,30 @@ async function resolveChatEnv(interactive: boolean): Promise<EnvResult> {
}
}
+async function resolveChatEnv(interactive: boolean): Promise<EnvResult> {
+ const apiKey = interactive ? await promptForProviderKey() : null;
+
+ // Always write a file, so the scaffold has a .env to edit rather than one the
+ // user must know to create. Without a key the entries stay commented out: an
+ // empty `OPENAI_API_KEY=` would shadow a key already exported in the shell.
+ const lines = apiKey
+ ? [`OPENAI_API_KEY=${apiKey}`]
+ : [
+ "# Your OpenAI-compatible provider key. Uncomment and fill it in.",
+ "# OPENAI_API_KEY=sk-your-key-here",
+ "# Optional:",
+ "# OPENAI_MODEL=gpt-5.2",
+ "# OPENAI_BASE_URL=https://api.openai.com/v1",
+ ];
+
+ return {
+ // False without a key, so the immediate dev-server gate and the
+ // "add your API key" message still apply even though .env now exists.
+ envWritten: apiKey != null,
+ envContent: lines.join("\n") + "\n",
+ };
+}
+
async function resolveCloudEnv(
name: string,
options: CreateAppOptions,
@@ -571,9 +703,11 @@ function getStartedMessage(o: {
name: string;
devCmd: string;
template: TemplateName;
+ backendGettingStarted?: string;
skillInstalled: boolean;
envWritten: boolean;
startDev: boolean;
+ devStartBlockedByMissingApiKey: boolean;
installCmd: string;
dependencyInstalled: boolean;
}): string {
@@ -592,17 +726,17 @@ function getStartedMessage(o: {
const nextStep = o.startDev
? `Starting the development server in "${o.name}"...\n\n> ${o.devCmd} run dev`
- : [
- `> cd ${o.name}`,
- ...(o.dependencyInstalled ? [] : [`> ${o.installCmd}`]),
- `> ${o.devCmd} run dev`,
- ].join("\n");
-
- return `${skillMessage}
-Done!
-
-${envNote}
-
-${nextStep}
-`;
+ : o.devStartBlockedByMissingApiKey
+ ? ""
+ : [
+ `> cd ${o.name}`,
+ ...(o.dependencyInstalled ? [] : [`> ${o.installCmd}`]),
+ `> ${o.devCmd} run dev`,
+ ].join("\n");
+
+ const frameworkNote = o.backendGettingStarted?.replaceAll("{{packageManager}}", o.devCmd) ?? "";
+
+ return `${[skillMessage.trim(), "Done!", envNote, frameworkNote, nextStep]
+ .filter(Boolean)
+ .join("\n\n")}\n`;
}
diff --git a/packages/openui-cli/src/index.ts b/packages/openui-cli/src/index.ts
index 70a4a3a6c..fbeeecf00 100644
--- a/packages/openui-cli/src/index.ts
+++ b/packages/openui-cli/src/index.ts
@@ -11,7 +11,12 @@ import { GenerateOptions, runGenerate } from "./commands/generate";
import { detectAgent, UNKNOWN_AGENT_NAME } from "./lib/detect-agent";
import { rejectConflictingImmediateFlags, resolveArgs } from "./lib/resolve-args";
import { telemetry } from "./lib/telemetry";
-import { handleCliError, normalizeAuth, normalizeTemplate } from "./lib/utils"; // Ensure utils.ts is included for type declarations
+import {
+ handleCliError,
+ normalizeAuth,
+ normalizeBackendFramework,
+ normalizeTemplate,
+} from "./lib/utils"; // Ensure utils.ts is included for type declarations
const program = new Command();
@@ -55,6 +60,10 @@ program
"-t, --template <template>",
"AI backend: openui-cloud (recommended default) | openui-self-hosted (infrastructure control)",
)
+ .option(
+ "--backend-framework <framework>",
+ "Backend framework: default | langgraph | vercel-ai-sdk",
+ )
.option("--api-key <key>", "OpenUI Cloud API key (cloud template; skips sign-in)")
.option("--auth <method>", "Cloud auth method: oauth | skip (manual is deprecated)")
.option("--skill", "Install the OpenUI agent skill for AI coding assistants")
@@ -76,12 +85,18 @@ Templates:
openui-self-hosted Choose when owning the OpenAI-compatible provider, AI route,
and persistence is a requirement. Available only via
--template; interactive runs default to openui-cloud.
+
+Backend frameworks:
+ default Uses OpenAI SDK.
+ langgraph Bootstraps a LangGraph agent with the selected model backend.
+ vercel-ai-sdk Scaffolds a Vercel AI SDK agent with the selected model backend.
`,
)
.action(
async (options: {
name?: string;
template?: string;
+ backendFramework?: string;
apiKey?: string;
auth?: string;
skill?: boolean;
@@ -94,6 +109,7 @@ Templates:
await runCreateApp({
name: options.name,
template: normalizeTemplate(options.template),
+ backendFramework: normalizeBackendFramework(options.backendFramework),
apiKey: options.apiKey,
auth: normalizeAuth(options.auth),
skill: options.skill,
diff --git a/packages/openui-cli/src/lib/create-telemetry.ts b/packages/openui-cli/src/lib/create-telemetry.ts
index 816f398ca..7e2758b99 100644
--- a/packages/openui-cli/src/lib/create-telemetry.ts
+++ b/packages/openui-cli/src/lib/create-telemetry.ts
@@ -8,6 +8,7 @@ const createFunnel = {
const createFunnelSteps = {
create_started: "0100",
ai_setup_selected: "0200",
+ backend_framework_selected: "0250",
scaffold_started: "0300",
scaffold_succeeded: "0310",
scaffold_failed: "0320",
diff --git a/packages/openui-cli/src/lib/create-types.ts b/packages/openui-cli/src/lib/create-types.ts
index aa38a849f..0a0ef97ff 100644
--- a/packages/openui-cli/src/lib/create-types.ts
+++ b/packages/openui-cli/src/lib/create-types.ts
@@ -1,10 +1,13 @@
import type { CloudAuthMethod, ResolvedAuthMethod } from "../auth/mint";
export type TemplateName = "openui-self-hosted" | "openui-cloud";
+/** On-disk overlay under `overlays/<name>/`. Selected via `--backend-framework`. */
+export type OverlayName = "default" | "langgraph" | "vercel-ai-sdk";
export interface CreateAppOptions {
name?: string;
template?: TemplateName;
+ backendFramework?: OverlayName;
skill?: boolean;
noInteractive?: boolean;
noInstall?: boolean;
diff --git a/packages/openui-cli/src/lib/overlays.ts b/packages/openui-cli/src/lib/overlays.ts
new file mode 100644
index 000000000..537dc2cae
--- /dev/null
+++ b/packages/openui-cli/src/lib/overlays.ts
@@ -0,0 +1,71 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { OverlayName } from "./create-types";
+import { CreateError } from "./telemetry";
+
+export const OVERLAYS_DIR = "overlays";
+export const OVERLAY_MANIFEST = "manifest.json";
+
+/**
+ * Describes everything a framework overlay changes beyond the files it ships.
+ * The overlay's own files are copied implicitly; each key below names one
+ * other surface the overlay needs to touch.
+ */
+export type OverlayManifest = {
+ /** Merged into the scaffolded package.json. */
+ packageJson?: {
+ dependencies?: Record<string, string>;
+ devDependencies?: Record<string, string>;
+ scripts?: Record<string, string>;
+ /** Base-template dependencies this overlay makes redundant. */
+ removeDependencies?: string[];
+ };
+ /** Applied after the overlay's files are copied. */
+ files?: {
+ /** Base-template paths this overlay supersedes, relative to the project root. */
+ remove?: string[];
+ };
+ /** Printed after scaffolding. `{{packageManager}}` is substituted. */
+ gettingStarted?: string;
+};
+
+export type TemplateOverlay = {
+ dir: string;
+ manifest: OverlayManifest;
+};
+
+export function resolveOverlay(
+ templateDir: string,
+ overlayName: OverlayName,
+): TemplateOverlay | undefined {
+ if (overlayName === "default") return undefined;
+
+ const overlayDir = path.join(templateDir, OVERLAYS_DIR, overlayName);
+ const manifestPath = path.join(overlayDir, OVERLAY_MANIFEST);
+ if (!fs.existsSync(manifestPath)) {
+ throw new CreateError(
+ "template_missing",
+ `Backend framework "${overlayName}" not found. Rebuild the CLI with \`pnpm build\`.`,
+ );
+ }
+
+ return {
+ dir: overlayDir,
+ manifest: JSON.parse(fs.readFileSync(manifestPath, "utf8")) as OverlayManifest,
+ };
+}
+
+export function applyOverlay(projectDir: string, overlay?: TemplateOverlay) {
+ if (!overlay) return;
+
+ for (const entry of fs.readdirSync(overlay.dir)) {
+ if (entry === OVERLAY_MANIFEST) continue;
+ fs.cpSync(path.join(overlay.dir, entry), path.join(projectDir, entry), {
+ recursive: true,
+ });
+ }
+
+ for (const relativePath of overlay.manifest.files?.remove ?? []) {
+ fs.rmSync(path.join(projectDir, relativePath), { recursive: true, force: true });
+ }
+}
diff --git a/packages/openui-cli/src/lib/utils.ts b/packages/openui-cli/src/lib/utils.ts
index 9f4c6fc47..357815d10 100644
--- a/packages/openui-cli/src/lib/utils.ts
+++ b/packages/openui-cli/src/lib/utils.ts
@@ -1,6 +1,7 @@
import type { CloudAuthMethod } from "../auth/mint";
import { createFunnelProps } from "./create-telemetry";
import type { TemplateName } from "./create-types";
+import { OverlayName } from "./create-types";
import type { CommandResult } from "./process-runner";
import {
CliCancelledError,
@@ -246,3 +247,25 @@ export function normalizeAuth(a?: string): CloudAuthMethod | undefined {
"INVALID_AUTH",
);
}
+
+export function normalizeBackendFramework(framework?: string): OverlayName | undefined {
+ if (!framework) return undefined;
+ switch (framework.toLowerCase()) {
+ case "default":
+ case "none":
+ case "no-framework":
+ return "default";
+ case "langgraph":
+ case "lang-graph":
+ return "langgraph";
+ case "vercel":
+ case "vercel-ai-sdk":
+ case "ai-sdk":
+ return "vercel-ai-sdk";
+ default:
+ throw new CreateError(
+ "bad_args",
+ `unknown backend framework "${framework}". Use: default | langgraph | vercel-ai-sdk.`,
+ );
+ }
+}