feat(gallery): promote scaffold gallery to root gallery/ app - #1371
Conversation
vivek7405
left a comment
There was a problem hiding this comment.
Review: root gallery app architecture, templates & CLI resolution
The promotion of the scaffold gallery to a top-level runnable app in /gallery cleanly establishes a single source of truth. Scaffolding, CLI prepack sync, and test suites are all aligned.
The new gallery/ workspace was never recorded, so every CI job died at `npm ci` with "can only install packages when your package.json and package-lock.json are in sync".
Promoting the gallery to a runnable root app gave it a root layout, a home page, a theme toggle, and cn.ts. copyGallery() copies app/, components/ and lib/ wholesale, so those four landed in every scaffolded app and the branch then skipped the scaffold's own versions to avoid the clobber. That silently downgraded 'webjs create': the generated layout lost displayName, cspNonce(), LayoutProps typing and the metadata.icons favicon, and cn.ts stopped being the verbatim @webjsdev/ui registry copy that 'webjs ui add' depends on. Filter the four out of both the copy and the prepack bundle instead, from one shared list, so monorepo-dev and installed-npm scaffolding emit byte-identical apps and the scaffold keeps writing its own shell. Gitignore the transient prepack bundle so it can never be committed back as a second source.
The new home page called cardClass({ interactive: true }) (it takes a class
string), badgeClass({ variant: 'secondary' }) (only default and outline
exist), and read f.category / f.description off NavItem, which carries
neither. Every card rendered two undefined holes, and webjs typecheck was
red on six errors.
Flatten FEATURE_GROUPS in the render function so a card can label itself
with the group it came from, and read the blurb the model actually has.
Also refresh cn.ts from the @webjsdev/ui registry: the file arrived as a
copy of the blog's older one, which is the drift promoting the gallery is
meant to end.
The gallery is promoted so framework changes get validated against it, but nothing ran it: its test:browser pointed at a bare wtr with no config and no runner dependency, and its node suite was in no job. Ship the scaffold's web-test-runner config, add the runner deps, and run typecheck plus 'webjs test' (node + browser) for gallery/ in the in-repo app job, next to website and blog. Migrate its database there first, because the auth test SKIPS rather than fails on a missing users table and would have gone green vacuously. Exclude **/browser/** from its tsconfig: those files run under the runner's mocha tdd globals, which are not in the app's type surface. Teach require-scaffold-with-src.sh the new gallery/ path, or the gate stops seeing a gallery demo as a teaching surface.
The image copied website and examples but not gallery/, so the artifact every service deploys could not serve it, and npm install inside the image had no manifest for the new workspace. Copy its manifest and source, compile its Tailwind alongside the others, and add the compose service (port 15005, its own SQLite volume) so local parity matches the intended gallery.webjs.dev service. Verified by building the image and booting the gallery from it: /__webjs/ready, the home page, a feature card, the auth card, and the todo example all 200, and the stylesheet is baked in.
gallery/ is now the canonical source of what every scaffolded app ships, so an agent editing it needs the rules that are specific to this directory: the generated templates copy is never authored, four app-shell files are not payload, and the gallery:clear + coverage-gate obligations that come with a new demo.
Review + readiness passPicked this up to get it mergeable. Every one of the 9 required checks was failing, and the review turned up a scaffold regression that would have shipped silently. Six commits on top. Blockers fixed1. 2. Promoting the gallery to a runnable app gave it The generator's own docstring stated the opposite invariant and was left in place: "The scaffold's own What a generated app lost: Fixed by filtering those four out of both the copy and the prepack bundle, from one shared list ( 3. The gallery home page was written against APIs that do not exist. Gaps closed against the issue's acceptance criteria
Doc surfaces synced: Verification
Left out, deliberately
One pre-existing gap this surfaced, not introduced here and not fixed here: a freshly scaffolded app's |
Five defects from the review of the readiness commits. The compose gallery service set only AUTH_SECRET, but the image sets NODE_ENV=production and the sessions card throws at module load without SESSION_SECRET, so every route under the sessions segment returned a 500 from the deploy artifact. The blog service two blocks above already sets both, for exactly this reason. FILE_URL_SECRET rides along because the file-storage card signs its download links and otherwise falls back to a dev value in production. .env.example documented neither, which is why the compose omission was easy to make, and gallery/AGENTS.md tells the reader that copying it is the whole first-run setup. hover:border-border-strong compiled to nothing: Tailwind v4 resolves border-<name> from a --color-<name> theme key, and the gallery's @theme block never mapped one, so the hover state did not exist on the home cards, the secondary button, or the todo rows. The generated scaffold already emits this mapping; only the gallery's own block was missing it. The home page hoisted a cardClass() call to module scope. That is a module side effect, so the page shipped to the browser with no client behaviour to justify it. Moving it into the render function fixes the half this PR introduced (nav.ts keeps the page shipping for a separate, pre-existing reason). npm run dev never started the gallery, so the port table added for it described a server that did not exist. It starts now, with a GALLERY_PORT override matching the other two apps.
Second review round, scoped to the six readiness commits (
|
The home page shipped to the browser in the gallery AND in every app
webjs create generates, for a page with no client behaviour at all. It
dragged card.ts, badge.ts, nav.ts and the ~400-line cn.ts along with it.
Two independent causes, both in modules/gallery/nav.ts.
FEATURES was a const initialised by a top-level FEATURE_GROUPS.flatMap()
call. A top-level call is a module side effect, so every importer was
pinned. It is a featureList() function now, called inside the render
function, and the generated home page calls it there too.
The second cause was the word "window" in the rate-limit blurb prose
("Retry-After past the window"). nav.ts is neither a route module nor a
component, so the elision analyser scans it with string literals intact
and the client-global pattern matched ordinary English inside a quoted
string. Reworded to "once the interval resets".
Verified: gallery app/page.ts goes shipped -> inert, and a freshly
generated app boots with app/page.ts absent from its boot script, 25
feature cards, and no undefined holes.
The analyser treating prose inside a string literal as a browser-global
reference is a framework-side false positive that outlives this reword.
Deferred finding fixed in-place (9a19005)The elision issue reported as out-of-scope above is fixed here rather than tracked separately. Investigating it showed my earlier diagnosis was only half right: there were two independent causes, both in 1. The top-level call. 2. The word "window" in prose. This is the one worth knowing about. The rate-limit blurb read Fixing only cause 1 left the verdict unchanged, which is why the first attempt looked like a no-op. Effect
This flows to the scaffold, since Repo suites after the change: Two things found while verifying, NOT changed hereThe analyser false positive outlives this reword. Any prose containing
CI note
|
Closes #1370
Promotes the scaffold gallery from
packages/cli/templates/gallery/to a first-class, top-level runnable WebJs application in/galleryat the root of the monorepo.Summary of changes
gallery/(@webjsdev/gallery) with full routes, components, modules, and tests.scripts/sync-scaffold-gallery.mjsfor prepack/postpack sync.packages/cli/lib/create.jsto source templates directly fromgallery/in dev mode.Test Plan
webjs checkinsidegallery/.gallery/.webjs createscaffolding works cleanly.