create-stackit 0.1.0

package/src/injectors/addons.js

@@ -0,0 +1,311 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { logger } from '../utils.js';
+
+/**
+ * Each addon is a self-contained injector. Register it in ADDON_REGISTRY.
+ * An injector receives { targetDir, framework, state, ui, pkg } and mutates pkg
+ * (returns updated pkg) and writes any files it needs.
+ */
+
+const ADDON_REGISTRY = {
+  'tanstack-query': injectTanstackQuery,
+  axios: injectAxios,
+  forms: injectForms,
+  toast: injectToast,
+  testing: injectTesting,
+  lint: injectLint,
+  hooks: injectHooks,
+  auth: injectAuth,
+};
+
+export async function applyAddons({ targetDir, framework, state, ui, addons }) {
+  if (!addons || addons.length === 0) return;
+
+  const pkgPath = path.join(targetDir, 'package.json');
+  let pkg = await fs.readJson(pkgPath);
+
+  for (const addon of addons) {
+    const fn = ADDON_REGISTRY[addon];
+    if (!fn) {
+      logger.warn(`  ↳ Unknown addon: ${addon}, skipping`);
+      continue;
+    }
+    pkg = (await fn({ targetDir, framework, state, ui, pkg })) || pkg;
+    logger.dim(`  ✓ injected: ${addon}`);
+  }
+
+  await fs.writeJson(pkgPath, pkg, { spaces: 2 });
+}
+
+// ───────────────────────────────────────────────
+// Injectors
+// ───────────────────────────────────────────────
+
+async function injectTanstackQuery({ targetDir, pkg }) {
+  pkg.dependencies = {
+    ...pkg.dependencies,
+    '@tanstack/react-query': '^5.59.0',
+    '@tanstack/react-query-devtools': '^5.59.0',
+  };
+
+  const file = path.join(targetDir, 'src/lib/react-query.ts');
+  await fs.outputFile(
+    file,
+    `import { QueryClient } from '@tanstack/react-query';
+
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      retry: 1,
+      refetchOnWindowFocus: false,
+      staleTime: 60_000,
+    },
+  },
+});
+`
+  );
+
+  await fs.outputFile(
+    path.join(targetDir, 'src/hooks/api/useApiQuery.ts'),
+    `import { useQuery, type UseQueryOptions, type QueryKey } from '@tanstack/react-query';
+
+export function useApiQuery<TData = unknown, TError = Error>(
+  key: QueryKey,
+  fn: () => Promise<TData>,
+  options?: Omit<UseQueryOptions<TData, TError>, 'queryKey' | 'queryFn'>
+) {
+  return useQuery<TData, TError>({
+    queryKey: key,
+    queryFn: fn,
+    ...options,
+  });
+}
+`
+  );
+
+  await fs.outputFile(
+    path.join(targetDir, 'src/hooks/api/useApiMutation.ts'),
+    `import { useMutation, type UseMutationOptions } from '@tanstack/react-query';
+
+export function useApiMutation<TData = unknown, TVariables = void, TError = Error>(
+  fn: (vars: TVariables) => Promise<TData>,
+  options?: Omit<UseMutationOptions<TData, TError, TVariables>, 'mutationFn'>
+) {
+  return useMutation<TData, TError, TVariables>({
+    mutationFn: fn,
+    ...options,
+  });
+}
+`
+  );
+
+  return pkg;
+}
+
+async function injectAxios({ targetDir, pkg }) {
+  pkg.dependencies = { ...pkg.dependencies, axios: '^1.7.7' };
+
+  await fs.outputFile(
+    path.join(targetDir, 'src/lib/api-client.ts'),
+    `import axios, { AxiosError } from 'axios';
+
+const baseURL =
+  (typeof import.meta !== 'undefined' && (import.meta as any).env?.VITE_API_URL) ||
+  process.env.NEXT_PUBLIC_API_URL ||
+  '/api';
+
+export const api = axios.create({
+  baseURL,
+  withCredentials: true,
+  timeout: 30_000,
+});
+
+api.interceptors.request.use((config) => {
+  const token =
+    typeof window !== 'undefined' ? window.localStorage.getItem('token') : null;
+  if (token) config.headers.Authorization = \`Bearer \${token}\`;
+  return config;
+});
+
+api.interceptors.response.use(
+  (res) => res,
+  (error: AxiosError<{ message?: string }>) => {
+    const message =
+      error.response?.data?.message ||
+      error.message ||
+      'Something went wrong';
+
+    if (typeof window !== 'undefined') {
+      window.dispatchEvent(new CustomEvent('api-error', { detail: message }));
+    }
+    return Promise.reject(error);
+  }
+);
+`
+  );
+  return pkg;
+}
+
+async function injectForms({ pkg }) {
+  pkg.dependencies = {
+    ...pkg.dependencies,
+    'react-hook-form': '^7.53.0',
+    zod: '^3.23.8',
+    '@hookform/resolvers': '^3.9.0',
+  };
+  return pkg;
+}
+
+async function injectToast({ targetDir, pkg }) {
+  pkg.dependencies = { ...pkg.dependencies, 'react-hot-toast': '^2.4.1' };
+
+  await fs.outputFile(
+    path.join(targetDir, 'src/components/ui/AppToaster.tsx'),
+    `import { useEffect } from 'react';
+import { Toaster, toast } from 'react-hot-toast';
+
+export function AppToaster() {
+  useEffect(() => {
+    const onApiError = (e: Event) => {
+      const detail = (e as CustomEvent<string>).detail;
+      toast.error(detail || 'Something went wrong');
+    };
+    window.addEventListener('api-error', onApiError);
+    return () => window.removeEventListener('api-error', onApiError);
+  }, []);
+
+  return <Toaster position="top-right" />;
+}
+`
+  );
+  return pkg;
+}
+
+async function injectTesting({ pkg }) {
+  pkg.devDependencies = {
+    ...pkg.devDependencies,
+    vitest: '^2.1.1',
+    '@testing-library/react': '^16.0.1',
+    '@testing-library/jest-dom': '^6.5.0',
+    '@testing-library/user-event': '^14.5.2',
+    jsdom: '^25.0.1',
+  };
+  pkg.scripts = {
+    ...pkg.scripts,
+    test: 'vitest',
+    'test:ui': 'vitest --ui',
+  };
+  return pkg;
+}
+
+async function injectLint({ pkg }) {
+  pkg.devDependencies = {
+    ...pkg.devDependencies,
+    eslint: '^9.12.0',
+    prettier: '^3.3.3',
+    'eslint-config-prettier': '^9.1.0',
+  };
+  pkg.scripts = {
+    ...pkg.scripts,
+    lint: 'eslint .',
+    format: 'prettier --write .',
+  };
+  return pkg;
+}
+
+async function injectHooks({ targetDir }) {
+  // Just write the hook files; no deps needed.
+  const hooksDir = path.join(targetDir, 'src/hooks/core');
+  await fs.outputFile(
+    path.join(hooksDir, 'useDebounce.ts'),
+    `import { useEffect, useState } from 'react';
+
+export function useDebounce<T>(value: T, delay = 500): T {
+  const [debounced, setDebounced] = useState(value);
+  useEffect(() => {
+    const t = setTimeout(() => setDebounced(value), delay);
+    return () => clearTimeout(t);
+  }, [value, delay]);
+  return debounced;
+}
+`
+  );
+
+  await fs.outputFile(
+    path.join(hooksDir, 'useThrottle.ts'),
+    `import { useCallback, useRef } from 'react';
+
+export function useThrottle<TArgs extends unknown[]>(
+  fn: (...args: TArgs) => void,
+  delay = 300
+) {
+  const last = useRef(0);
+  return useCallback(
+    (...args: TArgs) => {
+      const now = Date.now();
+      if (now - last.current >= delay) {
+        last.current = now;
+        fn(...args);
+      }
+    },
+    [fn, delay]
+  );
+}
+`
+  );
+
+  await fs.outputFile(
+    path.join(hooksDir, 'useToggle.ts'),
+    `import { useCallback, useState } from 'react';
+
+export function useToggle(initial = false) {
+  const [value, setValue] = useState(initial);
+  const toggle = useCallback(() => setValue((v) => !v), []);
+  return [value, toggle, setValue] as const;
+}
+`
+  );
+
+  await fs.outputFile(
+    path.join(hooksDir, 'usePrevious.ts'),
+    `import { useEffect, useRef } from 'react';
+
+export function usePrevious<T>(value: T): T | undefined {
+  const ref = useRef<T | undefined>(undefined);
+  useEffect(() => {
+    ref.current = value;
+  }, [value]);
+  return ref.current;
+}
+`
+  );
+
+  await fs.outputFile(
+    path.join(targetDir, 'src/hooks/data/normalize.ts'),
+    `export function normalizeArray<T extends Record<string, any>>(
+  arr: T[],
+  key: keyof T = 'id' as keyof T
+): Record<string, T> {
+  return arr.reduce<Record<string, T>>((acc, item) => {
+    acc[String(item[key])] = item;
+    return acc;
+  }, {});
+}
+`
+  );
+}
+
+async function injectAuth({ targetDir, pkg }) {
+  // Stub — real implementation depends on chosen state lib.
+  // Leaving a placeholder file so the user has a starting point.
+  await fs.outputFile(
+    path.join(targetDir, 'src/features/auth/README.md'),
+    `# Auth feature
+
+This is a scaffolded auth module. Wire up your endpoints in \`api/\`,
+state in \`store/\`, and protected routes per your framework.
+`
+  );
+  return pkg;
+}

