create-lumen 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+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,115 @@
+# create-lumen
+
+Scaffold a React + Vite project with your choice of **feature-based** or **component-based** architecture.
+
+```bash
+npm create lumen
+```
+
+## What it does
+
+Creates a production-ready React + Vite project with:
+
+- **Architecture choice** — feature-based (domain-driven) or component-based (grouped by type)
+- **TypeScript or JavaScript**
+- **CSS framework** — Tailwind CSS, Bootstrap, or vanilla CSS
+- **State management** — Zustand, Redux Toolkit, or none
+- **React Router** — client-side routing (optional)
+- **Testing** — Vitest or Jest (optional)
+- **Linter** — ESLint (default) or Oxlint
+- **Icon library** — Lucide React, Huge Icons, or none
+- **Axios** — pre-configured HTTP client (optional)
+- **README + LICENSE** — auto-generated (MIT)
+- **Git init** — auto-initialize a git repo
+- **Path alias** — `@/` imports configured out of the box
+
+Your choices are cached and used as defaults next time.
+
+## Quick start
+
+### From npm (recommended)
+
+```bash
+npm create lumen my-app
+cd my-app
+npm run dev
+```
+
+### From this repo
+
+```bash
+git clone https://github.com/Its-JrDev/create-lumen.git
+cd create-lumen
+npm install
+npm link
+npx create-lumen my-app
+cd my-app
+npm run dev
+```
+
+### Quick setup defaults
+
+TypeScript · Tailwind CSS · Feature-based · Router · ESLint · Vitest
+
+## Architecture
+
+### Feature-based
+
+Organized by domain. Each feature is self-contained:
+
+```
+src/
+├── app/              # App root
+├── features/
+│   └── home/
+│       ├── pages/
+│       ├── components/
+│       └── services/
+├── layouts/
+├── pages/
+├── routes/
+├── store/
+├── hooks/
+└── utils/
+```
+
+Scaffold new features instantly:
+
+```bash
+npm run create:feature auth
+```
+
+### Component-based
+
+Organized by type. Components grouped by their role:
+
+```
+src/
+├── components/
+│   ├── common/       # Shared, reusable
+│   ├── form/         # Form elements
+│   └── layout/       # Layout primitives
+├── pages/
+├── layouts/
+├── routes/
+├── store/
+├── hooks/
+└── utils/
+```
+
+## Path alias
+
+All projects use the `@/` path alias:
+
+```tsx
+import { Button } from "@/components/common/Button";
+import { useAuth } from "@/hooks/useAuth";
+```
+
+## Requirements
+
+- Node.js >= 18
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+import { main } from "../src/main.js";
+import chalk from "chalk";
+
+console.log(
+  chalk.bold.cyan("\n  ✦ LUMEN") +
+    chalk.gray(" v1.0.0") +
+    chalk.gray(
+      "\n  Scaffold a React + Vite project with architecture choice\n"
+    )
+);
+
+main().catch((e) => {
+  console.error(chalk.red("\nError:"), e.message || e);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "create-lumen",
+  "version": "1.0.0",
+  "description": "Scaffold a React + Vite project with architecture choice: feature-based or component-based.",
+  "type": "module",
+  "bin": {
+    "create-lumen": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "scaffold",
+    "create",
+    "cli",
+    "vite",
+    "react",
+    "typescript",
+    "feature-based",
+    "component-based",
+    "architecture",
+    "starter",
+    "boilerplate"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "chalk": "^5.6.2",
+    "execa": "^9.6.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/cleanup.js

@@ -0,0 +1,7 @@
+import { deleteIfExists } from "./utils/fs.js";
+
+export async function cleanupBoilerplate(projectPath) {
+  await deleteIfExists(`${projectPath}/public`);
+  await deleteIfExists(`${projectPath}/src/assets`);
+  await deleteIfExists(`${projectPath}/.oxlintrc.json`);
+}

package/src/config-cache.js

@@ -0,0 +1,27 @@
+import { access, readFile, writeFile } from "fs/promises";
+import os from "os";
+import path from "path";
+
+const CONFIG_PATH = path.join(os.homedir(), ".lumen-config.json");
+
+export async function configExists() {
+  try {
+    await access(CONFIG_PATH);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function loadConfig() {
+  try {
+    const content = await readFile(CONFIG_PATH, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return {};
+  }
+}
+
+export async function saveConfig(data) {
+  await writeFile(CONFIG_PATH, JSON.stringify(data, null, 2), "utf-8");
+}

package/src/configure.js

@@ -0,0 +1,161 @@
+import { promises as fsp } from "fs";
+import path from "path";
+import { readFileContent } from "./utils/fs.js";
+
+export async function configureProject(projectPath, language, cssFramework) {
+  const ext = language === "ts" ? "ts" : "js";
+
+  // Set up tsconfig/jsconfig with @/* paths
+  if (language === "ts") {
+    await configureTsconfig(projectPath);
+  } else {
+    await configureJsconfig(projectPath);
+  }
+
+  // Add tsconfigPaths: true to vite.config for non-tailwind setups
+  if (cssFramework !== "tailwind") {
+    await addTsconfigPathsToViteConfig(projectPath, ext);
+  }
+
+  // Add scripts to package.json
+  await configurePackageJson(projectPath);
+}
+
+async function configureTsconfig(projectPath) {
+  // Create/update tsconfig.app.json with paths
+  const tsconfigAppPath = path.join(projectPath, "tsconfig.app.json");
+  try {
+    const content = await readFileContent(tsconfigAppPath);
+    const config = JSON.parse(content);
+
+    if (!config.compilerOptions) config.compilerOptions = {};
+    config.compilerOptions.baseUrl = ".";
+    config.compilerOptions.paths = {
+      "@/*": ["./src/*"],
+    };
+
+    await fsp.writeFile(
+      tsconfigAppPath,
+      JSON.stringify(config, null, 2) + "\n",
+      "utf8"
+    );
+  } catch {
+    // Create tsconfig.app.json if it doesn't exist
+    const config = {
+      compilerOptions: {
+        target: "ES2020",
+        useDefineForClassFields: true,
+        lib: ["ES2020", "DOM", "DOM.Iterable"],
+        module: "ESNext",
+        skipLibCheck: true,
+        moduleResolution: "bundler",
+        allowImportingTsExtensions: true,
+        resolveJsonModule: true,
+        isolatedModules: true,
+        noEmit: true,
+        jsx: "react-jsx",
+        strict: true,
+        noUnusedLocals: true,
+        noUnusedParameters: true,
+        noFallthroughCasesInSwitch: true,
+        baseUrl: ".",
+        paths: {
+          "@/*": ["./src/*"],
+        },
+      },
+      include: ["src"],
+    };
+    await fsp.writeFile(
+      tsconfigAppPath,
+      JSON.stringify(config, null, 2) + "\n",
+      "utf8"
+    );
+  }
+
+  // Create/update root tsconfig.json with references
+  const rootTsconfigPath = path.join(projectPath, "tsconfig.json");
+  const rootTsconfig = {
+    files: [],
+    references: [{ path: "./tsconfig.app.json" }],
+  };
+  await fsp.writeFile(
+    rootTsconfigPath,
+    JSON.stringify(rootTsconfig, null, 2) + "\n",
+    "utf8"
+  );
+}
+
+async function configureJsconfig(projectPath) {
+  const jsconfigPath = path.join(projectPath, "jsconfig.json");
+  const config = {
+    compilerOptions: {
+      baseUrl: ".",
+      paths: {
+        "@/*": ["./src/*"],
+      },
+    },
+    include: ["src"],
+  };
+  await fsp.writeFile(jsconfigPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+}
+
+async function addTsconfigPathsToViteConfig(projectPath, ext) {
+  const viteConfigPath = path.join(projectPath, `vite.config.${ext}`);
+  try {
+    let content = await readFileContent(viteConfigPath);
+
+    if (content.includes("tsconfigPaths")) return;
+
+    const lines = content.split("\n");
+
+    // Find where imports end (last import line index)
+    let lastImportIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+      if (lines[i].startsWith("import ")) lastImportIdx = i;
+    }
+
+    // Insert path/fileURLToPath imports after last import
+    const newImports = [
+      'import path from "path";',
+      'import { fileURLToPath } from "url";',
+      "const __dirname = path.dirname(fileURLToPath(import.meta.url));",
+    ];
+    lines.splice(lastImportIdx + 1, 0, ...newImports);
+
+    let result = lines.join("\n");
+
+    if (result.includes("resolve:")) {
+      result = result.replace(
+        /resolve:\s*\{/,
+        'resolve: {\n    tsconfigPaths: true,\n    alias: [{ find: "@", replacement: path.resolve(__dirname, "src") }],'
+      );
+    } else {
+      result = result.replace(
+        /defineConfig\(\{/,
+        'defineConfig({\n  resolve: {\n    tsconfigPaths: true,\n    alias: [{ find: "@", replacement: path.resolve(__dirname, "src") }],\n  },'
+      );
+    }
+
+    await fsp.writeFile(viteConfigPath, result, "utf8");
+  } catch {
+    // file doesn't exist, skip
+  }
+}
+
+async function configurePackageJson(projectPath) {
+  const pkgPath = path.join(projectPath, "package.json");
+  try {
+    const content = await readFileContent(pkgPath);
+    const pkg = JSON.parse(content);
+
+    if (!pkg.scripts) pkg.scripts = {};
+
+    pkg.scripts.dev = "vite";
+    pkg.scripts.build = "vite build";
+    pkg.scripts.preview = "vite preview";
+
+    await fsp.writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
+  } catch {
+    // file doesn't exist, skip
+  }
+}

package/src/confirm-empty-folder.js

@@ -0,0 +1,45 @@
+import { isCancel, select } from "@clack/prompts";
+import { access, mkdir, readdir, rm } from "fs/promises";
+import path from "path";
+import { onCancel } from "./prompts.js";
+
+export async function confirmEmptyFolder(projectName) {
+  const cwd = process.cwd();
+  const targetPath = path.resolve(cwd, projectName || "");
+
+  try {
+    await access(targetPath);
+  } catch {
+    return targetPath;
+  }
+
+  const files = await readdir(targetPath);
+  if (files.length === 0) return targetPath;
+
+  const remove = await select({
+    message: `Folder "${projectName}" already exists and is not empty. How would you like to proceed?`,
+    options: [
+      { label: "Delete all files and continue", value: true },
+      { label: "Cancel setup", value: false },
+    ],
+    initialValue: true,
+  });
+
+  if (isCancel(remove) || !remove) {
+    onCancel();
+  }
+
+  if (targetPath === cwd) {
+    const inside = await readdir(targetPath);
+    await Promise.all(
+      inside.map((name) =>
+        rm(path.join(targetPath, name), { recursive: true, force: true })
+      )
+    );
+  } else {
+    await rm(targetPath, { recursive: true, force: true });
+    await mkdir(targetPath);
+  }
+
+  return targetPath;
+}

package/src/css.js

@@ -0,0 +1,59 @@
+import fs from "fs";
+import { promises as fsp } from "fs";
+import path from "path";
+import { deleteIfExists } from "./utils/fs.js";
+
+export async function setupCssFramework({
+  projectPath,
+  templatesDir,
+  language,
+  cssFramework,
+  ext,
+  pkg,
+}) {
+  process.chdir(projectPath);
+  const cssDir = path.join(templatesDir, "css");
+  const indexCssPath = path.join(projectPath, "src", "index.css");
+
+  if (cssFramework === "tailwind") {
+    const viteConfigFile = `vite.config.${language === "ts" ? "ts" : "js"}`;
+    const viteConfigTarget = path.join(projectPath, viteConfigFile);
+    const viteConfigContent = await fsp.readFile(
+      path.join(cssDir, "tailwind", viteConfigFile),
+      "utf8"
+    );
+    await fsp.writeFile(viteConfigTarget, viteConfigContent, "utf8");
+
+    const indexCssContent = await fsp.readFile(
+      path.join(cssDir, "tailwind", "src", "index.css"),
+      "utf8"
+    );
+    await fsp.writeFile(indexCssPath, indexCssContent, "utf8");
+  } else if (cssFramework === "bootstrap") {
+    const mainFile = path.join(projectPath, "src", `main.${ext}`);
+    if (fs.existsSync(mainFile)) {
+      let mainContent = await fsp.readFile(mainFile, "utf8");
+      if (
+        !mainContent.includes("bootstrap/dist/css/bootstrap.min.css")
+      ) {
+        mainContent =
+          "import 'bootstrap/dist/css/bootstrap.min.css';\n" + mainContent;
+        await fsp.writeFile(mainFile, mainContent, "utf8");
+      }
+    }
+    const indexCssContent = await fsp.readFile(
+      path.join(cssDir, "bootstrap", "src", "index.css"),
+      "utf8"
+    );
+    await fsp.writeFile(indexCssPath, indexCssContent, "utf8");
+  } else {
+    const indexCssContent = await fsp.readFile(
+      path.join(cssDir, "none", "src", "index.css"),
+      "utf8"
+    );
+    await fsp.writeFile(indexCssPath, indexCssContent, "utf8");
+  }
+
+  // Clean up Vite's default App.css
+  await deleteIfExists(path.join(projectPath, "src", "App.css"));
+}

package/src/dependencies.js

@@ -0,0 +1,101 @@
+import { execa } from "execa";
+
+export async function installDeps(pkgManager, dev, packages, cwd) {
+  let cmd, args;
+  switch (pkgManager) {
+    case "pnpm":
+      cmd = "pnpm";
+      args = dev ? ["add", "-D", ...packages] : ["add", ...packages];
+      break;
+    case "yarn":
+      cmd = "yarn";
+      args = dev ? ["add", "-D", ...packages] : ["add", ...packages];
+      break;
+    case "bun":
+      cmd = "bun";
+      args = dev ? ["add", "-d", ...packages] : ["add", ...packages];
+      break;
+    default:
+      cmd = "npm";
+      args = dev
+        ? ["install", "-D", ...packages]
+        : ["install", ...packages];
+  }
+  await execa(cmd, args, { stdio: "pipe", cwd });
+}
+
+export async function installAllDeps(responses, pkg, cwd) {
+  const deps = [];
+  const devDeps = [];
+
+  // CSS framework
+  if (responses.cssFramework === "tailwind") {
+    devDeps.push("tailwindcss", "@tailwindcss/vite");
+    deps.push("clsx", "tailwind-merge");
+  } else if (responses.cssFramework === "bootstrap") {
+    deps.push("bootstrap", "react-bootstrap");
+  }
+
+  // State management
+  if (responses.stateManagement === "redux") {
+    deps.push("@reduxjs/toolkit", "react-redux");
+  } else if (responses.stateManagement === "zustand") {
+    deps.push("zustand");
+  }
+
+  // Router
+  if (responses.router) {
+    deps.push("react-router-dom");
+  }
+
+  // Icons
+  if (responses.iconLibrary === "lucide") {
+    deps.push("lucide-react");
+  } else if (responses.iconLibrary === "huge") {
+    deps.push("@hugeicons/react", "@hugeicons/core-free-icons");
+  }
+
+  // Axios
+  if (responses.axios) {
+    deps.push("axios");
+  }
+
+  // Testing
+  if (responses.testing === "vitest") {
+    devDeps.push(
+      "vitest",
+      "@testing-library/react",
+      "@testing-library/jest-dom",
+      "jsdom"
+    );
+  } else if (responses.testing === "jest") {
+    devDeps.push(
+      "jest",
+      "ts-jest",
+      "@types/jest",
+      "@testing-library/react",
+      "@testing-library/jest-dom",
+      "jsdom"
+    );
+  }
+
+  // Linter
+  if (responses.linter === "eslint") {
+    devDeps.push("eslint", "@eslint/js", "eslint-plugin-react-hooks", "eslint-plugin-react-refresh", "globals");
+    if (responses.language === "ts") {
+      devDeps.push("typescript-eslint");
+    }
+  } else if (responses.linter === "oxlint") {
+    devDeps.push("oxlint");
+  }
+
+  // Always re-install react + react-dom for consistency
+  deps.push("react", "react-dom");
+
+  if (deps.length > 0) {
+    await installDeps(pkg, false, deps, cwd);
+  }
+  if (devDeps.length > 0) {
+    await installDeps(pkg, true, devDeps, cwd);
+  }
+}