From 9f043e0e26afd6b7f18cabb88fb484feee1ee165 Mon Sep 17 00:00:00 2001 From: Engincan VESKE Date: Wed, 6 May 2026 17:56:44 +0300 Subject: [PATCH] docs: update React UI overview navigation Co-authored-by: Cursor --- docs/en/docs-nav.json | 52 ++++ docs/en/framework/ui/react/index.md | 451 +++++----------------------- 2 files changed, 129 insertions(+), 374 deletions(-) diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index 8d2fcc6e10..56079eb813 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -1873,6 +1873,58 @@ "text": "Overview", "path": "framework/ui/react/index.md", "isIndex": true + }, + { + "text": "Configuration and Development", + "items": [ + { + "text": "Environment Variables", + "path": "framework/ui/react/environment-variables.md" + }, + { + "text": "Unit Testing", + "path": "framework/ui/react/unit-testing.md" + } + ] + }, + { + "text": "Core Features", + "items": [ + { + "text": "Authorization", + "path": "framework/ui/react/authorization.md" + }, + { + "text": "Localization", + "path": "framework/ui/react/localization.md" + }, + { + "text": "Permission Management", + "path": "framework/ui/react/permission-management.md" + }, + { + "text": "HTTP Requests", + "path": "framework/ui/react/http-requests.md" + } + ] + }, + { + "text": "Customization and Components", + "items": [ + { + "text": "Customization", + "path": "framework/ui/react/customization.md" + }, + { + "text": "Components", + "path": "framework/ui/react/components/index.md", + "isIndex": true + } + ] + }, + { + "text": "Admin Console", + "path": "framework/ui/react/admin-console.md" } ] }, diff --git a/docs/en/framework/ui/react/index.md b/docs/en/framework/ui/react/index.md index e5fd471543..4483e7c84f 100644 --- a/docs/en/framework/ui/react/index.md +++ b/docs/en/framework/ui/react/index.md @@ -1,439 +1,142 @@ ```json //[doc-seo] { - "Description": "Learn how to build modern web applications with ABP using React UI — a React-first approach with a dedicated Admin Console, built on Vite, shadcn/ui, Zod, and Axios." + "Description": "Learn how to build modern web applications with ABP React UI, including runtime configuration, authentication, Admin Console, shadcn/ui components, and testing." } ``` # React UI -## Introduction +ABP provides a **React UI** option for building modern, client-side web applications. React UI is part of the **modern template system** and is available with **ABP Studio v3.0+** through the Modern Wizard or with `abp new --modern` using [ABP CLI](../../../cli/index.md). -ABP provides a **React UI** option for building modern, client-side web applications. The React UI is part of the **modern template system** and is available when you create a solution through the **Modern Wizard** in [ABP Studio](../../../studio/index.md) or with `abp new --modern` using [ABP CLI](../../../cli/index.md). +React UI is not available in classic, non-modern templates. Use ABP Studio's modern template flow or `Volo.Abp.Studio.Cli` to create a React-based solution. -> React UI is **not** available in the classic (non-modern) templates. Use `Volo.Abp.Studio.Cli` or ABP Studio's modern template flow to create a React-based solution. The classic CLI path (`--old`) does not create modern React solutions. +## Technology Stack -The React UI is built on a modern, industry-standard stack: +The React UI template is built with: | Technology | Purpose | -|---|---| -| [Vite](https://vitejs.dev/) | Build tool and dev server | +| --- | --- | +| [Vite](https://vite.dev/) | Build tool and dev server | | [React](https://react.dev/) | UI framework | -| [shadcn/ui](https://ui.shadcn.com/) | Component library (built on Radix UI + Tailwind CSS) | +| [TanStack Router](https://tanstack.com/router) | Client-side routing | +| [TanStack Query](https://tanstack.com/query) | Server state and API request orchestration | +| [shadcn/ui](https://ui.shadcn.com/) | Source-owned component library built on Radix UI and Tailwind CSS | | [Zod](https://zod.dev/) | Schema validation | +| [React Hook Form](https://react-hook-form.com/) | Form state management | | [Axios](https://axios-http.com/) | HTTP client | | [Vitest](https://vitest.dev/) | Unit testing | -| [React Router](https://reactrouter.com/) | Client-side routing | -| [OpenID Connect / OIDC](https://openid.net/connect/) | Authentication (via the ABP Auth Server) | +| [OpenID Connect / OIDC](https://openid.net/connect/) | Authentication against the ABP Auth Server | -## React App and Admin Console - -When you create a modern solution with React UI, it contains two UI surfaces: **your React application** and the **ABP Admin Console**. - -### React App (Your Application) - -This is **your application** — the user-facing SPA that you own and customize freely. It comes with: - -- A sample **Books CRUD page** when the template is generated with sample CRUD support, demonstrating how to build a full create/read/update/delete page with the ABP backend -- A plain **Users page** as a minimal reference -- Pre-configured authentication via OIDC against the ABP Auth Server -- Pre-configured HTTP client (Axios) with ABP API integration - -This is where you build your business-specific pages and features. - -The location of the React app differs by template type: - -- **Layered (`app --modern`) and Single-layer (`app-nolayers --modern`)**: the React app lives in the `react/` folder at the solution root. -- **Microservice (`microservice --modern`)**: the React app lives at `apps/react/`. - -### React Admin Console (`Volo.Abp.AdminConsole`) - -The **ABP Admin Console** is a pre-built React application that provides all standard ABP module management pages. It is delivered via the `Volo.Abp.AdminConsole` NuGet package and requires no modification on your part — it is updated automatically when you update your ABP packages. - -The Admin Console includes pages for: - -- Users & Roles management -- Organization Units -- Settings -- Audit Logs -- OpenIddict (Application, Scope management) -- Language Management *(if included)* -- Text Template Management *(if included)* -- GDPR *(if included)* -- SaaS / Tenant Management *(if included)* -- And all other optional module pages based on your solution configuration - -How the Admin Console is hosted also differs by template type: - -- **Layered and Single-layer templates**: The `Volo.Abp.AdminConsole` package is added directly to your `*.HttpApi.Host` project. It serves the Admin Console React app at the `/admin-console/*` path of your backend (e.g., `https://localhost:44300/admin-console/`). There is no separate `apps/react-admin-console/` folder — the Admin Console UI is embedded in and served by the backend. -- **Microservice template**: The Admin Console runs as a standalone React app at `apps/react-admin-console/`, served through the Web Gateway (YARP) alongside the main React app. +The template also includes ABP-specific NPM packages: -In both cases the Admin Console is accessible from the main React app via a navigation link. +- [`@volo/abp-app-config`](https://github.com/volosoft/volo/tree/dev/abp/npm/packs/abp-app-config) +- [`@volo/abp-oidc-auth`](https://github.com/volosoft/volo/tree/dev/abp/npm/packs/abp-oidc-auth) +- [`@volo/abp-react-app-config`](https://github.com/volosoft/volo/tree/dev/abp/npm/packs/abp-react-app-config) +- [`@volo/abp-react-oidc-auth`](https://github.com/volosoft/volo/tree/dev/abp/npm/packs/abp-react-oidc-auth) -## Creating a Solution - -### Using ABP CLI - -Install or update `Volo.Abp.Studio.Cli`, then pass the `--modern` flag to `abp new`: - -````bash -# Layered app with React UI (default when --modern is used) -abp new Acme.BookStore --template app --modern - -# Single-layer app with React UI -abp new Acme.BookStore --template app-nolayers --modern - -# Microservice solution with React UI + React Admin Console -abp new Acme.BookStore --template microservice --modern -```` - -The `react` UI framework is the default when `--modern` is specified. You can also pass it explicitly: - -````bash -abp new Acme.BookStore --template app --modern --ui-framework react -```` - -To create a solution without any UI (API-only backend): +## React App and Admin Console -````bash -abp new Acme.BookStore --template app --modern --ui-framework no-ui -```` +A modern React solution contains two UI surfaces: -See the [ABP CLI documentation](../../../cli/index.md#modern-templates) for the full list of modern templates, supported UI/mobile combinations, and modern-only options like `--shadcn-theme`, `--admin-password`, `--modular`, and `--services`. +- **Your React application**: the developer-owned SPA where you build application-specific pages and features. +- **ABP Admin Console**: the React-based administration UI for ABP modules. -### Using ABP Studio +The Admin Console is provided by the `Volo.Abp.AdminConsole` NuGet package in layered and single-layer templates. In microservice templates, it is also generated as a separate `apps/react-admin-console/` app and served through the Web Gateway. -Open ABP Studio and use the **New Solution** wizard. Choose the modern template flow, select the solution type you want to create, and use **React** as the UI framework. The wizard shows the options supported by the selected modern template and generates the solution with the same modern template system used by `abp new --modern`. +See [Admin Console](./admin-console.md) for hosting, module discovery, and permission details. ## Solution Structure -The layout of the React-related files depends on the template type. +The React app location depends on the modern template type: -### Layered and Single-layer Templates +- **Layered (`app --modern`) and single-layer (`app-nolayers --modern`)**: the React app lives in the `react/` folder at the solution root. +- **Microservice (`microservice --modern`)**: the React app lives at `apps/react/`. -For `app --modern` and `app-nolayers --modern`, the React app lives in the `react/` folder at the solution root. The Admin Console is embedded in the backend via the `Volo.Abp.AdminConsole` NuGet package; there is no separate React Admin Console folder. +Typical structure: -``` -Acme.BookStore/ -├── react/ # Your React application -│ ├── src/ -│ │ ├── pages/ # Your page components -│ │ │ ├── books/ # Sample Books CRUD page -│ │ │ └── users/ # Sample Users page -│ │ ├── components/ # Shared UI components -│ │ ├── lib/ # Utilities, API clients -│ │ ├── hooks/ # Custom React hooks -│ │ └── main.tsx # Entry point -│ ├── public/ -│ │ └── dynamic-env.json # Runtime configuration -│ ├── package.json -│ └── vite.config.ts +```text +react/ +├── dynamic-env.json +├── public/ ├── src/ -│ ├── Acme.BookStore.Application/ -│ ├── Acme.BookStore.Domain/ -│ ├── Acme.BookStore.EntityFrameworkCore/ -│ └── Acme.BookStore.HttpApi.Host/ # Hosts Admin Console at /admin-console/* -└── ... -``` - -### Microservice Template - -For `microservice --modern`, both the React app and the React Admin Console are standalone apps under the `apps/` directory, each served through the Web Gateway (YARP). - -``` -Acme.BookStore/ -├── apps/ -│ ├── react/ # Your React application -│ │ ├── src/ -│ │ │ ├── pages/ -│ │ │ ├── components/ -│ │ │ ├── lib/ -│ │ │ ├── hooks/ -│ │ │ └── main.tsx -│ │ ├── public/ -│ │ │ └── dynamic-env.json # Runtime configuration -│ │ ├── package.json -│ │ └── vite.config.ts -│ ├── react-admin-console/ # ABP Admin Console (managed by ABP) -│ │ ├── public/ -│ │ │ └── dynamic-env.json -│ │ └── ... -│ └── auth-server/ # OpenIddict Auth Server -├── gateways/ -│ └── web/ # YARP reverse proxy for React apps -├── services/ -│ ├── identity/ -│ ├── administration/ -│ └── ... -└── ... -``` - -## Configuration - -### Runtime Configuration (`dynamic-env.json`) - -The React app reads its runtime configuration from `public/dynamic-env.json`. This file is loaded at startup and allows you to change settings without rebuilding the application, which is useful for different environments like development, staging, and production. - -```json -{ - "oAuthConfig": { - "issuer": "https://localhost:44301/", - "clientId": "Acme.BookStore_App", - "scope": "openid profile email offline_access BookStore" - }, - "apis": { - "default": { - "url": "https://localhost:44300", - "rootNamespace": "Acme.BookStore" - } - } -} -``` - -| Key | Description | -|---|---| -| `oAuthConfig.issuer` | URL of the OpenIddict Auth Server | -| `oAuthConfig.clientId` | The OpenIddict client ID registered for this app | -| `oAuthConfig.scope` | OAuth scopes to request | -| `apis.default.url` | Base URL of the backend API | -| `apis.default.rootNamespace` | Root namespace used for API proxy generation | - -For the **microservice** modern template, the `apis.default.url` points to the **Web Gateway** (YARP reverse proxy) instead of a single backend host. - -### Admin Console Configuration - -For the **microservice** template, the Admin Console has its own `dynamic-env.json` (at `apps/react-admin-console/public/dynamic-env.json`) and uses a separate OpenIddict client (`_AdminConsole`). - -For **layered and single-layer** templates, the Admin Console is embedded in the backend via the `Volo.Abp.AdminConsole` package and does not have a separate configuration file — it inherits its settings from the backend host. - -## Authentication - -Both the React app and the Admin Console authenticate using **OpenID Connect (OIDC)** against the ABP Auth Server (OpenIddict). The auth flow is handled transparently — when a user visits a protected page, they are redirected to the Auth Server login page and returned to the app after successful authentication. All clients use the **Authorization Code flow with PKCE**, which is the recommended flow for SPAs. - -The number of seeded OpenIddict clients depends on the template: - -- **Layered and Single-layer templates**: one client is seeded — `_App` for the React SPA. The Admin Console is embedded in the backend and shares the same authentication context. -- **Microservice template**: two clients are seeded — `_App` for the main React SPA and `_AdminConsole` for the standalone React Admin Console app. - -## Making API Calls - -The React app uses **Axios** as the HTTP client, pre-configured with: - -- The base URL from `dynamic-env.json` -- Automatic Bearer token injection from the OIDC session -- ABP-compatible error handling (reads `error.data` from ABP error responses) - -**Example: Fetching a list of books** - -```typescript -import { useQuery } from '@tanstack/react-query'; -import { apiClient } from '@/lib/api-client'; - -interface BookDto { - id: string; - name: string; - type: number; - publishDate: string; - price: number; -} - -interface PagedResult { - items: T[]; - totalCount: number; -} - -export function useBooks() { - return useQuery({ - queryKey: ['books'], - queryFn: () => - apiClient - .get>('/api/app/book') - .then((res) => res.data), - }); -} -``` - -## Localization - -The React app integrates with ABP's [localization system](../../../framework/fundamentals/localization.md). Localization resources are fetched from the backend at startup via the `/api/abp/application-configuration` endpoint and made available throughout the app. - -**Example: Using localization in a component** - -```typescript -import { useLocalization } from '@/hooks/use-localization'; - -export function MyComponent() { - const { l } = useLocalization('BookStore'); - - return

