Frontend Template

A production-ready React template with authentication, protected routes, and modular architecture.

Tech Stack

React 19
Vite 7
TypeScript 5
TanStack Query (React Query)
React Router DOM 7
React Hook Form + Zod
Axios
Tailwind CSS 4
ESLint 9 + Prettier
Untitled UI React

Getting Started

pnpm install
pnpm dev

Open http://localhost:5173 with your browser to see the result.

Scripts

pnpm dev              # Start development server
pnpm build            # Build for production
pnpm preview          # Preview production build
pnpm lint             # Run ESLint with auto-fix
pnpm lint:check       # Run ESLint without auto-fix (CI)
pnpm format           # Format with Prettier
pnpm format:check     # Check formatting (CI)
pnpm type-check       # TypeScript type checking
pnpm generate:module  # Generate a new CRUD module

Environment Variables

Environment variables are validated at startup using Zod. If required variables are missing or invalid, the app will fail fast with helpful error messages.

Create a .env.local file:

VITE_API_BASE_URL=http://localhost:4000/api

To add new environment variables:

Add to the schema in src/libs/env.ts
Add to .env.example

import { env, isDev, isProd } from '@/libs/env';

const apiUrl = env.VITE_API_BASE_URL; // Type-safe, validated

CI/CD

Git Hooks (Husky)

pnpm install  # Automatically sets up husky via "prepare" script

Pre-commit:

Runs lint-staged (ESLint + Prettier on staged files)
Fixed files are automatically re-staged
Runs type-check on entire codebase

Pre-push:

Runs full build to catch build errors before pushing

GitHub Actions

CI runs on every push/PR to main:

Lint check
Format check
Type check
Build

See .github/workflows/ci.yml for configuration.

Docker

Build and run with Docker Compose:

docker compose up --build

Or build manually:

docker build -t frontend-template --build-arg VITE_API_BASE_URL=http://localhost:4000/api .
docker run -p 3000:80 frontend-template

Project Structure

src/
├── components/
│   ├── application/
│   │   ├── data-table/       # Generic DataTable component
│   │   ├── error-boundary/   # ErrorBoundary, QueryErrorBoundary
│   │   ├── app-navigation/   # Sidebar and header navigation
│   │   └── modals/           # Modal components
│   ├── base/
│   │   ├── _rhf/             # React Hook Form adapted components
│   │   └── [component]/      # Base UI components
│   ├── guards/               # Route guards (AuthGuard, GuestGuard, RoleGuard)
│   └── page-loading.tsx      # Full page loading
├── contexts/                 # React contexts
├── hooks/                    # Custom hooks
├── layouts/                  # Layout components
├── libs/
│   ├── storage/              # Token storage utilities
│   ├── validators/           # Zod validation schemas
│   ├── env.ts                # Environment configuration
│   └── usePageMetadata.ts    # Page title/description hook
├── modules/                  # Feature modules
│   ├── auth/                 # Authentication module
│   ├── users/                # Users CRUD module
│   └── common/               # Shared utilities and types
├── pages/                    # Page components
├── providers/                # App providers
├── routes/                   # Route configuration
├── services/                 # Axios instances
├── styles/                   # Global CSS
└── utils/                    # Utility functions

scripts/
├── generate-module.cjs       # Module generator script
└── templates/                # Generator templates
    ├── module/               # Module file templates
    └── page/                 # Page file templates

Naming Conventions

Type	Convention	Example
Module UI components	PascalCase	`SigninForm.tsx`
Page components	PascalCase	`DashboardPage.tsx`
Module type files	PascalCase	`AuthUser.ts`, `SigninRequest.ts`
Other files	kebab-case	`use-user-profile.ts`, `auth-api.ts`
Component exports	PascalCase	`UserProfile`
Hooks	camelCase with prefix	`useUserProfile`
Types	PascalCase	`AuthUser`
Validators	camelCase	`signinValidator`

Route Configuration

Routes are defined using createBrowserRouter with object-based configuration in src/routes/index.tsx:

