create-stackit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YOUR_NAME
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,194 @@
+# create-stackit
+
+Pragmatic React / Next.js starter generator. Answer a few questions and get a
+production-ready project with your exact stack — no manual wiring required.
+
+## Quick start
+
+```bash
+npm create stackit@latest
+# or
+npx create-stackit
+# or pass a project name directly
+npx create-stackit my-app
+```
+
+The CLI walks you through every choice interactively.
+
+---
+
+## What gets generated
+
+Each project is assembled from one of **16 curated templates** covering every
+combination of the four axes below, then enriched by whichever add-ons you
+select.
+
+| Axis | Options |
+|---|---|
+| Framework | Vite + React · Next.js |
+| Language | TypeScript · JavaScript |
+| State | Zustand · Redux Toolkit |
+| UI | shadcn/ui + Tailwind · Material UI |
+
+### Folder structure
+
+| Style | Layout |
+|---|---|
+| **Modular** *(default)* | `src/features/<name>/` — self-contained feature modules |
+| **Atomic** | `src/components/atoms / molecules / organisms / templates` |
+
+### Add-ons (toggle at prompt time)
+
+| Add-on | What it injects |
+|---|---|
+| TanStack Query | `QueryClient`, `useApiQuery`, `useApiMutation` hooks |
+| Axios | Pre-configured `api` client with auth + error interceptors |
+| react-hook-form + zod | Form library wired with a zod resolver |
+| react-hot-toast | `<AppToaster>` component + API-error event bridge |
+| Vitest + RTL | Test scripts, jsdom environment, `@testing-library` deps |
+| ESLint + Prettier | Lint/format scripts, `eslint-config-prettier` |
+| Custom hooks | `useDebounce`, `useThrottle`, `useToggle`, `usePrevious` |
+| Auth boilerplate | Scaffold for JWT + refresh token flow |
+
+---
+
+## CLI flags
+
+Every prompt can be pre-answered with a flag — the CLI skips those questions
+and goes straight to the rest.
+
+```
+Usage: create-stackit [project-name] [options]
+
+Arguments:
+  project-name              name of the project directory
+
+Options:
+  -f, --framework <fw>      vite | next
+  -l, --language <lang>     ts | js
+  -s, --state <state>       zustand | redux
+  -u, --ui <ui>             shadcn | mui
+  --structure <s>           atomic | modular
+  --pm <pm>                 npm | pnpm | yarn  (auto-detected if omitted)
+  --skip-install            skip dependency installation
+  --skip-git                skip git initialization
+  -V, --version             output the version number
+  -h, --help                display help
+```
+
+### Examples
+
+```bash
+# Fully interactive
+npx create-stackit
+
+# Pre-fill name + framework, answer the rest interactively
+npx create-stackit my-app --framework vite
+
+# Fully non-interactive (no prompts at all)
+npx create-stackit my-app \
+  --framework next \
+  --language ts \
+  --state redux \
+  --ui shadcn \
+  --structure modular \
+  --pm pnpm
+
+# Skip heavy steps during development
+npx create-stackit my-app --skip-install --skip-git
+```
+
+---
+
+## Package manager support
+
+`create-stackit` detects whichever package manager you are already using
+(by checking lock files in the current directory) and uses it automatically.
+Pass `--pm` to override.
+
+| Flag | Installs with | Runs scripts with |
+|---|---|---|
+| `npm` | `npm install` | `npm run dev` |
+| `pnpm` | `pnpm install` | `pnpm dev` |
+| `yarn` | `yarn` | `yarn dev` |
+
+---
+
+## After generation
+
+```bash
+cd my-app
+```
+
+If you passed `--skip-install`, install dependencies first:
+
+```bash
+npm install      # npm
+pnpm install     # pnpm
+yarn             # yarn
+```
+
+Start the dev server:
+
+```bash
+npm run dev   # npm
+pnpm dev      # pnpm
+yarn dev      # yarn
+```
+
+Build for production:
+
+```bash
+npm run build   # npm
+pnpm build      # pnpm
+yarn build      # yarn
+```
+
+For **Next.js** projects — serve the production build:
+
+```bash
+npm run start   # npm
+pnpm start      # pnpm
+yarn start      # yarn
+```
+
+---
+
+## Requirements
+
+- **Node.js** `>=18.18.0` (LTS 20.x recommended)
+- **Git** — optional, only needed when "Initialize a git repository?" is accepted
+
+---
+
+## Template matrix
+
+All 16 template keys follow the pattern `{framework}-{lang}-{state}-{ui}`:
+
+```
+vite-ts-zustand-shadcn    vite-ts-zustand-mui
+vite-ts-redux-shadcn      vite-ts-redux-mui
+vite-js-zustand-shadcn    vite-js-zustand-mui
+vite-js-redux-shadcn      vite-js-redux-mui
+
+next-ts-zustand-shadcn    next-ts-zustand-mui
+next-ts-redux-shadcn      next-ts-redux-mui
+next-js-zustand-shadcn    next-js-zustand-mui
+next-js-redux-shadcn      next-js-redux-mui
+```
+
+---
+
+## Contributing
+
+1. Fork and clone the repo.
+2. `npm install`
+3. `npm run test:local` — scaffold a project into `./test-app` and verify it.
+4. To add a new template, create `templates/<key>/` and add the key to
+   `SUPPORTED_COMBOS` in `src/choices.js`.
+
+---
+
+## License
+
+MIT