package/src/injectors/structure.js

@@ -0,0 +1,51 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+
+/**
+ * Templates ship with `modular` structure by default.
+ * If user picks `atomic`, we restructure components/ into atoms/molecules/organisms.
+ * Otherwise we just ensure the modular skeleton exists.
+ */
+export async function applyStructure({ targetDir, framework, structure }) {
+  const srcDir = path.join(targetDir, 'src');
+
+  if (structure === 'atomic') {
+    const atomicBase = path.join(srcDir, 'components');
+    await fs.ensureDir(path.join(atomicBase, 'atoms'));
+    await fs.ensureDir(path.join(atomicBase, 'molecules'));
+    await fs.ensureDir(path.join(atomicBase, 'organisms'));
+    await fs.ensureDir(path.join(atomicBase, 'templates'));
+    await fs.outputFile(
+      path.join(atomicBase, 'README.md'),
+      `# Atomic structure
+
+- \`atoms/\` — smallest building blocks (Button, Input, Label)
+- \`molecules/\` — small groupings (SearchBar = Input + Button)
+- \`organisms/\` — complex sections (Header, ProductList)
+- \`templates/\` — page-level layouts (no real data)
+`
+    );
+    return;
+  }
+
+  // modular (default)
+  await fs.ensureDir(path.join(srcDir, 'features'));
+  await fs.ensureDir(path.join(srcDir, 'components/ui'));
+  await fs.ensureDir(path.join(srcDir, 'components/shared'));
+  await fs.outputFile(
+    path.join(srcDir, 'features/README.md'),
+    `# Feature modules
+
+Each feature is self-contained:
+
+\`\`\`
+features/auth/
+  api/         — service calls
+  components/  — feature-only components
+  hooks/       — feature-only hooks
+  store/       — feature state slice
+  types.ts
+\`\`\`
+`
+  );
+}

