Users List Demo

This project is a demo application built with React, TypeScript, and TanStack technologies. It showcases a user list with pagination and filtering, detail pages, following modern best practices for data validation, type safety, and maintainability.

Table of contents

• Users List Demo
  • Table of contents
  • Setup and run the application
    • Prerequisites
    • Installation
    • Running the application
    • Building for production
    • Previewing the production build
  • Core principles
    • Type safety
    • Data validation
    • Linting & formatting
    • Data fetching
    • Error handling
  • Project structure
  • Scripts
  • Tools and libraries used
  • TODO
  • Learn More

---

Setup and run the application

Prerequisites

Make sure you have the following installed:

• node v.22
• pnpm

Installation

Clone the repository and install dependencies:

pnpm i

Running the application

Start the development server:

pnpm start

The app will be available at http://localhost:3000

Building for production

Build the application for production:

pnpm build

The output will be in the dist directory.

Previewing the production build

Preview the production build locally:

pnpm preview

---

Core principles

Type safety

• All code is written in TypeScript.
• Types are defined in src/types/ and used throughout the app for API responses, components, and route params.

Data validation

API responses are validated via zod to ensure data integrity and prevent runtime errors.

Linting & formatting

• Code quality is enforced using ESLint and Prettier.
• Run pnpm lint to check for lint errors and pnpm format to auto-format code.
• Code formatting is enforced with husky and lint staged, to ensure clean and standardized commits

Data fetching

• Uses TanStack Query for efficient data fetching and caching.
• Route loaders and React Query hooks are used for API calls and state management.

Error handling

• Error boundaries are implemented in src/components/ErrorBoundary/ to catch and display errors gracefully.

---

Project structure

src/
  api/           # API calls and data utilities
  components/    # Reusable UI components
  integrations/  # Third-party integrations (e.g., TanStack Query)
  localization/  # i18n setup and translation files
  pages/         # Page components
  routes/        # Route definitions (file-based)
  types/         # TypeScript type definitions
  ui/            # UI primitives (Avatar, Badge, Button, etc.)
  utils/         # Utility functions

Scripts

Script	Description
pnpm start	Start development server
pnpm build	Build for production
pnpm preview	Preview production build locally
pnpm lint	Run ESLint checks
pnpm format	Format code with Prettier
pnpm check	Type-check the project

Tools and libraries used

• React: UI library for building interactive interfaces
• TypeScript: Type safety and developer tooling
• Vite: Fast build tool and development server
• TanStack Router: File-based routing
• TanStack Query: Data fetching and caching
• Zod: Data validation
• usehooks-ts: A powerful set of custom hooks
• Tailwind CSS: Utility-first CSS framework
• ESLint & Prettier: Code quality and formatting

TODO

• Due to current DummyJSON API limitation, filters cannot be used simultaneously. Currently, the choosen UX is to limit filtering by a single property, but there are more approaches:

  • local filtering: if records are limited or performance are secondary, consider fetching all user entries and then filtering locally data
  • updating API: in a real-world application, where the backend is custom-developed, consider handling filtering via complex user query params or passing data inside request body.

• Extract loading components outside index and /user/${id} routes, providing a skeleton component, mostly similar to the final expected loaded page.

• Add page size inside pagination bar.

• Disable/hide TanStack dev tools in production mode.

Learn More

• TanStack Documentation
• React Documentation
• TypeScript Handbook
• Vite Documentation
• Tailwind CSS Documentation