create-react-scaffold-cli 0.1.0

package/bin/index.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+import prompts from 'prompts';
+import { createProject } from '../scripts/createProject.js';
+
+async function init() {
+  const responses = await prompts([
+    {
+      type: 'text',
+      name: 'projectName',
+      message: 'What is your project name?',
+      validate: (value) => (value ? true : 'Project name is required'),
+    },
+    {
+      type: 'toggle',
+      name: 'installDeps',
+      message: 'Do you want to install dependencies now?',
+      initial: true,
+      active: 'yes',
+      inactive: 'no',
+    },
+  ]);
+
+  const { projectName, installDeps } = responses;
+
+  if (!projectName) {
+    console.log('❌ Project creation cancelled');
+    process.exit(1);
+  }
+
+  await createProject(projectName, { installDeps });
+}
+
+init();

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "create-react-scaffold-cli",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "create-react-scaffold": "bin/index.js"
+  },
+  "dependencies": {
+    "commander": "^14.0.2",
+    "execa": "^9.6.1",
+    "fs-extra": "^11.3.3",
+    "prompts": "^2.4.2",
+    "react-scaffold": "^0.1.3"
+  }
+}

package/scripts/createProject.js

@@ -0,0 +1,30 @@
+import path from 'path';
+import fs from 'fs-extra';
+import { execa } from 'execa';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export async function createProject(name, options) {
+  const { installDeps } = options;
+
+  const targetDir = path.resolve(process.cwd(), name);
+  const templateDir = path.resolve(__dirname, '../templates/base');
+
+  console.log(`📁 Creating project: ${name}`);
+  await fs.copy(templateDir, targetDir);
+
+  if (installDeps) {
+    console.log('📦 Installing dependencies...');
+    await execa('npm', ['install'], {
+      cwd: targetDir,
+      stdio: 'inherit',
+    });
+  } else {
+    console.log('⏭ Skipped dependency installation');
+    console.log(`➡ Run 'npm install' inside ${name} when ready`);
+  }
+
+  console.log('✅ Project ready!');
+}

package/templates/base/.env

@@ -0,0 +1 @@
+VITE_BACKEND_URL=""

package/templates/base/.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

package/templates/base/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "singleQuote": true,
+  "semi": true,
+  "trailingComma": "es5",
+  "printWidth": 100,
+  "tabWidth": 2,
+  "plugins": ["prettier-plugin-jsdoc"]
+}

package/templates/base/.vscode/extensions.json

@@ -0,0 +1,8 @@
+{
+  "recommendations": [
+    "dbaeumer.vscode-eslint",
+    "esbenp.prettier-vscode",
+    "bradlc.vscode-tailwindcss",
+    "dsznajder.es7-react-js-snippets"
+  ]
+}

package/templates/base/.vscode/settings.json

@@ -0,0 +1,16 @@
+{
+  "typescript.updateImportsOnFileMove.enabled": "always",
+  "javascript.updateImportsOnFileMove.enabled": "always",
+  "editor.formatOnPaste": true,
+  "editor.formatOnSave": true,
+  "editor.cursorSmoothCaretAnimation": "on",
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  },
+  "cSpell.words": ["premiumlogo"],
+  "[javascriptreact]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "liveServer.settings.port": 5501
+}

package/templates/base/eslint.config.js

