@developerankitkumar/create-reactforge 1.0.2 → 1.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +279 -44
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,13 +1,13 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @developerankitkumar/create-reactforge
|
|
2
2
|
|
|
3
|
-
A
|
|
3
|
+
A CLI to scaffold a production-ready **React + TypeScript** admin dashboard starter — with MUI v9, SCSS architecture, authentication, server-side table, smart form fields, dynamic theming, and mock/real API support. License-verified download.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
---
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## Quick Start
|
|
8
8
|
|
|
9
9
|
```bash
|
|
10
|
-
npx
|
|
10
|
+
npx @developerankitkumar/create-reactforge my-new-app
|
|
11
11
|
```
|
|
12
12
|
|
|
13
13
|
Then run:
|
|
@@ -18,71 +18,306 @@ npm install
|
|
|
18
18
|
npm run dev
|
|
19
19
|
```
|
|
20
20
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
- Material UI (MUI)
|
|
25
|
-
- SCSS architecture
|
|
26
|
-
- Dynamic Light, Dark, and System themes
|
|
27
|
-
- Authentication and protected routes
|
|
28
|
-
- Mock API and real backend API modes
|
|
29
|
-
- Configurable backend URL
|
|
30
|
-
- Reusable layout with sidebar and topbar
|
|
31
|
-
- Reusable form and table components
|
|
32
|
-
- User management example
|
|
33
|
-
- Snackbar notifications
|
|
34
|
-
- Excel import and file upload components
|
|
35
|
-
- Font Awesome Free icons
|
|
21
|
+
> **Requires a license key** — format: `AK-XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX`
|
|
22
|
+
|
|
23
|
+
---
|
|
36
24
|
|
|
37
25
|
## Interactive Setup
|
|
38
26
|
|
|
39
|
-
The CLI
|
|
27
|
+
The CLI asks 4 questions:
|
|
40
28
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
29
|
+
| Step | Question | Options |
|
|
30
|
+
|------|----------|---------|
|
|
31
|
+
| 1 | Project name | Any lowercase name |
|
|
32
|
+
| 2 | Default theme | System *(recommended)*, Light, Dark |
|
|
33
|
+
| 3 | API mode | Mock API *(no backend needed)*, Real API |
|
|
34
|
+
| 4 | Backend URL | Only asked when Real API is selected |
|
|
45
35
|
|
|
46
|
-
|
|
36
|
+
After answering, it:
|
|
37
|
+
1. Validates your license key against the license server
|
|
38
|
+
2. Downloads and extracts the starter template ZIP
|
|
39
|
+
3. Patches `ThemeModeContext.tsx` with your chosen theme
|
|
40
|
+
4. Creates `.env` with your API mode and base URL
|
|
41
|
+
5. Sets your project name in `package.json`
|
|
42
|
+
6. Generates a `.gitignore`
|
|
47
43
|
|
|
48
|
-
|
|
44
|
+
---
|
|
49
45
|
|
|
50
|
-
|
|
51
|
-
VITE_USE_MOCK=true
|
|
52
|
-
VITE_API_BASE_URL=http://localhost:8000
|
|
53
|
-
```
|
|
46
|
+
## Stack
|
|
54
47
|
|
|
55
|
-
|
|
48
|
+
| Technology | Version | Purpose |
|
|
49
|
+
|------------|---------|---------|
|
|
50
|
+
| React | 19 | UI framework |
|
|
51
|
+
| TypeScript | 5+ | Type safety |
|
|
52
|
+
| Vite | 8 | Build tool |
|
|
53
|
+
| MUI (Material UI) | v9 | UI component library |
|
|
54
|
+
| React Router | v7 | Client-side routing |
|
|
55
|
+
| SCSS | — | Styling architecture |
|
|
56
|
+
| Axios | — | HTTP client |
|
|
57
|
+
| Font Awesome Free | — | Icons |
|
|
58
|
+
|
|
59
|
+
---
|
|
56
60
|
|
|
57
61
|
## Project Structure
|
|
58
62
|
|
|
59
|
-
```
|
|
63
|
+
```
|
|
60
64
|
src/
|
|
61
65
|
├── components/
|
|
66
|
+
│ ├── AppSnackbar/ → Global snackbar notification system
|
|
67
|
+
│ ├── CommonServerTable/ → Server-side table (search, sort, pagination, skeleton)
|
|
68
|
+
│ ├── ExcelImport/ → Excel file import with dialog preview
|
|
69
|
+
│ ├── FileDropZone/ → Drag-and-drop file upload zone
|
|
70
|
+
│ ├── ProtectedRoute.tsx → Route guards (RequireAuth / RequireGuest)
|
|
71
|
+
│ ├── SectionHeading/ → Page section heading component
|
|
72
|
+
│ ├── SmartField/ → Unified form field (14+ kinds)
|
|
73
|
+
│ ├── StatusChip/ → Colored status badge chip
|
|
74
|
+
│ ├── TableActionBtn/ → Row action buttons (edit / delete / view)
|
|
75
|
+
│ ├── appButton/ → Custom styled MUI button wrapper
|
|
76
|
+
│ └── layout/
|
|
77
|
+
│ ├── Layout.tsx → App shell with sidebar + topbar
|
|
78
|
+
│ ├── Sidebar/ → Collapsible sidebar navigation
|
|
79
|
+
│ └── Topbar/ → Top navigation bar with theme toggle
|
|
80
|
+
│
|
|
62
81
|
├── context/
|
|
63
|
-
├──
|
|
64
|
-
├──
|
|
82
|
+
│ ├── AuthContext.tsx → Login state, user info, permissions
|
|
83
|
+
│ ├── PageHeaderContext.tsx → Dynamic page title/breadcrumb
|
|
84
|
+
│ └── ThemeModeContext.tsx → Light / Dark / System theme + primary color
|
|
85
|
+
│
|
|
65
86
|
├── pages/
|
|
87
|
+
│ ├── Login/ → Login page with form validation
|
|
88
|
+
│ ├── dashboard/ → Overview/stats page
|
|
89
|
+
│ ├── users/ → User listing with CRUD (server-side table)
|
|
90
|
+
│ ├── components/ → Component showcase/demo page
|
|
91
|
+
│ └── NotFound/ → 404 page
|
|
92
|
+
│
|
|
66
93
|
├── services/
|
|
94
|
+
│ ├── httpClient.ts → Axios instance with auth headers
|
|
95
|
+
│ ├── mockClient.ts → Mock API client (reads from mock/ JSON)
|
|
96
|
+
│ ├── authApis.ts → Login / logout / me API calls
|
|
97
|
+
│ └── userApis.ts → User CRUD API calls
|
|
98
|
+
│
|
|
99
|
+
├── mock/
|
|
100
|
+
│ ├── login.json → Mock login response
|
|
101
|
+
│ ├── me.json → Mock current user
|
|
102
|
+
│ ├── users.json → Mock user list
|
|
103
|
+
│ └── roles.json → Mock roles list
|
|
104
|
+
│
|
|
105
|
+
├── interface/
|
|
106
|
+
│ ├── Auth.ts → Auth types (LoginPayload, User, etc.)
|
|
107
|
+
│ ├── User.ts → User model types
|
|
108
|
+
│ └── UserList.ts → UserList response types
|
|
109
|
+
│
|
|
67
110
|
├── styles/
|
|
111
|
+
│ ├── main.scss → Entry SCSS (imports all partials)
|
|
112
|
+
│ ├── abstracts/
|
|
113
|
+
│ │ ├── _variables.scss → SCSS variables
|
|
114
|
+
│ │ ├── _mixins.scss → SCSS mixins
|
|
115
|
+
│ │ └── _functions.scss → SCSS functions
|
|
116
|
+
│ ├── base/
|
|
117
|
+
│ │ ├── _reset.scss → CSS reset
|
|
118
|
+
│ │ ├── _global.scss → Global styles + CSS token defaults
|
|
119
|
+
│ │ └── _typography.scss → Typography scale
|
|
120
|
+
│ ├── layout/
|
|
121
|
+
│ │ ├── _dashboard.scss → Dashboard layout styles
|
|
122
|
+
│ │ ├── _header.scss → Header styles
|
|
123
|
+
│ │ └── _sidebar.scss → Sidebar styles
|
|
124
|
+
│ └── themes/
|
|
125
|
+
│ ├── _light.scss → Light theme CSS tokens
|
|
126
|
+
│ └── _dark.scss → Dark theme CSS tokens
|
|
127
|
+
│
|
|
68
128
|
├── types/
|
|
129
|
+
│ └── global.ts → Global TypeScript types
|
|
130
|
+
│
|
|
69
131
|
└── utils/
|
|
132
|
+
├── authHeaders.ts → Helper to get auth headers
|
|
133
|
+
├── formatters.ts → Date / currency formatters
|
|
134
|
+
└── snackbar.ts → Snackbar trigger helpers
|
|
70
135
|
```
|
|
71
136
|
|
|
72
|
-
|
|
137
|
+
---
|
|
73
138
|
|
|
74
|
-
|
|
75
|
-
|
|
139
|
+
## Components
|
|
140
|
+
|
|
141
|
+
### `SmartField` — Unified Form Field
|
|
142
|
+
|
|
143
|
+
One component for all form inputs. Supports 14+ kinds:
|
|
144
|
+
|
|
145
|
+
| `kind` | Value type | Description |
|
|
146
|
+
|--------|-----------|-------------|
|
|
147
|
+
| `text` | `string` | Plain text input |
|
|
148
|
+
| `password` | `string` | Password with show/hide toggle |
|
|
149
|
+
| `email` | `string` | Email input |
|
|
150
|
+
| `phone` | `string` | Phone input with icon |
|
|
151
|
+
| `url` | `string` | URL input with icon |
|
|
152
|
+
| `number` | `string \| number` | Number input |
|
|
153
|
+
| `currency` | `string \| number` | Number with currency symbol |
|
|
154
|
+
| `multiline` / `textarea` | `string` | Multi-row text area |
|
|
155
|
+
| `date` | `string` | MUI DatePicker (`YYYY-MM-DD`) |
|
|
156
|
+
| `time` | `string` | Time input |
|
|
157
|
+
| `date-range` | `string` | Two date pickers (`"start,end"`) |
|
|
158
|
+
| `time-range` | `string` | Two time inputs (`"start,end"`) |
|
|
159
|
+
| `select` | `string \| string[]` | Dropdown / multi-select / searchable |
|
|
160
|
+
| `radio` | `string` | Radio button group |
|
|
161
|
+
| `toggle` | `boolean` | Custom styled switch |
|
|
162
|
+
| `checkbox` | `boolean` | Bordered checkbox (fully clickable) |
|
|
163
|
+
| `tags` | `string[]` | Free-entry chip input |
|
|
164
|
+
| `slider` | `number` | Range slider with percent display |
|
|
165
|
+
| `otp` | `string` | Digit-by-digit OTP input |
|
|
166
|
+
| `rating` | `number` | Star rating with value label |
|
|
167
|
+
| `file` | `string` | File upload with filename display |
|
|
168
|
+
| `color` | `string` | Color swatch picker (hex) |
|
|
169
|
+
|
|
170
|
+
Built-in: `required` validation, `validate` function, `forceError`, `error` (external), `hint`, `size` (`small` / `medium`), `disabled`.
|
|
171
|
+
|
|
172
|
+
---
|
|
173
|
+
|
|
174
|
+
### `CommonServerTable` — Server-Side Data Table
|
|
175
|
+
|
|
176
|
+
Full-featured table with server-side search, sort, and pagination.
|
|
177
|
+
|
|
178
|
+
```tsx
|
|
179
|
+
<CommonServerTable
|
|
180
|
+
columns={columns}
|
|
181
|
+
fetcher={fetchUsers}
|
|
182
|
+
getRowId={(row) => row.id}
|
|
183
|
+
actions={[editAction, deleteAction]}
|
|
184
|
+
searchPlaceholder="Search users..."
|
|
185
|
+
initialSortBy="name"
|
|
186
|
+
reloadKey={reload}
|
|
187
|
+
/>
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
Features: skeleton loading, empty state, search debounce, column sort, page size selector, row action buttons.
|
|
191
|
+
|
|
192
|
+
---
|
|
193
|
+
|
|
194
|
+
### `AppSnackbar` — Global Notifications
|
|
195
|
+
|
|
196
|
+
```tsx
|
|
197
|
+
import { useSnackbar } from '@/utils/snackbar'
|
|
198
|
+
|
|
199
|
+
const snackbar = useSnackbar()
|
|
200
|
+
snackbar.success('Saved!')
|
|
201
|
+
snackbar.error('Something went wrong.')
|
|
202
|
+
snackbar.info('Loading...')
|
|
203
|
+
snackbar.warning('Check inputs.')
|
|
76
204
|
```
|
|
77
205
|
|
|
78
|
-
|
|
206
|
+
---
|
|
207
|
+
|
|
208
|
+
### `ExcelImport` — Excel File Import
|
|
209
|
+
|
|
210
|
+
Drag-and-drop or click to select an `.xlsx` / `.csv` file. Shows a dialog preview of parsed rows before confirming import.
|
|
211
|
+
|
|
212
|
+
---
|
|
213
|
+
|
|
214
|
+
### `FileDropZone` — File Upload Zone
|
|
215
|
+
|
|
216
|
+
Drag-and-drop zone for any file type. Configurable accept types, size limits, and upload callback.
|
|
217
|
+
|
|
218
|
+
---
|
|
219
|
+
|
|
220
|
+
### `StatusChip` — Status Badge
|
|
221
|
+
|
|
222
|
+
```tsx
|
|
223
|
+
<StatusChip status="active" />
|
|
224
|
+
<StatusChip status="inactive" />
|
|
225
|
+
<StatusChip status="pending" />
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
Color-coded MUI Chip with configurable status map.
|
|
229
|
+
|
|
230
|
+
---
|
|
231
|
+
|
|
232
|
+
### `TableActionBtn` — Row Actions
|
|
233
|
+
|
|
234
|
+
```tsx
|
|
235
|
+
<TableActionBtn
|
|
236
|
+
actions={[
|
|
237
|
+
{ label: 'Edit', icon: 'edit', onClick: handleEdit },
|
|
238
|
+
{ label: 'Delete', icon: 'delete', onClick: handleDelete },
|
|
239
|
+
]}
|
|
240
|
+
/>
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
---
|
|
244
|
+
|
|
245
|
+
### `SectionHeading` — Page Section Title
|
|
246
|
+
|
|
247
|
+
```tsx
|
|
248
|
+
<SectionHeading title="User Management" subtitle="Manage all registered users" />
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
---
|
|
252
|
+
|
|
253
|
+
### `AppButton` — Styled Button
|
|
254
|
+
|
|
255
|
+
A wrapper around MUI `Button` that follows the project's theme color and size conventions.
|
|
256
|
+
|
|
257
|
+
---
|
|
258
|
+
|
|
259
|
+
## Theming
|
|
260
|
+
|
|
261
|
+
The starter ships with Light, Dark, and System themes. Theme is toggled from the topbar.
|
|
262
|
+
|
|
263
|
+
**CSS tokens (override in `:root`):**
|
|
264
|
+
|
|
265
|
+
```css
|
|
266
|
+
:root {
|
|
267
|
+
--theme-color: #6366f1;
|
|
268
|
+
--surface: #ffffff;
|
|
269
|
+
--border: #e2e8f0;
|
|
270
|
+
--text-h: #1e293b;
|
|
271
|
+
--muted: #94a3b8;
|
|
272
|
+
--accent-tint: #eef2ff;
|
|
273
|
+
--secondary-color: #ffffff;
|
|
274
|
+
}
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
You can also change the primary color at runtime — it updates MUI buttons, snackbars, and all SmartField accents dynamically.
|
|
278
|
+
|
|
279
|
+
---
|
|
280
|
+
|
|
281
|
+
## Environment Variables
|
|
282
|
+
|
|
283
|
+
```env
|
|
284
|
+
VITE_USE_MOCK=true # true = Mock API, false = Real API
|
|
285
|
+
VITE_API_BASE_URL= # Backend base URL (used when VITE_USE_MOCK=false)
|
|
286
|
+
VITE_NGROK_SKIP= # Set to "true" to skip ngrok browser warning header
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
---
|
|
290
|
+
|
|
291
|
+
## Authentication Flow
|
|
292
|
+
|
|
293
|
+
- Login page → calls `/api/v1/auth/login` (or mock)
|
|
294
|
+
- Token stored in `localStorage`
|
|
295
|
+
- `AuthContext` exposes `user`, `isLoggedIn`, `login()`, `logout()`
|
|
296
|
+
- `RequireAuth` / `RequireGuest` route guards redirect accordingly
|
|
297
|
+
- `httpClient` auto-attaches `Authorization: Bearer <token>` to every request
|
|
298
|
+
|
|
299
|
+
---
|
|
300
|
+
|
|
301
|
+
## Mock API Mode
|
|
302
|
+
|
|
303
|
+
When `VITE_USE_MOCK=true`, all API calls are intercepted by `mockClient.ts` and return data from `src/mock/*.json`. No backend needed — ideal for frontend development and demos.
|
|
304
|
+
|
|
305
|
+
---
|
|
306
|
+
|
|
307
|
+
## Pages
|
|
79
308
|
|
|
80
|
-
|
|
309
|
+
| Route | Page | Description |
|
|
310
|
+
|-------|------|-------------|
|
|
311
|
+
| `/admin/login` | Login | Auth page (guest only) |
|
|
312
|
+
| `/admin/dashboard` | Dashboard | Stats overview |
|
|
313
|
+
| `/admin/users` | Users | Server-side user table with CRUD |
|
|
314
|
+
| `/admin/components` | Components | SmartField + component showcase |
|
|
315
|
+
| `*` | NotFound | 404 page |
|
|
81
316
|
|
|
82
|
-
|
|
317
|
+
---
|
|
83
318
|
|
|
84
|
-
|
|
319
|
+
## License
|
|
85
320
|
|
|
86
|
-
|
|
321
|
+
MIT — template requires a valid ReactForge license key to download.
|
|
87
322
|
|
|
88
|
-
|
|
323
|
+
Get your license key at **[ankitdeveloper.site](https://ankitdeveloper.site)**
|