Skip to content

Commit c1a4e4f

Browse files
pasqualiniguipasqualinigui
committed
feat: initial commit of React Fluksos Senior Template
0 parents  commit c1a4e4f

34 files changed

Lines changed: 8880 additions & 0 deletions

‎.biomeignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
routeTree.gen.ts

‎.env.example‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
VITE_API_URL=http://localhost:3000/api

‎.github/workflows/deploy-ftp.yml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
name: Deploy via FTP
2+
3+
on:
4+
push:
5+
branches:
6+
- main # Change this to your deployment branch if needed
7+
8+
jobs:
9+
web-deploy:
10+
name: 🎉 Deploy
11+
runs-on: ubuntu-latest
12+
steps:
13+
- name: 🚚 Get latest code
14+
uses: actions/checkout@v4
15+
16+
- name: ⚙️ Setup Node.js
17+
uses: actions/setup-node@v4
18+
with:
19+
node-version: 20
20+
21+
- name: 📦 Setup pnpm
22+
uses: pnpm/action-setup@v3
23+
with:
24+
version: 9
25+
26+
- name: 📥 Install Dependencies
27+
run: pnpm install --frozen-lockfile
28+
29+
- name: 🏗️ Build Project
30+
run: pnpm run build
31+
32+
# Uncomment the block below and set up GitHub Secrets to enable FTP deployment
33+
#
34+
# - name: 🚀 Sync files to FTP
35+
# uses: SamKirkland/FTP-Deploy-Action@v4.3.5
36+
# with:
37+
# server: ${{ secrets.FTP_SERVER }}
38+
# username: ${{ secrets.FTP_USERNAME }}
39+
# password: ${{ secrets.FTP_PASSWORD }}
40+
# local-dir: ./dist/ # The build output directory
41+
# server-dir: /public_html/ # Change to your server's public directory
42+