{l('Books')}

; -} -``` - -The `l(key)` function looks up the key in the loaded localization resources for the given resource name (`'BookStore'` in this example). - -## Authorization - -Permission checks are available via a hook that reads the current user's granted permissions from the ABP application configuration: - -```typescript -import { usePermissions } from '@/hooks/use-permissions'; - -export function BooksPage() { - const { isGranted } = usePermissions(); - - return ( -
- {isGranted('BookStore.Books.Create') && ( - - )} -
- ); -} +│ ├── components/ +│ ├── lib/ +│ ├── locales/ +│ ├── pages/ +│ ├── routes/ +│ └── main.tsx +├── package.json +├── vite.config.ts +└── vitest.config.ts ``` -Permissions are defined on the server side using ABP's [permission system](../../../framework/fundamentals/authorization/index.md) and are automatically available in the React app. - -## Tech Stack Details - -### shadcn/ui Components - -The React app uses [shadcn/ui](https://ui.shadcn.com/) as the component library. shadcn/ui is not a traditional npm package — components are copied directly into your project under `src/components/ui/`, giving you full ownership and the ability to customize them freely. - -Common components available out of the box include: `Button`, `Input`, `Table`, `Dialog`, `Form`, `Select`, `Tabs`, `Card`, `Badge`, `Dropdown Menu`, and more. - -### Form Validation with Zod - -Forms use [Zod](https://zod.dev/) schemas for validation, integrated with [React Hook Form](https://react-hook-form.com/): - -```typescript -import { z } from 'zod'; -import { useForm } from 'react-hook-form'; -import { zodResolver } from '@hookform/resolvers/zod'; +## Creating a Solution -const createBookSchema = z.object({ - name: z.string().min(1).max(128), - price: z.number().min(0), - publishDate: z.string(), -}); +Install or update `Volo.Abp.Studio.Cli`, then create a modern solution: -type CreateBookInput = z.infer; +```bash +# Layered app with React UI +abp new Acme.BookStore --template app --modern --ui-framework react -export function CreateBookForm() { - const form = useForm({ - resolver: zodResolver(createBookSchema), - }); +# Single-layer app with React UI +abp new Acme.BookStore --template app-nolayers --modern --ui-framework react - // ... -} +# Microservice solution with React UI +abp new Acme.BookStore --template microservice --modern --ui-framework react ``` -### Testing with Vitest - -The React app is pre-configured with [Vitest](https://vitest.dev/) for unit testing: - -```bash -# Run tests -npm run test - -# Run tests with coverage -npm run test:coverage -``` +You can also use ABP Studio v3.0+ and select the modern template flow in the New Solution wizard. The wizard preconfigures local ports, runtime configuration, OIDC clients, theme options, and React/Admin Console wiring based on the selected template and modules. ## Running the Application -### Development - -1. Start the backend (from ABP Studio or `dotnet run` in the `*.HttpApi.Host` project). -2. Navigate to the React app directory and start the dev server. +Start the backend from ABP Studio or by running the backend host projects, then start the React development server. -For **layered and single-layer** templates, the React app is in the `react/` folder at the solution root: +For layered and single-layer templates: -````bash +```bash cd react npm install npm run dev -```` +``` -For the **microservice** template, the React app is under `apps/`: +For microservice templates: -````bash +```bash cd apps/react npm install npm run dev -```` - -The app will be available at `https://localhost:3000` (or the port configured in `vite.config.ts`). - -3. Access the Admin Console: - - **Layered / Single-layer**: navigate to the backend URL + `/admin-console/` (e.g., `https://localhost:44300/admin-console/`). - - **Microservice**: navigate to the Web Gateway URL + `/admin-console/`. - -### Production Build - -````bash -# Layered / Single-layer -cd react && npm run build - -# Microservice -cd apps/react && npm run build -```` - -The output is placed in `dist/` and can be served by any static file host or CDN. - -## Accessing the Admin Console - -The Admin Console is accessible from within the main React app. After logging in, you will find a link to the Admin Console in the navigation. In layered and single-layer solutions it is served by the backend at `/admin-console/*`; in microservice solutions it is served as a standalone React app through the Web Gateway. - -The Admin Console provides full management capabilities for: - -- **Identity**: Users, Roles, Claims, Organization Units -- **OpenIddict**: Applications, Scopes -- **Settings**: Application-wide and tenant-level settings -- **Audit Logs**: View and filter audit log entries -- **Language Management** *(optional)* -- **Text Template Management** *(optional)* -- **GDPR** *(optional)* -- **SaaS / Tenant Management** *(optional)* -- **And more**, depending on the modules included in your solution - -## Customization - -### Adding New Pages - -Create a new file under `src/pages/` and register the route in the router configuration: +``` -```typescript -// src/router.tsx (or similar) -import { BooksPage } from './pages/books/books-page'; -import { MyNewPage } from './pages/my-feature/my-new-page'; +Run tests with: -const routes = [ - { path: '/books', element: }, - { path: '/my-feature', element: }, - // ... -]; +```bash +npm run test ``` -### Adding Menu Items +Build for production with: -Add entries to the navigation configuration to include your new pages in the sidebar or top navigation: - -```typescript -// src/config/navigation.ts (or similar) -export const navigationItems = [ - { label: 'Books', path: '/books', icon: BookIcon }, - { label: 'My Feature', path: '/my-feature', icon: StarIcon }, -]; +```bash +npm run build ``` -### Customizing shadcn/ui Components +## Documentation Map + +Use these pages to learn each part of the React UI: -Since shadcn/ui components live in `src/components/ui/`, you can modify them directly. For example, to change the default button variant or add a new variant, edit `src/components/ui/button.tsx`. +- [Environment Variables](./environment-variables.md): runtime configuration, `dynamic-env.json`, Vite variables, and Studio-generated defaults. +- [Authorization](./authorization.md): OIDC, Authorization Code flow with PKCE, auth provider, hooks, and route guards. +- [Localization](./localization.md): i18next, local JSON resources, ABP localization keys, and request culture. +- [Permission Management](./permission-management.md): fetching granted policies, `usePermissions()`, route protection, and conditional UI. +- [HTTP Requests](./http-requests.md): Axios setup, interceptors, typed API modules, and TanStack Query usage. +- [Customization](./customization.md): changing pages, themes, sidebar items, user menu entries, and shadcn/ui components. +- [Components](./components/index.md): component architecture, UI primitives, layout components, forms, and routing. +- [Unit Testing](./unit-testing.md): Vitest, React Testing Library, examples, and test workflow. +- [Admin Console](./admin-console.md): the `Volo.Abp.AdminConsole` package, `/admin-console/*` hosting, module discovery, and optional modules. ## See Also -- [ABP CLI — Modern Templates](../../../cli/index.md#modern-templates) - [ABP Studio](../../../studio/index.md) +- [ABP CLI](../../../cli/index.md) +- [Authorization](../../../framework/fundamentals/authorization/index.md) - [Localization](../../../framework/fundamentals/localization.md) -- [Authorization / Permissions](../../../framework/fundamentals/authorization/index.md) -- [Auto API Controllers](../../../framework/api-development/auto-controllers.md)