mirror of https://github.com/abpframework/abp.git
maliming
2 weeks ago
20 changed files with 1936 additions and 441 deletions
|
After Width: | Height: | Size: 29 KiB |
|
After Width: | Height: | Size: 1.4 MiB |
|
After Width: | Height: | Size: 10 KiB |
|
After Width: | Height: | Size: 81 KiB |
|
After Width: | Height: | Size: 30 KiB |
@ -0,0 +1,116 @@ |
|||
# React UI for ABP Framework Is Finally Here |
|||
|
|||
If you have followed ABP for a while, you probably know that React support has been one of the most requested topics in the community. |
|||
|
|||
With **ABP 10.4.0-rc.1**, that wait ends. React in ABP is no longer just something people ask about, hope for, or imagine as the next step. You can now create it, run it, and explore it today as a beta/preview experience in the modern template system. |
|||
|
|||
As part of the ABP Framework team, and as one of the developers working on this React effort, I am genuinely happy to finally share it. This RC gives the community an early chance to try it, share feedback, and help us polish the final details before **ABP 10.4 stable**, where we plan to make the React UI generally available. |
|||
|
|||
 |
|||
|
|||
## Why this matters |
|||
|
|||
ABP Framework has always been about helping teams build modern, maintainable, production-ready applications faster. With the new React UI, we are extending that same vision to teams who want ABP on the backend and React on the frontend without losing the built-in application features that make ABP productive from day one. |
|||
|
|||
This is not another empty starter. The goal is a **first-class UI option** that fits into the ABP application startup experience and works naturally with familiar ABP concepts such as authentication, authorization, localization, multi-tenancy, modularity, runtime configuration, and deployment. |
|||
|
|||
There is one important detail: the React UI belongs to ABP's **modern template system**. You create it with the `--modern` flag in the ABP CLI or by selecting the modern template flow in ABP Studio. You can find the technical documentation here: [React UI documentation](https://abp.io/docs/10.4/framework/ui/react). |
|||
|
|||
## A quick look at the architecture |
|||
|
|||
The final shape is clearer now: a modern React solution gives you a real React application in the solution, plus the ABP administration experience. |
|||
|
|||
First, there is **your React application**. In the modern templates, this lives directly in the solution as a real app under `react/` or `apps/react/`. It contains the frontend code you work with every day, including pages, components, routing, API integration, runtime configuration, and authentication setup. |
|||
|
|||
Second, there is the **ABP Admin Console**. The Admin Console is a pre-built React application that provides the standard ABP module management pages. It is delivered through the `Volo.Abp.AdminConsole` NuGet package, so it can evolve with ABP package updates while your own React application stays focused on your product's business features. |
|||
|
|||
For layered and single-layer modern applications, the Admin Console is hosted by the backend and served under `/admin-console/*`. For microservice solutions, it runs as a separate React app under `apps/react-admin-console/`, with its own runtime configuration and the same `/admin-console/` base path. In both cases, the main React app can link users into the Admin Console when they need full administrative screens. |
|||
|
|||
This split is a practical design choice. Your business UI stays yours, while administration capabilities remain available, consistent, and upgradeable. |
|||
 |
