llms.txt

create-electrobun-stack LLMs guide

Purpose:
Scaffold an Electrobun desktop app with Bun, React, Preact, Svelte, or SvelteKit, TypeScript, Vite, Biome, typed Electrobun RPC, and optional integrations. The generated project includes ces.json so future tooling can understand and expand the stack.

Primary commands:

bunx create-electrobun-stack my-app
bunx create-electrobun-stack add --cwd my-app --orm drizzle

V1 public contract:
- create-electrobun-stack <project-name> [options]
- create-electrobun-stack add [options]
- Supported operational flags: --dry-run, --yes, --cwd, --app-id, --install, --no-install, --git, --no-git, --list-templates, --version, --help.
- Supported stack flags are the documented Stack Options and Electrobun Feature Options.
- minimal is the canonical V1 template. standard and full are accepted aliases that render the same files as minimal while preserving manifest identity.

Local repository command:

bun run src/index.ts my-app
bun run src/index.ts add --cwd my-app --settings database

Default stack:

--template minimal
--frontend react
--router tanstack-router
--query none
--runtime bun
--build-env dev
--build-targets current
--api electrobun-rpc
--navigation local-only
--native-utils none
--window-style native
--styling tailwindcss
--ui none
--app-menu edit
--auth none
--database none
--orm none
--db-setup none
--settings none
--package-manager bun
--packaging none
--testing bun
--addons none
--examples rpc
--install
--no-git

Generated app:
- Bun native process in src/bun.
- React, Preact, Svelte, or SvelteKit renderer in src/views/main.
- Shared types in src/shared.
- Typed RPC contract in src/shared/rpc/schema.ts when --api electrobun-rpc is selected.
- ces.json manifest at project root.
- Generated README tailored to selected options.
- Default layout includes TanStack Router route files, src/bun/menu.ts, and tests/manifest.test.ts.

Common generated commands with Bun:

bun install
bun run dev
bun run build
bun run typecheck
bun run lint
bun run format
bun test

Option behavior:
- --router tanstack-router adds TanStack Router file routes, @tanstack/router-plugin, src/views/main/routes, and routeTree.gen.ts.
- --router react-router adds React Router with HashRouter.
- --router none renders Home directly.
- --frontend preact adds a Preact renderer with @preact/preset-vite. It currently requires --router none, --query none, and --ui none.
- --frontend svelte adds a direct Svelte renderer with @sveltejs/vite-plugin-svelte. It currently requires --router none, --query none, and --ui none.
- --frontend sveltekit adds a static SvelteKit renderer with @sveltejs/adapter-static and SvelteKit file routing. It currently requires --router none, --query none, and --ui none.
- --query tanstack-query adds @tanstack/react-query and QueryClientProvider.
- --styling tailwindcss adds Tailwind CSS v4 and @tailwindcss/vite.
- --styling css omits Tailwind dependencies.
- --ui shadcn adds components.json and requires Tailwind CSS.
- --api electrobun-rpc adds BrowserWindow RPC wiring, Bun handlers, shared RPC schema, and renderer RPC client.
- --api none omits BrowserWindow RPC wiring.
- --examples rpc adds starter greeting/logging RPC demo.
- --examples none omits demo calls and generated README RPC example section.
- --navigation local-only adds Electrobun navigation rules for bundled views.
- --native-utils file-dialogs adds a typed RPC request backed by Electrobun Utils.openFileDialog.
- --native-utils clipboard adds typed RPC requests for Utils clipboard read/write/clear.
- --native-utils desktop-kit enables file dialogs and clipboard utilities together.
- --window-style hidden-inset uses Electrobun hiddenInset titlebar and adds a draggable renderer header.
- --app-menu edit adds an Electrobun ApplicationMenu with standard Edit roles.
- --auth app-lock adds a local renderer unlock screen. It is not remote auth.
- --database sqlite adds a Bun SQLite client.
- --database json-file adds a local JSON record store at data/app-db.json.
- --orm drizzle adds Drizzle schema/config and requires SQLite.
- --db-setup seed adds starter database metadata and requires sqlite or json-file.
- --settings json adds data/settings.json persistence and requires Electrobun RPC.
- --settings database stores settings in SQLite and requires Electrobun RPC plus SQLite.
- --package-manager bun|npm|pnpm|yarn controls install/run command text and package manager metadata.
- --packaging installers adds scripts/package-electrobun.ts plus package:release, package:linux, package:mac, and package:windows scripts for AppImage, deb, DMG collection, and NSIS wrapping around Electrobun artifacts.
- --testing bun adds bun test and tests/manifest.test.ts.
- --testing desktop-smoke adds bun test, tests/manifest.test.ts, and tests/desktop-smoke.test.ts with mocked Electrobun launch verification.
- --testing none omits tests.
- --addons turborepo adds turbo.json and a check script.

Invalid combinations:
- Drizzle requires SQLite.
- Seed data requires a generated database.
- Database-backed settings require SQLite.
- Settings require Electrobun RPC.
- Native utility examples require Electrobun RPC.
- RPC examples require Electrobun RPC.
- shadcn requires Tailwind CSS.
- Non-React frontends require --router none, --query none, and --ui none.

Add command:
- Reads ces.json from cwd or --cwd.
- Enables missing features only.
- Preserves createdAt.
- Refreshes ces.json.
- Installs dependencies unless --no-install is passed.
- Infers prerequisites:
  - --orm drizzle -> --database sqlite
  - --db-setup seed -> --database json-file when no database is present
  - --settings database -> --database sqlite and --api electrobun-rpc
  - --settings json -> --api electrobun-rpc
  - --native-utils file-dialogs|clipboard|desktop-kit -> --api electrobun-rpc
  - --examples rpc -> --api electrobun-rpc
  - --ui shadcn -> --styling tailwindcss
- Does not remove features or switch package managers/build settings.

Manifest:
- ces.json includes $schema, version, createdAt, reproducibleCommand, projectName, packageName, appIdentifier, template, stack fields, packaging, addons, examples, git, install, and features.
- V1 manifests are additive. Unknown fields should be tolerated. Breaking manifest migrations require a documented migration path.
- Keep ces.json in source control.
- Prefer create-electrobun-stack add over hand-editing ces.json.

Release validation:
- bun run validate:render scaffolds the representative validation matrix and runs Biome against rendered projects.
- bun run validate installs each representative generated project and runs typecheck, lint, tests when present, and build.
- bun run pack:check runs npm pack --dry-run.
- bun run pack:smoke packs the tarball, installs it into a temp consumer project, checks --version, dry-runs a scaffold, and scaffolds a real app without dependency install.

Important paths in this repository:
- src/options.ts defines option types, defaults, choices, validation, and flag parsing helpers.
- src/prompts.ts defines interactive prompts.
- src/cli.ts parses arguments and implements create/add flows.
- src/manifest.ts creates and reads manifest stack metadata.
- src/scaffold.ts renders templates and option overlays.
- scripts/validate-generated-projects.ts runs the generated-project validation matrix.
- scripts/smoke-packed-package.ts runs the packed-package smoke test.
- templates/minimal/base contains common generated files.
- templates/minimal/options contains feature overlays.
- tests/cli.test.ts is the main behavior test suite.

Do not invent Electrobun APIs when explaining the generated app. The starter uses Electrobun's typed RPC, BrowserWindow/BrowserView APIs, ApplicationMenu roles, navigation rules, Utils.openFileDialog, and Utils clipboard helpers where selected.