Skip to content

Commit 665b211

Browse files
TDanks2000TDanks2000
committed
feat: harden generated Electrobun stack
1 parent 6c5deec commit 665b211

40 files changed

Lines changed: 5137 additions & 1540 deletions

‎README.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# create-electrobun-stack
2+
3+
Scaffold a production-minded Electrobun desktop app with Bun, React, TypeScript, Vite, Biome, typed Electrobun RPC, and a small set of optional integrations that can be enabled at create time or added later.
4+
5+
The generator is intentionally explicit: every selected stack option is written to `ces.json`, the generated project README explains what was scaffolded, and the `add` command can use that manifest to enable missing features without asking you to remember the original command.
6+
7+
## Quick Start
8+
9+
```bash
10+
bunx create-electrobun-stack my-app
11+
cd my-app
12+
bun run dev
13+
```
14+
15+
Requirements:
16+
17+
- Bun `>=1.3.0`.
18+
- A desktop OS supported by Electrobun for running or building generated apps.
19+
20+
Use the local command while developing this repository:
21+
22+
```bash
23+
bun run src/index.ts my-app
24+
```
25+
26+
## Default Stack
27+
28+
The default project is a Bun-powered Electrobun app with:
29+
30+
- React renderer built with Vite.
31+
- TanStack Router file routes.
32+
- Tailwind CSS v4.
33+
- Typed Electrobun RPC between the Bun process and the WebView.
34+
- Native Edit menu shortcuts.
35+
- Local-only navigation rules for bundled views.
36+
- Bun test scaffold.
37+
- Biome formatting and linting.
38+
- A starter RPC example.
39+
- A `ces.json` manifest with a reproducible command and feature flags.
40+
41+
Equivalent flags:
42+
43+
```bash
44+
bunx create-electrobun-stack my-app \
45+
--template minimal \
46+
--frontend react \
47+
--router tanstack-router \
48+
--query none \
49+
--runtime bun \
50+
--build-env dev \
51+
--build-targets current \
52+
--api electrobun-rpc \
53+
--navigation local-only \
54+
--native-utils none \
55+
--window-style native \
56+
--styling tailwindcss \
57+
--ui none \
58+
--app-menu edit \
59+
--auth none \
60+
--database none \
61+
--orm none \
62+
--db-setup none \
63+
--settings none \
64+
--package-manager bun \
65+
--testing bun \
66+
--addons none \
67+
--examples rpc \
68+
--install \
69+
--no-git
70+
```
71+
72+
## Common Recipes
73+
74+
Create without installing dependencies:
75+
76+
```bash
77+
bunx create-electrobun-stack my-app --no-install
78+
```
79+
80+
Preview the resolved stack without writing files:
81+
82+
```bash
83+
bunx create-electrobun-stack my-app --dry-run
84+
```
85+
86+
Create with SQLite, Drizzle, and database-backed settings:
87+
88+
```bash
89+
bunx create-electrobun-stack my-app \
90+
--database sqlite \
91+
--orm drizzle \
92+
--settings database
93+
```
94+
95+
Create a simpler renderer with React Router and TanStack Query:
96+
97+
```bash
98+
bunx create-electrobun-stack my-app \
99+
--router react-router \
100+
--query tanstack-query
101+
```
102+
103+
Start small and add a feature later:
104+
105+
```bash
106+
cd my-app
107+
bunx create-electrobun-stack add --orm drizzle
108+
```
109+
110+
`add` reads `ces.json`, infers prerequisites such as SQLite for Drizzle, updates the scaffolded files, and refreshes the manifest.
111+
112+
## Generated Commands
113+
114+
Most generated projects expose:
115+
116+
```bash
117+
bun run dev
118+
bun run build
119+
bun run typecheck
120+
bun run lint
121+
bun run format
122+
bun test
123+
```
124+
125+
Some options add commands. For example, `--addons turborepo` adds `bun run check`, and `--orm drizzle` adds Drizzle scripts.
126+
127+
## Docs
128+
129+
- [Docs index](./docs/README.md): where to start.
130+
- [CLI reference](./docs/cli.md): every command and operational flag.
131+
- [Stack options](./docs/options.md): what each option adds and where to find it after scaffolding.
132+
- [Generated project guide](./docs/generated-project.md): file structure, app lifecycle, and maintenance workflow.
133+
- [Add command](./docs/add-command.md): how to grow an existing generated app.
134+
- [Manifest reference](./docs/manifest.md): `ces.json` fields and schema.
135+
- [Templates](./docs/templates.md): how template overlays are organized.
136+
- [LLM guide](./docs/llm.txt): compact agent-oriented reference.
137+
138+
## Development
139+
140+
```bash
141+
bun install
142+
bun test
143+
bun run typecheck
144+
bun run lint
145+
```
146+
147+
The CLI entrypoint is `src/index.ts`. Stack choices live in `src/options.ts`, manifest generation lives in `src/manifest.ts`, and template rendering lives in `src/scaffold.ts`.