package/bin/index.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { runPrompts } from '../src/prompts.js';
+import { generateProject } from '../src/generator.js';
+import { logger, printBanner } from '../src/utils.js';
+import {runScript, installCommandString} from '../src/pm.js'
+
+const program = new Command();
+
+program
+  .name('create-stackit')
+  .description('Pragmatic Front-End starter generator')
+  .version('0.1.0')
+  .argument('[project-name]', 'name of the project directory')
+  .option('-f, --framework <framework>', 'vite | next')
+  .option('l, --language <language>', 'js | ts')
+  .option('-s, --state <state>', 'zustand | redux')
+  .option('-u, --ui <ui>', 'shadcn | mui')
+  .option('--structure <structure>', 'atomic | modular')
+  .option('--pm <pm>', 'npm | pnpm | yarn (auto-detected if omitted)')
+  .option('--skip-install', 'skip dependency installation')
+  .option('--skip-git', 'skip git initialization')
+  .action(async (projectName, options) => {
+    try {
+      printBanner();
+
+      // Merge CLI flags with interactive prompts
+      const answers = await runPrompts({
+        projectName,
+        framework: options.framework,
+        language: options.language,
+        state: options.state,
+        ui: options.ui,
+        structure: options.structure,
+        packageManager: options.packageManager
+      });
+
+      await generateProject({
+        ...answers,
+        skipInstall: options.skipInstall,
+        skipGit: options.skipGit,
+      });
+
+      const pm = answers.packageManager || 'npm';
+      logger.success('\n✨ Project created successfully!\n');
+      logger.info(`  cd ${answers.projectName}`);
+      if (options.skipInstall) {
+        logger.info(`${installCommandString(pm)}`);
+      }
+      logger.info(` ${runScript(pm, 'dev')}\n`);
+    } catch (err) {
+      if (err && err.isCancelled) {
+        logger.warn('\n✋ Cancelled.\n');
+        process.exit(0);
+      }
+      logger.error('\n❌ Failed to create project:\n');
+      console.error(chalk.red(err?.stack || err?.message || err));
+      process.exit(1);
+    }
+  });
+
+program.parseAsync(process.argv);

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "create-stackit",
+  "version": "0.1.0",
+  "description": "Pragmatic React/Next.js starter generator with curated, production-grade templates",
+  "type": "module",
+  "bin": {
+    "create-stackit": "./bin/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates"
+  ],
+  "scripts": {
+    "start": "node ./bin/index.js",
+    "test:local": "node ./bin/index.js test-app"
+  },
+  "keywords": [
+    "react",
+    "vite",
+    "next",
+    "starter",
+    "boilerplate",
+    "cli",
+    "zustand",
+    "redux",
+    "shadcn",
+    "tanstack-query"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "execa": "^9.5.1",
+    "fs-extra": "^11.2.0",
+    "ora": "^8.1.1",
+    "prompts": "^2.4.2",
+    "validate-npm-package-name": "^6.0.0"
+  }
+}

