Revamp create-blitzpack UX and flow

Author: CarboxyDev

README.md

@@ -45,9 +45,11 @@ The setup wizard will guide you through project creation and next steps. Make su
 
 During setup, choose a profile:
 
-- **Recommended**: Full app features + Docker deployment assets + CD workflow.
-- **Platform-First**: Full app features, no deployment assets.
-- **Custom**: Pick app features and deployment options independently.
+- **Recommended**: Core app with everything included.
+- **Platform-Agnostic**: Core app without dockerfiles.
+- **Modular**: Core app with features of your choice.
+
+If you choose **Modular**, the wizard opens feature customization before scaffolding.
 
 **What's running after setup:**
 

create-blitzpack/README.md

@@ -31,9 +31,11 @@ pnpm create blitzpack [project-name] [options]
 
 The scaffold wizard supports three profiles:
 
-- **Recommended**: All app features plus Docker deployment assets and CD workflow.
-- **Platform-First**: All app features, without deployment assets.
-- **Custom**: Pick app features and deployment options independently.
+- **Recommended**: Core app with everything included.
+- **Platform-Agnostic**: Core app without dockerfiles.
+- **Modular**: Core app with features of your choice.
+
+Each profile is a setup path. The **Modular** path opens full feature customization before files are created.
 
 ## Requirements
 