‎biome.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"$schema": "https://biomejs.dev/schemas/2.4.14/schema.json",
2+
"$schema": "https://biomejs.dev/schemas/2.4.15/schema.json",
33
"formatter": {
44
"indentStyle": "space",
55
"indentWidth": 2

‎bun.lock‎

Lines changed: 10 additions & 10 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/README.md‎

Lines changed: 25 additions & 114 deletions
Original file line numberDiff line numberDiff line change
@@ -1,124 +1,35 @@
1-
# create-electrobun-stack
1+
# Documentation
22

3-
`create-electrobun-stack` scaffolds an Electrobun desktop app with Bun, React, TanStack Router, strict TypeScript, Biome, and typed Electrobun RPC. Tailwind CSS is the default styling option; plain CSS is also supported.
3+
This folder is the durable reference for `create-electrobun-stack`. It is meant to work for humans scanning the project and for LLMs that need accurate, low-ambiguity context.
44

5-
The CLI is designed to feel like `better-t-stack`: pass a project name and optional stack flags. If you do not pass stack options, it uses the current default stack.
5+
## Start Here
66

7-
## Quick Start
7+
- [CLI reference](./cli.md) covers commands, flags, defaults, and examples.
8+
- [Stack options](./options.md) explains each scaffold option, what files it affects, and the combinations that are valid.
9+
- [Generated project guide](./generated-project.md) explains the app that gets created and how to work in it after scaffolding.
10+
- [Add command](./add-command.md) explains how existing generated apps are expanded through `ces.json`.
11+
- [Manifest reference](./manifest.md) documents `ces.json` and links to the JSON schema.
12+
- [Templates](./templates.md) explains the template overlay structure used by the generator.
13+
- [LLM guide](./llm.txt) is a compact plain-text summary for agents and retrieval systems.
814

9-
```bash
10-
bunx create-electrobun-stack my-app
11-
cd my-app
12-
bun run dev
13-
```
15+
## Recommended Reading Path
1416

15-
For local development in this repository:
17+
For a first app:
1618

17-
```bash
18-
bun run src/index.ts my-app
19-
```
19+
1. Read the root [README](../README.md).
20+
2. Use [CLI reference](./cli.md) for commands.
21+
3. Use [Stack options](./options.md) before choosing optional integrations.
22+
4. Use [Generated project guide](./generated-project.md) once the app exists.
2023

21-
By default, the CLI:
24+
For contributing to the generator:
2225

23-
- Uses the `minimal` template.
24-
- Installs dependencies with `bun install`.
25-
- Does not initialize git unless `--git` is passed.
26-
- Uses native typed Electrobun RPC rather than custom IPC.
27-
- Adds an Electrobun Edit menu for native copy/paste shortcuts unless `--app-menu none` is passed.
28-
- Blocks non-`views://` renderer navigation unless `--navigation none` is passed.
29-
- Includes the starter RPC example unless `--examples none` is passed.
30-
- Includes a Bun test scaffold unless `--testing none` is passed.
31-
- Supports optional app lock auth, settings persistence, seed data, Turborepo task running, static API mode, and multiple package managers.
32-
- Writes `ces.json` in the generated project root with Better-T-Stack-style metadata, a reproducible command, selected stack fields, and feature flags for future CLI commands.
26+
1. Read [Templates](./templates.md) to understand `base` and option overlays.
27+
2. Read [Manifest reference](./manifest.md) before changing `ces.json`.
28+
3. Update [LLM guide](./llm.txt) when user-facing options or behavior changes.
3329

34-
## Default Stack
30+
## Documentation Rules
3531

36-
```bash
37-
--template minimal
38-
--frontend react
39-
--runtime bun
40-
--build-env dev
41-
--build-targets current
42-
--api electrobun-rpc
43-
--navigation local-only
44-
--window-style native
45-
--styling tailwindcss
46-
--ui none
47-
--app-menu edit
48-
--auth none
49-
--database none
50-
--orm none
51-
--db-setup none
52-
--settings none
53-
--package-manager bun
54-
--testing bun
55-
--addons none
56-
--examples rpc
57-
--install
58-
--no-git
59-
```
60-
61-
## Common Commands
62-
63-
Create and install:
64-
65-
```bash
66-
bunx create-electrobun-stack my-app
67-
```
68-
69-
Create without installing:
70-
71-
```bash
72-
bunx create-electrobun-stack my-app --no-install
73-
```
74-
75-
Preview without writing files:
76-
77-
```bash
78-
bunx create-electrobun-stack my-app --dry-run
79-
```
80-
81-
Create inside a specific directory:
82-
83-
```bash
84-
bunx create-electrobun-stack my-app --cwd ~/Desktop
85-
```
86-
87-
Set the Electrobun app identifier:
88-
89-
```bash
90-
bunx create-electrobun-stack my-app --app-id com.example.myapp
91-
```
92-
93-
Initialize git after scaffolding:
94-
95-
```bash
96-
bunx create-electrobun-stack my-app --git
97-
```
98-
99-
List templates:
100-
101-
```bash
102-
bunx create-electrobun-stack --list-templates
103-
```
104-
105-
## Generated App Commands
106-
107-
```bash
108-
bun run dev
109-
bun run build
110-
bun test
111-
bun run typecheck
112-
bun run lint
113-
bun run format
114-
```
115-
116-
## Generated Manifest
117-
118-
Every generated project includes `ces.json` at the project root. It uses a Better-T-Stack-inspired shape with `$schema`, `version`, `createdAt`, `reproducibleCommand`, project identifiers, flat stack fields such as `database`, `orm`, `settings`, `frontend`, `addons`, `examples`, and a `features` map for future add-command checks.
119-
120-
## Current Scope
121-
122-
The implemented templates are `minimal`, `standard`, and `full`; `standard` and `full` currently use the same stable Electrobun template profile while keeping their manifest identity. Tailwind CSS and plain CSS are supported, `--ui shadcn` adds shadcn/ui project config when using Tailwind CSS, SQLite is supported, `--db-setup seed` adds starter metadata, and `--orm drizzle` adds Drizzle ORM when paired with `--database sqlite`. `--settings json` adds a VS Code-style `data/settings.json` store, and `--settings database` stores the same settings through SQLite when paired with `--database sqlite`. `--api none` omits runtime RPC wiring, `--auth app-lock` adds a local UI lock, and `--addons turborepo` adds Turbo task config. Electrobun-specific options include `--app-menu edit|none`, `--navigation local-only|none`, `--window-style native|hidden-inset`, `--build-env dev|canary|stable`, and `--build-targets current|all`. The default `--testing bun` adds a Bun test script and manifest smoke test; `--testing none` omits it. The default `--examples rpc` renders the starter RPC greeting/logging demo; `--examples none` keeps the typed RPC bridge but omits the demo calls and README section.
123-
124-
The CLI uses `@clack/prompts` for interactive prompts, spinners, and cancellation handling.
32+
- Keep this folder flat unless a topic becomes large enough to justify a subfolder.
33+
- Prefer exact flag names, generated paths, and commands over broad descriptions.
34+
- Document what exists now. Mark future ideas as future work only when they are relevant to current behavior.
35+
- When adding a scaffold option, update `cli.md`, `options.md`, `generated-project.md` if generated files change, `manifest.md` if manifest fields change, `templates.md` if template layout changes, and `llm.txt`.

0 commit comments

Comments
 (0)