Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
This document provides a comprehensive guide for setting up, understanding, and running the frontend-luan-van project. It is a Next.js application for an eyewear store, featuring a feature-based architecture, a dedicated service layer for business logic, and robust state management. The project is designed for deployment on Vercel and utilizes AI-assisted development practices.
The application is structured to separate concerns, with distinct directories for pages, shared components, feature-specific modules, services, and state management stores. This modular approach facilitates scalability and maintainability.
Project Setup
To get the project running locally, you need Node.js (version 20+) and pnpm as the package manager.
This diagram illustrates the basic setup and development workflow.
Sources: E2E_TESTING.md:7-12, package.json:5-11
Dependencies
The project relies on several key libraries for its functionality.
| Library | Version | Description |
|---|---|---|
next | 16.0.1 | The React framework for building the application. |
react | ^19 | The library for building user interfaces. |
axios | ^1.13.1 | Promise-based HTTP client for API communication. |
zustand | ^5.0.8 | A small, fast, and scalable state-management solution. |
@tanstack/react-query | ^5.90.7 | Server-state management library. |
@playwright/test | ^1.56.1 | End-to-end testing framework. |
jest | ^30.0.0 | JavaScript testing framework for unit tests. |
tailwindcss | ^4.1.9 | A utility-first CSS framework. |
shadcn/ui | - | UI components built using Radix UI and Tailwind CSS. |
zod | 3.25.76 | TypeScript-first schema declaration and validation. |
Sources: package.json:13-75
Available Scripts
The package.json file defines several scripts for common development tasks.
| Script | Command | Description |
|---|---|---|
dev | next dev -p 3001 | Starts the development server on port 3001. |
build | next build | Builds the application for production. |
start | next start -p 3001 | Starts the production server on port 3001. |
lint | eslint . | Lints the codebase for errors and style issues. |
test | jest | Runs unit tests using Jest. |
test:watch | jest --watch | Runs unit tests in watch mode. |
test:e2e | playwright test | Runs all end-to-end tests using Playwright. |
test:e2e:ui | playwright test --ui | Runs E2E tests in interactive UI mode. |
test:e2e:debug | playwright test --debug | Runs E2E tests in debug mode. |
Sources: package.json:5-11, E2E_TESTING.md:15-28
Architecture
The project follows a set of architectural principles to ensure code is organized, maintainable, and type-safe.
Sources: README.md:27-29, README.md:71-73
Project Structure
The repository is organized using a feature-based approach. Core logic is separated into directories like lib, services, and stores.
This diagram shows the high-level directory structure.
Sources: README.md:11-25
Architectural Principles
- Feature-based Organization: Each business feature (e.g.,
products,cart) is encapsulated in its own folder withinfeatures/, containing its own components, hooks, types, and utility functions. - Service Layer: Business logic, such as API calls and data transformation, is isolated in service classes (e.g.,
AdminProductsService). This makes the logic reusable across different parts of the application. - State Management: The application uses a combination of state management tools:
- Zustand: For global state like cart, user, and UI status.
- React Hooks: For local component state.
- React Query: For managing server state, caching, and data fetching.
- Type Safety: TypeScript is used throughout the project, with specific patterns like branded types for IDs and discriminated unions for API responses to ensure runtime safety. Zod is used for schema validation.
Sources: README.md:31-50, features/products/services/admin-products.service.ts
API Communication
All communication with the backend is handled by a centralized API client built with Axios.
Sources: lib/api-client.ts
API Client Configuration
The client is configured with a base URL and timeout. It also includes a special header to bypass ngrok browser warnings.
| Configuration | Value | Source |
|---|---|---|
BASE_URL | process.env.NEXT_PUBLIC_API_URL or http://localhost:3000 | lib/api-client.ts:24 |
TIMEOUT | 10000 (10 seconds) | lib/api-client.ts:25 |
RETRY_COUNT | 3 | lib/api-client.ts:26 |
RETRY_DELAY | 1000 (1 second) | lib/api-client.ts:27 |
Sources: lib/api-client.ts:23-28
Authentication and Token Refresh
The API client uses interceptors to manage authentication tokens automatically.
- Request Interceptor: Before any request is sent, the interceptor retrieves the
accessTokenfrom theuseAuthStoreand adds it to theAuthorizationheader. - Response Interceptor: If a request fails with a
401 Unauthorizedstatus, the interceptor attempts to refresh the token. It uses therefreshTokento call the/auth/refreshendpoint. If successful, it updates the tokens in the store and retries the original request with the newaccessToken. If the refresh fails, the user is logged out and redirected to the login page.
The following sequence diagram illustrates the token refresh flow.
Sources: lib/api-client.ts:43-116
API Helper Functions
The api-client.ts file provides a set of helper functions for making different types of HTTP requests. There are standard helpers (apiGet, apiPost, etc.) and validated helpers (apiGetValidated, apiPostValidated, etc.) that use Zod to parse and validate the response data against a provided schema.
Sources: lib/api-client.ts:168-278
Testing
The project includes configurations for both unit and end-to-end (E2E) testing to ensure code quality and application stability.
Unit Testing
Unit tests are written with Jest and React Testing Library. They can be executed by running the pnpm test command.
Sources: package.json:7
End-to-End Testing
E2E tests are implemented using Playwright. The configuration is located in playwright.config.ts and tests are stored in the e2e/ directory.
Key settings from E2E_TESTING.md:
- Base URL:
http://localhost:3000 - Browsers: Chromium, Firefox, WebKit
- Reports: HTML reports are generated in
playwright-report/
To run E2E tests, use the scripts defined in package.json:
pnpm test:e2e: Run all tests.pnpm test:e2e:ui: Run tests in an interactive UI mode.pnpm test:e2e:debug: Run tests in debug mode.
Sources: E2E_TESTING.md:15-43