Skip to content

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

Open
AbhinRustagi wants to merge 11 commits into
mainfrom
be-framework-select
Open

feat(cli): select a backend framework at scaffold time#964
AbhinRustagi wants to merge 11 commits into
mainfrom
be-framework-select

Conversation

@AbhinRustagi

@AbhinRustagi AbhinRustagi commented Aug 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

What

openui create can now scaffold a LangGraph or Vercel AI SDK backend instead of the template's default SDK route.

Changes

  • New --backend-framework flag and prompt — default, langgraph, vercel-ai-sdk. default behaves exactly as before.
  • Internally each framework is an overlay under overlays/<framework>/ inside a template. Its files are copied over the scaffold, and manifest.json describes everything else.
  • The manifest is grouped by what it touches — packageJson (dependencies, devDependencies, scripts, removeDependencies), files.remove, and gettingStarted.
  • Framework scaffolds can't reuse the shipped lockfiles, so those are dropped and the install does a full resolve.
  • --immediate no longer starts the dev server when the template's API key is missing; it prints the remaining steps and exits non-zero.
  • Telemetry records the chosen framework and whether it came from a flag, a prompt, or the default.

Public CLI copy stays "backend framework". Overlay naming is internal only. No framework overlays ship in this PR — those land later in the stack. Until then, picking a framework fails with a clear "backend framework not found" error, so this is safe to merge on its own.

Test Plan

  • Verified locally

tsc, prettier and eslint clean. Built the CLI and scaffolded:

  • --template openui-self-hosted with no flag — unchanged, still uses npm ci
  • --backend-framework langgraph — fails with Backend framework "langgraph" not found
  • --backend-framework nope — rejected, lists the valid values

Checklist

  • I updated docs/README when needed (docs follow in the next PR)
  • I considered backwards compatibility

@vercel

vercel Bot commented Aug 13, 2026 •
edited
Loading

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
openui-docs Ready Ready Preview Aug 24, 2026 7:08pm

Request Review

@AbhinRustagi AbhinRustagi mentioned this pull request Aug 13, 2026
Open
3 tasks
@AbhinRustagi AbhinRustagi mentioned this pull request Aug 13, 2026
Merged
2 tasks
@AbhinRustagi
AbhinRustagi force-pushed the be-framework-select branch 3 times, most recently from a1f41f5 to c13ac70 Compare August 17, 2026 08:06
@AbhinRustagi
AbhinRustagi changed the base branch from main to be-framework-adapter August 24, 2026 11:58
Base automatically changed from be-framework-adapter to main August 24, 2026 14:33
AbhinRustagi and others added 2 commits August 24, 2026 22:28
@AbhinRustagi @vishxrad
feat(cli): select a backend framework at scaffold time
ff8dbdc 
Add a `--backend-framework` flag and matching interactive prompt to
`openui create`, plus the machinery that applies a framework overlay on
top of a base template.

- `BackendFramework` type and `normalizeBackendFramework()` accept
  `default`, `langgraph` and `vercel-ai-sdk` (with `none`/`no-framework`,
  `lang-graph`, `vercel`/`ai-sdk` aliases) and reject anything else.
- `resolveBackendOverlay()` reads `backends/<framework>/manifest.json`
  from the template; `applyBackendOverlay()` copies the overlay files
  over the scaffolded project and honours `removeFiles`.
- `rewritePackageJson()` merges the manifest's `dependencies`,
  `devDependencies` and `scripts`, and applies `removeDependencies`.
- `backends/` is excluded from the base template copy so only the
  selected overlay lands in the generated project.
- Framework scaffolds cannot reuse the shipped lockfiles, so those are
  dropped and the install switches to `npm install` / `pnpm install
  --no-frozen-lockfile`.
- The dev server no longer starts when the required API key
  (`THESYS_API_KEY` or `OPENAI_API_KEY`) is missing; the CLI prints the
  remaining steps and exits non-zero instead.
- Telemetry gains a `backend_framework_selected` funnel step recording
  whether the value came from a flag, a prompt, or the default.

`default` keeps the existing behaviour. Selecting a framework before its
overlay ships fails with a clear `template_missing` error.

Squashed from 14 commits by Visharad Kashyap:
  dcbc7d3 feat(cli): scaffold selected backend framework
  63d4869 fix(cli): keep cloud transport for framework tools
  ef5a812 feat(cli): add backend diagnostic tool
  c2b54e8 fix(cli): restore weather tool and AI SDK name
  be3a53e fix(cli): block dev start without api key
  534e108 fix(cli): use native framework streams
  9dc595c fix(cli): use packaged Vercel AI SDK adapter
  a4b47c6 Add OSS framework tool loops
  ddd5961 chore(cli): update template package versions
  6daa3d3 feat(cli): use native cloud framework streams
  a075d0c feat(cli): scaffold deployable cloud framework backends
  c5f55d0 fix(cli): use published langchain package
  ead198c fix(cli): track latest langchain release
  c157f92 refactor(cli): compose backend template overlays

Co-Authored-By: Visharad Kashyap <154831195+vishxrad@users.noreply.github.com>
@AbhinRustagi
fix(cli): always write .env for the self-hosted scaffold
044dcc1 
Self-hosted scaffolds could finish with no `.env` at all — in
non-interactive runs, and interactively when the key prompt was left
blank. `writeEnv` bails on empty content, and unlike the Cloud template
there is no `APP_ID` to make it non-empty. The closing message then said
"Add your API key to .env", pointing at a file that did not exist, and no
`.env.example` ships either.

Always build content, commented out when no key was supplied, so there is
a file to edit. Commented rather than an empty `OPENAI_API_KEY=`, which
would shadow a key already exported in the shell.

`resolveChatEnv` now mirrors `resolveCloudEnv`: prompt (extracted to
`promptForProviderKey`), assemble `lines`, and return once with
`envWritten: apiKey != null`. That flag stays false without a key, so the
telemetry `env_written` property stays accurate and the immediate
dev-server gate still refuses to start.
@AbhinRustagi
fix(cli): sort package.json deps after merging backend manifest
6508570 
Object.assign was appending overlay packages at the bottom; re-sort
dependencies and devDependencies alphabetically like npm/pnpm install.
@AbhinRustagi
fix(cli): keep npm package-lock for backend framework scaffolds
1a57231 
Backend overlays can ship package-lock.json; stop deleting it and use
npm ci when the lock is present instead of always falling back to install.
@AbhinRustagi
fix(cli): start dev even when the API key is missing
2ea2e35 
Drop the missing-key block so --immediate still launches the server; the
.env warning already tells the user to add a key.
@AbhinRustagi
Revert "fix(cli): start dev even when the API key is missing"
8d31620 
This reverts commit 2ea2e35.
@AbhinRustagi
fix(cli): clarify missing-API-key skip when starting dev
57536ae 
Spell out where to put the key (and Cloud key URL) instead of a bare error.
@AbhinRustagi
refactor(cli): use overlay naming internally for framework scaffolds
99607ef 
Keep --backend-framework as the public CLI surface; rename the on-disk
module and types to overlays/ for the internal implementation.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@abhithesys abhithesys abhithesys left review comments

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@AbhinRustagi @abhithesys