export const router = createBrowserRouter([
    {
        path: "/",
        element: <RootLayout />,
        children: [
            { index: true, element: <HomePage /> },
            {
                path: "auth",
                element: <GuestGuard><AuthLayout /></GuestGuard>,
                children: [
                    { path: "login", element: <LoginPage /> },
                    { path: "register", element: <RegisterPage /> },
                ],
            },
            {
                path: "dashboard",
                element: <AuthGuard><EmailVerifiedGuard><DashboardLayout /></EmailVerifiedGuard></AuthGuard>,
                children: [
                    { index: true, element: <DashboardPage /> },
                ],
            },
        ],
    },
]);

Route Guards

AuthGuard

Protects routes requiring authentication. Redirects to /auth/login if not authenticated.

GuestGuard

For auth pages (login, register). Redirects to /dashboard if already authenticated.

EmailVerifiedGuard

Ensures user has verified email before accessing protected content.

RoleGuard

Restricts access based on user role hierarchy.

import { Role } from "@/modules/auth";

// In route configuration
{
    path: "users",
    element: (
        <RoleGuard minimumRole={Role.Admin} pageLevel>
            <UsersPage />
        </RoleGuard>
    ),
}

// Inline usage
<RoleGuard minimumRole={Role.Admin}>
    <AdminOnlyButton />
</RoleGuard>

Role-based Access Control

The auth module provides a role system with hierarchy:

// Role hierarchy (highest to lowest)
enum Role {
    Superadmin = "superadmin",
    Admin = "admin",
    User = "user",
}

// useRole hook for checking permissions
import { useRole, Role } from "@/modules/auth";

const { role, isAtLeast, isExactly } = useRole();

isAtLeast(Role.Admin);     // true if Admin or Superadmin
isExactly(Role.User);      // true only if User

// Role labels and badge colors for UI
import { ROLE_LABELS, ROLE_BADGE_COLORS } from "@/modules/auth";

<Badge color={ROLE_BADGE_COLORS[user.role]}>
    {ROLE_LABELS[user.role]}
</Badge>

Common Module Utilities

The @/modules/common module provides reusable factories and hooks.

createCrudAPI

Factory for creating standard CRUD API methods:

import { createCrudAPI } from '@/modules/common';

const crudAPI = createCrudAPI<Entity, CreateDTO, UpdateDTO, ListParams>({
  axios: axiosInstance,
  endpoint: '/entities',
});

// Returns: { getAll, getById, create, update, delete }

createQueryKeys

Factory for consistent query key patterns:

import { createQueryKeys } from '@/modules/common';

const entityKeys = createQueryKeys<ListParams>('entities');

// Returns:
// entityKeys.all         → ["entities"]
// entityKeys.lists()     → ["entities", "list"]
// entityKeys.list(params)→ ["entities", "list", params]
// entityKeys.details()   → ["entities", "detail"]
// entityKeys.detail(id)  → ["entities", "detail", id]

useTableFilters

Generic hook for managing table filters via URL search params:

import { useTableFilters } from '@/modules/common';

interface MyFilters extends BaseTableFilters {
  search: string;
  status: string;
}

const { filters, setFilter, setPage, resetFilters, hasActiveFilters } = useTableFilters<MyFilters>({
  defaults: { page: 1, limit: 10, search: '', status: '' },
  resetPageOn: ['search', 'status'], // Reset to page 1 when these change
});

Application Components

DataTable

Generic data table with loading states, pagination, and empty states:

import { DataTable, type ColumnDef } from "@/components/application/data-table/data-table";

const columns: ColumnDef<User>[] = [
    {
        id: "name",
        header: "Name",
        isRowHeader: true,
        cell: (user) => <span>{user.name}</span>,
    },
    {
        id: "actions",
        header: "",
        cell: (user) => <RowActions user={user} />,
    },
];