package/src/pm.js

@@ -0,0 +1,94 @@
+/**
+ * Package manager detection + helpers.
+ *
+ * Detection logic mirrors what create-vite / create-next-app do:
+ * read process.env.npm_config_user_agent which looks like:
+ *   "npm/10.5.0 node/v20.11.0 darwin x64"
+ *   "yarn/1.22.22 npm/? node/v20.11.0 darwin x64"
+ *   "pnpm/9.12.0 npm/? node/v20.11.0 darwin x64"
+ *
+ * This is set by whichever PM invoked the CLI (e.g. `pnpm create stackit`).
+ */
+
+export const SUPPORTED_PMS = ['npm', 'yarn', 'pnpm'];
+
+/**
+ * Detect the PM that invoked this CLI. Returns null if not detected
+ * or if the detected PM isn't in our supported list.
+ */
+export function detectPackageManager() {
+  const userAgent = process.env.npm_config_user_agent;
+  if (!userAgent) return null;
+
+  // Take just the first token: "pnpm/9.12.0" → "pnpm"
+  const name = userAgent.split(' ')[0]?.split('/')[0];
+  if (!name) return null;
+
+  return SUPPORTED_PMS.includes(name) ? name : null;
+}
+
+/**
+ * Get install args for a given PM. All three accept bare invocation
+ * but we pass the explicit subcommand for clarity in logs.
+ */
+export function getInstallCommand(pm) {
+  switch (pm) {
+    case 'yarn':
+      return { cmd: 'yarn', args: [] }; // yarn alone = install
+    case 'pnpm':
+      return { cmd: 'pnpm', args: ['install'] };
+    case 'npm':
+    default:
+      return { cmd: 'npm', args: ['install'] };
+  }
+}
+
+/**
+ * Get the user-facing run command for a script.
+ * e.g. runScript('pnpm', 'dev') → 'pnpm dev'
+ *      runScript('npm', 'dev')  → 'npm run dev'
+ */
+export function runScript(pm, script) {
+  switch (pm) {
+    case 'yarn':
+      return `yarn ${script}`;
+    case 'pnpm':
+      return `pnpm ${script}`;
+    case 'npm':
+    default:
+      return `npm run ${script}`;
+  }
+}
+
+/**
+ * Get the install command as a single user-facing string,
+ * for README and "next steps" messaging.
+ */
+export function installCommandString(pm) {
+  switch (pm) {
+    case 'yarn':
+      return 'yarn';
+    case 'pnpm':
+      return 'pnpm install';
+    case 'npm':
+    default:
+      return 'npm install';
+  }
+}
+
+/**
+ * The packageManager field value for package.json.
+ * Used by Corepack to enforce PM consistency across a team.
+ * Versions are minimums; users can bump as needed.
+ */
+export function getPackageManagerField(pm) {
+  switch (pm) {
+    case 'yarn':
+      return 'yarn@1.22.22';
+    case 'pnpm':
+      return 'pnpm@9.12.0';
+    case 'npm':
+    default:
+      return 'npm@10.8.0';
+  }
+}