package/src/choices.js

@@ -0,0 +1,63 @@
+// Centralized choices. Adding a new template? Update SUPPORTED_COMBOS too.
+export const PINNED_NODE_VERSION = '20.18.0';
+export const ENGINES_NODE_RANGE = '>=18.18.0';
+
+export const CHOICES = {
+  framework: [
+    { title: 'Vite + React', value: 'vite', description: 'SPA, fast HMR, lightweight' },
+    { title: 'Next.js', value: 'next', description: 'SSR/SSG, app router, SEO-ready' },
+  ],
+  language: [
+    { title: 'TypeScript', value: 'ts', description: 'Type-safe, IDE-friendly' },
+    { title: 'JavaScript', value: 'js', description: 'No compilation step' },
+  ],
+  state: [
+    { title: 'Zustand', value: 'zustand', description: 'Lightweight, modern, minimal boilerplate' },
+    { title: 'Redux Toolkit', value: 'redux', description: 'Enterprise, predictable, devtools-rich' },
+  ],
+  ui: [
+    { title: 'shadcn/ui + Tailwind', value: 'shadcn', description: 'Customizable, copy-paste components' },
+    { title: 'Material UI', value: 'mui', description: 'Battle-tested, large component library' },
+  ],
+  structure: [
+    { title: 'Atomic', value: 'atomic', description: 'atoms / molecules / organisms' },
+    { title: 'Modular (feature-based)', value: 'modular', description: 'features/auth, features/dashboard...' },
+  ],
+  packageManager: [
+    { title: 'npm', value: 'npm' },
+    { title: 'pnpm', value: 'pnpm', description: 'Fast, disk-efficient' },
+    { title: 'yarn', value: 'yarn', description: 'Classic v1 (stable)' },
+  ],
+  addons: [
+    { title: 'TanStack Query (data fetching)', value: 'tanstack-query', selected: true },
+    { title: 'Axios + interceptors wrapper', value: 'axios', selected: true },
+    { title: 'react-hook-form + zod', value: 'forms', selected: true },
+    { title: 'react-hot-toast (toasts)', value: 'toast', selected: true },
+    { title: 'Vitest + RTL (testing)', value: 'testing', selected: false },
+    { title: 'ESLint + Prettier', value: 'lint', selected: true },
+    { title: 'Custom hooks library (useDebounce, useThrottle, etc.)', value: 'hooks', selected: true },
+    { title: 'Auth boilerplate (JWT + refresh)', value: 'auth', selected: false },
+  ],
+};
+
+// All 16 combos: vite|next × ts|js × zustand|redux × shadcn|mui
+export const SUPPORTED_COMBOS = new Set([
+  'vite-ts-zustand-shadcn',
+  'vite-ts-zustand-mui',
+  'vite-ts-redux-shadcn',
+  'vite-ts-redux-mui',
+  'vite-js-zustand-shadcn',
+  'vite-js-zustand-mui',
+  'vite-js-redux-shadcn',
+  'vite-js-redux-mui',
+  'next-ts-zustand-shadcn',
+  'next-ts-zustand-mui',
+  'next-ts-redux-shadcn',
+  'next-ts-redux-mui',
+  'next-js-zustand-shadcn',
+  'next-js-zustand-mui',
+  'next-js-redux-shadcn',
+  'next-js-redux-mui',
+]);
+
+export const FALLBACK_MAP = {};

package/src/generator.js