<DataTable
    data={users}
    columns={columns}
    isLoading={isLoading}
    meta={meta}
    page={filters.page}
    onPageChange={setPage}
    title="Users"
    badge={meta?.total}
    hasActiveFilters={hasActiveFilters}
    emptyState={{
        icon: Users01,
        title: "No users found",
        description: "There are no users to display.",
        filteredDescription: "No users match your filters.",
    }}
    headerContent={<Filters />}
/>

Error Boundaries

Catch and handle errors gracefully:

import { ErrorBoundary } from "@/components/application/error-boundary/error-boundary";
import { QueryErrorBoundary } from "@/components/application/error-boundary/query-error-boundary";

// For general React errors
<ErrorBoundary>
    <MyComponent />
</ErrorBoundary>

// For React Query errors (with retry integration)
<QueryErrorBoundary>
    <DataFetchingComponent />
</QueryErrorBoundary>

Page Metadata

Set page title and meta description for SEO:

import { usePageMetadata } from "@/libs/usePageMetadata";

export const UsersPage = () => {
    usePageMetadata({
        title: "Users",
        description: "Manage system users" // optional
    });

    return <div>...</div>;
};

Sidebar Navigation

Configure sidebar items in src/layouts/DashboardLayout/Sidebar.tsx:

import { Home03, Users01, Folder } from '@untitledui/icons';

const navItems: (NavItemType | NavItemDividerType)[] = [
  {
    label: 'Dashboard',
    href: '/dashboard',
    icon: Home03,
  },
  {
    label: 'Users',
    href: '/dashboard/users',
    icon: Users01,
  },
  {
    divider: true, // Section divider
    label: 'Settings', // Divider label (shown when expanded)
  },
  {
    label: 'Settings',
    href: '/dashboard/settings',
    icon: Settings01,
  },
];

The sidebar supports collapsed mode with icon-only navigation and horizontal dividers.

Query Key Factory

Query keys are defined in the module's constants/ folder:

// src/modules/users/constants/query-keys.ts
export const userQueryKeys = {
  all: ['users'] as const,
  profile: () => [...userQueryKeys.all, 'profile'] as const,
  detail: (id: string) => [...userQueryKeys.all, 'detail', id] as const,
  list: () => [...userQueryKeys.all, 'list'] as const,
};

Usage in services:

import { userQueryKeys } from '../constants';

export const useUserProfile = () => {
  return useQuery({
    queryKey: userQueryKeys.profile(),
    queryFn: usersAPI.getMe,
  });
};

Authentication System

Token Storage

Tokens are stored in localStorage:

import { tokenStorage } from '@/libs/storage';

tokenStorage.setTokens(accessToken, refreshToken);
tokenStorage.getAccessToken();
tokenStorage.getRefreshToken();
tokenStorage.clearTokens();
tokenStorage.hasValidToken();

Token Flow

Login/Register: Backend returns tokens → stored in localStorage
API Requests: Token added via axios interceptor (Authorization: Bearer ${token})
Token Refresh: On 401 response, refresh endpoint is called automatically
Logout: Tokens cleared from localStorage

Adding Protected Routes

Edit src/routes/index.tsx:

{
    path: "your-route",
    element: (
        <AuthGuard>
            <YourLayout />
        </AuthGuard>
    ),
    children: [...],
}

Module Structure

Each module follows a layered architecture:

modules/[module-name]/
├── api/
│   └── [module]API.ts        # API endpoint functions
├── constants/
│   ├── query-keys.ts         # Query key factory
│   └── index.ts              # Constants exports
├── libs/
│   ├── use[Module]Filters.ts # Table filter hooks
│   └── index.ts              # Libs exports
├── services/
│   └── use[Action].ts        # TanStack Query hooks
├── types/
│   ├── [TypeName].ts         # Individual type files (PascalCase)
│   └── index.ts              # Types exports
├── ui/
│   ├── [Module]Table.tsx     # Table component
│   ├── [Module]Filters.tsx   # Filters component
│   ├── Create[Entity]Modal.tsx
│   ├── Edit[Entity]Modal.tsx
│   ├── Delete[Entity]Dialog.tsx
│   └── index.ts              # UI exports
└── index.ts                  # Public module exports