create-blitzpack/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-blitzpack",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "Create a new Blitzpack project - full-stack TypeScript monorepo with Next.js and Fastify",
   "type": "module",
   "bin": {
@@ -16,18 +16,17 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
+    "@clack/prompts": "^1.0.0",
     "chalk": "^5.6.2",
     "commander": "^13.1.0",
     "fs-extra": "^11.3.3",
     "giget": "^2.0.0",
     "ora": "^8.2.0",
-    "prompts": "^2.4.2",
     "validate-npm-package-name": "^6.0.2"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",
     "@types/node": "^22.19.3",
-    "@types/prompts": "^2.4.9",
     "@types/validate-npm-package-name": "^4.0.2",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3"

create-blitzpack/src/checks.ts

@@ -1,10 +1,15 @@
 import chalk from 'chalk';
 import { execSync } from 'child_process';
+import ora from 'ora';
+
+import { isDockerInstalled } from './docker.js';
+import { isGitInstalled } from './git.js';
 
 interface CheckResult {
   passed: boolean;
   name: string;
-  message?: string;
+  required: boolean;
+  message: string;
 }
 
 function checkNodeVersion(): CheckResult {
@@ -16,67 +21,124 @@ function checkNodeVersion(): CheckResult {
       return {
         passed: true,
         name: 'Node.js',
+        required: true,
+        message: nodeVersion,
       };
     }
 
     return {
       passed: false,
       name: 'Node.js',
+      required: true,
       message: `Node.js >= 20.0.0 required (found ${nodeVersion})`,
     };
   } catch {
     return {
       passed: false,
       name: 'Node.js',
+      required: true,
       message: 'Failed to check Node.js version',
     };
   }
 }
 
 function checkPnpmInstalled(): CheckResult {
   try {
-    execSync('pnpm --version', { stdio: 'ignore' });
+    const version = execSync('pnpm --version', {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
     return {
       passed: true,
       name: 'pnpm',
+      required: true,
+      message: `v${version}`,
     };
   } catch {
     return {
       passed: false,
       name: 'pnpm',
+      required: true,
       message: 'pnpm not found. Install: npm install -g pnpm',
     };
   }
 }
 
+function checkGit(): CheckResult {
+  const installed = isGitInstalled();
+  return {
+    passed: installed,
+    name: 'git',
+    required: false,
+    message: installed
+      ? 'available (repository initialization supported)'
+      : 'not found (git init step will be skipped)',
+  };
+}
+
+function checkDocker(): CheckResult {
+  const installed = isDockerInstalled();
+  return {
+    passed: installed,
+    name: 'Docker',
+    required: false,
+    message: installed
+      ? 'available (automatic local DB setup supported)'
+      : 'not found (start PostgreSQL separately)',
+  };
+}
+
 export async function runPreflightChecks(): Promise<boolean> {
   console.log();
-  console.log(chalk.bold('  Checking requirements...'));
+  console.log(chalk.bold('  System readiness'));
+  console.log(chalk.dim('  Validating required and optional local tooling...'));
   console.log();
 
-  const checks: CheckResult[] = [checkNodeVersion(), checkPnpmInstalled()];
+  const checks: CheckResult[] = [
+    checkNodeVersion(),
+    checkPnpmInstalled(),
+    checkGit(),
+    checkDocker(),
+  ];
 
-  let hasErrors = false;
+  const requiredFailures: CheckResult[] = [];
+  const optionalWarnings: CheckResult[] = [];
 
   for (const check of checks) {
+    const spinner = ora(`Checking ${check.name}...`).start();
+
     if (check.passed) {
-      console.log(chalk.green('  ✔'), check.name);
+      spinner.succeed(chalk.bold(check.name));
     } else {
-      hasErrors = true;
-      console.log(chalk.red('  ✖'), check.name);
-      if (check.message) {
-        console.log(chalk.dim(`    ${check.message}`));
+      if (check.required) {
+        requiredFailures.push(check);
+        spinner.fail(chalk.bold(check.name));
+      } else {
+        optionalWarnings.push(check);
+        spinner.warn(chalk.bold(check.name));
       }
+      console.log(chalk.dim(`    ${check.message}`));
     }
   }
 
   console.log();
 
-  if (hasErrors) {
+  if (optionalWarnings.length > 0) {
+    console.log(chalk.yellow('  Optional tools missing:'));
+    for (const warning of optionalWarnings) {
+      console.log(chalk.dim(`    • ${warning.name}: ${warning.message}`));
+    }
+    console.log();
+  }
+
+  if (requiredFailures.length > 0) {
     console.log(
       chalk.red('  ✖'),
-      'Requirements not met. Please fix the errors above.'
+      'Required dependencies are missing. Fix the items below and try again:'
     );
+    for (const failure of requiredFailures) {
+      console.log(chalk.dim(`    • ${failure.name}: ${failure.message}`));
+    }
     console.log();
     return false;
   }

create-blitzpack/src/commands/create.ts

@@ -1,9 +1,9 @@
+import { confirm, isCancel } from '@clack/prompts';
 import chalk from 'chalk';
 import { spawn } from 'child_process';
 import fs from 'fs-extra';
-import ora from 'ora';
+import ora, { type Ora } from 'ora';
 import path from 'path';
-import prompts from 'prompts';
 
 import { runPreflightChecks } from '../checks.js';
 import type { FeatureOptions } from '../constants.js';
@@ -47,6 +47,42 @@ interface CreateFlags {
   dryRun?: boolean;
 }
 
+function renderProgressBar(current: number, total: number): string {
+  const width = 28;
+  const clampedTotal = Math.max(total, 1);
+  const ratio = Math.min(Math.max(current / clampedTotal, 0), 1);
+  const filled = Math.round(width * ratio);
+  const empty = width - filled;
+  const filledBar = chalk.cyan('█'.repeat(filled));
+  const emptyBar = chalk.dim('░'.repeat(empty));
+  const percentage = `${Math.round(ratio * 100)}`.padStart(3, ' ');
+  return `[${filledBar}${emptyBar}] ${percentage}%`;
+}
+
+function renderStepTrack(step: number, total: number): string {
+  const segments: string[] = [];
+
+  for (let index = 1; index <= total; index++) {
+    if (index < step) {
+      segments.push(chalk.green('●'));
+    } else if (index === step) {
+      segments.push(chalk.cyan('◆'));
+    } else {
+      segments.push(chalk.dim('◇'));
+    }
+  }
+
+  return segments.join(chalk.dim('──'));
+}
+
+function printStepHeader(step: number, total: number, title: string): void {
+  const completed = step - 1;
+  console.log();
+  console.log(chalk.cyan(`  Step ${step}/${total}`), chalk.bold(title));
+  console.log(`  ${renderProgressBar(completed, total)}`);
+  console.log(`  ${renderStepTrack(step, total)}`);
+}
+
 function printDryRun(options: {
   projectName: string;
   projectSlug: string;
@@ -139,14 +175,12 @@ export async function create(
     const files = await fs.readdir(targetDir);
     if (files.length > 0) {
       if (options.useCurrentDir) {
-        const { confirm } = await prompts({
-          type: 'confirm',
-          name: 'confirm',
-          message: `Current directory is not empty. Continue?`,
-          initial: false,
+        const shouldContinue = await confirm({
+          message: 'Current directory is not empty. Continue?',
+          initialValue: false,
         });
 
-        if (!confirm) {
+        if (isCancel(shouldContinue) || !shouldContinue) {
           return;
         }
       } else {
@@ -156,13 +190,24 @@ export async function create(
     }
   }
 
-  const spinner = ora();
+  const shouldRunSetup = await promptAutomaticSetup();
+  const totalSteps =
+    2 +
+    (options.skipGit ? 0 : 1) +
+    (options.skipInstall ? 0 : 1) +
+    (shouldRunSetup ? 1 : 0);
+  let currentStep = 0;
+  let spinner: Ora | undefined;
 
   try {
-    spinner.start('Downloading template from GitHub...');
+    currentStep += 1;
+    printStepHeader(currentStep, totalSteps, 'Scaffold template');
+    spinner = ora('Downloading template from GitHub...').start();
     await downloadAndPrepareTemplate(targetDir, spinner, options.features);
 
-    spinner.start('Configuring project...');
+    currentStep += 1;
+    printStepHeader(currentStep, totalSteps, 'Configure project files');
+    spinner.start('Applying template transforms...');
     await transformFiles(
       targetDir,
       {
@@ -176,16 +221,24 @@ export async function create(
     spinner.succeed('Configured project');
 
     if (!options.skipGit && isGitInstalled()) {
+      currentStep += 1;
+      printStepHeader(currentStep, totalSteps, 'Initialize git repository');
       spinner.start('Initializing git repository...');
       const gitSuccess = initGit(targetDir);
       if (gitSuccess) {
         spinner.succeed('Initialized git repository');
       } else {
         spinner.warn('Failed to initialize git repository');
       }
+    } else if (!options.skipGit) {
+      currentStep += 1;
+      printStepHeader(currentStep, totalSteps, 'Initialize git repository');
+      spinner.warn('Skipped git initialization (git not installed)');
     }
 
     if (!options.skipInstall) {
+      currentStep += 1;
+      printStepHeader(currentStep, totalSteps, 'Install dependencies');
       spinner.start('Installing dependencies...');
       const success = await runInstall(targetDir);
       if (success) {
@@ -197,12 +250,11 @@ export async function create(
       }
     }
 
-    // Prompt for automatic setup
     let ranAutomaticSetup = false;
-    const shouldRunSetup = await promptAutomaticSetup();
 
     if (shouldRunSetup) {
-      console.log();
+      currentStep += 1;
+      printStepHeader(currentStep, totalSteps, 'Run local database setup');
       spinner.start('Starting PostgreSQL database...');
       const dockerSuccess = runDockerCompose(targetDir);
       if (dockerSuccess) {
@@ -231,7 +283,7 @@ export async function create(
       ranAutomaticSetup
     );
   } catch (error) {
-    spinner.fail();
+    spinner?.fail();
     printError(
       error instanceof Error ? error.message : 'Unknown error occurred'
     );