@@ -0,0 +1,48 @@
+import js from '@eslint/js';
+import react from 'eslint-plugin-react';
+import reactHooks from 'eslint-plugin-react-hooks';
+import reactRefresh from 'eslint-plugin-react-refresh';
+import globals from 'globals';
+
+export default [
+  js.configs.recommended,
+  {
+    files: ['**/*.{js,jsx}'],
+    languageOptions: {
+      ecmaVersion: 2020,
+      sourceType: 'module',
+      parseOptions: {
+        ecmaVersion: {
+          jsx: true,
+        },
+      },
+      globals: {
+        ...globals.browser,
+        window: 'readonly',
+        document: 'readonly',
+      },
+    },
+    plugins: {
+      react,
+      'react-hooks': reactHooks,
+      'react-refresh': reactRefresh,
+    },
+    settings: {
+      react: {
+        version: 'detect',
+      },
+    },
+    rules: {
+      'no-console': 'error',
+      'prefer-const': 'error',
+      'no-fallthrough': 'error',
+      'no-duplicate-imports': 'error',
+      'react/react-in-jsx-scope': 'off',
+      'react/prop-types': 'off',
+      'react-hooks/rules-of-hooks': 'error',
+      'react-hooks/exhaustive-deps': 'warn', // important for hooks
+      'no-undef': 'error', // ⚠ this one detects undefined variables
+      'no-unused-vars': ['warn', { vars: 'all', args: 'after-used', ignoreRestSiblings: true }],
+    },
+  },
+];

package/templates/base/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1, viewport-fit=cover, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"
+    />
+    <title>vite-project</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>

package/templates/base/jsconfig.json

@@ -0,0 +1,7 @@
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}

package/templates/base/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "vite-project",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "lint": "eslint .",
+    "preview": "vite preview",
+    "prepare": "husky"
+  },
+  "lint-staged": {
+    "src/**/*.{js,jsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "src/**/*.css": [
+      "prettier --write"
+    ],
+    "package.json": [
+      "prettier --write"
+    ]
+  },
+  "dependencies": {
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-dropdown-menu": "^2.1.16",
+    "@radix-ui/react-scroll-area": "^1.2.10",
+    "@radix-ui/react-select": "^2.2.6",
+    "@tailwindcss/postcss": "^4.1.18",
+    "@tanstack/react-query": "^5.90.16",
+    "@tanstack/react-query-devtools": "^5.91.2",
+    "axios": "^1.13.2",
+    "clsx": "^2.1.1",
+    "nuqs": "^2.8.6",
+    "postcss": "^8.5.6",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-hot-toast": "^2.6.0",
+    "react-icons": "^5.5.0",
+    "tailwind-merge": "^3.4.0",
+    "tailwindcss": "^4.1.18"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/react": "^19.2.5",
+    "@types/react-dom": "^19.2.3",
+    "@typescript-eslint/eslint-plugin": "^8.51.0",
+    "@typescript-eslint/parser": "^8.51.0",
+    "@vitejs/plugin-react": "^5.1.1",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.26",
+    "eslint-plugin-unused-imports": "^4.3.0",
+    "globals": "^16.5.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "prettier": "3.7.4",
+    "prettier-plugin-jsdoc": "^1.8.0",
+    "vite": "^7.2.4"
+  }
+}

package/templates/base/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

package/templates/base/readme.md

@@ -0,0 +1,97 @@
+# React Feature‑First Scaffold
+
+## Purpose
+
+This repository is an **internal, opinionated React scaffold** designed for large-scale frontend applications. It enforces a **feature‑first architecture**, clear ownership boundaries, and predictable patterns so teams can scale safely without architectural drift.
+
+This scaffold will later be distributed via an internal **NPM CLI** (similar to `create-react-app`) to bootstrap projects with best practices preconfigured.
+
+---
+
+## Core Principles
+
+- **Feature-first, not layer-first**
+- **Explicit boundaries** between app / features / shared
+- **Locality of logic** (keep things close to where they are used)
+- **Predictable imports** and naming conventions
+- **Low cognitive load** for new developers
+
+---
+
+## Tech Stack
+
+### Runtime
+
+- **React 19** – UI layer
+- **Vite** – fast dev & build tooling
+
+### Styling
+
+- **Tailwind CSS** – utility-first styling
+- **tailwind-merge** – class conflict resolution
+- **clsx** – conditional class composition
+
+### Data & State
+
+- **@tanstack/react-query** – server-state management
+- **Axios** – HTTP client
+
+### UI Utilities
+
+- **Radix UI** – accessible headless components
+- **react-hot-toast** – notifications
+- **react-icons** – icon system
+
+### Code Quality
+
+- **ESLint** – linting with strict rules
+- **Prettier** – formatting
+- **Husky + lint-staged** – pre-commit enforcement
+
+---
+
+## High-Level Folder Structure
+
+```txt
+src/
+  app/        # Application bootstrap & global wiring
+  features/   # Business features (isolated, self-contained)
+  shared/     # Cross-feature reusable modules
+```
+
+Each top-level folder has **its own README** explaining rules and responsibilities.
+
+---
+
+## Installation (WIP)
+
+> CLI installation instructions will be added once the NPM package is published.
+
+For now:
+
+```bash
+npm install
+npm run dev
+```
+
+---
+
+## Documentation Index
+
+- `src/app/README.md` – Application bootstrap & providers
+- `src/features/README.md` – Feature architecture rules
+- `src/shared/README.md` – Shared modules & reuse policy
+
+---
+
+## Philosophy
+
+> **Architecture is a product feature.**
+
+This scaffold exists to reduce decision fatigue, prevent architectural erosion, and help teams move faster with confidence.
+
+---
+
+## Ownership
+
+This scaffold is maintained internally and should be treated as a **living standard**. Changes must be intentional, documented, and agreed upon by the frontend team.