Module Generator

The fastest way to create a new CRUD module:

pnpm generate:module <module-name>

Examples:

pnpm generate:module product    # Creates: products module
pnpm generate:module category   # Creates: categories module (handles irregular plurals)
pnpm generate:module person     # Creates: people module

What gets generated:

src/modules/<plural>/ - Complete module with types, API, services, libs, UI
src/pages/<Plural>Page.tsx - Page with CRUD functionality
Route at /dashboard/<plural>
Sidebar navigation item

Generated UI components:

<Plural>Table - DataTable with columns and row actions
<Plural>Filters - Search input with debounce
Create<Singular>Modal - Create form with validation
Edit<Singular>Modal - Edit form with pre-populated data
Delete<Singular>Dialog - Confirmation dialog

After generating, customize:

Update types in src/modules/<plural>/types/
Add columns to the table in ui/<Plural>Table.tsx
Add form fields to modals
Run pnpm type-check to verify

Manual Module Creation

For custom modules, create the folder structure manually:

// 1. Types
// src/modules/posts/types/Post.ts
export type Post = {
  id: string;
  title: string;
  content: string;
};

// 2. Query Keys (or use createQueryKeys factory)
// src/modules/posts/constants/query-keys.ts
import { createQueryKeys } from '@/modules/common';

export const postQueryKeys = createQueryKeys<PostsParams>('posts');

// 3. API (or use createCrudAPI factory)
// src/modules/posts/api/postsAPI.ts
import { createCrudAPI } from '@/modules/common';

export const postsAPI = createCrudAPI<Post, CreatePostRequest, UpdatePostRequest, PostsParams>({
  axios: axiosInstance,
  endpoint: '/posts',
});

// 4. Service hooks
// src/modules/posts/services/usePosts.ts
export const usePosts = (params: PostsParams) => {
  return useQuery({
    queryKey: postQueryKeys.list(params),
    queryFn: () => postsAPI.getAll(params),
  });
};

Validators

Validators use Zod and are located in src/libs/validators/.

// src/libs/validators/create-post.ts
import { z } from 'zod';

export const createPostValidator = z.object({
  title: z.string({ error: 'Title is required' }).min(1, 'Title is required'),
  content: z.string({ error: 'Content is required' }).min(1, 'Content is required'),
});

export type CreatePostFormData = z.infer<typeof createPostValidator>;

Usage with React Hook Form:

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { createPostValidator, CreatePostFormData } from '@/libs/validators/create-post';

const form = useForm<CreatePostFormData>({
  resolver: zodResolver(createPostValidator),
});

React Hook Form Components

RHF-adapted components are in src/components/base/_rhf/. They wrap base components with useController.

Available components:

RHFInput - Text input
RHFPasswordInput - Password input with visibility toggle
RHFTextarea - Textarea
RHFCheckbox - Checkbox

Usage:

import { RHFInput } from "@/components/base/_rhf/rhf-input";

<RHFInput
    name="email"
    control={form.control}
    label="Email"
    placeholder="Enter your email"
/>

Axios Instances

Two axios instances are available in src/services/index.ts:

axiosInstance (default export): For authenticated requests. Includes 401 interceptor that automatically refreshes tokens.
authAxiosInstance: For auth endpoints (login, register). No token refresh interceptor.

Theme System

Theme toggling uses class-based switching via ThemeProvider:

Light mode: light-mode class
Dark mode: dark-mode class
System mode: follows OS preference

import { useTheme } from '@/providers/theme-provider';

const { theme, setTheme, cycleTheme } = useTheme();
// theme: "light" | "dark" | "system"

Error Handling

Use getErrorMessage for consistent error messages:

import { getErrorMessage } from '@/modules/common';

onError: (error) => {
  toast.error(getErrorMessage(error, 'Failed to save'));
};

API Response Types

Generic pagination types are available in @/modules/common:

import { PaginatedResponse, PaginationMeta } from '@/modules/common';

