Askr
Tooling

Tooling

Use tooling with the current published Askr packages.

  • @askrjs/cli0.0.5
  • @askrjs/vite0.0.7

How to use tooling

Run the published CLI through the project package boundary and review generated artifacts before committing them.

  1. Import the published @askrjs/cli and @askrjs/vite entrypoint.
  2. Keep tooling configuration next to the component, route, or server composition root that owns it.
  3. Handle pending, unavailable, cancellation, and failure states, then verify the production path.
npx @askrjs/cli@0.0.5 add page audit-log
npx @askrjs/cli@0.0.5 add action approve-request --route /requests/{id}
npx @askrjs/cli@0.0.5 openapi --check
npx @askrjs/cli@0.0.5 ssg --config ./ssg.config.ts --output ./dist

CLI workflow

The askr binary from @askrjs/cli covers the whole project lifecycle from one entry point: askr create scaffolds a new app, askr add page and askr add action generate route-first files into an existing one, and askr openapi, askr ssg, and the outdated/update/upgrade trio handle API contracts, static builds, and dependency maintenance. Run askr --help to see the full command list with one-line descriptions, or askr <command> --help for that command's specific flags. Every subcommand hangs off the single askr executable -- there are no separate compatibility binaries like askr-create or askr-add.

Vite integration

@askrjs/vite supplies the plugin pair that teaches a normal Vite project Askr's JSX and template conventions: askr() handles the browser build, and askrServer({ entry }), imported from the @askrjs/vite/server subpath, wires up server rendering. Both plugins expose only a stable name field in their published types (askr:vite and askr:server) rather than Vite's own recursive Plugin type, so a bundler like vite-plus that inspects plugin arrays doesn't end up comparing two different copies of that type. In practice you list both in vite.config.ts: plugins: [askr(), askrServer({ entry: 'src/server/entry-server.ts' })].

Generated artifacts

CLI commands write real, ready-to-run files rather than TODO-filled stubs. askr create produces a full project tree plus .askr/blueprint.json and .askr/builder-brief.md describing which template was picked and why, and askr add page/add action register new files directly into src/pages/app/_routes.tsx or src/pages/public/_routes.tsx depending on --branch. askr openapi writes a deterministic YAML document by loading a TypeScript module's default export and calling its toOpenApiDocument() method, and askr ssg writes a static HTML tree plus an incremental-build manifest. All of these writes are atomic, so a crash mid-run doesn't leave a half-written artifact behind.

Safe updates

askr outdated, update, and upgrade are read-only discovery followed by opt-in write: outdated lists what's available without touching anything, update applies only safe range changes, and upgrade additionally allows next-version major bumps for stable packages and breaking minor bumps for 0.x packages. Peer requirements between co-dependencies are still enforced during upgrade -- a package that would move outside another selected package's declared peer range is left for manual review instead of being forced through. None of the three commands touches a lockfile, runs installs or lifecycle scripts, or edits overrides, resolutions, catalogs, or packageManager metadata; they only rewrite dependency version strings in package.json.