@solid-stack/create-app

A modern, type-safe CLI generator for scaffolding Solid Stack and TypeScript projects, built with TypeScript, tsup, cac, @clack/prompts, giget, and execa.

✨ Features

• 🎯 Config-Driven Brain: Template definitions, questions, and post-clone mutations are centralized in src/templates.config.ts.
• ⚡ Interactive & Headless (CI/CD): Beautiful interactive terminal UI powered by @clack/prompts, with comprehensive CLI flag support (--template, --git, --install, --force, --yes, --package-manager).
• 📥 Fast & Safe Downloads: Powered by giget to pull templates securely from GitHub or custom Git providers without requiring Git installed for the download.
• 🔧 Post-Clone File Mutation: Automatically updates package.json names, versions, and dynamically injects dependencies based on user choices.
• 🚀 Automated Tooling: Auto-initializes Git repositories and runs package installation with automatic package manager detection (pnpm, npm, yarn, bun).
• 🛡️ Type-Safe & Modular: Full TypeScript type safety, clean architecture, custom error handling hierarchy, and @solid-stack/di token compatibility.
• 📦 Dual ESM + CJS Output: Compiled via tsup with tree-shaking, sourcemaps, and full .d.ts declaration generation.

📦 Usage

Interactive Mode

npx @solid-stack/create-app

or with destination directory:

npx @solid-stack/create-app my-new-app

Headless / CI/CD Mode

# Scaffold backend starter with git and pnpm install
npx @solid-stack/create-app my-api -t ts-project --git --install -p pnpm

# Scaffold Next.js frontend starter skipping interactive prompts
npx @solid-stack/create-app my-web -t nextjs --yes

# Use arbitrary GitHub template
npx @solid-stack/create-app custom-app -t github:solid-stack-digital/ts-project-template --force

🛠️ CLI Flags & Options

| Flag | Shorthand | Description | Default | | --- | --- | --- | --- | | [dir] | | Target directory to create the project in | Interactive prompt | | --template <name> | -t | Template ID (ts-fullstack-template, agnos-express, ts-project, nextjs, ts-package, nextjs-saas, express-api) or git repo | Interactive prompt | | --install | -i | Automatically install dependencies | Interactive prompt | | --no-install | | Skip dependency installation | false | | --git | -g | Initialize a Git repository | Interactive prompt | | --no-git | | Skip Git repository initialization | false | | --force | -f | Overwrite existing directory if not empty | false | | --package-manager <pm> | -p | Package manager to use (pnpm, npm, yarn, bun) | Auto-detected | | --auth <token> | -a | GitHub Personal Access Token (or set GITHUB_TOKEN) | | | --no-check-access | | Skip pre-flight repository access verification | false | | --yes | -y | Run non-interactively using default choices | false | | --help | -h | Display help screen | | | --version | -v | Display version number | |

🔒 Private Repository Access & Authentication

[!IMPORTANT] The template repositories in the Solid Stack Digital ecosystem are private. Only authorized members of the Solid Stack Digital organization have access to clone templates and use this utility.

Before running create-app, ensure you are authenticated using one of the following methods:

1. SSH Key (Recommended)

Ensure your SSH key is added to your GitHub account:

ssh -T [email protected]

2. GitHub Personal Access Token (PAT)

Set the GITHUB_TOKEN environment variable with repo scope permissions:

export GITHUB_TOKEN=ghp_your_personal_access_token
npx @solid-stack/create-app my-app

or pass the --auth flag:

npx @solid-stack/create-app my-app --auth ghp_your_personal_access_token

3. GitHub CLI

Authenticate using the official GitHub CLI:

gh auth login

🧩 Templates Configuration (src/templates.config.ts)

create-app uses a config-driven architecture. Templates are defined with their prompts and postClone mutation hooks:

import { resolve } from "node:path";
import { readFile, writeFile } from "node:fs/promises";
import type { Template } from "@solid-stack/create-app";

export const TEMPLATES: Template[] = [
  {
    id: "nextjs-saas",
    name: "Next.js SaaS Starter",
    repo: "github:solid-stack-digital/nextjs-project-template",
    prompts: [
      {
        id: "useTailwind",
        type: "confirm",
        message: "Would you like to use Tailwind CSS?",
        initial: true,
      },
      {
        id: "database",
        type: "select",
        message: "Which database ORM would you like?",
        options: [
          { value: "prisma", label: "Prisma" },
          { value: "drizzle", label: "Drizzle" },
        ],
      },
    ],
    postClone: async (targetDir, answers, context) => {
      const pkgPath = resolve(targetDir, "package.json");
      const pkgContent = JSON.parse(await readFile(pkgPath, "utf-8"));

      if (answers.useTailwind) {
        pkgContent.devDependencies["tailwindcss"] = "^4.0.0";
      }
      if (answers.database === "prisma") {
        pkgContent.dependencies["@prisma/client"] = "^5.22.0";
      }

      await writeFile(pkgPath, JSON.stringify(pkgContent, null, 2) + "\n");
    },
  },
];

💻 Programmatic Usage

You can also invoke createApp programmatically in Node.js / TypeScript:

import { createApp } from "@solid-stack/create-app";

const result = await createApp({
  targetDir: "./my-app",
  template: "ts-project",
  install: true,
  git: true,
  packageManager: "pnpm",
  yes: true,
});

console.log("Project created at:", result.projectPath);

🏗️ Available Scripts

| Command | Description | | --- | --- | | pnpm dev | Starts tsup in watch mode for development | | pnpm build | Bundles ESM/CJS outputs and generates TypeScript declaration files | | pnpm test | Runs tests using Vitest | | pnpm test:watch | Runs Vitest in interactive watch mode | | pnpm test:coverage | Runs tests with code coverage reporting | | pnpm typecheck | Typechecks the project using TypeScript (tsc --noEmit) | | pnpm check | Runs typecheck, tests, and build in sequence | | pnpm prepublishOnly | Runs tests, build, and dist validation before publishing |

📄 License

MIT © Solid Stack Digital