// PaginationMeta structure
interface PaginationMeta {
  total: number;
  page: number;
  limit: number;
  totalPages: number;
  hasNextPage: boolean;
  hasPreviousPage: boolean;
}

// Usage with your data type
type PostsResponse = PaginatedResponse<Post>;
// Resolves to: { data: Post[]; meta: PaginationMeta; }

Code Style

Prefer editing existing files over creating new ones
Keep components focused and single-purpose
Use TypeScript strict mode
Run pnpm lint before committing
DO NOT write comments in code - Code should be self-documenting through clear naming and structure

AI Agent Guidelines

Rules and patterns for AI-assisted development.

Import Order

Imports must follow this order (enforced by ESLint):

// 1. React and external libraries
import { useState } from 'react';
import { useQuery } from '@tanstack/react-query';
import { z } from 'zod';

// 2. Internal modules (@/modules/*)
import { useUsers } from '@/modules/users';
import { Role } from '@/modules/auth';

// 3. Components (@/components/*)
import { DataTable } from '@/components/application/data-table/data-table';
import { Button } from '@/components/base/buttons/button';

// 4. Other internal imports (@/*)
import { usePageMetadata } from '@/libs/usePageMetadata';
import { cx } from '@/utils/cx';

// 5. Relative imports (../ and ./)
import { usePostsFilters } from '../libs';
import type { Post } from '../types';

Decision Rules

When to use Module Generator:

Creating a new CRUD resource with list/create/edit/delete
Standard REST API endpoints
Needs table, filters, and modals

When to create manually:

Non-CRUD features (auth, settings, dashboards)
Custom UI patterns
Complex business logic

When to use factories:

createCrudAPI → Standard REST endpoints (GET, POST, PUT, DELETE)
createQueryKeys → Any module with React Query
useTableFilters → Any paginated list with URL-synced filters

When to add to common module:

Utility is used by 2+ modules
Generic enough to be reusable
Not tied to specific business logic

Do NOT

// ❌ Don't use axios directly in components
const data = await axios.get("/users");

// ✅ Use module API layer
const data = await usersAPI.getUsers();

// ❌ Don't define query keys inline
useQuery({ queryKey: ["users", "list"] });

// ✅ Use query key factory
useQuery({ queryKey: userQueryKeys.list() });

// ❌ Don't create files outside module structure
src/helpers/userHelpers.ts

// ✅ Keep in module
src/modules/users/libs/userHelpers.ts

// ❌ Don't mix API calls with UI logic
const Component = () => {
    const response = await axiosInstance.get("/users");
};

// ✅ Use service hooks
const Component = () => {
    const { data } = useUsers();
};

// ❌ Don't duplicate types
type User = { id: string; name: string };
type UserData = { id: string; name: string };

// ✅ Reuse and extend
type UserWithPosts = User & { posts: Post[] };

// ❌ Don't hardcode strings for roles
if (user.role === "admin")

// ✅ Use Role enum
if (user.role === Role.Admin)

// ❌ Don't forget error boundaries for data fetching
<UsersTable />

// ✅ Wrap with QueryErrorBoundary
<QueryErrorBoundary>
    <UsersTable />
</QueryErrorBoundary>

// ❌ Don't skip page metadata
export const UsersPage = () => { ... }

// ✅ Always set page title
export const UsersPage = () => {
    usePageMetadata({ title: "Users" });
    ...
}

// ❌ Don't write comments in code
const getUser = () => { // Gets user data
    return usersAPI.getUsers();
};

// ✅ Code should be self-documenting
const getUser = () => {
    return usersAPI.getUsers();
};

Type Conventions

// Use `type` for object shapes and unions
type User = {
    id: string;
    name: string;
};

type Status = "active" | "inactive";

// Use `interface` for component props (enables declaration merging)
interface ButtonProps {
    children: ReactNode;
    onClick?: () => void;
}

// Request/Response types use PascalCase with suffix
type CreateUserRequest = { ... };
type UpdateUserRequest = { ... };
type UsersResponse = PaginatedResponse<User>;