package/src/prompts.js

@@ -0,0 +1,179 @@
+import prompts from 'prompts';
+import path from 'node:path';
+import fs from 'fs-extra';
+import validateProjectName from 'validate-npm-package-name';
+import chalk from 'chalk';
+import { CHOICES } from './choices.js';
+import {SUPPORTED_PMS, detectPackageManager} from './pm.js'
+import {logger} from './utils.js'
+
+const onCancel = () => {
+  const err = new Error('User cancelled');
+  err.isCancelled = true;
+  throw err;
+};
+
+function validateName(name) {
+  if (!name || !name.trim()) return 'Project name is required';
+  const result = validateProjectName(name);
+  if (!result.validForNewPackages) {
+    const issues = [...(result.errors || []), ...(result.warnings || [])];
+    return issues.join(', ') || 'Invalid project name';
+  }
+  return true;
+}
+
+async function confirmOverwrite(targetDir) {
+  if (!fs.existsSync(targetDir)) return true;
+  const files = fs.readdirSync(targetDir);
+  if (files.length === 0) return true;
+
+  const { overwrite } = await prompts(
+    {
+      type: 'confirm',
+      name: 'overwrite',
+      message: chalk.yellow(
+        `Directory "${path.basename(targetDir)}" is not empty. Overwrite?`
+      ),
+      initial: false,
+    },
+    { onCancel }
+  );
+
+  return overwrite;
+}
+
+export async function runPrompts(initial) {
+  const questions = [];
+
+  if (!initial.projectName) {
+    questions.push({
+      type: 'text',
+      name: 'projectName',
+      message: 'Project name:',
+      initial: 'my-stackit-app',
+      validate: validateName,
+    });
+  }
+
+  if (!initial.framework) {
+    questions.push({
+      type: 'select',
+      name: 'framework',
+      message: 'Framework?',
+      choices: CHOICES.framework,
+      initial: 0,
+    });
+  }
+
+  if (!initial.language) {
+    questions.push({
+      type: 'select',
+      name: 'language',
+      message: 'Language?',
+      choices: CHOICES.language,
+      initial: 0,
+    });
+  }
+
+  if (!initial.state) {
+    questions.push({
+      type: 'select',
+      name: 'state',
+      message: 'State management?',
+      choices: CHOICES.state,
+      initial: 0,
+    });
+  }
+
+  if (!initial.ui) {
+    questions.push({
+      type: 'select',
+      name: 'ui',
+      message: 'UI library?',
+      choices: CHOICES.ui,
+      initial: 0,
+    });
+  }
+
+  if (!initial.structure) {
+    questions.push({
+      type: 'select',
+      name: 'structure',
+      message: 'Folder structure?',
+      choices: CHOICES.structure,
+      initial: 1, // modular default — better for real apps
+    });
+  }
+
+
+  let resolvedPm = null;
+  let pmSource = null;
+
+  if(initial.packageManager){
+    if(!SUPPORTED_PMS.includes(initial.packageManager)){
+      throw new Error(
+        `Unsupported package manager: "${initial.packageManager}". ` +
+          `Supported: ${SUPPORTED_PMS.join(', ')}`
+      )
+    }
+    resolvedPm = initial.packageManager;
+    pmSource = 'flag'
+  }else{
+    const detected = detectPackageManager();
+    if(detected){
+      resolvedPm= detected;
+      pmSource='detected';
+      logger.dim(`  ↳ detected package manager: ${chalk.cyan(detected)}`);
+    }else{
+      questions.push({
+        type: 'select',
+        name: 'packageManager',
+        message: 'Package Manager',
+        choices: CHOICES.packageManager,
+      })
+    }
+  }
+
+  // Always-asked toggles
+  questions.push(
+    {
+      type: 'multiselect',
+      name: 'addons',
+      message: 'Pick add-ons (space to toggle, enter to confirm):',
+      choices: CHOICES.addons,
+      hint: '- Space to select, Enter to submit',
+      instructions: false,
+    },
+    {
+      type: 'confirm',
+      name: 'initGit',
+      message: 'Initialize a git repository?',
+      initial: true,
+    }
+  );
+
+  const answered = await prompts(questions, { onCancel });
+  const finalAnswers = { ...initial, ...answered };
+
+  // Validate even if name came from CLI
+  const nameCheck = validateName(finalAnswers.projectName);
+  if (nameCheck !== true) {
+    throw new Error(`Invalid project name: ${nameCheck}`);
+  }
+
+  // Compute target dir + overwrite confirmation
+  const targetDir = path.resolve(process.cwd(), finalAnswers.projectName);
+  const ok = await confirmOverwrite(targetDir);
+  if (!ok) onCancel();
+
+  return {
+    ...finalAnswers,
+    targetDir,
+    templateKey: buildTemplateKey(finalAnswers),
+  };
+}
+
+function buildTemplateKey({ framework, language, state, ui }) {
+  return `${framework}-${language ?? 'ts'}-${state}-${ui}`;
+}