‎.gitignore‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Logs
2+
logs
3+
*.log
4+
npm-debug.log*
5+
yarn-debug.log*
6+
yarn-error.log*
7+
pnpm-debug.log*
8+
lerna-debug.log*
9+
10+
node_modules
11+
dist
12+
dist-ssr
13+
*.local
14+
15+
# Editor directories and files
16+
.vscode/*
17+
!.vscode/extensions.json
18+
.idea
19+
.DS_Store
20+
*.suo
21+
*.ntvs*
22+
*.njsproj
23+
*.sln
24+
*.sw?
25+
26+
# Project specifics
27+
.tanstack
28+
*.tsbuildinfo
29+
.env
30+
.env.local
31+

‎.husky/pre-commit‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
pnpm typecheck && pnpm lint:fix

‎GEMINI.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# 🤖 PROJECT AI INSTRUCTIONS (VIBE CODING PROTOCOL)
2+
3+
Hello, AI Assistant (Cursor, Copilot, Gemini, Claude, Windsurf, etc).
4+
When interacting with this repository, you MUST strictly adhere to the following senior-level architecture and toolchain guidelines. This is a highly modernized, strict, and scalable template. Do not hallucinate legacy configurations.
5+
6+
## 1. CORE STACK (MODERN)
7+
- **React**: 19 (Do not use legacy React 17/18 hooks unnecessarily. Favor the new `use` hook and transitions where applicable).
8+
- **Vite**: 8+ (Configured in `vite.config.ts`).
9+
- **Package Manager**: `pnpm` ONLY. Never use `npm` or `yarn`. If you need to install a package, always use `pnpm add`.
10+
11+
## 2. STYLING & UI (TAILWIND v4)
12+
- **Engine**: Tailwind CSS v4.
13+
- **CRITICAL**: There is NO `tailwind.config.ts` or `postcss.config.js`. Do NOT attempt to create them.
14+
- All theme variables and Shadcn/ui configurations are mapped directly via standard CSS variables and the `@theme` directive inside `src/globals.css`.
15+
- Components reside in `src/components/ui/`. They are generated via Shadcn CLI.
16+
- Always use the `cn()` utility from `src/lib/utils.ts` to merge Tailwind classes.
17+
18+
## 3. ROUTING (TANSTACK ROUTER)
19+
- **Library**: `@tanstack/react-router` (File-based routing).
20+
- **CRITICAL**: NEVER use `react-router-dom`.
21+
- We use file-based routing inside the `src/routes/` directory.
22+
- `src/routeTree.gen.ts` is auto-generated by `@tanstack/router-plugin`. Do not modify it manually.
23+
- **Ignore Directive**: The auto-generated route tree contains a `// biome-ignore` comment to bypass strict any-checks; do NOT remove this ignore directive under any circumstance.
24+
- Provide a `Route` component and optionally `errorComponent` / `pendingComponent` in your route files.
25+
26+
## 4. LINTING & FORMATTING (BIOME)
27+
- **Tool**: `@biomejs/biome`.
28+
- **CRITICAL**: There is NO `eslint` or `prettier` in this project. Do NOT install them. Do NOT generate `.eslintrc` or `.prettierrc`.
29+
- Biome handles all formatting and linting (including Tailwind class sorting via `nursery/useSortedClasses`).
30+
- Run `pnpm lint:fix` to auto-fix code. Do NOT rely on IDE Prettier extensions.
31+
32+
## 5. STATE MANAGEMENT & DATA FETCHING
33+
- **Server State**: `@tanstack/react-query`. Used globally via `AppQueryProvider`.
34+
- **HTTP Client**: `axios`. An optimized instance is pre-configured at `src/lib/api.ts`. Always import `api` from there rather than calling raw `axios` or `fetch`.
35+
- **Client State**: `zustand` is available for complex global client state. Avoid overusing it if TanStack Query can handle the data (e.g. do not store API responses in Zustand).
36+
- **Forms**: Always use `react-hook-form` paired with `@hookform/resolvers/zod` and `zod` for schema validation.
37+
38+
## 6. STRICT RULES & ANTI-PATTERNS
39+
- **NO `any`**: TypeScript strict mode is ON. Avoid `any` at all costs. Use `unknown` if absolutely necessary, or `zod` for payload validation.
40+
- **Environment Variables**: Use `import.meta.env.VITE_...` and always type them inside `src/vite-env.d.ts` inside the `ImportMetaEnv` interface.
41+
- **Error Handling**: Do not leave screens blank on errors. Rely on the Root Error Boundary configured in `src/routes/__root.tsx`.
42+
- **Imports**: Always use absolute imports with the `@/` alias pointing to `src/`. Do not use relative paths like `../../components`.
43+
- **Icons**: Always use `lucide-react` for icons.
44+
45+
## 7. WORKFLOW SCRIPTS
46+
- `pnpm dev`: Start development server.
47+
- `pnpm build`: Run typecheck and build for production.
48+
- `pnpm lint:fix`: Fix linting and formatting issues.
49+
- `pnpm typecheck`: Run TS compiler without emitting files.
50+
- Note: `husky` is configured to run typecheck and linting on `pre-commit`. You cannot commit broken code.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Pasqualini Guilherme
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
<h1 align="center">REACT FLUKSOS TEMPLATE</h1>
2+
3+
<p align="center">
4+
<em>The Ultimate Senior Boilerplate for Modern React Applications</em>
5+
</p>
6+
7+
<p align="center">
8+
<em>Built with the tools and technologies:</em>
9+
</p>
10+
11+
<p align="center">
12+
<img src="https://img.shields.io/badge/Vite-646CFF?style=for-the-badge&logo=vite&logoColor=white" alt="Vite">
13+
<img src="https://img.shields.io/badge/React_19-20232A?style=for-the-badge&logo=react&logoColor=61DAFB" alt="React 19">
14+
<img src="https://img.shields.io/badge/TypeScript_6-007ACC?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript">
15+
<img src="https://img.shields.io/badge/Tailwind_CSS_v4-38B2AC?style=for-the-badge&logo=tailwind-css&logoColor=white" alt="Tailwind v4">
16+
<img src="https://img.shields.io/badge/Shadcn_UI-000000?style=for-the-badge&logo=shadcnui&logoColor=white" alt="Shadcn UI">
17+
<img src="https://img.shields.io/badge/Biome-60A5FA?style=for-the-badge&logo=biome&logoColor=white" alt="Biome">
18+
<img src="https://img.shields.io/badge/TanStack_Query-FF4154?style=for-the-badge&logo=reactquery&logoColor=white" alt="TanStack Query">
19+
<img src="https://img.shields.io/badge/TanStack_Router-FF4154?style=for-the-badge&logo=reactrouter&logoColor=white" alt="TanStack Router">
20+
<img src="https://img.shields.io/badge/Zustand-EA4335?style=for-the-badge&logo=react&logoColor=white" alt="Zustand">
21+
<img src="https://img.shields.io/badge/Husky-42b983?style=for-the-badge&logo=git&logoColor=white" alt="Husky">
22+
</p>
23+
24+
---
25+
26+
## 📖 Table of Contents
27+
- [Overview](#-overview)
28+
- [Why React Fluksos?](#-why-react-fluksos)
29+
- [Features](#-features)
30+
- [Getting Started](#-getting-started)
31+
- [Project Structure](#-project-structure)
32+
- [Scripts & Commands](#-scripts--commands)
33+
- [License](#-license)
34+
35+
---
36+
37+
## 🚀 Overview
38+
**React Fluksos** is a meticulously crafted, enterprise-grade React template engineered for performance, type safety, and impeccable Developer Experience (DX).
39+
40+
Designed as a definitive starting point for modern Single Page Applications (SPAs) and fast landing pages, it completely abandons legacy tools like ESLint and Prettier in favor of the blazing-fast Rust-based Biome toolchain.
41+
42+
## 🤔 Why React Fluksos?
43+
This project aims to eliminate the painful configuration phase of modern frontend development. It enforces strict architectural boundaries, utilizes the latest major versions of all core tools, and includes a pre-configured, battle-tested `pre-commit` hook pipeline.
44+
45+
It is the ultimate "Blank Canvas" for Senior Developers.
46+
47+
---
48+
49+
## 🎯 Features
50+
51+
- **Blazing Fast Builds**: Powered by Vite 8 and the official `@vitejs/plugin-react` (Rolldown-ready).
52+
- **Absolute Type Safety**: TypeScript 6.0 in Strict Mode, combined with `@tanstack/react-router` for 100% type-safe file-based routing.
53+
- **Modern Styling Engine**: Fully integrated with Tailwind CSS v4 (no PostCSS required) and Shadcn/ui CLI.
54+
- **State & Data Management**: Pre-configured `AppQueryProvider` (TanStack Query) with optimized caching strategies, plus a pre-wired `Axios` instance for API consumption.
55+
- **Rock-Solid DX**: Replaces ESLint/Prettier with Biome for instant formatting and linting. Enforces code quality via Husky `pre-commit` hooks and `lint-staged`.
56+
- **Built-in Theme Provider**: Elegant Dark/Light mode switching using pure Context API and Tailwind v4 variables.
57+
- **Robust Error Handling**: Global Error Boundaries and 404 Pages pre-configured at the routing root.
58+
59+
---
60+
61+
## 🏁 Getting Started
62+
63+
### Prerequisites
64+
This project demands modern tooling to run locally:
65+
- **Node.js**: v20 or higher.
66+
- **Package Manager**: Strictly `pnpm` (v9 or v10). NPM and Yarn will be rejected by engine locking.
67+
68+
### Installation
69+
70+
Clone the repository and set it up as your own:
71+
```bash
72+
git clone https://github.com/pasqualinigui/reactfluksos.git my-new-project
73+
cd my-new-project
74+
```
75+
76+
Install the dependencies:
77+
```bash
78+
pnpm install
79+
```
80+
81+
Configure environment variables:
82+
```bash
83+
cp .env.example .env
84+
```
85+
86+
### Usage
87+
Run the project locally in development mode:
88+
```bash
89+
pnpm run dev
90+
```
91+
92+
---
93+
94+
## 📁 Project Structure
95+
96+
```text
97+
src/
98+
├── components/
99+
│ ├── layout/ # Global layout wrappers
100+
│ ├── providers/ # Context providers (Theme, Query)
101+
│ └── ui/ # Shadcn/ui raw components
102+
├── features/ # Domain-driven modules
103+
├── lib/ # Utility functions and API instances (Axios)
104+
├── routes/ # TanStack file-based routes
105+
├── services/ # API integration layers
106+
└── store/ # Global state (Zustand)
107+
```
108+
109+
---
110+
111+
## 💻 Scripts & Commands
112+
113+
- `pnpm run dev`: Starts the Vite development server.
114+
- `pnpm run build`: Compiles the application for production (dist/).
115+
- `pnpm run typecheck`: Runs strict TypeScript validation without emitting files.
116+
- `pnpm run lint`: Analyzes the codebase using Biome.
117+
- `pnpm run lint:fix`: Automatically fixes linting errors and formats the code.
118+
- `pnpm run test`: Runs the Vitest test suite.
119+
120+
---
121+
122+
## 📜 License
123+
124+
Distributed under the MIT License. See `LICENSE` for more information.
125+
126+
<p align="left">
127+
<a href="#top">⬆️ Return to Top</a>
128+
</p>

‎biome.json‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
{
2+
"$schema": "https://biomejs.dev/schemas/2.4.8/schema.json",
3+
"vcs": {
4+
"enabled": true,
5+
"clientKind": "git",
6+
"useIgnoreFile": true
7+
},
8+
"files": {
9+
"ignoreUnknown": false,
10+
"includes": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.js", "src/**/*.jsx"]
11+
},
12+
"formatter": {
13+
"enabled": true,
14+
"indentStyle": "space",
15+
"indentWidth": 2,
16+
"lineEnding": "lf",
17+
"lineWidth": 100,
18+
"formatWithErrors": false
19+
},
20+
"linter": {
21+
"enabled": true,
22+
"rules": {
23+
"recommended": true,
24+
"style": {
25+
"noNonNullAssertion": "off",
26+
"useImportType": "error",
27+
"useBlockStatements": "off",
28+
"noUselessElse": "error"
29+
},
30+
"complexity": {
31+
"noExcessiveCognitiveComplexity": "off",
32+
"noUselessCatch": "error",
33+
"noVoid": "error"
34+
},
35+
"correctness": {
36+
"noUnusedImports": "error",
37+
"noUnusedVariables": "error",
38+
"useExhaustiveDependencies": "warn"
39+
},
40+
"suspicious": {
41+
"noExplicitAny": "error",
42+
"noEmptyInterface": "warn",
43+
"noArrayIndexKey": "error",
44+
"noDocumentCookie": "off"
45+
},
46+
"security": {
47+
"noDangerouslySetInnerHtml": "off"
48+
},
49+
"a11y": {
50+
"useFocusableInteractive": "off",
51+
"useSemanticElements": "off",
52+
"useAriaPropsForRole": "off"
53+
},
54+
"nursery": {
55+
"useSortedClasses": {
56+
"level": "warn",
57+
"options": {
58+
"attributes": ["className", "class"],
59+
"functions": ["cn", "cva"]
60+
}
61+
}
62+
}
63+
}
64+
},
65+
"javascript": {
66+
"formatter": {
67+
"quoteStyle": "single",
68+
"jsxQuoteStyle": "double",
69+
"trailingCommas": "es5",
70+
"semicolons": "always",
71+
"arrowParentheses": "always",
72+
"bracketSpacing": true,
73+
"bracketSameLine": false
74+
}
75+
},
76+
"assist": {
77+
"enabled": true,
78+
"actions": {
79+
"source": {
80+
"organizeImports": "on"
81+
}
82+
}
83+
}
84+
}

‎components.json‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
{
2+
"$schema": "https://ui.shadcn.com/schema.json",
3+
"style": "base-nova",
4+
"rsc": false,
5+
"tsx": true,
6+
"tailwind": {
7+
"config": "",
8+
"css": "src/globals.css",
9+
"baseColor": "neutral",
10+
"cssVariables": true,
11+
"prefix": ""
12+
},
13+
"iconLibrary": "lucide",
14+
"rtl": false,
15+
"aliases": {
16+
"components": "@/components",
17+
"utils": "@/lib/utils",
18+
"ui": "@/components/ui",
19+
"lib": "@/lib",
20+
"hooks": "@/hooks"
21+
},
22+
"menuColor": "default",
23+
"menuAccent": "subtle",
24+
"registries": {}
25+
}

0 commit comments

Comments
 (0)