Skip to content

feat(create-jsvision): publish a create-app scaffolder (npm/yarn/pnpm create) #169

Description

@blendsdk

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

  • packages/create-jsvision/ publishes with a bin; npm create jsvision my-app produces a
    standalone, runnable project outside this repo.
  • End-to-end test: scaffold to a temp dir → install → tsc --noEmit → headless smoke run. String
    containment is not sufficient for the artifact every new user runs first.
  • The existing plugin skill still scaffolds in-monorepo apps (no regression).
  • Wired into the release workflow; engines.node >= 22 throughout.
  • Zero native dependencies (yarn check:deps clean).

Blocked by the template-typecheck fix. Blocks the "Quick start" section of the install guide (#145).

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    effort: LLarge — multi-planenhancementNew feature or requestepicLarge multi-part feature; likely needs its own requirements/plan (CodeOps RD)needs-decisionOpen design decision blocks or scopes the workpriority: highDo sooner — high leverage or high ROI

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions