Installing packages is not enough — a reader's goal is a running application. Ship a published
scaffolder so the documented first step is:
npm create jsvision my-app # or: yarn create jsvision my-app
# pnpm create jsvision my-app
This is a promotion, not a new build
A working scaffolder already exists at
tools/claude-plugin/skills/jsvision-new-app/scripts/new-jsvision-app.mjs (309 lines): a pure,
fs-free buildAppFiles(name, archetype) returning Map<relPath, contents>, auto-discovered
archetypes (basic, form, grid, dashboard) under tools/claude-plugin/templates/,
path-traversal rejection, a refuse-to-overwrite writeApp wrapper, and a spec/impl test pair at
packages/examples/test/new-jsvision-app.{spec,impl}.test.ts.
What separates it from npm create jsvision:
| Gap |
Today |
Needed |
| Output shape |
writes packages/<slug>/, names it @jsvision/<slug>, sets "private": true, tsconfig extends ../../tsconfig.base.json |
a standalone project in ./<name>/ with a self-contained tsconfig |
| Distribution |
a Claude-plugin script, invoked by an agent |
a published npm package with a bin |
| Node floor |
template pins engines.node >= 20 |
SDK requires >= 22 |
| Output correctness |
generated main.ts fails tsc |
see the template-typecheck issue — a hard prerequisite |
| Browser archetype |
none |
blocked: @jsvision/web is internal and unpublished |
Naming
create-jsvision (unscoped) — the only form where npm create jsvision, yarn create jsvision, and
pnpm create jsvision all work identically. The scoped alternative forces
npm create @jsvision/app, and yarn 1.x handles scoped creates poorly. All three names
(create-jsvision, @jsvision/create-app, @jsvision/create) are currently free on npm.
Open decisions (why this wants requirements first)
- Two output modes or one? Standalone for users vs. the existing in-monorepo mode the plugin
skill depends on. Keeping buildAppFiles pure and parameterising the output shape is the obvious
path, but the plugin skill must not regress.
- Interactive or flags-only? Flags + a plain
readline fallback keeps the zero-dependency
posture. A TUI wizard built on @jsvision/ui would be a genuine dogfooding showcase, but adds an
install-time dependency on the very SDK being scaffolded. Recommend flags first.
- Versioning. Does
create-jsvision join the lockstep version set (yarn sync-package-versions)
or version independently? The templates pin an @jsvision/ui range, which couples them either way.
- Archetype set. Keep the existing four? A browser archetype is blocked while
web is internal.
- Non-TTY / CI behaviour.
Acceptance criteria
Blocked by the template-typecheck fix. Blocks the "Quick start" section of the install guide (#145).
Installing packages is not enough — a reader's goal is a running application. Ship a published
scaffolder so the documented first step is:
This is a promotion, not a new build
A working scaffolder already exists at
tools/claude-plugin/skills/jsvision-new-app/scripts/new-jsvision-app.mjs(309 lines): a pure,fs-free
buildAppFiles(name, archetype)returningMap<relPath, contents>, auto-discoveredarchetypes (
basic,form,grid,dashboard) undertools/claude-plugin/templates/,path-traversal rejection, a refuse-to-overwrite
writeAppwrapper, and a spec/impl test pair atpackages/examples/test/new-jsvision-app.{spec,impl}.test.ts.What separates it from
npm create jsvision:packages/<slug>/, names it@jsvision/<slug>, sets"private": true,tsconfigextends../../tsconfig.base.json./<name>/with a self-contained tsconfigbinengines.node >= 20>= 22main.tsfailstsc@jsvision/webis internal and unpublishedNaming
create-jsvision(unscoped) — the only form wherenpm create jsvision,yarn create jsvision, andpnpm create jsvisionall work identically. The scoped alternative forcesnpm create @jsvision/app, and yarn 1.x handles scoped creates poorly. All three names(
create-jsvision,@jsvision/create-app,@jsvision/create) are currently free on npm.Open decisions (why this wants requirements first)
skill depends on. Keeping
buildAppFilespure and parameterising the output shape is the obviouspath, but the plugin skill must not regress.
readlinefallback keeps the zero-dependencyposture. A TUI wizard built on
@jsvision/uiwould be a genuine dogfooding showcase, but adds aninstall-time dependency on the very SDK being scaffolded. Recommend flags first.
create-jsvisionjoin the lockstep version set (yarn sync-package-versions)or version independently? The templates pin an
@jsvision/uirange, which couples them either way.webis internal.Acceptance criteria
packages/create-jsvision/publishes with abin;npm create jsvision my-appproduces astandalone, runnable project outside this repo.
tsc --noEmit→ headless smoke run. Stringcontainment is not sufficient for the artifact every new user runs first.
engines.node >= 22throughout.yarn check:depsclean).Blocked by the template-typecheck fix. Blocks the "Quick start" section of the install guide (#145).