"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 |
| [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.
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).
│ ├── 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.
| `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 (`<ProjectName>_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 — `<ProjectName>_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 — `<ProjectName>_App` for the main React SPA and `<ProjectName>_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<T> {
items: T[];
totalCount: number;
}
export function useBooks() {
return useQuery({
queryKey: ['books'],
queryFn: () =>
apiClient
.get<PagedResult<BookDto>>('/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 <h1>{l('Books')}</h1>;
}
```
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 (
<div>
{isGranted('BookStore.Books.Create') && (
<button>Create Book</button>
)}
</div>
);
}
│ ├── 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<typeofcreateBookSchema>;
```bash
# Layered app with React UI
abp new Acme.BookStore --template app --modern --ui-framework react
export function CreateBookForm() {
const form = useForm<CreateBookInput>({
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: <BooksPage/> },
{ path: '/my-feature', element: <MyNewPage/> },
// ...
];
```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:
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.
Engincan VESKE
5 months ago