create-react-scaffold-cli 1.0.1 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-react-scaffold-cli",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "main": "index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
@@ -16,7 +16,7 @@
     "react-architecture"
   ],
   "author": "Muhammad Arsalan",
-  "license": "ISC",
+  "license": "MIT",
   "description": "A CLI to scaffold a feature-first React application with clear boundaries and long-term maintainability.",
   "dependencies": {
     "commander": "^14.0.2",

package/templates/base/{readme.md → README.md}

@@ -1,95 +1,165 @@
-# 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.
-
-```bash
-npx create-react-scaffold-cli
-
-```
-
----
-
-## 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.
+# React Feature‑First Scaffold
+
+## Purpose
+
+This repository is an **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
+
+> CLI installation instructions.
+
+```bash
+npx create-react-scaffold-cli
+
+```
+
+---
+
+## Documentation Index
+
+- `src/app/README.md` – Application bootstrap & providers
+- `src/features/README.md` – Feature architecture rules
+- `src/shared/README.md` – Shared modules & reuse policy
+
+---
+
+## Set Up
+
+### Install dependencies
+
+```bash
+npm i
+```
+
+### Run application
+
+---
+
+```
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+### Lint application
+
+```
+npm run lint
+```
+
+### Prettify code
+
+```
+npm run prettier
+```
+
+### Build application
+
+```
+npm run build
+```
+
+### Preview application
+
+```
+npm run preview
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+# Learning Resources
+
+## Tailwind CSS
+
+To learn more about `Tailwind CSS`, take a look at the following resources:
+
+- [Tailwind ](https://tailwindcss.com) - Tailwind documentation and related resources.
+
+## Framer Motion
+
+To learn more about `Framer Motion`, take a look at the following resources:
+
+- [Framer Motion](https://www.framer.com/motion) - Framer Motion documentation and related resources.
+
+## React Query
+
+To learn more about `TanStack Query`, take a look at the following resources:
+
+- [TanStack Query](https://tanstack.com/query/latest) - React Query documentation and related resources.
+
+## Nuqs
+
+To learn more about `Nuqs`, take a look at the following resources:
+
+- [Nuqs](https://nuqs.dev/) - React Query documentation and related resources.
+
+## 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/docs/DOCS.md

@@ -0,0 +1,7 @@
+# Scaffold Guides
+
+## Codebase Modules (source of truth)
+
+- [app](../src/app/app.readme.md)
+- [shared](../src/shared/shared.readme.md)
+- [features](../src/features/features.readme.md)

package/templates/base/package.json

@@ -32,12 +32,14 @@
     "@tanstack/react-query-devtools": "^5.91.2",
     "axios": "^1.13.2",
     "clsx": "^2.1.1",
+    "framer-motion": "^12.26.2",
     "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",
+    "react-router-dom": "^7.12.0",
     "tailwind-merge": "^3.4.0",
     "tailwindcss": "^4.1.18"
   },

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

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

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

@@ -1,4 +1,36 @@
+import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom';
+import { featureRoutes } from './routes.registry';
+import { AuthMiddleware } from './middlewares';
+import { Layouts } from '@/shared/constants';
+import { memo } from '@/shared/utils';
 
-export const Router = () => {
-  return <div className="">{authRoute}</div>;
+const layoutMap = {
+  dashboard: null,
+  none: ({ children }) => children,
 };
+
+export const Router = memo(() => {
+  return (
+    <BrowserRouter>
+      <Routes>
+        {featureRoutes.map((route, index) => {
+          const Layout = layoutMap[route.layout ?? Layouts.None];
+
+          let element = <Layout>{route.element}</Layout>;
+
+          if (route.protected) {
+            element = (
+              <AuthMiddleware>
+                <Layout>{route.element}</Layout>
+              </AuthMiddleware>
+            );
+          }
+
+          return <Route key={index} path={route.path} element={element} />;
+        })}
+
+        <Route path="/*" element={<Navigate to="/login" replace />} />
+      </Routes>
+    </BrowserRouter>
+  );
+});

package/templates/base/src/app/middlewares/AuthMiddleware.jsx

@@ -0,0 +1,5 @@
+import { memo } from '@/shared/utils';
+
+export const AuthMiddleware = memo(({ children }) => {
+  return children;
+});

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

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

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

@@ -1,8 +1,8 @@
 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';
+import { MutationCache, QueryCache, QueryClient, QueryClientProvider } from '@tanstack/react-query';
 
 export const QueryProvider = ({ children }) => {
   const [queryCache] = React.useState(

package/templates/base/src/app/routes.registry.js

@@ -0,0 +1,6 @@
+import { sampleRoutes } from '@/features/sample';
+
+export const featureRoutes = [
+  ...sampleRoutes,
+  // ...anotherFeatureRoutes
+];

package/templates/base/src/features/sample/constants/sample.assets.js

@@ -0,0 +1,8 @@
+export const SampleAssets = {
+  Images: {
+    Sample: './assets/images/',
+  },
+  Icons: {
+    Sample: './assets/icons/',
+  },
+};

package/templates/base/src/features/sample/constants/sample.navigations.js

@@ -0,0 +1,5 @@
+export const SampleNavigation = {
+  Sample: '/sample',
+};
+
+export const SampleSearchParamsKey = {};

package/templates/base/src/features/sample/constants/sample.queryKeys.js

@@ -0,0 +1,3 @@
+export const sampleQueryKey = {
+  all: ['sample'],
+};

package/templates/base/src/features/sample/index.js

@@ -0,0 +1 @@
+export { sampleRoutes } from './sample.routes';

package/templates/base/src/features/sample/pages/SamplePage.jsx

@@ -0,0 +1,8 @@
+import React from 'react';
+import { memo } from '@/shared/utils';
+
+const SamplePage = memo(() => {
+  return <div>SamplePage</div>;
+});
+
+export default SamplePage;

package/templates/base/src/features/sample/pages/index.js

@@ -0,0 +1 @@
+export const SamplePage = React.lazy(() => import('./SamplePage'));

package/templates/base/src/features/sample/sample.routes.js

@@ -0,0 +1,13 @@
+import React from 'react';
+import { Layouts } from '@/shared/constants';
+import { SampleNavigation } from './constants/sample.navigations';
+import { SamplePage } from './pages';
+
+export const sampleRoutes = [
+  {
+    path: SampleNavigation.Sample,
+    element: <SamplePage />,
+    protected: true,
+    layout: Layouts.None,
+  },
+];

package/templates/base/src/shared/{shared_readme.md → SHARED.md}

@@ -1,6 +1,7 @@
 # Shared Module
 
 ## Purpose
+
 The `shared` folder contains **cross-feature reusable code**.
 
 It exists to prevent duplication — not to become a dumping ground.
@@ -12,6 +13,7 @@ It exists to prevent duplication — not to become a dumping ground.
 ## What Belongs in Shared
 
 Only code that is:
+
 - Used by **multiple features**
 - **Stateless or generic**
 - Independent of business rules
@@ -38,12 +40,14 @@ shared/
 ## Rules
 
 ### ✅ Allowed
+
 - UI primitives (Button, Modal)
 - Generic hooks (useDebounce)
 - Axios/query setup
 - Theme tokens
 
 ### ❌ Not Allowed
+
 - Feature logic
 - Business rules
 - Feature-specific constants
@@ -67,11 +71,13 @@ import { authQueryKeys } from '@/features/auth';
 ## Constants Policy
 
 Shared constants should be:
+
 - Truly global
 - Stable
 - Rarely changed
 
 Examples:
+
 - Pagination defaults
 - Environment keys
 - Generic route params
@@ -83,6 +89,7 @@ Examples:
 Global contexts should be rare.
 
 Before adding one, ask:
+
 1. Is this needed by multiple unrelated features?
 2. Can this live inside a feature instead?
 
@@ -95,4 +102,3 @@ If unsure — **do not add it here**.
 Shared code is a **dependency magnet**.
 
 The smaller it stays, the healthier the system remains.
-

package/templates/base/src/shared/constants/app.constants.js

@@ -1,3 +1,9 @@
 export const ENV = {
   BACKEND_URL: import.meta.env.VITE_BACKEND_URL,
 };
+
+export const Layouts = {
+  Dashboard: 'dashboard',
+  Auth: 'auth',
+  None: 'none',
+};

package/templates/base/src/shared/constants/assets.constants.js

@@ -0,0 +1,5 @@
+export const AppAssets = {
+  Logos: {},
+  Images: {},
+  Icons: {},
+};

package/templates/base/src/shared/constants/index.js

@@ -0,0 +1,2 @@
+export * from './app.constants';
+export { AppAssets } from './assets.constants';

package/templates/base/src/shared/utils/localStorage.js

@@ -0,0 +1,18 @@
+export const LocalStorageGetItem = (key) => {
+  if (typeof window !== 'undefined') {
+    return localStorage.getItem(key);
+  }
+  return null;
+};
+
+export const LocalStorageSetItem = (key, value) => {
+  if (typeof window !== 'undefined') {
+    localStorage.setItem(key, value);
+  }
+};
+
+export const LocalStorageRemoveItem = (key) => {
+  if (typeof window !== 'undefined') {
+    localStorage.removeItem(key);
+  }
+};

package/templates/base/src/shared/utils/memo.js

@@ -1,3 +1,9 @@
 import React from 'react';
 
+/**
+ * @template T
+ * @param {React.ComponentType<T>} Component
+ * @returns {React.MemoExoticComponent<React.FC<T>>}
+ */
+
 export const memo = (Component) => React.memo(Component);

package/templates/base/src/shared/utils/regix.js

@@ -0,0 +1,3 @@
+export const normalizeRegex = (string) => {
+  return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+};

package/templates/base/vite.config.js

@@ -1,13 +1,12 @@
-import { defineConfig } from "vite";
-import react from "@vitejs/plugin-react";
-import path from "path";
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import path from 'path';
 
-// https://vite.dev/config/
 export default defineConfig({
   plugins: [react()],
   resolve: {
     alias: {
-      "@": path.resolve(import.meta.dirname, "./src"),
+      '@': path.resolve(import.meta.dirname, './src'),
     },
   },
   preview: {