Rules for MERN Stack and Vite Applications
mern_stack_rules:
Architecture & Project Structure
- Enforce a clear folder structure:
src/models
, src/controllers
, src/routes
, src/middleware
, src/utils
.
- Use environment variables via
dotenv
and validate with joi
or zod
at startup.
- Define Express app in
app.js
, separate server startup in server.js
.
- Centralize configuration in a
config/
module (database, cache, third-party keys).
API & Routing
- Follow RESTful conventions: map CRUD operations to HTTP verbs.
- Use Express Router for modular route definitions; group by resource.
- Implement input validation with
joi
or zod
in middleware.
- Standardize responses:
{ success: boolean, data: any, error?: string }
.
Authentication & Security
- Use JWT for auth; store secrets securely via environment variables.
- Protect routes with auth middleware; allow role-based access controls.
- Sanitize user input to prevent injection attacks (e.g.,
express-validator
).
- Apply security headers via
helmet
, enable CORS via cors
.
Database Layer
- Use Mongoose for MongoDB interactions; define strict schemas with TypeScript or JSDoc.
- Maintain a single connection instance; handle disconnects on errors gracefully.
- Implement soft deletes with a
deletedAt
timestamp field pattern.
- Encapsulate database calls in service modules for testability.
Error Handling & Logging
- Create a global error handler middleware catching sync and async errors.
- Use custom Error classes (e.g.,
ValidationError
, AuthError
).
- Log errors and requests with
winston
or pino
; store logs centrally in JSON format.
Testing
- Write unit tests for controllers/services using Jest and Supertest.
- Mock external dependencies (DB, email) for isolated tests.
- Enforce 80% coverage; run tests in CI pipelines.
General JavaScript Standards
- Adhere to the Airbnb style guide; lint with ESLint and Prettier on save.
- Use ES6+ features:
async/await
, destructuring, modules.
- Avoid
any
in TypeScript; prefer strict typing and interfaces.
vite_app_rules:
Vite Configuration
- Define aliases in
vite.config.js
under resolve.alias
for @/components
, @/utils
.
- Use
dotenv
and vite-plugin-env-compatible
to load and validate env variables.
- Optimize dependencies with
optimizeDeps.include
and exclude
as needed.
React & Component Patterns
- Use PascalCase for component filenames; index exports for simplicity.
- Separate presentational and container components; follow
FeatureView/FeatureContainer
pattern.
- Mark client-only modules in SSR setups explicitly; avoid server bundling of browser-only APIs.
Styling & CSS
- Integrate Tailwind CSS via
tailwind.config.cjs
; use @apply
sparingly in CSS modules.
- Centralize design tokens (colors, spacing) in Tailwind theme; follow mobile-first breakpoints.
- Use
clsx
for conditional classNames; avoid inline style objects.
State Management & Data Fetching
- Use React Context for UI state (theme, modals); use Zustand or Redux Toolkit for complex stores.
- Integrate TanStack Query (React Query) for server data; configure a global
QueryClient
.
- Standardize query keys; handle staleTime and retry strategies.
Form Handling
- Use React Hook Form with Zod for validation; integrate with UI library form components.
- Show loading and error states using
formState
hooks.
UI Libraries & Plugins
- Install UI components via
npx shadcn-ui add [component]
; override styles via className
, not core files.
- Implement dark mode toggles with
next-themes
or useTheme
hooks.
Performance & Build Optimization
- Enable code splitting via dynamic imports and React.lazy.
- Use
@vitejs/plugin-react-swc
or similar for faster builds.
- Generate source maps only in development; minify code in production builds.
Testing & Linting
- Use Vitest for unit tests; mock modules with
vi.mock
.
- Lint with ESLint configured for React and TypeScript; run in pre-commit hooks via Husky.