@@ -0,0 +1,133 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import fs from 'fs-extra';
+import ora from 'ora';
+import chalk from 'chalk';
+import { execa } from 'execa';
+import { SUPPORTED_COMBOS, FALLBACK_MAP, ENGINES_NODE_RANGE } from './choices.js';
+import { logger } from './utils.js';
+import { applyAddons } from './injectors/addons.js';
+import { applyStructure } from './injectors/structure.js';
+import { getInstallCommand, getPackageManagerField } from './pm.js';
+
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.resolve(__dirname, '..', 'templates');
+
+export async function generateProject(opts) {
+  const {
+    projectName,
+    targetDir,
+    templateKey,
+    framework,
+    state,
+    ui,
+    structure,
+    addons = [],
+    initGit,
+    skipInstall,
+    skipGit,
+    packageManager = 'npm',
+  } = opts;
+
+  // 1. Resolve template (with fallback)
+  const resolvedTemplate = resolveTemplate(templateKey);
+  if (resolvedTemplate.fallback) {
+    logger.warn(
+      `Combo "${templateKey}" not directly supported. Using "${resolvedTemplate.key}" as base and patching diff.`
+    );
+  }
+
+  const templatePath = path.join(TEMPLATES_DIR, resolvedTemplate.key);
+  if (!fs.existsSync(templatePath)) {
+    throw new Error(
+      `Template not found at ${templatePath}. Did you forget to scaffold it?`
+    );
+  }
+
+  // 2. Copy template
+  const copySpinner = ora('Copying template files...').start();
+  try {
+    await fs.ensureDir(targetDir);
+    await fs.copy(templatePath, targetDir, {
+      filter: (src) => !src.includes('node_modules') && !src.endsWith('.lock'),
+    });
+    copySpinner.succeed('Template files copied');
+  } catch (err) {
+    copySpinner.fail('Copy failed');
+    throw err;
+  }
+
+  // 3. Patch package.json with project name
+  await patchPackageJson(targetDir, projectName, packageManager);
+
+  // 3a. Write .nvmrc for Node version pinning
+  await fs.outputFile(path.join(targetDir, '.nvmrc'), `${`PINNED_NODE_VERSION`}\n`)
+
+  // 4. Apply structure (atomic vs modular folder layout)
+  await applyStructure({ targetDir, framework, structure });
+
+  // 5. Apply add-ons (axios, query, forms, etc.)
+  await applyAddons({ targetDir, framework, state, ui, addons });
+
+  // 6. If fallback was used, swap UI / state
+  if (resolvedTemplate.fallback) {
+    logger.info(chalk.dim('  ↳ Patching UI/state diff...'));
+    // Hook for diff-patcher; stubbed for now
+  }
+
+  // 7. Install
+  if (!skipInstall) {
+    const installSpinner = ora('Installing dependencies (this may take a minute)...').start();
+    try {
+      await execa('npm', ['install'], { cwd: targetDir });
+      installSpinner.succeed('Dependencies installed');
+    } catch (err) {
+      installSpinner.fail(
+        `${packageManager} install failed — you can run it manually`
+      );
+      logger.warn(err.shortMessage || err.message);
+    }
+  }
+
+  // 8. Git init
+  if (initGit && !skipGit) {
+    const gitSpinner = ora('Initializing git repository...').start();
+    try {
+      await execa('git', ['init'], { cwd: targetDir });
+      await execa('git', ['add', '.'], { cwd: targetDir });
+      await execa(
+        'git',
+        ['commit', '-m', 'chore: initial commit from create-stackit'],
+        { cwd: targetDir }
+      );
+      gitSpinner.succeed('Git repository initialized');
+    } catch (err) {
+      gitSpinner.warn('Git init skipped (git not available or failed)');
+    }
+  }
+}
+
+function resolveTemplate(templateKey) {
+  if (SUPPORTED_COMBOS.has(templateKey)) {
+    return { key: templateKey, fallback: false };
+  }
+  const fallbackKey = FALLBACK_MAP[templateKey];
+  if (fallbackKey) {
+    return { key: fallbackKey, fallback: true };
+  }
+  throw new Error(
+    `Unsupported combination: ${templateKey}. Supported: ${[...SUPPORTED_COMBOS].join(', ')}`
+  );
+}
+
+async function patchPackageJson(targetDir, projectName, packageManager) {
+  const pkgPath = path.join(targetDir, 'package.json');
+  if (!fs.existsSync(pkgPath)) return;
+  const pkg = await fs.readJson(pkgPath);
+  pkg.name = projectName;
+  pkg.version = '0.1.0';
+  pkg.engines = { ...(pkg.engines || {}), node: ENGINES_NODE_RANGE };
+  pkg.packageManager = getPackageManagerField(packageManager);
+  await fs.writeJson(pkgPath, pkg, { spaces: 2 });
+}