package/templates/base/src/app/App.jsx

@@ -0,0 +1,13 @@
+import { Toaster } from '@/shared/ui';
+import { QueryProvider } from './providers';
+
+function App({ children }) {
+  return (
+    <QueryProvider>
+      {children}
+      <Toaster />
+    </QueryProvider>
+  );
+}
+
+export default App;

package/templates/base/src/app/Router.jsx

@@ -0,0 +1,4 @@
+
+export const Router = () => {
+  return <div className="">{authRoute}</div>;
+};

package/templates/base/src/app/app_readme.md

@@ -0,0 +1,74 @@
+# App Module
+
+## Purpose
+The `app` layer is responsible for **bootstrapping the application**. It wires together global providers, routing, and application-level configuration.
+
+This folder should remain **small, boring, and stable**.
+
+> If something changes frequently, it probably does NOT belong here.
+
+---
+
+## Responsibilities
+
+The `app` module may contain:
+
+- Application entry point (`main.jsx`)
+- Root component (`App.jsx`)
+- Global providers (React Query, Theme, etc.)
+- Application router
+- Global middlewares
+- One-time initialization logic
+
+---
+
+## Folder Structure
+
+```txt
+app/
+  middlewares/   # Global middlewares (logging, guards, etc.)
+  providers/     # Global providers (QueryProvider, ThemeProvider)
+  App.jsx        # Root component
+  Router.jsx     # App-level router
+  main.jsx       # Application entry
+  index.css      # Global styles
+```
+
+---
+
+## Rules
+
+### ✅ Allowed
+- Global providers
+- App-wide configuration
+- Router composition
+
+### ❌ Not Allowed
+- Feature-specific logic
+- Business rules
+- UI components
+- API calls
+- Feature contexts
+
+---
+
+## Import Rules
+
+```js
+// ✅ Allowed
+import { QueryProvider } from './providers';
+import { AppRouter } from './Router';
+
+// ❌ Not Allowed
+import { LoginForm } from '@/features/auth/components';
+```
+
+---
+
+## Philosophy
+
+The `app` layer is a **composition root**, not a feature owner.
+
+Keep it minimal.
+Keep it predictable.
+

package/templates/base/src/app/index.css

@@ -0,0 +1 @@
+@import 'tailwindcss';

package/templates/base/src/app/main.jsx

@@ -0,0 +1,10 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import App from './App.jsx';
+import './index.css';
+
+createRoot(document.getElementById('root')).render(
+  <StrictMode>
+    <App />
+  </StrictMode>
+);

package/templates/base/src/app/providers/QueryProvider.jsx