// Filter types extend BaseTableFilters
interface UsersFilters extends BaseTableFilters {
    search: string;
    role: Role | "";
}

Component Patterns

Page component structure:

export const EntityPage = () => {
    // 1. Page metadata
    usePageMetadata({ title: "Entities" });

    // 2. State for modals
    const [isCreateOpen, setIsCreateOpen] = useState(false);
    const [editing, setEditing] = useState<Entity | null>(null);
    const [deleting, setDeleting] = useState<Entity | null>(null);

    // 3. Render
    return (
        <PageWrapper>
            <PageHeader>...</PageHeader>
            <PageContent>
                <QueryErrorBoundary>
                    <EntityTable onEdit={setEditing} onDelete={setDeleting} />
                </QueryErrorBoundary>
                <CreateEntityModal ... />
                <EditEntityModal ... />
                <DeleteEntityDialog ... />
            </PageContent>
        </PageWrapper>
    );
};

Table component structure:

export const EntityTable = ({ onEdit, onDelete }: Props) => {
    // 1. Filters hook
    const { filters, setPage, setSearch, hasActiveFilters } = useEntityFilters();

    // 2. Data fetching
    const { data, isLoading } = useEntities(filters);

    // 3. Column definitions (memoized)
    const columns = useMemo(() => [...], [onEdit, onDelete]);

    // 4. Render DataTable
    return <DataTable ... />;
};

Modal component structure:

export const CreateEntityModal = ({ isOpen, onClose }: Props) => {
    // 1. Mutation hook
    const { mutate, isPending } = useCreateEntity();

    // 2. Form setup
    const { control, handleSubmit, reset } = useForm({ resolver: zodResolver(schema) });

    // 3. Submit handler
    const onSubmit = (data) => {
        mutate(data, { onSuccess: () => { reset(); onClose(); } });
    };

    // 4. Render modal with form
    return <DialogTrigger isOpen={isOpen} ...>...</DialogTrigger>;
};

File Naming Quick Reference

What	Convention	Example
Page	`PascalCase` + Page	`UsersPage.tsx`
Module UI	`PascalCase`	`UsersTable.tsx`, `CreateUserModal.tsx`
Hooks	camelCase + use	`useUsers.ts`, `useCreateUser.ts`
API	camelCase + API	`usersAPI.ts`
Types	PascalCase	`User.ts`, `CreateUserRequest.ts`
Utils/libs	camelCase	`useUsersFilters.ts`
Constants	kebab-case	`query-keys.ts`

Resources

This template uses Untitled UI React components.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.github		.github
.husky		.husky
public		public
scripts		scripts
src		src
.cursorrules		.cursorrules
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.prettierrc		.prettierrc
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
README.md		README.md
bun.lock		bun.lock
docker-compose.yml		docker-compose.yml
eslint.config.js		eslint.config.js
index.html		index.html
nginx.conf		nginx.conf
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts
vite.svg		vite.svg

flexsw917/react_frontend

Folders and files

Latest commit

History

Repository files navigation

Frontend Template

Tech Stack

Getting Started

Scripts

Environment Variables

CI/CD

Git Hooks (Husky)

GitHub Actions

Docker

Project Structure

Naming Conventions

Route Configuration

Route Guards

AuthGuard

GuestGuard

EmailVerifiedGuard

RoleGuard

Role-based Access Control

Common Module Utilities

createCrudAPI

createQueryKeys

useTableFilters

Application Components

DataTable

Error Boundaries

Page Metadata

Sidebar Navigation

Query Key Factory

Authentication System

Token Storage

Token Flow

Adding Protected Routes

Module Structure

Module Generator

Manual Module Creation

Validators

React Hook Form Components

Axios Instances

Theme System

Error Handling

API Response Types

Code Style

AI Agent Guidelines

Import Order

Decision Rules

Do NOT

Type Conventions

Component Patterns

File Naming Quick Reference

Resources

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages