ShipUI CLI v0.2.0: Starters, Blueprints, and Security Hardening

ShipUI CLI v0.2.0 is out. This is a big one.

The CLI started as a way to install individual components. Now it can scaffold entire features and full themed projects from scratch.

# Scaffold a complete themed Next.js project
npx @voltenworks/shipui init --theme aloha

# Add auth with Clerk in one command
npx @voltenworks/shipui add auth --provider clerk --theme aloha

# Add a dashboard scaffold
npx @voltenworks/shipui add dashboard --theme folio

Starters

Starters are multi-file feature scaffolds. Instead of installing one component at a time, a starter installs an entire feature: pages, components, hooks, validation, and CSS.

Auth Starter

The auth starter installs login, signup, and forgot-password pages with form hooks, Zod validation, and an AuthForm component. It supports provider selection so you get the right middleware and wiring out of the box.

npx @voltenworks/shipui add auth --provider clerk
npx @voltenworks/shipui add auth --provider clerk --theme aloha

After installing, wrap your root layout with ClerkProvider and add your Clerk API keys to .env.local. The CLI creates a .env.example with the required variables.

Dashboard Starter

The dashboard starter installs an admin layout with sidebar, topbar, shell, an overview page with stat cards, activity feed, and checklist, plus a settings page.

npx @voltenworks/shipui add dashboard
npx @voltenworks/shipui add dashboard --theme folio

Both starters work with or without a theme. Base installs give you the structure. Theme installs give you the full styled experience.

Blueprint Init

The init command can now scaffold a complete themed Next.js project from an empty directory.

npx @voltenworks/shipui init --theme aloha --yes
npx @voltenworks/shipui init --theme aloha --features auth --provider clerk --yes
npx @voltenworks/shipui init --theme aloha --features auth,dashboard --yes

This runs create-next-app, writes all theme files, installs dependencies, and optionally installs starters. One command, full project.

For existing Next.js projects, init still creates a shipui.json config file with your project paths and optional default theme.

Semantic Theming

You no longer need to pass --theme on every command. Set a default theme in shipui.json:

{
  "theme": "aloha"
}

Or the CLI auto-detects your theme from globals.css markers. Theme resolution order:

--theme flag (explicit)
"theme" field in shipui.json
Auto-detected from CSS markers

shipui.json v2

The config schema has been updated. Existing v1 configs are automatically migrated. New fields:

{
  "$schemaVersion": 2,
  "theme": "aloha",
  "projectType": "custom",
  "features": {
    "auth": { "included": true, "provider": "clerk", "providerInstalled": true },
    "dashboard": { "included": true }
  }
}

The CLI tracks which starters are installed and their provider configuration. This lets future commands know what's already set up.

Security Fixes

We ran a security review on the entire codebase and fixed two real vulnerabilities:

Command injection in dependency installation. The installDeps function was using execSync with string interpolation, which meant a compromised registry could inject shell commands through package names. We switched to execFileSync with an argument array. No shell involved.

Path traversal in file writing. The component file writer (writeComponentFiles) was missing the path validation guards that the starter and blueprint writers already had. A malicious registry response could have written files outside the project directory. All file writers now validate that paths don't escape the project root.

Both of these required a compromised or man-in-the-middle'd registry to exploit, but they were real attack surfaces and they're now closed.

Additional hardening: the layout font className injection now uses a balanced-brace parser instead of a regex (handles nested expressions like cn("foo", {bar: true})), and the template-literal className match is anchored to the <body> tag to avoid modifying other elements.

Test Suite

v0.2.0 ships with 118 unit tests across 9 test files covering every lib module: parse, auth, css-merger, config, deps, writer, paths, api, and cache.

npx vitest run
# 9 passed | 118 tests | 150ms

Updated Commands

The list command now shows a starters section with provider information. The info command handles starter lookup with provider details. Both reflect the expanded registry.

npx @voltenworks/shipui list          # components + starters
npx @voltenworks/shipui info auth     # starter details with providers

Bug Fixes

Hyphenated theme slugs (e.g. solar-dark) now work correctly in CSS marker detection and input parsing
Layout font className handling appends to existing classes instead of replacing them
.env.example appends missing vars to an existing file instead of only creating new ones
Non-JSON API error responses are handled gracefully
Env var dedup logic fixed
Default to Clerk in non-interactive init mode

Upgrading

npx @voltenworks/shipui@latest doctor

If you have a shipui.json from v0.1.x, it will be migrated automatically on next use. No manual changes needed.

The CLI source is public at github.com/voltenworks/shipui-cli. If you find issues, open a ticket or email support@voltenworks.com.

Browse components | View themes