Problem
The scaffold gallery currently lives inside packages/cli/templates/gallery/ as un-executed template files. Because it is not structured as a top-level runnable app in the monorepo, framework updates cannot easily be validated against the gallery code via webjs check or automated browser tests, leading to template rot and code duplication.
Design / approach
Promote the scaffold gallery to a first-class, top-level application in /gallery at the root of the monorepo (alongside website/):
gallery/ will serve as a fully functional, live WebJs application deployed at https://gallery.webjs.dev.
gallery/ becomes the single source of truth for gallery components, feature demos, and example apps.
packages/cli/lib/create.js and CLI build scripts will source templates directly from /gallery in dev mode.
- Use the established
prepack / postpack sync pattern (scripts/sync-scaffold-gallery.mjs, matching sync-scaffold-skill.mjs) to package gallery/ into @webjsdev/cli for npm distribution.
- Remove duplicated static files in
packages/cli/templates/gallery/ from git tracking.
Implementation Plan (for the implementing agent)
1. Root Monorepo Structure
- Root
package.json: Add "gallery" to the workspaces array. Add top-level helper scripts (dev:gallery, test:browser:gallery).
2. Root gallery/ Application ([NEW])
- Config & Package:
gallery/package.json (@webjsdev/gallery), gallery/tsconfig.json, gallery/AGENTS.md, gallery/CONVENTIONS.md.
- App Routes: Move
app/features/ (25 single-concept card routes) and app/examples/ (Todo app) from template to gallery/app/. Add root gallery/app/layout.ts and gallery/app/page.ts dashboard.
- Modules & Logic: Move
modules/ (domain logic, #db/* sqlite models, auth, todo logic) to gallery/modules/.
- Components & Lib: Move gallery design system (
components/ui/) and helper utilities (lib/utils/ui.ts) to gallery/components/ and gallery/lib/.
- Testing: Add unit tests (
test/unit/), request pipeline tests (test/auth/), and Web Test Runner browser tests (test/browser/) inside gallery/test/.
3. CLI Packaging & Scaffolding
scripts/sync-scaffold-gallery.mjs ([NEW]): Prepack script to copy gallery/{app,modules,components,lib,test} into packages/cli/templates/gallery/ during prepack and clean up transient copies during postpack.
packages/cli/package.json: Wire sync-scaffold-gallery.mjs into prepack and postpack.
packages/cli/lib/create.js: Update copyGallery() to resolve galleryDir from root gallery/ in monorepo dev mode, falling back to TEMPLATES/gallery in installed npm package mode.
packages/cli/templates/gallery/: Untrack duplicate static template files in Git.
Invariants & Gotchas to Respect
- Node 24+ & Bun Parity:
gallery/ must boot and pass tests on both Node and Bun (bun --bun run dev).
- Convention Checks:
webjs check and webjs doctor must pass cleanly for gallery/.
- Offline Scaffolding:
prepack must bundle the gallery so npx webjs create continues to work completely offline from npm.
Acceptance criteria
Problem
The scaffold gallery currently lives inside
packages/cli/templates/gallery/as un-executed template files. Because it is not structured as a top-level runnable app in the monorepo, framework updates cannot easily be validated against the gallery code viawebjs checkor automated browser tests, leading to template rot and code duplication.Design / approach
Promote the scaffold gallery to a first-class, top-level application in
/galleryat the root of the monorepo (alongsidewebsite/):gallery/will serve as a fully functional, live WebJs application deployed athttps://gallery.webjs.dev.gallery/becomes the single source of truth for gallery components, feature demos, and example apps.packages/cli/lib/create.jsand CLI build scripts will source templates directly from/galleryin dev mode.prepack/postpacksync pattern (scripts/sync-scaffold-gallery.mjs, matchingsync-scaffold-skill.mjs) to packagegallery/into@webjsdev/clifor npm distribution.packages/cli/templates/gallery/from git tracking.Implementation Plan (for the implementing agent)
1. Root Monorepo Structure
package.json: Add"gallery"to theworkspacesarray. Add top-level helper scripts (dev:gallery,test:browser:gallery).2. Root
gallery/Application ([NEW])gallery/package.json(@webjsdev/gallery),gallery/tsconfig.json,gallery/AGENTS.md,gallery/CONVENTIONS.md.app/features/(25 single-concept card routes) andapp/examples/(Todo app) from template togallery/app/. Add rootgallery/app/layout.tsandgallery/app/page.tsdashboard.modules/(domain logic,#db/*sqlite models, auth, todo logic) togallery/modules/.components/ui/) and helper utilities (lib/utils/ui.ts) togallery/components/andgallery/lib/.test/unit/), request pipeline tests (test/auth/), and Web Test Runner browser tests (test/browser/) insidegallery/test/.3. CLI Packaging & Scaffolding
scripts/sync-scaffold-gallery.mjs([NEW]): Prepack script to copygallery/{app,modules,components,lib,test}intopackages/cli/templates/gallery/duringprepackand clean up transient copies duringpostpack.packages/cli/package.json: Wiresync-scaffold-gallery.mjsintoprepackandpostpack.packages/cli/lib/create.js: UpdatecopyGallery()to resolvegalleryDirfrom rootgallery/in monorepo dev mode, falling back toTEMPLATES/galleryin installed npm package mode.packages/cli/templates/gallery/: Untrack duplicate static template files in Git.Invariants & Gotchas to Respect
gallery/must boot and pass tests on both Node and Bun (bun --bun run dev).webjs checkandwebjs doctormust pass cleanly forgallery/.prepackmust bundle the gallery sonpx webjs createcontinues to work completely offline from npm.Acceptance criteria
gallery/lives at monorepo root as a runnable, testable WebJs application.webjs create my-appcorrectly scaffolds gallery templates sourced fromgallery/.npx webjs check,npm test, andnpm run test:browserrun and pass insidegallery/.packages/cli/templates/gallery/are removed from git tracking and auto-synced viaprepack.https://gallery.webjs.dev.