@@ -0,0 +1,75 @@
+import React from 'react';
+import { MutationCache, QueryCache, QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { AxiosError } from 'axios';
+import toast from 'react-hot-toast';
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
+
+export const QueryProvider = ({ children }) => {
+  const [queryCache] = React.useState(
+    new QueryCache({
+      onError: () => {},
+    })
+  );
+
+  const [mutationCache] = React.useState(
+    new MutationCache({
+      onError: (error) => {
+        const isAxiosError = error instanceof AxiosError;
+
+        if (!isAxiosError) {
+          return toast.error('Something went wrong.');
+        }
+        if (error.code === AxiosError.ERR_NETWORK) {
+          return toast.error('Network Error');
+        }
+        if (error.status === 500) {
+          return toast.error('Network Error');
+        }
+        const { response } = error;
+        if (!response) {
+          return toast.error('Something went wrong');
+        }
+        const { data } = response;
+        if (!data) {
+          return toast.error('Something went wrong');
+        }
+        const { message } = data;
+        if (!message) {
+          return toast.error('Something went wrong');
+        }
+        const isIterable = Array.isArray(message);
+        if (!isIterable) {
+          return toast.error(message);
+        }
+        for (let index = 0; index < message.length; index++) {
+          const error = message[index];
+          toast.error(error);
+        }
+      },
+    })
+  );
+
+  const [client] = React.useState(
+    new QueryClient({
+      queryCache: queryCache,
+      mutationCache: mutationCache,
+      defaultOptions: {
+        queries: {
+          retry: false,
+          refetchOnWindowFocus: false,
+          refetchOnReconnect: false,
+        },
+        mutations: {
+          retry: false,
+        },
+      },
+    })
+  );
+
+  return (
+    <QueryClientProvider client={client}>
+      {children}
+      <ReactQueryDevtools />
+    </QueryClientProvider>
+  );
+};

package/templates/base/src/app/providers/index.js

@@ -0,0 +1 @@
+export { QueryProvider } from './QueryProvider';

package/templates/base/src/features/features_readme.md

@@ -0,0 +1,102 @@
+# Features Module
+
+## Purpose
+
+The `features` folder is the **core of the application**.
+
+Each feature represents a **self-contained unit of business functionality** with clear ownership and boundaries.
+
+> If a user-facing requirement exists, it belongs to a feature.
+
+---
+
+## Feature-First Architecture
+
+Instead of grouping by technical layers (components, hooks, services), we group by **business capability**.
+
+This improves:
+
+- Scalability
+- Ownership
+- Discoverability
+- Refactor safety
+
+---
+
+## Feature Structure
+
+```txt
+features/<feature-name>/
+  assets/               # Feature-specific images/icons
+  components/           # Reusable UI within the feature
+  constants/            # Feature constants
+  hooks/                # Feature-specific hooks
+  pages/                # Route-level components
+
+  <feature>.assets.js
+  <feature>.context.js
+  <feature>.navigations.js
+  <feature>.queryKeys.js
+  <feature>.routes.jsx
+
+  index.js               # Public API of the feature
+```
+
+---
+
+## Rules
+
+### Feature Ownership
+
+- A feature **owns its logic, UI, assets, and state**
+- Features should not depend on other features
+
+### Imports
+
+```js
+// ✅ Allowed
+import { Button } from '@/shared/ui';
+import { useAuth } from '@/features/auth';
+
+// ❌ Not Allowed
+import { useProfile } from '@/features/profile';
+```
+
+---
+
+## Constants Policy
+
+Feature constants include:
+
+- Query keys
+- Navigation definitions
+- Route names
+- Feature-level config
+
+> Constants should stay **inside the feature** unless reused across multiple features.
+
+---
+
+## Contexts
+
+- Contexts should be **feature-scoped by default**
+- Global contexts require strong justification
+
+---
+
+## Deletion Rule
+
+If a feature is removed:
+
+- Delete the entire folder
+- No side effects elsewhere
+
+If deletion breaks other features, boundaries are violated.
+
+---
+
+## Example Feature
+
+`sample/` is a reference feature and can be safely removed.
+
+Use it as a blueprint for new features.