package/src/utils.js

@@ -0,0 +1,18 @@
+import chalk from 'chalk';
+
+export const logger = {
+  info: (msg) => console.log(chalk.cyan(msg)),
+  success: (msg) => console.log(chalk.green(msg)),
+  warn: (msg) => console.log(chalk.yellow(msg)),
+  error: (msg) => console.log(chalk.red(msg)),
+  dim: (msg) => console.log(chalk.dim(msg)),
+};
+
+export function printBanner() {
+  console.log();
+  console.log(chalk.bold.magenta('  ╭───────────────────────────────╮'));
+  console.log(chalk.bold.magenta('  │  ') + chalk.bold.white('create-stackit') + chalk.bold.magenta('  v0.1.0       │'));
+  console.log(chalk.bold.magenta('  │  ') + chalk.dim('pragmatic react starters    ') + chalk.bold.magenta('│'));
+  console.log(chalk.bold.magenta('  ╰───────────────────────────────╯'));
+  console.log();
+}

package/templates/next-js-redux-mui/README.md

@@ -0,0 +1,15 @@
+# {{PROJECT_NAME}}
+
+Generated with [create-stackit](https://github.com/your-handle/create-stackit).
+
+## Stack
+- Next.js + JavaScript
+- Redux Toolkit
+- Material UI
+
+## Scripts
+```bash
+npm run dev      # start dev server
+npm run build    # production build
+npm run start    # start production server
+```

package/templates/next-js-redux-mui/app/layout.jsx

@@ -0,0 +1,12 @@
+import React from 'react'
+import { Providers } from './providers'
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  )
+}

package/templates/next-js-redux-mui/app/page.jsx

@@ -0,0 +1,15 @@
+'use client'
+import { useDispatch, useSelector } from 'react-redux'
+import { increment } from '../src/store/counterSlice'
+
+export default function Home() {
+  const count = useSelector((state) => state.counter.value)
+  const dispatch = useDispatch()
+  return (
+    <main>
+      <h1>create-stackit</h1>
+      <p>Count: {count}</p>
+      <button onClick={() => dispatch(increment())}>Increment</button>
+    </main>
+  )
+}