|||
|
|||
## A different frontend philosophy |
|||
|
|||
One of the most important things to understand is that this React UI is **not** being shaped with exactly the same architecture as some previous UI options. |
|||
|
|||
We are not trying to ship the whole frontend experience as a closed set of page implementations coming from npm packages. Instead, the generated solution includes the actual page code inside the app itself. You can open it, understand it, refactor it, redesign it, and adapt it without fighting against a packaged black box. |
|||
|
|||
The Admin Console covers ABP's standard module administration pages. Your own React application remains intentionally open and direct. That gives teams a good balance: built-in administrative power from ABP, and full ownership of the product-facing frontend. |
|||
|
|||
## Built for AI-driven development |
|||
|
|||
The new React UI is also shaped for the era of **AI-assisted development**. |
|||
|
|||
React, TypeScript, Vite, TanStack Router, TanStack Query, Axios, Zod, React Hook Form, and shadcn/ui are technologies that modern coding assistants understand very well. Just as importantly, the generated application contains real frontend code in the solution. That gives AI tools and coding agents concrete project context to read, extend, and refactor. |
|||
|
|||
This direction also fits the broader ABP AI story. ABP Studio already includes an AI assistant experience, and the new **ABP AI Agent** is being introduced to bring code generation, project understanding, issue fixing, and natural-language application evolution directly into the ABP workflow. You can follow that work here: [The Future of ABP Studio: AI Agent + Code Generation](https://abp.io/community/events/community-talks/the-future-of-abp-studio-ai-agent-code-generation-live-fekeoyjr). For the wider toolset, see the [ABP AI Toolkit](https://abp.io/ai/toolkit). |
|||
|
|||
## What the React experience looks like |
|||
|
|||
The current template already points to the kind of experience React developers expect from a modern application: |
|||
|
|||
- A Vite-powered React + TypeScript frontend |
|||
- TanStack Router for client-side routing |
|||
- TanStack Query for server state and data fetching |
|||
- OIDC authentication against the ABP Auth Server |
|||
- Axios-based HTTP client integration |
|||
- Runtime configuration through `dynamic-env.json` |
|||
- Localization and permission-aware behavior integrated with ABP application configuration |
|||
- Tailwind CSS and shadcn/ui components that live in your project and can be customized directly |
|||
- Zod and React Hook Form for form handling and validation |
|||
- Vitest for frontend tests |
|||
- A dedicated Admin Console for ABP module administration |
|||
|
|||
Even in its current form, the React UI already feels like a real ABP solution experience, not just a login page plus a few demo screens. |
|||
|
|||
 |
|||
|
|||
## More than a hello world |
|||
|
|||
The generated React app is intentionally small enough to understand, but it is not empty. |
|||
|
|||
Out of the box, you already get the kind of foundation most teams expect: login, registration, forgot-password and reset-password flows, runtime configuration, localization, permission-aware routing, API proxy generation, and a simple users page that can deep-link into the Admin Console when full user management is needed. |
|||
|
|||
Depending on the selected options, it can also include a sample Books CRUD page that demonstrates how to build a full create/read/update/delete flow against an ABP backend. |
|||
|
|||
The Admin Console provides the standard management experience for ABP modules, including identity management, roles, organization units, settings, audit logs, OpenIddict administration, language management, text templates, GDPR, SaaS and tenant management, and other module pages depending on your solution configuration. |
|||
|
|||
That is the core value: developers get a clean React application to build their product, while ABP continues to provide the administrative capabilities expected from a production-ready application platform. |
|||
|
|||
## Try it with ABP 10.4 RC |
|||
|
|||
During the RC period, you can create a modern React solution with ABP 10.4.0-rc.1: |
|||
|
|||
```bash |
|||
abp new Acme.BookStore --template app --modern |
|||
``` |
|||
|
|||
The React UI is the default UI option when `--modern` is used, but you can also pass it explicitly: |
|||
|
|||
```bash |
|||
abp new Acme.BookStore --template app --modern --ui-framework react |
|||
``` |
|||
|
|||
For a single-layer application: |
|||
|
|||
```bash |
|||
abp new Acme.BookStore --template app-nolayers --modern |
|||
``` |
|||
|
|||
For a microservice solution: |
|||
|
|||
```bash |
|||
abp new Acme.BookStore --template microservice --modern |
|||
``` |
|||
|
|||
Once ABP 10.4 stable is released, the same modern React experience is planned to become generally available without needing to target the RC version explicitly. |
|||
|
|||
 |
|||
|
|||
## What's next |
|||
|
|||
The React UI is now real in ABP 10.4 RC, and the final polishing work continues toward the stable release. If you have been waiting for a real React path in ABP, this is the point where it stops being a wish and starts becoming something you can actually build with. |
|||
|
|||
For me, one of the nicest parts of this RC is that we can finally stop talking about React support in ABP as a future idea and start improving something real together. |
|||
|
|||
Try it, explore it, and share feedback with us while we keep polishing it for **ABP 10.4 stable**. |
|||
@ -0,0 +1,191 @@ |
|||
```json |
|||
//[doc-seo] |
|||
{ |
|||
"Description": "Learn how the ABP Admin Console works with React UI applications and how it is hosted under /admin-console." |
|||
} |
|||
``` |
|||
|
|||
# Admin Console |
|||
|
|||
The **ABP Admin Console** is the React-based administration UI for ABP applications. It provides management pages for ABP modules and is available in React UI solutions created with ABP Studio v3.0+ or `abp new --modern --ui-framework react`. |
|||
|
|||
The Admin Console is delivered as the `Volo.Abp.AdminConsole` NuGet package for layered and single-layer solutions. In microservice solutions, the template also includes a standalone `apps/react-admin-console/` React app. |
|||
|
|||
## What It Provides |
|||
|
|||
The Admin Console contains administration pages for the ABP modules included in the host application. Module pages are activated based on the backend services available in the host, so a solution only shows pages for modules it actually has. |
|||
|
|||
The built-in module areas include: |
|||
|
|||
| Module | Notes | |
|||
| --- | --- | |
|||
| Identity Pro | User, role, claim, and organization unit management when Identity services are available. | |
|||
| Account Pro | Account management pages and account-related flows. | |
|||
| OpenIddict | Application and scope management when OpenIddict services are available. | |
|||
| Audit Logging UI | Optional. Visible when Audit Logging services are available. | |
|||
| AI Management | Optional. Visible when AI Management services are available. | |
|||
| Text Template Management | Optional. Visible when Text Template Management services are available. | |
|||
|
|||
Other module pages, such as Setting Management, SaaS, GDPR, or customization pages, can also be available depending on the solution and installed modules. |
|||
|
|||
## Hosting Model |
|||
|
|||
The Admin Console is served under: |
|||
|
|||
```text |
|||
/admin-console/* |
|||
``` |
|||
|
|||
API endpoints used by the Admin Console are served under: |
|||
|
|||
```text |
|||
/admin-console/api/* |
|||
``` |
|||
|
|||
The `Volo.Abp.AdminConsole` package embeds the built React SPA under `wwwroot/admin-console/` and registers it with ABP's Virtual File System. `AdminConsoleSpaMiddleware` then serves static assets and falls back to `index.html` for client-side routes. |
|||
|
|||
The middleware deliberately lets `/admin-console/api/*` requests pass through to MVC controllers. |
|||
|
|||
## Layered and Single-Layer Templates |
|||
|
|||
For layered and single-layer modern templates: |
|||
|
|||
- The developer-owned React app is in the `react/` folder. |
|||
- The Admin Console UI is embedded in the backend through the `Volo.Abp.AdminConsole` NuGet package. |
|||
- There is no separate `react-admin-console/` source folder in the generated solution. |
|||
- The backend host serves Admin Console pages under `/admin-console/*`. |
|||
|
|||
Example URL: |
|||
|
|||
```text |
|||
https://localhost:44300/admin-console/ |
|||
``` |
|||
|
|||
The main React app links to the Admin Console through `getAdminConsoleUrl()`. |
|||
|
|||
## Microservice Template |
|||
|
|||
For the microservice modern template: |
|||
|
|||
- The main React app is in `apps/react/`. |
|||
- The Admin Console app is in `apps/react-admin-console/`. |
|||
- Both are served through the Web Gateway. |
|||
- The Admin Console has its own OpenIddict client, normally `<ProjectName>_AdminConsole`. |
|||
|
|||
The main React app uses `adminConsoleUrl` from `dynamic-env.json` to open the Admin Console origin and `/admin-console` base path. |
|||
|
|||
## Module Discovery |
|||
|
|||
The Admin Console calls: |
|||
|
|||
```text |
|||
GET /admin-console/api/modules |
|||
``` |
|||
|
|||
The backend checks for module application service contracts and returns which module areas are available. The discovery keys include: |
|||
|
|||
| Key | Backend service check | |
|||
| --- | --- | |
|||
| `identity` | `Volo.Abp.Identity.IIdentityUserAppService` | |
|||
| `saas` | `Volo.Saas.Host.ITenantAppService` | |
|||
| `auditLogging` | `Volo.Abp.AuditLogging.IAuditLogsAppService` | |
|||
| `gdpr` | `Volo.Abp.Gdpr.IGdprRequestAppService` | |
|||
| `openIddict` | `Volo.Abp.OpenIddict.Applications.IApplicationAppService` | |
|||
| `textTemplateManagement` | `Volo.Abp.TextTemplateManagement.TextTemplates.ITemplateDefinitionAppService` | |
|||
| `aiManagement` | AI Management service contracts, with a legacy AI engine fallback. | |
|||
|
|||
`settingManagement` is always returned as available by the discovery endpoint, while access to pages is still controlled by permissions. |
|||
|
|||
## Configuration Endpoint |
|||
|
|||
The Admin Console also uses: |
|||
|
|||
```text |
|||
GET /admin-console/api/config |
|||
``` |
|||
|
|||
This endpoint provides Admin Console runtime settings such as authority, client ID, scopes, application name, customization options, and localization language configuration. |
|||
|
|||
Host applications can configure Admin Console options from the `AdminConsole` configuration section or by configuring `AbpAdminConsoleOptions`. |
|||
|
|||
## Configuring the Admin Console |
|||
|
|||
In layered and single-layer modern React templates, the embedded Admin Console is configured from the backend host application's `appsettings.json` file. The generated template includes an `AdminConsole` section similar to the following: |
|||
|
|||
```json |
|||
{ |
|||
"AdminConsole": { |
|||
"IsEnabled": true, |
|||
"RedirectRootToAdminConsole": true, |
|||
"Authority": "https://localhost:44300", |
|||
"ClientId": "Acme_BookStore_AdminConsole", |
|||
"Scope": "openid profile email offline_access Acme_BookStore", |
|||
"LocalizationLanguages": [ "en", "tr" ], |
|||
"ThemeOverrideCssPath": "/theme-override.css", |
|||
"InitialTheme": "system", |
|||
"CustomizationPermissionName": "AdminConsole.Customization" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
You can also configure the same values in the module class with `AbpAdminConsoleOptions`: |
|||
|
|||
```csharp |
|||
public override void ConfigureServices(ServiceConfigurationContext context) |
|||
{ |
|||
Configure<AbpAdminConsoleOptions>(options => |
|||
{ |
|||
options.IsEnabled = true; |
|||
options.RedirectRootToAdminConsole = true; |
|||
options.Authority = "https://localhost:44300"; |
|||
options.ClientId = "Acme_BookStore_AdminConsole"; |
|||
options.Scope = "openid profile email offline_access Acme_BookStore"; |
|||
options.LocalizationLanguages = new[] { "en", "tr" }; |
|||
options.ThemeOverrideCssPath = "/theme-override.css"; |
|||
options.InitialTheme = "system"; |
|||
options.CustomizationPermissionName = "AdminConsole.Customization"; |
|||
}); |
|||
} |
|||
``` |
|||
|
|||
The most commonly changed options are: |
|||
|
|||
| Option | Description | |
|||
| --- | --- | |
|||
| `IsEnabled` | Enables or disables the embedded Admin Console SPA middleware. | |
|||
| `RedirectRootToAdminConsole` | Redirects the backend root path (`/`) to `/admin-console`. | |
|||
| `Authority` | OpenID Connect authority URL. If it is `null`, the host origin is used. | |
|||
| `ClientId` | OpenIddict client ID used by the Admin Console SPA. | |
|||
| `Scope` | Space-separated OAuth scopes requested by the Admin Console. | |
|||
| `LocalizationLanguages` | UI language codes exposed to the Admin Console. If empty, the frontend falls back to `en`. | |
|||
| `ThemeOverrideCssPath` | Optional CSS path or absolute URL injected into the Admin Console HTML. | |
|||
| `InitialTheme` | Initial theme behavior: `light`, `dark`, `system`, or `both`. | |
|||
| `CustomizationPermissionName` | Permission required to show and use the Admin Console customization page. If not set, customization is disabled. | |
|||
|
|||
The `ApplicationName`, `LogoUrl`, `InitialTheme`, and `ThemeOverrideCssPath` values can also be changed from the Admin Console customization UI when `CustomizationPermissionName` is configured and the current user has that permission. Values saved from the customization UI are stored as settings and override the defaults from configuration. |
|||
|
|||
In microservice solutions, the Admin Console is a separate React app under `apps/react-admin-console/`. It still uses its own OpenIddict client (`<ProjectName>_AdminConsole`) and runtime configuration, while the backend exposes the same `/admin-console/api/config` and `/admin-console/api/modules` endpoints. |
|||
|
|||
## Permissions |
|||
|
|||
Admin Console routes still require permissions. For example: |
|||
|
|||
- Identity pages use `AbpIdentity.*` permissions. |
|||
- OpenIddict pages use `OpenIddictPro.Application` and `OpenIddictPro.Scope`. |
|||
- Audit Logging uses `AuditLogging.AuditLogs`. |
|||
- Text Template Management uses `TextTemplateManagement.*`. |
|||
- AI Management uses `AIManagement.*`. |
|||
|
|||
The main React app's Admin Console menu item only requires authentication. The Admin Console performs detailed permission checks for its own pages. |
|||
|
|||
## Customization |
|||
|
|||
The developer-owned React app is intended for application-specific pages. The Admin Console is an ABP-managed administration surface and should normally be updated by updating ABP packages. |
|||
|
|||
For layered and single-layer hosts, the package supports host-side options such as application name, localization languages, and theme override CSS path. For larger UI changes, prefer building your own pages in the main React app or extending the backend modules through supported ABP extension points. |
|||
|
|||
## See Also |
|||
|
|||
- [React UI](./index.md) |
|||
- [Environment Variables](./environment-variables.md) |
|||
- [Permission Management](./permission-management.md) |
|||
@ -0,0 +1,183 @@ |
|||
```json |
|||
//[doc-seo] |
|||
{ |
|||
"Description": "Learn how authentication and authorization are configured in ABP React UI applications." |
|||
} |
|||
``` |
|||
|
|||
# Authorization in React UI |
|||
|
|||
OAuth is preconfigured in ABP React UI templates. When you create a React solution with ABP Studio v3.0+ or `abp new --modern --ui-framework react`, the template includes OpenID Connect settings, an OpenIddict client, route guards, and authentication hooks. |
|||
|
|||
The React app authenticates against the ABP Auth Server using the **Authorization Code flow with PKCE**, which is the recommended flow for browser-based applications. |
|||
|
|||
## Packages |
|||
|
|||
The template uses these packages for authentication: |
|||
|
|||
| Package | Purpose | |
|||
| --- | --- | |
|||
| `@volo/abp-oidc-auth` | Framework-agnostic OIDC client helpers for ABP/OpenIddict backends. | |
|||
| `@volo/abp-react-oidc-auth` | React adapter for the ABP OIDC client. | |
|||
| `oidc-client-ts` | Underlying OIDC protocol implementation. | |
|||
|
|||
The package list also includes `@volo/abp-app-config` and `@volo/abp-react-app-config`, which are used to fetch application configuration and permissions after authentication. |
|||
|
|||
## OAuth Configuration |
|||
|
|||
The OIDC settings are resolved from runtime configuration first and fall back to `src/env.ts`. |
|||
|
|||
```ts |
|||
export function getOAuthConfig(): { |
|||
issuer: string |
|||
redirectUri: string |
|||
clientId: string |
|||
scope: string |
|||
responseType: 'code' |
|||
} { |
|||
return { |
|||
issuer: loadedConfig?.oAuthConfig?.issuer ?? env.oauth.issuer, |
|||
redirectUri: loadedConfig?.oAuthConfig?.redirectUri ?? env.oauth.redirectUri, |
|||
clientId: loadedConfig?.oAuthConfig?.clientId ?? env.oauth.clientId, |
|||
scope: loadedConfig?.oAuthConfig?.scope ?? env.oauth.scope, |
|||
responseType: 'code', |
|||
} |
|||
} |
|||
``` |
|||
|
|||
The important configuration values are: |
|||
|
|||
- `oAuthConfig.issuer`: Auth Server / OpenIddict authority URL. |
|||
- `oAuthConfig.redirectUri`: URL where the Auth Server redirects after login. |
|||
- `oAuthConfig.clientId`: OpenIddict client ID, normally `<ProjectName>_App`. |
|||
- `oAuthConfig.scope`: Scopes requested by the React app. |
|||
|
|||
See [Environment Variables](./environment-variables.md) for the full runtime configuration model. |
|||
|
|||
## Initializing Authentication |
|||
|
|||
The app loads runtime configuration before initializing OIDC: |
|||
|
|||
```tsx |
|||
async function bootstrap() { |
|||
await loadRuntimeConfig() |
|||
initUserManager() |
|||
createRoot(document.getElementById('root')!).render( |
|||
<StrictMode> |
|||
<App /> |
|||
</StrictMode> |
|||
) |
|||
} |
|||
``` |
|||
|
|||
`initUserManager()` creates the ABP React OIDC client: |
|||
|
|||
```ts |
|||
client = createAbpReactOidcAuth({ |
|||
authority: config.issuer, |
|||
clientId: config.clientId, |
|||
redirectUri: config.redirectUri, |
|||
postLogoutRedirectUri: config.redirectUri, |
|||
scope: config.scope, |
|||
responseType: config.responseType, |
|||
automaticSilentRenew: true, |
|||
userStoreType: 'localStorage', |
|||
userStorePrefix: `oidc.${config.clientId}`, |
|||
silentRedirectUri: `${window.location.origin}/silent-renew.html`, |
|||
}) |
|||
``` |
|||
|
|||
The template stores the OIDC user in local storage and enables silent renewal with `public/silent-renew.html`. |
|||
|
|||
## Auth Provider and Hook |
|||
|
|||
`AuthProvider` wraps the app and handles the OIDC callback: |
|||
|
|||
```tsx |
|||
export function AuthProvider({ children }: { children: ReactNode }) { |
|||
const authClient = getAuthClient() |
|||
|
|||
useEffect(() => { |
|||
const params = new URLSearchParams(window.location.search) |
|||
if (!params.has('code') || !params.has('state')) return |
|||
void authClient.handleSigninCallback().then(() => |
|||
window.history.replaceState({}, document.title, window.location.pathname) |
|||
) |
|||
}, []) |
|||
|
|||
return <authClient.AuthProvider>{children}</authClient.AuthProvider> |
|||
} |
|||
``` |
|||
|
|||
Use `useAuth()` in components: |
|||
|
|||
```tsx |
|||
import { useAuth } from '@/lib/auth/AuthContext' |
|||
|
|||
export function LoginButton() { |
|||
const { isAuthenticated, isLoading, login, logout, user } = useAuth() |
|||
|
|||
if (isLoading) return null |
|||
|
|||
return isAuthenticated ? ( |
|||
<button onClick={() => void logout()}>{user?.name ?? 'Logout'}</button> |
|||
) : ( |
|||
<button onClick={() => void login()}>Login</button> |
|||
) |
|||
} |
|||
``` |
|||
|
|||
## Route Protection |
|||
|
|||
The React template uses TanStack Router. Protected routes use `beforeLoad` guards. |
|||
|
|||
```ts |
|||
const identityLayoutRoute = createRoute({ |
|||
getParentRoute: () => rootRoute, |
|||
path: '/identity', |
|||
component: IdentityLayout, |
|||
beforeLoad: authGuard, |
|||
}) |
|||
``` |
|||
|
|||
`authGuard` checks the current OIDC user and redirects unauthenticated users to the Auth Server: |
|||
|
|||
```ts |
|||
export async function authGuard({ location }: GuardContext) { |
|||
const user = await userManager.getUser() |
|||
if (!user || user.expired) { |
|||
await userManager.signinRedirect({ |
|||
state: { returnUrl: location.href }, |
|||
}) |
|||
throw new Error('Redirecting to login') |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Routes that also require a permission use `createPermissionGuard`: |
|||
|
|||
```ts |
|||
const usersRoute = createRoute({ |
|||
getParentRoute: () => identityLayoutRoute, |
|||
path: 'users', |
|||
component: UsersPage, |
|||
beforeLoad: createPermissionGuard('AbpIdentity.Users'), |
|||
}) |
|||
``` |
|||
|
|||
Permission checks are explained in [Permission Management](./permission-management.md). |
|||
|
|||
## OpenIddict Clients |
|||
|
|||
The generated OpenIddict clients depend on the template: |
|||
|
|||
- Layered and single-layer modern templates use the main React client, normally `<ProjectName>_App`. |
|||
- Microservice modern templates also include an Admin Console client, normally `<ProjectName>_AdminConsole`, because the Admin Console is a separate React app. |
|||
|
|||
If you change URLs after generation, update both the runtime configuration and the corresponding OpenIddict client redirect URLs. |
|||
|
|||
## See Also |
|||
|
|||
- [Environment Variables](./environment-variables.md) |
|||
- [Permission Management](./permission-management.md) |
|||
- [Authorization](../../../framework/fundamentals/authorization/index.md) |
|||
@ -0,0 +1,184 @@ |
|||
```json |
|||
//[doc-seo] |
|||
{ |
|||
"Description": "Learn about the component architecture and UI libraries used by ABP React UI applications." |
|||
} |
|||
``` |
|||
|
|||
# Components |
|||
|
|||
ABP React UI templates use a source-owned component architecture. The generated app includes shadcn/ui-style primitives, layout components, feature components, route pages, and shared infrastructure under `src/lib/`. |
|||
|
|||
The goal is to give you a working React application that you can customize without replacing framework-owned black boxes. |
|||
|
|||
## Component Structure |
|||
|
|||
The main React app is organized like this: |
|||
|
|||
```text |
|||
src/ |
|||
├── components/ |
|||
│ ├── layout/ |
|||
│ ├── ui/ |
|||
│ └── identity/ |
|||
├── lib/ |
|||
│ ├── api/ |
|||
│ ├── auth/ |
|||
│ ├── i18n/ |
|||
│ ├── routing/ |
|||
│ └── theme/ |
|||
├── locales/ |
|||
├── pages/ |
|||
└── routes/ |
|||
``` |
|||
|
|||
The exact folders can vary by selected template options and modules. |
|||
|
|||
## UI Stack |
|||
|
|||
The React template uses: |
|||
|
|||
| Library | Purpose | |
|||
| --- | --- | |
|||
| React | UI rendering. | |
|||
| Vite | Build tool and development server. | |
|||
| TanStack Router | Client-side routing. | |
|||
| TanStack Query | Server state, queries, mutations, and cache invalidation. | |
|||
| shadcn/ui-style components | Source-owned UI primitives built on Radix UI and Tailwind CSS. | |
|||
| Radix UI | Accessible low-level UI primitives. | |
|||
| Tailwind CSS | Utility-first styling and design tokens. | |
|||
| React Hook Form | Form state management. | |
|||
| Zod | Form and DTO validation schemas. | |
|||
| Axios | HTTP client. | |
|||
| i18next / react-i18next | Localization. | |
|||
| Zustand | Lightweight client state when needed. | |
|||
| Sonner | Toast notifications. | |
|||
| Lucide React | Icons. | |
|||
|
|||
## `components/ui` |
|||
|
|||
`src/components/ui/` contains reusable UI primitives. These components are copied into your project and can be edited directly. |
|||
|
|||
Common components include: |
|||
|
|||
- `Button` |
|||
- `Input` |
|||
- `Label` |
|||
- `Table` |
|||
- `Dialog` |
|||
- `DropdownMenu` |
|||
- `Select` |
|||
- `Card` |
|||
- `Tabs` |
|||
- `Badge` |
|||
- `DatePicker` |
|||
- `ConfirmDialog` |
|||
|
|||
Use these primitives to build application pages and feature components. |
|||
|
|||
```tsx |
|||
import { Button } from '@/components/ui/button' |
|||
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card' |
|||
|
|||
export function ReportCard() { |
|||
return ( |
|||
<Card> |
|||
<CardHeader> |
|||
<CardTitle>Reports</CardTitle> |
|||
</CardHeader> |
|||
<CardContent> |
|||
<Button>Refresh</Button> |
|||
</CardContent> |
|||
</Card> |
|||
) |
|||
} |
|||
``` |
|||
|
|||
## Layout Components |
|||
|
|||
Layout components are under `src/components/layout/`. |
|||
|
|||
Important components include: |
|||
|
|||
- `RootLayout`: root shell used by TanStack Router. |
|||
- `Header`: top bar, login button, theme toggle, and user menu. |
|||
- `Sidebar`: route-config-driven navigation menu. |
|||
- `UserMenu`: account-related dropdown menu. |
|||
|
|||
The sidebar reads `src/lib/routing/route-config.ts`, checks authentication and permissions, and renders internal or external links. |
|||
|
|||
## Feature Components |
|||
|
|||
Feature-specific components should live near the feature that owns them. For example, Identity-specific layout components live under `src/components/identity/`, while Books-specific UI is implemented in `src/pages/books/BooksPage.tsx` in the sample template. |
|||
|
|||
As a rule: |
|||
|
|||
- Put generic, reusable primitives in `components/ui`. |
|||
- Put application layout in `components/layout`. |
|||
- Put feature-specific components under `components/<feature>` or next to the page when they are only used by one page. |
|||
|
|||
## Pages |
|||
|
|||
Route pages live under `src/pages/`. A page usually combines: |
|||
|
|||
- UI primitives from `components/ui`. |
|||
- API functions from `src/lib/api`. |
|||
- Server state from TanStack Query. |
|||
- Form state from React Hook Form. |
|||
- Validation schemas from Zod. |
|||
- Permissions from `usePermissions()`. |
|||
- Localized strings from `useTranslation()`. |
|||
|
|||
The Books page is the best full CRUD reference when the sample CRUD option is selected. |
|||
|
|||
## Forms |
|||
|
|||
Forms use React Hook Form and Zod: |
|||
|
|||
```tsx |
|||
const productSchema = z.object({ |
|||
name: z.string().min(1, 'Required'), |
|||
price: z.number().min(0), |
|||
}) |
|||
|
|||
type ProductFormData = z.infer<typeof productSchema> |
|||
|
|||
const form = useForm<ProductFormData>({ |
|||
resolver: zodResolver(productSchema), |
|||
defaultValues: { |
|||
name: '', |
|||
price: 0, |
|||
}, |
|||
}) |
|||
``` |
|||
|
|||
This keeps runtime validation and TypeScript types close to each other. |
|||
|
|||
## Routing Components |
|||
|
|||
Routes are configured in `src/routes/router.tsx` with TanStack Router. Use: |
|||
|
|||
- `authGuard` for authenticated pages. |
|||
- `createPermissionGuard('Permission.Name')` for permission-protected pages. |
|||
- `RootLayout` and nested layouts for shared page structure. |
|||
|
|||
Menu entries are configured separately in `src/lib/routing/route-config.ts`, so route registration and navigation display can evolve independently. |
|||
|
|||
## API Components and Hooks |
|||
|
|||
API functions live under `src/lib/api/` and use the shared `api` Axios instance. Components normally consume these functions through TanStack Query: |
|||
|
|||
```tsx |
|||
const usersQuery = useQuery({ |
|||
queryKey: ['app', 'users', queryParams], |
|||
queryFn: () => getAppUsers(queryParams), |
|||
}) |
|||
``` |
|||
|
|||
This keeps HTTP details out of rendering components and gives you caching, loading states, refetching, and mutation invalidation. |
|||
|
|||
## See Also |
|||
|
|||
- [Customization](../customization.md) |
|||
- [HTTP Requests](../http-requests.md) |
|||
- [Unit Testing](../unit-testing.md) |
|||
@ -0,0 +1,208 @@ |
|||
```json |
|||
//[doc-seo] |
|||
{ |
|||
"Description": "Learn how to customize ABP React UI applications, including pages, themes, sidebar navigation, and the user menu." |
|||
} |
|||
``` |
|||
|
|||
# Customization |
|||
|
|||
The React app generated by ABP is fully owned by your solution. All source code is available, so you can change pages, components, routes, themes, menus, API calls, and layout behavior just like in any other React application. |
|||
|
|||
This page focuses on the main developer-owned React app. The same general approach applies to the public-web React app if your solution includes one. The Admin Console is an ABP-managed administration surface; see [Admin Console](./admin-console.md) for details. |
|||
|
|||
## General Customization |
|||
|
|||
Application pages live under `src/pages/`. The template includes practical references: |
|||
|
|||
- **Users page**: a simple page that lists users and links to the Admin Console for full user and role management. |
|||
- **Books page**: a full CRUD sample when the sample CRUD option is selected during solution creation. It demonstrates TanStack Query, forms, Zod validation, dialogs, tables, permissions, and toast notifications. |
|||
|
|||
Shared UI and infrastructure live under: |
|||
|
|||
```text |
|||
src/ |
|||
├── components/ |
|||
│ ├── layout/ |
|||
│ └── ui/ |
|||
├── lib/ |
|||
│ ├── api/ |
|||
│ ├── auth/ |
|||
│ ├── i18n/ |
|||
│ ├── routing/ |
|||
│ └── theme/ |
|||
└── pages/ |
|||
``` |
|||
|
|||
## Adding a Page |
|||
|
|||
Create a page under `src/pages/`: |
|||
|
|||
```tsx |
|||
export function ReportsPage() { |
|||
return ( |
|||
<div className="space-y-6"> |
|||
<h1 className="text-3xl font-bold tracking-tight">Reports</h1> |
|||
</div> |
|||
) |
|||
} |
|||
``` |
|||
|
|||
Register it with TanStack Router in `src/routes/router.tsx`: |
|||
|
|||
```tsx |
|||
const reportsRoute = createRoute({ |
|||
getParentRoute: () => rootRoute, |
|||
path: '/reports', |
|||
component: ReportsPage, |
|||
beforeLoad: createPermissionGuard('MyProjectName.Reports'), |
|||
}) |
|||
|
|||
const routeTree = rootRoute.addChildren([ |
|||
indexRoute, |
|||
reportsRoute, |
|||
]) |
|||
``` |
|||
|
|||
Use `authGuard` for pages that only require authentication and `createPermissionGuard` for pages that require a permission. |
|||
|
|||
## Theming |
|||
|
|||
The React template uses **shadcn/ui**-style components, Radix UI primitives, Tailwind CSS, and CSS variables. |
|||
|
|||
Theme tokens are defined in `src/styles/globals.css`: |
|||
|
|||
```css |
|||
:root { |
|||
--background: oklch(0.978 0.003 264); |
|||
--foreground: oklch(0.205 0.008 264); |
|||
--primary: oklch(0.48 0.10 278); |
|||
--radius: 0.5rem; |
|||
} |
|||
|
|||
.dark { |
|||
--background: oklch(0.16 0.004 264); |
|||
--foreground: oklch(0.92 0.005 264); |
|||
--primary: oklch(0.62 0.12 278); |
|||
} |
|||
``` |
|||
|
|||
ABP Studio's modern wizard can generate different shadcn theme color presets and light/dark/system theme behavior. |
|||
|
|||
## Changing Theme Colors |
|||
|
|||
To make a quick theme change, edit the CSS variables in `src/styles/globals.css`: |
|||
|
|||
```css |
|||
:root { |
|||
--primary: oklch(0.623 0.188 259.6); |
|||
--primary-foreground: oklch(1 0 0); |
|||
} |
|||
``` |
|||
|
|||
Because the generated shadcn/ui components consume these variables through Tailwind tokens, the change applies across buttons, links, active sidebar entries, focus rings, and other components that use the primary color. |
|||
|
|||
## Theme Mode Switcher |
|||
|
|||
Theme mode is handled by `src/lib/theme/ThemeProvider.tsx`. It supports: |
|||
|
|||
- `light` |
|||
- `dark` |
|||
- `system` |
|||
|
|||
The header cycles through the allowed modes: |
|||
|
|||
```tsx |
|||
const THEME_CYCLE: Theme[] = ['light', 'dark', 'system'] |
|||
|
|||
function ThemeToggle() { |
|||
const { theme, resolvedTheme, setTheme } = useTheme() |
|||
|
|||
function cycleTheme() { |
|||
const currentIndex = THEME_CYCLE.indexOf(theme) |
|||
const nextIndex = currentIndex < 0 ? 0 : (currentIndex + 1) % THEME_CYCLE.length |
|||
setTheme(THEME_CYCLE[nextIndex]) |
|||
} |
|||
|
|||
return <Button variant="ghost" size="icon" onClick={cycleTheme}>...</Button> |
|||
} |
|||
``` |
|||
|
|||
To remove the switcher or replace it with a dropdown, edit `src/components/layout/Header.tsx`. |
|||
|
|||
## Modifying the Sidebar Menu |
|||
|
|||
Sidebar navigation is defined in `src/lib/routing/route-config.ts`. |
|||
|
|||
Add a menu item: |
|||
|
|||
```ts |
|||
import { BarChart3 } from 'lucide-react' |
|||
|
|||
export const routeConfig: RouteConfigItem[] = [ |
|||
{ |
|||
path: '/reports', |
|||
nameKey: 'Menu:Reports', |
|||
icon: BarChart3, |
|||
order: 10, |
|||
requiredPolicy: 'MyProjectName.Reports', |
|||
}, |
|||
] |
|||
``` |
|||
|
|||
Then add the localization key to `src/locales/en.json`: |
|||
|
|||
```json |
|||
{ |
|||
"Menu:Reports": "Reports" |
|||
} |
|||
``` |
|||
|
|||
Use these properties depending on the menu item: |
|||
|
|||
| Property | Use | |
|||
| --- | --- | |
|||
| `path` | Internal route path or logical path for an external item. | |
|||
| `nameKey` | Localization key shown in the sidebar. | |
|||
| `icon` | Optional Lucide icon. | |
|||
| `order` | Sorting order. | |
|||
| `requiredPolicy` | Hide the item unless the permission is granted. | |
|||
| `requiresAuth` | Hide the item unless the user is authenticated. | |
|||
| `externalHref` | Open an external URL or another app, such as the Admin Console. | |
|||
| `children` | Add nested sidebar items. | |
|||
|
|||
## Sidebar vs User Menu |
|||
|
|||
Use the **sidebar navigation** for application pages and module entry points. |
|||
|
|||
Use the **user menu** for account-specific actions, profile links, sessions, security logs, linked accounts, and logout. The user menu is implemented in `src/components/layout/UserMenu.tsx`. |
|||
|
|||
Example user menu item: |
|||
|
|||
```tsx |
|||
<DropdownMenuItem asChild className="cursor-pointer"> |
|||
<a href="/account/preferences"> |
|||
<Settings className="size-4" /> |
|||
{t('MyAccount::Preferences')} |
|||
</a> |
|||
</DropdownMenuItem> |
|||
``` |
|||
|
|||
## Customizing UI Components |
|||
|
|||
shadcn/ui components are copied into your project under `src/components/ui/`. They are not black-box components from a package. You can edit them directly. |
|||
|
|||
For example: |
|||
|
|||
- Change button variants in `src/components/ui/button.tsx`. |
|||
- Change dialog structure in `src/components/ui/dialog.tsx`. |
|||
- Add a new reusable component under `src/components/ui/`. |
|||
- Add feature-specific components under `src/components/<feature>/`. |
|||
|
|||
Keep generic primitives in `components/ui` and business-specific components close to the feature or page that owns them. |
|||
|
|||
## See Also |
|||
|
|||
- [Components](./components/index.md) |
|||
- [Permission Management](./permission-management.md) |
|||
- [Admin Console](./admin-console.md) |
|||
@ -0,0 +1,121 @@ |
|||
```json |
|||
//[doc-seo] |
|||
{ |
|||
"Description": "Learn how runtime configuration and environment variables work in ABP React UI applications." |
|||
} |
|||
``` |
|||
|
|||
# Environment Variables |
|||
|
|||
ABP React UI applications use a runtime configuration file and Vite environment variables together. The template is preconfigured by ABP Studio's modern wizard, available with ABP Studio **v3.0+**, so a newly created solution already contains working local values for the API, Auth Server, OpenIddict client, and Admin Console link. |
|||
|
|||
You usually change these values when moving the application to another environment such as staging or production. |
|||
|
|||
## Configuration Sources |
|||
|
|||
The React template reads configuration from these places: |
|||
|
|||
- `dynamic-env.json`: runtime configuration that can be changed without rebuilding the application. |
|||
- `public/dynamic-env.json`: the file served by the app. The Vite build copies the root `dynamic-env.json` into this location when it exists. |
|||
- `src/env.ts`: local fallback values used when runtime configuration is not loaded. |
|||
- `.env` files / shell variables: Vite variables such as `VITE_API_URL`, `VITE_AUTH_URL`, and `VITE_APP_URL`. |
|||
|
|||
For layered and single-layer modern templates, the React app is in the `react/` folder. For the microservice modern template, it is in `apps/react/`. |
|||
|
|||
## `dynamic-env.json` |
|||
|
|||
The runtime configuration file has the same purpose as Angular's dynamic environment configuration: it lets you deploy the same build artifact to different environments and change the API or authentication endpoints at runtime. |
|||
|
|||
```json |
|||
{ |
|||
"application": { |
|||
"baseUrl": "https://localhost:3000", |
|||
"name": "Acme.BookStore" |
|||
}, |
|||
"oAuthConfig": { |
|||
"issuer": "https://localhost:44301/", |
|||
"redirectUri": "https://localhost:3000", |
|||
"clientId": "Acme_BookStore_App", |
|||
"scope": "offline_access openid profile email phone AuthServer IdentityService AdministrationService" |
|||
}, |
|||
"apis": { |
|||
"default": { |
|||
"url": "https://localhost:44300", |
|||
"rootNamespace": "Acme.BookStore" |
|||
} |
|||
}, |
|||
"adminConsoleUrl": "https://localhost:44307" |
|||
} |
|||
``` |
|||
|
|||
The template loads `/dynamic-env.json` first and then tries `/getEnvConfig` for compatibility with environments that expose the file through that endpoint. |
|||
|
|||
## Available Values |
|||
|
|||
| Key | Description | |
|||
| --- | --- | |
|||
| `application.baseUrl` | Public URL of the React application. It is used as a fallback for OAuth redirect URLs. | |
|||
| `application.name` | Application name. | |
|||
| `application.logoUrl` | Optional logo URL for application branding. | |
|||
| `oAuthConfig.issuer` | Auth Server / OpenIddict authority URL. | |
|||
| `oAuthConfig.redirectUri` | Redirect URI registered for the React OpenIddict client. | |
|||
| `oAuthConfig.clientId` | OpenIddict client ID. The main React app uses `<ProjectName>_App`. | |
|||
| `oAuthConfig.scope` | OAuth scopes requested by the SPA. | |
|||
| `apis.default.url` | Backend API base URL. In microservice solutions, this normally points to the Web Gateway. | |
|||
| `apis.default.rootNamespace` | Root namespace used by generated API code and module-specific clients. | |
|||
| `adminConsoleUrl` | Origin of the Admin Console app. The React template uses it to open `/admin-console`. | |
|||
|
|||
The `DynamicEnv` type also includes fields such as `production`, `oAuthConfig.requireHttps`, `oAuthConfig.responseType`, `oAuthConfig.strictDiscoveryDocumentValidation`, and `oAuthConfig.skipIssuerCheck`. The template's OIDC setup always uses the Authorization Code flow by setting `responseType` to `code`. |
|||
|
|||
## Vite Variables |
|||
|
|||
The React template uses Vite and reads environment variables with `loadEnv(mode, process.cwd(), '')`, so variables are not limited to the `VITE_` prefix inside `vite.config.ts`. |
|||
|
|||
The important variables for developers are: |
|||
|
|||
| Variable | Description | |
|||
| --- | --- | |
|||
| `VITE_API_URL` | Overrides the backend API or gateway URL used by the dev proxy and runtime fallback. | |
|||
| `VITE_AUTH_URL` | Overrides the Auth Server URL used by the dev proxy and runtime fallback. If omitted, the dev proxy can fall back to `VITE_API_URL`. | |
|||
| `VITE_APP_URL` | Overrides the React app URL used as the OAuth redirect URI fallback. | |
|||
|
|||
Example: |
|||
|
|||
```bash |
|||
VITE_API_URL=https://api.bookstore.example.com |
|||
VITE_AUTH_URL=https://auth.bookstore.example.com |
|||
VITE_APP_URL=https://bookstore.example.com |
|||
``` |
|||
|
|||
## What ABP Studio Preconfigures |
|||
|
|||
When a React solution is created with ABP Studio v3.0+ or `abp new --modern`, the template fills these values from the generated solution configuration: |
|||
|
|||
- Local launch ports for the React app, Web Gateway/API host, Auth Server, and Admin Console. |
|||
- The OpenIddict client ID, usually `<ProjectName>_App`. |
|||
- OAuth scopes based on the selected modules, such as Identity, Administration, SaaS, Audit Logging, GDPR, File Management, AI Management, Language Management, or Chat. |
|||
- `adminConsoleUrl` when the template includes a separate Admin Console application. |
|||
|
|||
For local development, these generated values should work without manual changes. For production, update the API URL, Auth Server URL, redirect URI, client ID if you changed the seeded client, and any environment-specific scopes. |
|||
|
|||
## Development Proxy |
|||
|
|||
In development, `vite.config.ts` proxies these paths: |
|||
|
|||
- `/api` to `VITE_API_URL` or the generated API/gateway URL. |
|||
- `/connect` to `VITE_AUTH_URL`, `VITE_API_URL`, or the generated Auth Server URL. |
|||
- `/getEnvConfig` to `VITE_API_URL` or the generated API/gateway URL. |
|||
|
|||
This allows the React app to call same-origin paths during development while the backend services run on their own ports. |
|||
|
|||
## Deployment |
|||
|
|||
For deployment, prefer changing `dynamic-env.json` instead of rebuilding the React application for each environment. The file should be served with `application/json` content type and should not be rewritten to `index.html` by SPA fallback rules. |
|||
|
|||
If your server exposes `/getEnvConfig`, configure it to return the same JSON content as `dynamic-env.json`. |
|||
|
|||
## See Also |
|||
|
|||
- [React UI](./index.md) |
|||
- [Authorization](./authorization.md) |
|||
- [HTTP Requests](./http-requests.md) |
|||
@ -0,0 +1,213 @@ |
|||
```json |
|||
//[doc-seo] |
|||
{ |
|||
"Description": "Learn how HTTP requests are made in ABP React UI applications with Axios, runtime configuration, and ABP interceptors." |
|||
} |
|||
``` |
|||
|
|||
# HTTP Requests |
|||
|
|||
ABP React UI templates use [Axios](https://axios-http.com/) for HTTP requests. The generated app contains a shared Axios instance with ABP-specific request and response interceptors, plus typed API modules for backend endpoints. |
|||
|
|||
The shared client is defined in `src/lib/api/axios.ts` and exported as `api`. |
|||
|
|||
## Base URL |
|||
|
|||
The Axios base URL is resolved at request time from runtime configuration: |
|||
|
|||
```ts |
|||
export function getApiBaseUrl(): string { |
|||
const apiUrl = getApiUrl() |
|||
if (apiUrl.startsWith('http://') || apiUrl.startsWith('https://')) { |
|||
return apiUrl.replace(/\/$/, '') + '/api' |
|||
} |
|||
if (import.meta.env.DEV) { |
|||
return '/api' |
|||
} |
|||
return apiUrl.replace(/\/$/, '') + '/api' |
|||
} |
|||
``` |
|||
|
|||
The API URL comes from: |
|||
|
|||
1. `dynamic-env.json` -> `apis.default.url` |
|||
2. `VITE_API_URL` |
|||
3. `src/env.ts` generated fallback |
|||
|
|||
In microservice solutions, `apis.default.url` normally points to the Web Gateway. In layered and single-layer solutions, it normally points to the HTTP API host. |
|||
|
|||
## Shared Axios Instance |
|||
|
|||
The template creates one shared instance: |
|||
|
|||
```ts |
|||
export const api = axios.create({ |
|||
baseURL: '', |
|||
headers: { |
|||
'X-Requested-With': 'XMLHttpRequest', |
|||
'Content-Type': 'application/json', |
|||
}, |
|||
}) |
|||
``` |
|||
|
|||
Use this instance for application API modules instead of creating new Axios clients. It centralizes ABP headers, authentication, tenant handling, language handling, and redirects. |
|||
|
|||
## Request Interceptor |
|||
|
|||
Before each request, the template: |
|||
|
|||
- Sets `baseURL` from runtime configuration. |
|||
- Adds `Authorization: Bearer <token>` from the OIDC user. |
|||
- Adds `__tenant` when the user has selected a tenant. |
|||
- Adds `Accept-Language` from i18next. |
|||
- Keeps default AJAX headers such as `X-Requested-With`. |
|||
|
|||
```ts |
|||
api.interceptors.request.use(async (config) => { |
|||
config.baseURL = getApiBaseUrl() |
|||
|
|||
const user = await userManager.getUser() |
|||
if (user?.access_token) { |
|||
config.headers.Authorization = `Bearer ${user.access_token}` |
|||
} |
|||
|
|||
const tenantId = sessionStorage.getItem('abp_tenant_id') |
|||
if (tenantId && !config.headers.__tenant) { |
|||
config.headers.__tenant = tenantId |
|||
} |
|||
|
|||
if (i18n?.language) { |
|||
config.headers['Accept-Language'] = |
|||
config.headers['Accept-Language'] ?? i18n.language |
|||
} |
|||
|
|||
return config |
|||
}) |
|||
``` |
|||
|
|||
## Response Interceptor |
|||
|
|||
The response interceptor handles common authorization failures: |
|||
|
|||
- `401 Unauthorized`: redirects to login unless `skipAuthRedirect` is set. |
|||
- `403 Forbidden`: redirects to `/403` unless `skip403Redirect` is set. |
|||
- Other errors are rejected so the caller can handle them. |
|||
|
|||
```ts |
|||
api.interceptors.response.use( |
|||
(response) => response, |
|||
async (error) => { |
|||
const status = error.response?.status |
|||
|
|||
if (status === 401 && !error.config?.skipAuthRedirect) { |
|||
await userManager.signinRedirect() |
|||
return Promise.reject(new Error('Unauthorized - redirecting to login')) |
|||
} |
|||
|
|||
if (status === 403 && !error.config?.skip403Redirect) { |
|||
window.location.href = '/403' |
|||
return Promise.reject(new Error('Forbidden')) |
|||
} |
|||
|
|||
return Promise.reject(error) |
|||
} |
|||
) |
|||
``` |
|||
|
|||
Use `skipAuthRedirect` or `skip403Redirect` for calls where the component should handle the error itself. |
|||
|
|||
## Typed API Modules |
|||
|
|||
The template organizes backend calls under `src/lib/api/`. For example, the Books sample defines DTOs and functions in `books.ts`: |
|||
|
|||
```ts |
|||
import { api } from './axios' |
|||
|
|||
export interface PagedResultDto<T> { |
|||
items: T[] |
|||
totalCount: number |
|||
} |
|||
|
|||
export interface BookDto { |
|||
id: string |
|||
name?: string |
|||
price: number |
|||
} |
|||
|
|||
export async function getBooks(): Promise<PagedResultDto<BookDto>> { |
|||
const { data } = await api.get<PagedResultDto<BookDto>>('/app/book', { |
|||
params: { |
|||
maxResultCount: 10, |
|||
skipCount: 0, |
|||
}, |
|||
}) |
|||
return data |
|||
} |
|||
``` |
|||
|
|||
Notice that the API module calls `/app/book`, not `/api/app/book`. The shared Axios base URL already includes the `/api` prefix when needed. |
|||
|
|||
## Using Requests from Components |
|||
|
|||
The template uses TanStack Query for server state: |
|||
|
|||
```tsx |
|||
const { data, isLoading } = useQuery({ |
|||
queryKey: ['books', skipCount], |
|||
queryFn: () => |
|||
getBooks({ |
|||
maxResultCount: 10, |
|||
skipCount, |
|||
sorting: 'creationTime desc', |
|||
}), |
|||
}) |
|||
``` |
|||
|
|||
Mutations use `useMutation` and invalidate related queries after success: |
|||
|
|||
```tsx |
|||
const createMutation = useMutation({ |
|||
mutationFn: createBook, |
|||
onSuccess: () => { |
|||
queryClient.invalidateQueries({ queryKey: ['books'] }) |
|||
toast.success(t('AbpUi::SavedSuccessfully')) |
|||
}, |
|||
}) |
|||
``` |
|||
|
|||
## Adding a New API Module |
|||
|
|||
Create a file under `src/lib/api/`: |
|||
|
|||
```ts |
|||
import { api } from './axios' |
|||
|
|||
export interface ProductDto { |
|||
id: string |
|||
name: string |
|||
} |
|||
|
|||
export async function getProducts(): Promise<ProductDto[]> { |
|||
const { data } = await api.get<ProductDto[]>('/app/product') |
|||
return data |
|||
} |
|||
``` |
|||
|
|||
Then consume it from a component with TanStack Query: |
|||
|
|||
```tsx |
|||
const productsQuery = useQuery({ |
|||
queryKey: ['products'], |
|||
queryFn: getProducts, |
|||
}) |
|||
``` |
|||
|
|||
## Development Proxy |
|||
|
|||
In development, Vite proxies `/api`, `/connect`, and `/getEnvConfig`. This lets the React app use same-origin paths while calls are forwarded to the backend, Auth Server, or gateway configured by `VITE_API_URL` and `VITE_AUTH_URL`. |
|||
|
|||
## See Also |
|||
|
|||
- [Environment Variables](./environment-variables.md) |
|||
- [Authorization](./authorization.md) |
|||
- [Permission Management](./permission-management.md) |
|||
@ -0,0 +1,158 @@ |
|||
```json |
|||
//[doc-seo] |
|||
{ |
|||
"Description": "Learn how localization works in ABP React UI applications with i18next and ABP application configuration." |
|||
} |
|||
``` |
|||
|
|||
# Localization |
|||
|
|||
ABP React UI templates use [i18next](https://www.i18next.com/) with [react-i18next](https://react.i18next.com/). The generated app includes local JSON resources and integrates with ABP application configuration through the `@volo/abp-app-config` packages. |
|||
|
|||
## Localization Files |
|||
|
|||
The main React app stores client-side translations under `src/locales/`. |
|||
|
|||
```text |
|||
src/ |
|||
├── locales/ |
|||
│ └── en.json |
|||
└── lib/ |
|||
└── i18n/ |
|||
└── i18n.ts |
|||
``` |
|||
|
|||
The default `i18n.ts` imports the English resource and registers it: |
|||
|
|||
```ts |
|||
import i18n from 'i18next' |
|||
import { initReactI18next } from 'react-i18next' |
|||
import en from '@/locales/en.json' |
|||
|
|||
i18n.use(initReactI18next).init({ |
|||
resources: { |
|||
en: { translation: en }, |
|||
}, |
|||
lng: 'en', |
|||
fallbackLng: 'en', |
|||
keySeparator: false, |
|||
nsSeparator: false, |
|||
interpolation: { |
|||
escapeValue: false, |
|||
}, |
|||
}) |
|||
``` |
|||
|
|||
`keySeparator` and `nsSeparator` are disabled so ABP-style keys such as `AbpIdentity::Users` and `Menu:Home` can be used directly. |
|||
|
|||
## Using Localized Text |
|||
|
|||
Use `useTranslation()` from `react-i18next` in components: |
|||
|
|||
```tsx |
|||
import { useTranslation } from 'react-i18next' |
|||
|
|||
export function BooksTitle() { |
|||
const { t } = useTranslation() |
|||
|
|||
return <h1>{t('Menu:Books')}</h1> |
|||
} |
|||
``` |
|||
|
|||
ABP localization keys commonly use the `ResourceName::Key` format: |
|||
|
|||
```tsx |
|||
{t('AbpIdentity::Users')} |
|||
{t('AbpAccount::Login')} |
|||
{t('AbpUi::SavedSuccessfully')} |
|||
``` |
|||
|
|||
Application-specific menu keys may use names like `Menu:Home` or `Menu:Books`. |
|||
|
|||
## Adding a Translation |
|||
|
|||
Add the key to `src/locales/en.json`: |
|||
|
|||
```json |
|||
{ |
|||
"Menu:Reports": "Reports", |
|||
"Reports": "Reports" |
|||
} |
|||
``` |
|||
|
|||
Then use it from a component: |
|||
|
|||
```tsx |
|||
const { t } = useTranslation() |
|||
|
|||
return <h1>{t('Reports')}</h1> |
|||
``` |
|||
|
|||
## Adding a Language |
|||
|
|||
Create a new JSON file, for example `src/locales/tr.json`: |
|||
|
|||
```json |
|||
{ |
|||
"Menu:Reports": "Raporlar", |
|||
"Reports": "Raporlar" |
|||
} |
|||
``` |
|||
|
|||
Register it in `src/lib/i18n/i18n.ts`: |
|||
|
|||
```ts |
|||
import en from '@/locales/en.json' |
|||
import tr from '@/locales/tr.json' |
|||
|
|||
i18n.use(initReactI18next).init({ |
|||
resources: { |
|||
en: { translation: en }, |
|||
tr: { translation: tr }, |
|||
}, |
|||
lng: 'en', |
|||
fallbackLng: 'en', |
|||
}) |
|||
``` |
|||
|
|||
If you add a language selector, call `i18n.changeLanguage('tr')` when the user chooses Turkish. |
|||
|
|||
## Server-Side ABP Localization |
|||
|
|||
ABP's backend localization system is still the source of truth for server-defined resources, validation messages, exception messages, and module texts. The React app uses ABP application configuration through `@volo/abp-app-config` / `@volo/abp-react-app-config` for auth and configuration data, and these packages can include localization resources when configured to do so. |
|||
|
|||
The main template currently creates the app configuration client with: |
|||
|
|||
```ts |
|||
export const appConfig = createAbpReactAppConfig({ |
|||
baseUrl: () => getApiUrl(), |
|||
includeLocalizationResources: false, |
|||
}) |
|||
``` |
|||
|
|||
Because `includeLocalizationResources` is disabled in the main React template, UI text is normally loaded from `src/locales/*.json`. If you enable server-provided localization resources, make sure your UI initialization merges them into i18next before rendering localized components. |
|||
|
|||
## Request Culture |
|||
|
|||
The shared Axios client sends the active i18next language with each request: |
|||
|
|||
```ts |
|||
if (i18n?.language) { |
|||
config.headers['Accept-Language'] = |
|||
config.headers['Accept-Language'] ?? i18n.language |
|||
} |
|||
``` |
|||
|
|||
This lets backend responses, validation messages, and exception messages use the selected culture when the server supports it. |
|||
|
|||
## Admin Console Localization |
|||
|
|||
The Admin Console has its own React app and localization setup. In layered and single-layer templates, it is served from the `Volo.Abp.AdminConsole` package. In microservice templates, it is generated as `apps/react-admin-console/`. |
|||
|
|||
The Admin Console host can expose available languages through `AdminConsole:LocalizationLanguages`, and `/admin-console/api/config` returns the normalized language list. |
|||
|
|||
## See Also |
|||
|
|||
- [React UI](./index.md) |
|||
- [HTTP Requests](./http-requests.md) |
|||
- [Localization](../../../framework/fundamentals/localization.md) |
|||
@ -0,0 +1,171 @@ |
|||
```json |
|||
//[doc-seo] |
|||
{ |
|||
"Description": "Learn how permissions are fetched, stored, checked, and applied in ABP React UI applications." |
|||
} |
|||
``` |
|||
|
|||
# Permission Management |
|||
|
|||
ABP permissions are defined on the server side and are exposed to the React app through ABP application configuration. The React template uses those permissions to protect routes, hide sidebar items, and conditionally render UI actions. |
|||
|
|||
For the server-side permission system, see [Authorization](../../../framework/fundamentals/authorization/index.md). |
|||
|
|||
## Packages |
|||
|
|||
The React template uses: |
|||
|
|||
| Package | Purpose | |
|||
| --- | --- | |
|||
| `@volo/abp-app-config` | Framework-agnostic ABP application configuration client. | |
|||
| `@volo/abp-react-app-config` | React hooks and adapters for application configuration. | |
|||
|
|||
The template creates a shared app configuration client in `src/lib/auth/permissions.ts`: |
|||
|
|||
```ts |
|||
export const appConfig = createAbpReactAppConfig({ |
|||
baseUrl: () => getApiUrl(), |
|||
includeLocalizationResources: false, |
|||
}) |
|||
``` |
|||
|
|||
## Fetching Permissions |
|||
|
|||
After the user logs in, `AuthProvider` fetches application configuration with the current access token: |
|||
|
|||
```ts |
|||
const user = await authClient.getUserManager().getUser() |
|||
if (user && !user.expired) { |
|||
await fetchAppConfig(user.access_token ?? null) |
|||
} |
|||
``` |
|||
|
|||
`fetchAppConfig` also sends the current tenant ID when one is selected: |
|||
|
|||
```ts |
|||
export async function fetchAppConfig(token: string | null): Promise<void> { |
|||
const headers: Record<string, string> = {} |
|||
const tenantId = sessionStorage.getItem('abp_tenant_id') |
|||
if (tenantId) headers.__tenant = tenantId |
|||
await appConfig.fetchConfig(token, { headers }) |
|||
} |
|||
``` |
|||
|
|||
The response includes the current user's granted policies. These are stored by the app configuration client and exposed to React components. |
|||
|
|||
## Checking Permissions in Components |
|||
|
|||
Use `usePermissions()` from `src/lib/auth/permissions.ts`: |
|||
|
|||
```tsx |
|||
import { usePermissions } from '@/lib/auth/permissions' |
|||
|
|||
export function BookActions() { |
|||
const { isGranted } = usePermissions() |
|||
|
|||
return ( |
|||
<> |
|||
{isGranted('MyProjectName.Books.Edit') && <button>Edit</button>} |
|||
{isGranted('MyProjectName.Books.Delete') && <button>Delete</button>} |
|||
</> |
|||
) |
|||
} |
|||
``` |
|||
|
|||
The Books page uses this pattern for edit and delete actions: |
|||
|
|||
```ts |
|||
const { isGranted } = usePermissions() |
|||
const canEdit = isGranted('MyProjectName.Books.Edit') |
|||
const canDelete = isGranted('MyProjectName.Books.Delete') |
|||
``` |
|||
|
|||
## Route Guards |
|||
|
|||
Routes can require a permission by using `createPermissionGuard`: |
|||
|
|||
```ts |
|||
const booksRoute = createRoute({ |
|||
getParentRoute: () => rootRoute, |
|||
path: '/books', |
|||
component: BooksPage, |
|||
beforeLoad: createPermissionGuard('MyProjectName.Books'), |
|||
}) |
|||
``` |
|||
|
|||
`createPermissionGuard` runs the authentication guard first, fetches app configuration if needed, and redirects to `/403` when the required policy is not granted. |
|||
|
|||
```ts |
|||
export function createPermissionGuard(requiredPolicy: string) { |
|||
return async (context: GuardContext) => { |
|||
await authGuard(context) |
|||
|
|||
if (!appConfig.getSnapshot()?.initialized) { |
|||
const user = await userManager.getUser() |
|||
await fetchAppConfig(user?.access_token ?? null) |
|||
} |
|||
|
|||
if (!isPolicyGranted(requiredPolicy)) throw redirect({ to: '/403' }) |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## Sidebar Visibility |
|||
|
|||
The sidebar reads `routeConfig` and hides items that require missing permissions: |
|||
|
|||
```ts |
|||
export const routeConfig: RouteConfigItem[] = [ |
|||
{ |
|||
path: '/identity/users', |
|||
nameKey: 'AbpIdentity::Users', |
|||
requiredPolicy: 'AbpIdentity.Users', |
|||
}, |
|||
] |
|||
``` |
|||
|
|||
The sidebar checks each item: |
|||
|
|||
```ts |
|||
if (item.requiresAuth && !isAuthenticated) return false |
|||
if (!item.requiredPolicy) return true |
|||
if (!isAuthenticated) return false |
|||
return isGranted(item.requiredPolicy) |
|||
``` |
|||
|
|||
Use `requiresAuth` for menu items that only require login. Use `requiredPolicy` when the item should only be visible to users with a specific permission. |
|||
|
|||
## Compound Policies |
|||
|
|||
The template's `isPolicyGranted` helper supports simple compound expressions: |
|||
|
|||
- `PermissionA || PermissionB` |
|||
- `PermissionA && PermissionB` |
|||
|
|||
This is useful for menu entries that should be visible when the user has one of several related module permissions. |
|||
|
|||
## Where Permissions Are Applied |
|||
|
|||
The generated React app uses permissions in these places: |
|||
|
|||
- **Users page**: the `/identity/users` route and sidebar entry require `AbpIdentity.Users`. The page links to the Admin Console for full user and role management. |
|||
- **Books page**: the route requires `MyProjectName.Books`; edit and delete actions check `MyProjectName.Books.Edit` and `MyProjectName.Books.Delete`. |
|||
- **Admin Console link**: the sidebar entry uses `requiresAuth` because the Admin Console performs its own module and route permission checks. |
|||
|
|||
The Admin Console applies module-specific permissions for pages such as: |
|||
|
|||
- Identity users and roles: `AbpIdentity.*`. |
|||
- OpenIddict applications and scopes: `OpenIddictPro.Application` and `OpenIddictPro.Scope`. |
|||
- Audit Logging UI: `AuditLogging.AuditLogs`. |
|||
- Text Template Management: `TextTemplateManagement.*`. |
|||
- AI Management: `AIManagement.*`. |
|||
|
|||
## Multi-Tenancy |
|||
|
|||
When a tenant is selected, the template stores the tenant ID in `sessionStorage` as `abp_tenant_id`. Permission and API requests send it with the `__tenant` header. This ensures the backend returns permissions and data for the selected tenant context. |
|||
|
|||
## See Also |
|||
|
|||
- [Authorization](./authorization.md) |
|||
- [HTTP Requests](./http-requests.md) |
|||
- [Authorization](../../../framework/fundamentals/authorization/index.md) |
|||
@ -0,0 +1,150 @@ |
|||
```json |
|||
//[doc-seo] |
|||
{ |
|||
"Description": "Learn how to run and write unit tests in ABP React UI applications with Vitest and React Testing Library." |
|||
} |
|||
``` |
|||
|
|||
# Unit Testing React UI |
|||
|
|||
ABP React UI templates are preconfigured for unit testing. A solution created with ABP Studio v3.0+ or `abp new --modern --ui-framework react` includes Vitest, jsdom, React Testing Library, and jest-dom. |
|||
|
|||
You can add a test file and run the test command without adding extra test infrastructure. |
|||
|
|||
## Test Stack |
|||
|
|||
The React template uses: |
|||
|
|||
| Package | Purpose | |
|||
| --- | --- | |
|||
| `vitest` | Test runner and assertion library. | |
|||
| `jsdom` | Browser-like DOM environment for component tests. | |
|||
| `@testing-library/react` | Render React components and query the DOM like a user. | |
|||
| `@testing-library/jest-dom` | Extra DOM assertions such as `toBeInTheDocument`. | |
|||
|
|||
The template also includes `src/test/setup.ts`, which imports `@testing-library/jest-dom/vitest` and initializes the React i18n setup. |
|||
|
|||
## Configuration |
|||
|
|||
The test configuration is in `vitest.config.ts`: |
|||
|
|||
```ts |
|||
import { defineConfig } from 'vitest/config' |
|||
import react from '@vitejs/plugin-react' |
|||
import path from 'path' |
|||
|
|||
export default defineConfig({ |
|||
plugins: [react()], |
|||
test: { |
|||
environment: 'jsdom', |
|||
setupFiles: ['./src/test/setup.ts'], |
|||
include: ['src/**/*.{test,spec}.{ts,tsx}'], |
|||
globals: true, |
|||
}, |
|||
resolve: { |
|||
alias: { |
|||
'@': path.resolve(__dirname, './src'), |
|||
}, |
|||
}, |
|||
}) |
|||
``` |
|||
|
|||
Tests can import application files with the same `@/` alias used by the app. |
|||
|
|||
## Running Tests |
|||
|
|||
Install dependencies once: |
|||
|
|||
```bash |
|||
npm install |
|||
``` |
|||
|
|||
Run tests in watch mode: |
|||
|
|||
```bash |
|||
npm run test |
|||
``` |
|||
|
|||
Run tests once, which is useful for CI: |
|||
|
|||
```bash |
|||
npm run test:run |
|||
``` |
|||
|
|||
The template's `package.json` maps these commands to `vitest` and `vitest run`. |
|||
|
|||
## Example Test |
|||
|
|||
The template includes example tests under `src/`. For example, `src/pages/home/HomePage.test.tsx` renders the home page and mocks the authentication hook: |
|||
|
|||
```tsx |
|||
import { describe, it, expect, vi, beforeEach } from 'vitest' |
|||
import { render, screen } from '@testing-library/react' |
|||
import { HomePage } from './HomePage' |
|||
import * as auth from '@/lib/auth/AuthContext' |
|||
|
|||
vi.mock('@/lib/auth/AuthContext', () => ({ |
|||
useAuth: vi.fn(), |
|||
})) |
|||
|
|||
describe('HomePage', () => { |
|||
beforeEach(() => { |
|||
vi.clearAllMocks() |
|||
}) |
|||
|
|||
it('renders login prompt when not authenticated', () => { |
|||
vi.mocked(auth.useAuth).mockReturnValue({ |
|||
isAuthenticated: false, |
|||
isLoading: false, |
|||
user: null, |
|||
login: vi.fn(), |
|||
logout: vi.fn(), |
|||
navigateToLogin: vi.fn(), |
|||
getAccessToken: vi.fn(), |
|||
} as unknown as ReturnType<typeof auth.useAuth>) |
|||
|
|||
render(<HomePage />) |
|||
expect(screen.getByText('Welcome')).toBeInTheDocument() |
|||
expect(screen.getByRole('button', { name: /login/i })).toBeInTheDocument() |
|||
}) |
|||
}) |
|||
``` |
|||
|
|||
This style keeps the test focused on visible behavior. Dependencies that would require real authentication, network calls, or browser redirects are mocked. |
|||
|
|||
## Writing a Component Test |
|||
|
|||
Create a `*.test.tsx` file next to the component: |
|||
|
|||
```tsx |
|||
import { render, screen } from '@testing-library/react' |
|||
import { describe, expect, it } from 'vitest' |
|||
import { Button } from '@/components/ui/button' |
|||
|
|||
describe('Button', () => { |
|||
it('renders its content', () => { |
|||
render(<Button>Save</Button>) |
|||
expect(screen.getByRole('button', { name: 'Save' })).toBeInTheDocument() |
|||
}) |
|||
}) |
|||
``` |
|||
|
|||
Prefer queries such as `getByRole`, `getByLabelText`, and `getByText` because they describe what the user can see or do. |
|||
|
|||
## Writing a Service or Hook Test |
|||
|
|||
For non-component logic, use Vitest directly. The template includes tests for routing guards, permissions, authentication context, and Axios interceptors. |
|||
|
|||
When testing API code, mock the shared Axios instance or the lower-level dependency instead of calling a real backend. When testing permission behavior, mock the application configuration client or use the exported permission helpers. |
|||
|
|||
## Interpreting Output |
|||
|
|||
Vitest reports each test file, failed assertions, stack traces, and a summary of passed/failed tests. In watch mode, it reruns affected tests when files change. In `test:run` mode, Vitest exits with a non-zero status code if any test fails, which makes it suitable for CI pipelines. |
|||
|
|||
If a component test fails because an ABP service is not initialized, mock the hook or provider used by the component. For example, pages that call `useAuth()` or `usePermissions()` should provide a controlled mock for those hooks unless the test is specifically verifying the provider. |
|||
|
|||
## See Also |
|||
|
|||
- [Components](./components/index.md) |
|||
- [Authorization](./authorization.md) |
|||
- [Permission Management](./permission-management.md) |
|||
Loading…
Reference in new issue