mirror of https://github.com/abpframework/abp.git
Zeynep Gizem Fırat
5 months ago
1401 changed files with 83368 additions and 5259 deletions
@ -0,0 +1,16 @@ |
|||
<Project Sdk="Microsoft.NET.Sdk"> |
|||
|
|||
<PropertyGroup> |
|||
<OutputType>Exe</OutputType> |
|||
<TargetFramework>net10.0</TargetFramework> |
|||
<ImplicitUsings>enable</ImplicitUsings> |
|||
<Nullable>enable</Nullable> |
|||
<RootNamespace>Volo.Abp.Docs.SyntaxCheck</RootNamespace> |
|||
<AssemblyName>CheckDocsSyntax</AssemblyName> |
|||
</PropertyGroup> |
|||
|
|||
<ItemGroup> |
|||
<PackageReference Include="Scriban" /> |
|||
</ItemGroup> |
|||
|
|||
</Project> |
|||
@ -0,0 +1,347 @@ |
|||
using System.Text.Json; |
|||
using Scriban; |
|||
using Scriban.Runtime; |
|||
using Scriban.Syntax; |
|||
|
|||
// Validates the Scriban template syntax embedded in `docs/en/` Markdown files.
|
|||
//
|
|||
// For each input file we run `Template.Parse` and a strict-mode render with the
|
|||
// same parameter set the docs renderer injects at runtime (each docs-params.json
|
|||
// `<name>` and its `<name>_Value` companion, plus Document_Language_Code,
|
|||
// Document_Version and Release_Status). StrictVariables is enabled on purpose so
|
|||
// references that would otherwise be silently rendered as empty strings surface
|
|||
// as build failures here.
|
|||
//
|
|||
// Known limitations:
|
|||
// - Partial template inlining is not executed: partial bodies are loaded from
|
|||
// external storage at render time, so they cannot be resolved in CI. Files
|
|||
// under `docs/en/` currently have no `//[doc-template]` references; if one is
|
|||
// added later, errors inside the partial body must be reviewed manually.
|
|||
// - Cookie- and query-string-driven parameter overrides are not injected, but
|
|||
// their keys still resolve to empty strings because they layer on top of the
|
|||
// same `<name>` / `<name>_Value` entries that are already injected.
|
|||
|
|||
namespace Volo.Abp.Docs.SyntaxCheck; |
|||
|
|||
internal static class Program |
|||
{ |
|||
private const string DefaultDocsRoot = "docs/en"; |
|||
private const string DocsParamsFileName = "docs-params.json"; |
|||
|
|||
private static readonly string[] BuiltInVariables = |
|||
{ |
|||
"Document_Language_Code", |
|||
"Document_Version", |
|||
"Release_Status" |
|||
}; |
|||
|
|||
public static int Main(string[] args) |
|||
{ |
|||
var useGitHubAnnotations = Environment.GetEnvironmentVariable("GITHUB_ACTIONS") == "true"; |
|||
|
|||
var inputPaths = args.Length == 0 |
|||
? new[] { DefaultDocsRoot } |
|||
: args; |
|||
|
|||
var files = new List<string>(); |
|||
foreach (var path in inputPaths) |
|||
{ |
|||
if (File.Exists(path)) |
|||
{ |
|||
if (path.EndsWith(".md", StringComparison.OrdinalIgnoreCase)) |
|||
{ |
|||
files.Add(Path.GetFullPath(path)); |
|||
} |
|||
} |
|||
else if (Directory.Exists(path)) |
|||
{ |
|||
foreach (var file in Directory.EnumerateFiles(path, "*.md", SearchOption.AllDirectories)) |
|||
{ |
|||
files.Add(Path.GetFullPath(file)); |
|||
} |
|||
} |
|||
else |
|||
{ |
|||
Console.Error.WriteLine($"WARN: path does not exist: {path}"); |
|||
} |
|||
} |
|||
|
|||
if (files.Count == 0) |
|||
{ |
|||
Console.WriteLine("No markdown files to check."); |
|||
return 0; |
|||
} |
|||
|
|||
Dictionary<string, string> renderParameters; |
|||
try |
|||
{ |
|||
renderParameters = BuildRenderParameters(files); |
|||
} |
|||
catch (Exception ex) |
|||
{ |
|||
Console.Error.WriteLine($"ERROR: failed to load docs-params: {ex.Message}"); |
|||
if (useGitHubAnnotations) |
|||
{ |
|||
Console.WriteLine($"::error::docs-params: {EscapeAnnotation(ex.Message)}"); |
|||
} |
|||
return 1; |
|||
} |
|||
|
|||
var errorCount = 0; |
|||
var warningCount = 0; |
|||
var fileIssueCount = 0; |
|||
var repoRoot = TryFindRepoRoot(Directory.GetCurrentDirectory()); |
|||
|
|||
foreach (var file in files) |
|||
{ |
|||
var fileIssues = CheckFile(file, renderParameters); |
|||
if (fileIssues.Count == 0) |
|||
{ |
|||
continue; |
|||
} |
|||
|
|||
fileIssueCount++; |
|||
|
|||
foreach (var issue in fileIssues) |
|||
{ |
|||
if (issue.Severity == IssueSeverity.Error) |
|||
{ |
|||
errorCount++; |
|||
} |
|||
else |
|||
{ |
|||
warningCount++; |
|||
} |
|||
|
|||
var displayPath = repoRoot != null |
|||
? Path.GetRelativePath(repoRoot, file) |
|||
: file; |
|||
|
|||
var severityLabel = issue.Severity == IssueSeverity.Error ? "error" : "warning"; |
|||
|
|||
Console.WriteLine( |
|||
$"{displayPath}:{issue.Line}:{issue.Column}: {severityLabel}: [{issue.Kind}] {issue.Message}"); |
|||
|
|||
if (useGitHubAnnotations) |
|||
{ |
|||
var command = issue.Severity == IssueSeverity.Error ? "error" : "warning"; |
|||
Console.WriteLine( |
|||
$"::{command} file={displayPath},line={issue.Line},col={issue.Column}::" + |
|||
$"{issue.Kind}: {EscapeAnnotation(issue.Message)}"); |
|||
} |
|||
} |
|||
} |
|||
|
|||
Console.WriteLine(); |
|||
Console.WriteLine($"Checked {files.Count} markdown file(s). " + |
|||
$"{fileIssueCount} file(s) with issues, " + |
|||
$"{errorCount} error(s), {warningCount} warning(s)."); |
|||
|
|||
if (errorCount > 0 || warningCount > 0) |
|||
{ |
|||
Console.WriteLine(); |
|||
Console.WriteLine("Tip: wrap inline Scriban-looking text with `{%{{{ ... }}}%}` " + |
|||
"or wrap whole code blocks with `{%{` ... `}%}` to escape Scriban parsing."); |
|||
} |
|||
|
|||
return errorCount > 0 ? 1 : 0; |
|||
} |
|||
|
|||
private static List<Issue> CheckFile(string file, IReadOnlyDictionary<string, string> renderParameters) |
|||
{ |
|||
var issues = new List<Issue>(); |
|||
string content; |
|||
try |
|||
{ |
|||
content = File.ReadAllText(file); |
|||
} |
|||
catch (Exception ex) |
|||
{ |
|||
issues.Add(new Issue("Read", 1, 1, ex.Message, IssueSeverity.Error)); |
|||
return issues; |
|||
} |
|||
|
|||
var template = Template.Parse(content, file); |
|||
|
|||
foreach (var message in template.Messages) |
|||
{ |
|||
var severity = message.Type switch |
|||
{ |
|||
Scriban.Parsing.ParserMessageType.Error => IssueSeverity.Error, |
|||
Scriban.Parsing.ParserMessageType.Warning => IssueSeverity.Warning, |
|||
_ => (IssueSeverity?)null |
|||
}; |
|||
|
|||
if (severity is null) |
|||
{ |
|||
continue; |
|||
} |
|||
|
|||
var kind = severity == IssueSeverity.Error ? "ScribanParseError" : "ScribanParseWarning"; |
|||
|
|||
issues.Add(new Issue( |
|||
kind, |
|||
message.Span.Start.Line + 1, |
|||
message.Span.Start.Column + 1, |
|||
message.Message, |
|||
severity.Value)); |
|||
} |
|||
|
|||
if (template.HasErrors) |
|||
{ |
|||
return issues; |
|||
} |
|||
|
|||
try |
|||
{ |
|||
var context = new TemplateContext |
|||
{ |
|||
StrictVariables = true |
|||
}; |
|||
|
|||
var scriptObject = new ScriptObject(); |
|||
foreach (var entry in renderParameters) |
|||
{ |
|||
scriptObject[entry.Key] = entry.Value; |
|||
} |
|||
|
|||
context.PushGlobal(scriptObject); |
|||
template.Render(context); |
|||
} |
|||
catch (ScriptRuntimeException ex) |
|||
{ |
|||
issues.Add(new Issue( |
|||
"ScribanRenderError", |
|||
ex.Span.Start.Line + 1, |
|||
ex.Span.Start.Column + 1, |
|||
ex.OriginalMessage, |
|||
IssueSeverity.Error)); |
|||
} |
|||
catch (Exception ex) |
|||
{ |
|||
issues.Add(new Issue("ScribanRenderError", 1, 1, ex.Message, IssueSeverity.Error)); |
|||
} |
|||
|
|||
return issues; |
|||
} |
|||
|
|||
private static Dictionary<string, string> BuildRenderParameters(IEnumerable<string> files) |
|||
{ |
|||
// Reproduces the keys the docs renderer places into its parameter
|
|||
// dictionary before rendering a documentation page.
|
|||
var parameters = new Dictionary<string, string>(StringComparer.Ordinal); |
|||
|
|||
foreach (var name in BuiltInVariables) |
|||
{ |
|||
parameters[name] = string.Empty; |
|||
} |
|||
|
|||
foreach (var paramName in DiscoverParameterNames(files)) |
|||
{ |
|||
parameters[paramName] = string.Empty; |
|||
parameters[paramName + "_Value"] = string.Empty; |
|||
} |
|||
|
|||
return parameters; |
|||
} |
|||
|
|||
private static HashSet<string> DiscoverParameterNames(IEnumerable<string> files) |
|||
{ |
|||
var names = new HashSet<string>(StringComparer.Ordinal); |
|||
var visitedDirs = new HashSet<string>(StringComparer.OrdinalIgnoreCase); |
|||
|
|||
foreach (var file in files) |
|||
{ |
|||
var dir = Path.GetDirectoryName(file); |
|||
while (!string.IsNullOrEmpty(dir) && visitedDirs.Add(dir)) |
|||
{ |
|||
var candidate = Path.Combine(dir, DocsParamsFileName); |
|||
if (File.Exists(candidate)) |
|||
{ |
|||
AddNamesFromDocsParamsFile(candidate, names); |
|||
} |
|||
|
|||
var parent = Path.GetDirectoryName(dir); |
|||
if (string.IsNullOrEmpty(parent) || parent == dir) |
|||
{ |
|||
break; |
|||
} |
|||
|
|||
dir = parent; |
|||
} |
|||
} |
|||
|
|||
return names; |
|||
} |
|||
|
|||
private static void AddNamesFromDocsParamsFile(string path, HashSet<string> sink) |
|||
{ |
|||
// A malformed docs-params.json would silently shrink the injected
|
|||
// variable set and turn parameter file regressions into hard-to-debug
|
|||
// "variable not found" errors on otherwise-fine markdown. Surface the
|
|||
// failure directly so the contributor fixes the JSON instead.
|
|||
using var doc = JsonDocument.Parse(File.ReadAllText(path)); |
|||
|
|||
if (!doc.RootElement.TryGetProperty("parameters", out var parameters) || |
|||
parameters.ValueKind != JsonValueKind.Array) |
|||
{ |
|||
throw new InvalidDataException( |
|||
$"{path}: expected a top-level `parameters` array."); |
|||
} |
|||
|
|||
foreach (var parameter in parameters.EnumerateArray()) |
|||
{ |
|||
if (parameter.TryGetProperty("name", out var nameElement) && |
|||
nameElement.ValueKind == JsonValueKind.String) |
|||
{ |
|||
var name = nameElement.GetString(); |
|||
if (!string.IsNullOrWhiteSpace(name)) |
|||
{ |
|||
sink.Add(name); |
|||
} |
|||
} |
|||
} |
|||
} |
|||
|
|||
private static string? TryFindRepoRoot(string startDir) |
|||
{ |
|||
var current = new DirectoryInfo(startDir); |
|||
while (current != null) |
|||
{ |
|||
var gitPath = Path.Combine(current.FullName, ".git"); |
|||
if (Directory.Exists(gitPath) || File.Exists(gitPath)) |
|||
{ |
|||
return current.FullName; |
|||
} |
|||
|
|||
current = current.Parent; |
|||
} |
|||
|
|||
return null; |
|||
} |
|||
|
|||
private static string EscapeAnnotation(string text) |
|||
{ |
|||
// GitHub workflow command escaping. `%` must be encoded first so the
|
|||
// sequences we introduce below are not double-escaped.
|
|||
return text |
|||
.Replace("%", "%25") |
|||
.Replace("\r", "%0D") |
|||
.Replace("\n", "%0A") |
|||
.Replace(":", "%3A") |
|||
.Replace(",", "%2C"); |
|||
} |
|||
|
|||
private enum IssueSeverity |
|||
{ |
|||
Warning, |
|||
Error |
|||
} |
|||
|
|||
private readonly record struct Issue( |
|||
string Kind, |
|||
int Line, |
|||
int Column, |
|||
string Message, |
|||
IssueSeverity Severity); |
|||
} |
|||
@ -1,17 +1,21 @@ |
|||
# This workflow is intentionally disabled. |
|||
# The workflows that previously depended on this file now handle cancellation |
|||
# natively via per-workflow `concurrency` blocks. |
|||
# The styfle/cancel-workflow-action has been archived upstream and is no longer maintained. |
|||
# |
|||
# To re-enable manual cancellation, change `on: workflow_dispatch` back to `on: [push]` |
|||
# and restore the styfle step, but the native `concurrency` approach is preferred. |
|||
name: cancel-workflow |
|||
on: [push] |
|||
on: |
|||
workflow_dispatch: |
|||
permissions: |
|||
contents: read |
|||
|
|||
jobs: |
|||
cancel: |
|||
permissions: |
|||
actions: write # for styfle/cancel-workflow-action to cancel/stop running workflows |
|||
name: 'Cancel Previous Runs' |
|||
name: 'Disabled - See file header comment' |
|||
runs-on: ubuntu-latest |
|||
timeout-minutes: 3 |
|||
timeout-minutes: 1 |
|||
steps: |
|||
- uses: styfle/cancel-workflow-action@0.6.0 |
|||
with: |
|||
workflow_id: 10629,1299107,2792859,8268314 |
|||
access_token: ${{ github.token }} |
|||
- name: No-op |
|||
run: echo "Cancellation is handled via concurrency groups in each workflow." |
|||
|
|||
@ -0,0 +1,221 @@ |
|||
# Validates Scriban template syntax in PR-changed Markdown files under docs/en/, |
|||
# so escape issues are caught before they reach the published documentation. |
|||
|
|||
name: Check Docs Syntax |
|||
|
|||
on: |
|||
pull_request: |
|||
paths: |
|||
- 'docs/en/**/*.md' |
|||
- 'docs/en/docs-params.json' |
|||
- '.github/scripts/CheckDocsSyntax/**' |
|||
- '.github/workflows/check-docs-syntax.yml' |
|||
|
|||
permissions: |
|||
contents: read |
|||
pull-requests: write |
|||
|
|||
jobs: |
|||
check-scriban-syntax: |
|||
name: Validate Scriban syntax in docs/en |
|||
runs-on: ubuntu-latest |
|||
|
|||
steps: |
|||
- name: Checkout |
|||
uses: actions/checkout@v4 |
|||
|
|||
- name: Setup .NET |
|||
uses: actions/setup-dotnet@v4 |
|||
with: |
|||
dotnet-version: '10.0.x' |
|||
|
|||
- name: Build syntax checker |
|||
run: dotnet build .github/scripts/CheckDocsSyntax/CheckDocsSyntax.csproj -c Release --nologo -v minimal |
|||
|
|||
- name: Get changed markdown files |
|||
id: changed |
|||
uses: actions/github-script@v7 |
|||
with: |
|||
script: | |
|||
const prNumber = context.payload.pull_request.number; |
|||
const changed = []; |
|||
let paramsChanged = false; |
|||
let page = 1; |
|||
while (true) { |
|||
const { data: files } = await github.rest.pulls.listFiles({ |
|||
owner: context.repo.owner, |
|||
repo: context.repo.repo, |
|||
pull_number: prNumber, |
|||
per_page: 100, |
|||
page, |
|||
}); |
|||
const PARAMS_PATH = 'docs/en/docs-params.json'; |
|||
for (const f of files) { |
|||
const isMutation = |
|||
f.status === 'added' || f.status === 'modified' || f.status === 'renamed'; |
|||
if (!isMutation) continue; |
|||
// For renames, GitHub puts the new path in `filename` and the |
|||
// old one in `previous_filename`. Detect docs-params.json on |
|||
// either side so renames into / out of that path still trigger |
|||
// the parameter-file validation path. |
|||
if (f.filename === PARAMS_PATH || f.previous_filename === PARAMS_PATH) { |
|||
paramsChanged = true; |
|||
} |
|||
if (f.filename.startsWith('docs/en/') && f.filename.endsWith('.md')) { |
|||
changed.push(f.filename); |
|||
} |
|||
} |
|||
if (files.length < 100) break; |
|||
page++; |
|||
} |
|||
core.setOutput('files', changed.join('\n')); |
|||
core.setOutput('count', changed.length.toString()); |
|||
core.setOutput('paramsChanged', paramsChanged ? 'true' : 'false'); |
|||
core.info(`Markdown files to check: ${changed.length}`); |
|||
core.info(`docs-params.json changed: ${paramsChanged}`); |
|||
for (const f of changed) { |
|||
core.info(` - ${f}`); |
|||
} |
|||
|
|||
- name: Run syntax checker |
|||
id: checker |
|||
if: steps.changed.outputs.count != '0' || steps.changed.outputs.paramsChanged == 'true' |
|||
env: |
|||
CHANGED_FILES: ${{ steps.changed.outputs.files }} |
|||
PARAMS_CHANGED: ${{ steps.changed.outputs.paramsChanged }} |
|||
run: | |
|||
mapfile -t files <<< "$CHANGED_FILES" |
|||
args=() |
|||
for f in "${files[@]}"; do |
|||
if [ -n "$f" ] && [ -f "$f" ]; then |
|||
args+=("$f") |
|||
fi |
|||
done |
|||
|
|||
if [ ${#args[@]} -eq 0 ]; then |
|||
if [ "$PARAMS_CHANGED" = "true" ] && [ -f "docs/en/index.md" ]; then |
|||
# No markdown changed, but docs-params.json did. Run the checker |
|||
# against a single known-clean page so BuildRenderParameters / |
|||
# docs-params.json parsing actually executes and fails fast on a |
|||
# malformed parameter file. |
|||
echo "docs-params.json changed but no markdown changed; validating params via docs/en/index.md." |
|||
args+=("docs/en/index.md") |
|||
else |
|||
echo "No existing markdown files to check (all changes are deletions)." |
|||
exit 0 |
|||
fi |
|||
fi |
|||
|
|||
# Capture the checker's stdout so a follow-up step can post it as a PR |
|||
# comment when the run fails, while still streaming it to the job log. |
|||
set -o pipefail |
|||
dotnet run --project .github/scripts/CheckDocsSyntax/CheckDocsSyntax.csproj \ |
|||
-c Release --no-build -- "${args[@]}" 2>&1 | tee checker-output.txt |
|||
|
|||
- name: Upsert PR comment on failure |
|||
if: failure() && steps.checker.conclusion == 'failure' |
|||
uses: actions/github-script@v7 |
|||
with: |
|||
script: | |
|||
const fs = require('fs'); |
|||
const MARKER = '<!-- check-docs-syntax-bot -->'; |
|||
const prNumber = context.payload.pull_request.number; |
|||
|
|||
let report = ''; |
|||
try { |
|||
report = fs.readFileSync('checker-output.txt', 'utf8').trim(); |
|||
} catch (e) { |
|||
report = '(checker output was not captured)'; |
|||
} |
|||
|
|||
const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`; |
|||
const body = [ |
|||
MARKER, |
|||
'### Docs syntax check failed', |
|||
'', |
|||
'The Scriban syntax checker reported issues in the Markdown files this PR changes. Wrap inline Scriban-looking text with `{%{{{ ... }}}%}` or wrap whole code blocks with `{%{` ... `}%}` to keep it from being parsed as a template.', |
|||
'', |
|||
'<details><summary>Checker output</summary>', |
|||
'', |
|||
'```', |
|||
report, |
|||
'```', |
|||
'', |
|||
'</details>', |
|||
'', |
|||
`[Full run log](${runUrl})`, |
|||
].join('\n'); |
|||
|
|||
// Find an existing bot comment to update (idempotent across re-runs). |
|||
let existing = null; |
|||
for (let page = 1; ; page++) { |
|||
const { data } = await github.rest.issues.listComments({ |
|||
owner: context.repo.owner, |
|||
repo: context.repo.repo, |
|||
issue_number: prNumber, |
|||
per_page: 100, |
|||
page, |
|||
}); |
|||
existing = data.find(c => c.body && c.body.startsWith(MARKER)); |
|||
if (existing || data.length < 100) break; |
|||
} |
|||
|
|||
if (existing) { |
|||
await github.rest.issues.updateComment({ |
|||
owner: context.repo.owner, |
|||
repo: context.repo.repo, |
|||
comment_id: existing.id, |
|||
body, |
|||
}); |
|||
core.info(`Updated existing bot comment (#${existing.id}).`); |
|||
} else { |
|||
const { data: created } = await github.rest.issues.createComment({ |
|||
owner: context.repo.owner, |
|||
repo: context.repo.repo, |
|||
issue_number: prNumber, |
|||
body, |
|||
}); |
|||
core.info(`Created bot comment (#${created.id}).`); |
|||
} |
|||
|
|||
- name: Resolve previous failure comment on success |
|||
# Clear any stale failure comment whenever this workflow run is green, |
|||
# even if the syntax checker step was skipped (e.g. when a later |
|||
# commit reverts the earlier failure so no markdown files appear in |
|||
# the PR's net diff). |
|||
if: success() |
|||
uses: actions/github-script@v7 |
|||
with: |
|||
script: | |
|||
const MARKER = '<!-- check-docs-syntax-bot -->'; |
|||
const prNumber = context.payload.pull_request.number; |
|||
|
|||
for (let page = 1; ; page++) { |
|||
const { data } = await github.rest.issues.listComments({ |
|||
owner: context.repo.owner, |
|||
repo: context.repo.repo, |
|||
issue_number: prNumber, |
|||
per_page: 100, |
|||
page, |
|||
}); |
|||
|
|||
const existing = data.find(c => c.body && c.body.startsWith(MARKER)); |
|||
if (existing) { |
|||
const body = [ |
|||
MARKER, |
|||
'### Docs syntax check passed', |
|||
'', |
|||
'The previously reported issues are no longer present in this PR.', |
|||
].join('\n'); |
|||
await github.rest.issues.updateComment({ |
|||
owner: context.repo.owner, |
|||
repo: context.repo.repo, |
|||
comment_id: existing.id, |
|||
body, |
|||
}); |
|||
core.info(`Cleared bot comment (#${existing.id}).`); |
|||
break; |
|||
} |
|||
|
|||
if (data.length < 100) break; |
|||
} |
|||
@ -0,0 +1,72 @@ |
|||
# ABP.IO Platform 10.3 Final Has Been Released! |
|||
|
|||
We are glad to announce that [ABP](https://abp.io/) 10.3 stable version has been released. |
|||
|
|||
## What's New With Version 10.3? |
|||
|
|||
All the new features were explained in detail in the [10.3 RC Announcement Post](https://abp.io/community/announcements/announcing-abp-10-3-release-candidate-hgnpr9jq), so there is no need to review them again. You can check it out for more details. |
|||
|
|||
## Getting Started with 10.3 |
|||
|
|||
### How to Upgrade an Existing Solution |
|||
|
|||
You can upgrade your existing solutions with either ABP Studio or ABP CLI. In the following sections, both approaches are explained: |
|||
|
|||
### Upgrading via ABP Studio |
|||
|
|||
If you are already using the ABP Studio, you can upgrade it to the latest version. ABP Studio periodically checks for updates in the background, and when a new version of ABP Studio is available, you will be notified through a modal. Then, you can update it by confirming the opened modal. See [the documentation](https://abp.io/docs/latest/studio/installation#upgrading) for more info. |
|||
|
|||
After upgrading the ABP Studio, then you can open your solution in the application, and simply click the **Upgrade ABP Packages** action button to instantly upgrade your solution: |
|||
|
|||
 |
|||
|
|||
### Upgrading via ABP CLI |
|||
|
|||
Alternatively, you can upgrade your existing solution via ABP CLI. First, you need to install the ABP CLI or upgrade it to the latest version. |
|||
|
|||
If you haven't installed it yet, you can run the following command: |
|||
|
|||
```bash |
|||
dotnet tool install -g Volo.Abp.Studio.Cli |
|||
``` |
|||
|
|||
Or to update the existing CLI, you can run the following command: |
|||
|
|||
```bash |
|||
dotnet tool update -g Volo.Abp.Studio.Cli |
|||
``` |
|||
|
|||
After installing/updating the ABP CLI, you can use the [`update` command](https://abp.io/docs/latest/CLI#update) to update all the ABP related NuGet and NPM packages in your solution as follows: |
|||
|
|||
```bash |
|||
abp update |
|||
``` |
|||
|
|||
You can run this command in the root folder of your solution to update all ABP related packages. |
|||
|
|||
## Migration Guides |
|||
|
|||
There are some important changes in this version that may affect your application. Please read the migration guide carefully, if you are upgrading from v10.2 or earlier versions: [ABP Version 10.3 Migration Guide](https://abp.io/docs/10.3/release-info/migration-guides/abp-10-3) |
|||
|
|||
## Community News |
|||
|
|||
### New ABP Community Articles |
|||
|
|||
As always, exciting articles have been contributed by the ABP community. I will highlight some of them here: |
|||
|
|||
- [Liming Ma](https://abp.io/community/members/maliming) has published 6 new posts: |
|||
- [Dynamic Events in ABP](https://abp.io/community/articles/dynamic-events-in-abp-dukq95m1) |
|||
- [Dynamic Background Jobs and Workers in ABP](https://abp.io/community/articles/dynamic-background-jobs-and-workers-in-abp-wfdkdsq9) |
|||
- [Shared User Accounts in ABP Multi-Tenancy](https://abp.io/community/articles/shared-user-accounts-in-abp-multitenancy-mf3bkg79) |
|||
- [Secure Client Authentication with private_key_jwt in ABP 10.3](https://abp.io/community/articles/secure-client-authentication-with-privatekeyjwt-in-abp-b2rf18bc) |
|||
- [Operation Rate Limiting in ABP Framework](https://abp.io/community/articles/operation-rate-limiting-in-abp-framework-f4jtd6sn) |
|||
- [Resource-Based Authorization in ABP Framework](https://abp.io/community/articles/resourcebased-authorization-in-abp-framework-choku1sn) |
|||
- [One Endpoint, Many AI Clients: Turning ABP Workspaces into OpenAI-Compatible Models](https://abp.io/community/articles/turning-abp-workspaces-into-openai-compatible-endpoints-u3ls1gp4) by [Engincan Veske](https://abp.io/community/members/EngincanV) |
|||
- [Automatically Validate Your Documentation: How We Built a Tutorial Validator](https://abp.io/community/articles/automatically-validate-your-documentation-m3ozgkhv) by [Mansur Besleney](https://abp.io/community/members/mansur.besleney) |
|||
- [Automate Localhost Access for Expo: A Guide to Dynamic Cloudflare Tunnels & Dev Builds](https://abp.io/community/articles/automate-localhost-access-for-expo-a-guide-to-dynamic-7cblqtj3) by [Sumeyye Kurtulus](https://abp.io/community/members/sumeyye.kurtulus) |
|||
|
|||
Thanks to the ABP Community for all the content they have published. You can also [post your ABP related (text or video) content](https://abp.io/community/posts/create) to the ABP Community. |
|||
|
|||
## About the Next Version |
|||
|
|||
The next feature version will be 10.4. You can follow the [release planning here](https://github.com/abpframework/abp/milestones). Please [submit an issue](https://github.com/abpframework/abp/issues/new) if you have any problems with this version. |
|||
|
After Width: | Height: | Size: 467 KiB |
|
After Width: | Height: | Size: 16 KiB |
@ -0,0 +1,214 @@ |
|||
# ABP Platform 10.4 RC Has Been Released |
|||
|
|||
We are happy to release [ABP](https://abp.io) version **10.4 RC** (Release Candidate). This blog post introduces the new features and important changes in this new version. |
|||
|
|||
Try this version and provide feedback for a more stable version of ABP v10.4! Thanks to you in advance. |
|||
|
|||
## Get Started with the 10.4 RC |
|||
|
|||
You can check the [Get Started page](https://abp.io/get-started) to see how to get started with ABP. You can either download [ABP Studio](https://abp.io/get-started#abp-studio-tab) (**recommended**, if you prefer a user-friendly GUI application - desktop application) or use the [ABP CLI](https://abp.io/docs/latest/cli). |
|||
|
|||
> The v10.4 RC versions of ABP Studio and the ABP CLI are still being tested and will be released shortly. |
|||
|
|||
By default, ABP Studio uses stable versions to create solutions. Therefore, if you want to create a solution with a preview version, first you need to create a solution and then switch your solution to the preview version from the ABP Studio UI: |
|||
|
|||
 |
|||
|
|||
## Migration Guide |
|||
|
|||
There are no explicitly marked breaking changes in this version. However, there are still some important migration notes for specific scenarios. Please check the migration guide if you are upgrading from v10.3 or earlier: [ABP Version 10.4 Migration Guide](https://abp.io/docs/10.4/release-info/migration-guides/abp-10-4). |
|||
|
|||
## What's New with ABP v10.4? |
|||
|
|||
In this section, I will introduce some major features released in this version. |
|||
Here is a brief list of titles explained in the next sections: |
|||
|
|||
- URL-Based Localization |
|||
- Localization File Splitting |
|||
- Blazor UI: MudBlazor Support |
|||
- Identity: Single-Use Email/SMS 2FA Token Providers |
|||
- Account Pro: Passwordless Email Login |
|||
- AI Management: MCP Server Enhancements |
|||
- LeptonX: URL-Based Localization and Theme Improvements |
|||
- Dependency and Security Updates |
|||
|
|||
### URL-Based Localization |
|||
|
|||
ABP v10.4 introduces URL-based localization support. You can now embed the culture directly in the URL path, such as `/tr/products` or `/en/about`. |
|||
|
|||
This is especially useful for public websites, documentation sites, e-commerce applications, and any application that needs SEO-friendly and shareable localized URLs. Instead of relying only on query string, cookie, or browser language detection, the selected culture can be part of the URL itself. |
|||
|
|||
You can enable it with a single configuration: |
|||
|
|||
```csharp |
|||
Configure<AbpRequestLocalizationOptions>(options => |
|||
{ |
|||
options.UseRouteBasedCulture = true; |
|||
}); |
|||
``` |
|||
|
|||
When enabled, ABP automatically handles route registration, URL generation, menu links, and language switching for MVC/Razor Pages, Blazor, and Angular UIs. |
|||
|
|||
For Angular applications, route trees can be wrapped with `withOptionalRouteCulturePrefix` so the same route configuration can handle both `/identity/users` and `/en/identity/users`: |
|||
|
|||
```typescript |
|||
import { Routes } from '@angular/router'; |
|||
import { withOptionalRouteCulturePrefix } from '@abp/ng.core'; |
|||
|
|||
const appRoutesCore: Routes = [ |
|||
// ... your routes |
|||
]; |
|||
|
|||
export const appRoutes = withOptionalRouteCulturePrefix(appRoutesCore); |
|||
``` |
|||
|
|||
For Blazor applications, ABP built-in module pages already include culture-aware route variants. If you have your own Blazor pages, add culture route variants manually: |
|||
|
|||
```razor |
|||
@page "/Products" |
|||
@page "/{culture}/Products" |
|||
``` |
|||
|
|||
> See the [URL-Based Localization](https://abp.io/docs/10.4/framework/fundamentals/url-based-localization) documentation and [#25174](https://github.com/abpframework/abp/pull/25174) for details. |
|||
|
|||
### Localization File Splitting |
|||
|
|||
ABP localization resources can now use multiple JSON files for the same culture. This is useful for large modules or applications where keeping all localization texts in a single `en.json` file becomes difficult to maintain. |
|||
|
|||
For example, you can split a resource by feature: |
|||
|
|||
```text |
|||
Localization/ |
|||
+-- MyResource/ |
|||
+-- en.json |
|||
+-- en_Authors.json |
|||
+-- en_Books.json |
|||
+-- en_Users.json |
|||
``` |
|||
|
|||
ABP merges these files into the same localization dictionary. Files are sorted by name before merging, and if the same key exists in multiple files, the value from the last file wins. |
|||
|
|||
> See the [Localization](https://abp.io/docs/10.4/framework/fundamentals/localization) documentation and [#25227](https://github.com/abpframework/abp/pull/25227) for details. |
|||
|
|||
### Blazor UI: MudBlazor Support |
|||
|
|||
ABP v10.4 starts the [MudBlazor](https://mudblazor.com/) integration work for the Blazor UI stack. |
|||
|
|||
This release adds MudBlazor-based package infrastructure, template integration, and module/theme support needed to build ABP Blazor applications with MudBlazor. Blazorise and MudBlazor are now supported side by side, the LeptonX theme works with both UI libraries, and when creating a new Blazor project you can pick which UI library to use. |
|||
|
|||
This is a major UI foundation change, so we especially encourage Blazor users to try the RC and share feedback before the stable release. |
|||
|
|||
***Selecting the UI library when creating a new Blazor project in ABP Studio:*** |
|||
|
|||
 |
|||
|
|||
***MudBlazor-based application home page:*** |
|||
|
|||
 |
|||
|
|||
***MudBlazor-based Identity management page:*** |
|||
|
|||
 |
|||
|
|||
> See [#25235](https://github.com/abpframework/abp/pull/25235) for details. |
|||
|
|||
### Identity: Single-Use Email/SMS 2FA Token Providers |
|||
|
|||
ABP v10.4 improves the security model for email and SMS two-factor authentication codes. |
|||
|
|||
Email and phone verification codes now use ABP's single-use token providers. Generated codes are encrypted, stored with an absolute expiration time, and consumed after successful validation. Generating a new code invalidates the previous one. |
|||
|
|||
You can configure token lifetime and code length: |
|||
|
|||
```csharp |
|||
Configure<AbpEmailTwoFactorTokenProviderOptions>(options => |
|||
{ |
|||
options.TokenLifespan = TimeSpan.FromMinutes(5); |
|||
options.CodeLength = 8; |
|||
}); |
|||
|
|||
Configure<AbpPhoneNumberTwoFactorTokenProviderOptions>(options => |
|||
{ |
|||
options.TokenLifespan = TimeSpan.FromMinutes(2); |
|||
}); |
|||
``` |
|||
|
|||
The authenticator app provider is not affected and continues to use the standard TOTP approach. |
|||
|
|||
> See the [Two Factor Authentication](https://abp.io/docs/10.4/modules/identity/two-factor-authentication) documentation and [#25316](https://github.com/abpframework/abp/pull/25316) for details. |
|||
|
|||
### Account Pro: Passwordless Email Login |
|||
|
|||
ABP Commercial v10.4 RC introduces passwordless email login for the Account Pro module. |
|||
|
|||
Users can sign in by receiving an email login link and/or a one-time password (OTP), depending on the configured login type. Administrators can enable the feature, choose the login mode, and configure token lifetime from the account settings. |
|||
|
|||
 |
|||
|
|||
The feature is designed with security in mind: |
|||
|
|||
- Login links and OTPs are single-use. |
|||
- Resending a login email invalidates previous tokens. |
|||
- Token operations respect the current tenant context. |
|||
- Rate limiting helps protect against brute-force and email spam scenarios. |
|||
- Email enumeration behavior follows the existing account security setting. |
|||
|
|||
This feature is especially useful for applications that want a smoother sign-in experience without removing the tenant-aware and security-focused account flow of ABP. |
|||
|
|||
***"Login via email":*** |
|||
|
|||
 |
|||
|
|||
***Type the One-time Password (OTP) to login:*** |
|||
|
|||
 |
|||
|
|||
### AI Management: MCP Server Enhancements |
|||
|
|||
The [AI Management module](https://abp.io/docs/latest/modules/ai-management) continues to improve its MCP (Model Context Protocol) support. |
|||
|
|||
In this release, MCP server configuration has been enhanced for `stdio` transport scenarios and workspace relationships. This makes it easier to connect local or process-based MCP servers to AI workspaces and use their tools from the chat playground. |
|||
|
|||
### LeptonX: URL-Based Localization and Theme Improvements |
|||
|
|||
LeptonX has been updated to work with the new URL-based localization flow across UI types, including Angular language switching and culture-aware navigation. |
|||
|
|||
This release also includes several theme improvements and fixes, such as PathBase-safe menu links, improved custom select synchronization, sidebar menu re-binding after async rendering, and MudBlazor-related theme support. |
|||
|
|||
### Dependency and Security Updates |
|||
|
|||
ABP v10.4 RC includes several dependency updates and security-related package bumps: |
|||
|
|||
- OpenIddict upgraded to **7.5.0** |
|||
- MongoDB.Driver upgraded to **3.8.0** |
|||
- Microsoft/System package updates for CVE-2026-40372 |
|||
- `System.Security.Cryptography.Xml` upgraded to **10.0.6** |
|||
- `@abp/lodash` lodash dependency updated |
|||
|
|||
> Check [Package Version Changes](https://abp.io/docs/10.4/package-version-changes) document for all updates. |
|||
|
|||
### Other Improvements and Enhancements |
|||
|
|||
- **Virtual File System**: `ReplaceEmbeddedByPhysical` can now receive exclusion filters, which gives developers more control over included/excluded physical files during development ([#25284](https://github.com/abpframework/abp/pull/25284)). |
|||
- **Exception logging**: Complex objects in exception data are now serialized more clearly in logs ([#25267](https://github.com/abpframework/abp/pull/25267)). |
|||
- **Feature management**: Improved batch state checker performance and added `RequireFeaturesSimpleBatchStateChecker` ([#25276](https://github.com/abpframework/abp/pull/25276)). |
|||
- **RabbitMQ**: Fixed a potential hang while acquiring a closed channel after RabbitMQ restart ([#25311](https://github.com/abpframework/abp/pull/25311)). |
|||
- **Shared user accounts**: Improved shared-user lookup and two-factor authentication flows for shared user scenarios. |
|||
- **Account and SaaS modules**: Improved shared-user invitation and account-page flows in tenant user sharing scenarios. |
|||
|
|||
## Community News |
|||
|
|||
### New ABP Community Articles |
|||
|
|||
As always, exciting articles have been contributed by the ABP community. I will highlight some of them here: |
|||
|
|||
- [Stop Sprinkling [RequiresFeature] Everywhere — A Centralized Feature Gate for ABP.IO](https://abp.io/community/articles/stop-sprinkling-requiresfeature-everywhere-a-centralized-7znie818) by [Mohammad AlMohammad AlMahmoud](https://abp.io/community/members/Mohammad97Dev) |
|||
- [Top AI Coding Models in 2026: Which One Should Developers Actually Use?](https://abp.io/community/articles/top-ai-coding-models-in-2026-which-one-should-developers-use-rivh8x15) by [Alper Ebiçoğlu](https://abp.io/community/members/alper) |
|||
|
|||
Thanks to the ABP Community for all the content they have published. You can also [post your ABP related (text or video) content](https://abp.io/community/posts/create) to the ABP Community. |
|||
|
|||
## Conclusion |
|||
|
|||
This version comes with some new features and a lot of enhancements to the existing features. You can see the [Road Map](https://abp.io/docs/10.4/release-info/road-map) documentation to learn about the release schedule and planned features for the next releases. Please try ABP v10.4 RC and provide feedback to help us release a more stable version. |
|||
|
|||
Thanks for being a part of this community! |
|||
|
After Width: | Height: | Size: 49 KiB |
|
After Width: | Height: | Size: 457 KiB |
|
After Width: | Height: | Size: 58 KiB |
|
After Width: | Height: | Size: 48 KiB |
|
After Width: | Height: | Size: 67 KiB |
|
After Width: | Height: | Size: 225 KiB |
|
After Width: | Height: | Size: 44 KiB |
|
After Width: | Height: | Size: 17 KiB |
@ -0,0 +1,89 @@ |
|||
# ABP.IO Platform 10.4 Final Has Been Released! |
|||
|
|||
We are glad to announce that [ABP](https://abp.io/) 10.4 stable version has been released. |
|||
|
|||
## What's New With Version 10.4? |
|||
|
|||
All the new features were explained in detail in the [10.4 RC Announcement Post](https://abp.io/community/announcements/announcing-abp-10-4-release-candidate-7ukyudm0), so there is no need to review them again. You can check it out for more details. |
|||
|
|||
## Getting Started with 10.4 |
|||
|
|||
### How to Upgrade an Existing Solution |
|||
|
|||
You can upgrade your existing solutions with either ABP Studio or ABP CLI. In the following sections, both approaches are explained: |
|||
|
|||
### Upgrading via ABP Studio |
|||
|
|||
If you are already using the ABP Studio, you can upgrade it to the latest version. ABP Studio periodically checks for updates in the background, and when a new version of ABP Studio is available, you will be notified through a modal. Then, you can update it by confirming the opened modal. See [the documentation](https://abp.io/docs/latest/studio/installation#upgrading) for more info. |
|||
|
|||
After upgrading the ABP Studio, then you can open your solution in the application, and simply click the **Upgrade ABP Packages** action button to instantly upgrade your solution: |
|||
|
|||
 |
|||
|
|||
### Upgrading via ABP CLI |
|||
|
|||
Alternatively, you can upgrade your existing solution via ABP CLI. First, you need to install the ABP CLI or upgrade it to the latest version. |
|||
|
|||
If you haven't installed it yet, you can run the following command: |
|||
|
|||
```bash |
|||
dotnet tool install -g Volo.Abp.Studio.Cli |
|||
``` |
|||
|
|||
Or to update the existing CLI, you can run the following command: |
|||
|
|||
```bash |
|||
dotnet tool update -g Volo.Abp.Studio.Cli |
|||
``` |
|||
|
|||
After installing/updating the ABP CLI, you can use the [`update` command](https://abp.io/docs/latest/CLI#update) to update all the ABP related NuGet and NPM packages in your solution as follows: |
|||
|
|||
```bash |
|||
abp update |
|||
``` |
|||
|
|||
You can run this command in the root folder of your solution to update all ABP related packages. |
|||
|
|||
## Migration Guides |
|||
|
|||
There are no explicitly marked breaking changes in this version. However, there are still some important migration notes for specific scenarios. Please read the migration guide carefully, if you are upgrading from v10.3 or earlier versions: [ABP Version 10.4 Migration Guide](https://abp.io/docs/10.4/release-info/migration-guides/abp-10-4) |
|||
|
|||
## Community News |
|||
|
|||
### Highlights from the ABP Community |
|||
|
|||
There have been some important announcements for the ABP community recently. Here are two highlights you may want to check out: |
|||
|
|||
#### React UI for ABP Framework Is Finally Here |
|||
|
|||
 |
|||
|
|||
React support has been one of the most requested topics in the ABP community, and with ABP 10.4, it becomes a first-class UI option in the modern template system. The new React UI is designed for teams that want ABP on the backend and React on the frontend while keeping ABP's built-in application features such as authentication, authorization, localization, multi-tenancy, modularity, runtime configuration, and deployment. |
|||
|
|||
Modern React solutions include your own React application as real source code in the solution, plus the ABP Admin Console for standard module administration screens. This means your product UI stays fully under your control, while ABP still provides a consistent and upgradeable administration experience. |
|||
|
|||
The React stack is built with familiar modern tools, including Vite, TypeScript, TanStack Router, TanStack Query, Axios, Zod, React Hook Form, Tailwind CSS, shadcn/ui, and Vitest. You can create a React UI solution with the `--modern` flag or by selecting the modern template flow in ABP Studio. You can read the announcement here: [React UI for ABP Framework Is Finally Here](https://abp.io/community/announcements/react-ui-for-abp-framework-is-finally-here-7rfmgb2v). |
|||
|
|||
#### Introducing ABP Studio AI Agent |
|||
|
|||
 |
|||
|
|||
ABP Studio now introduces ABP Agent, a deeply integrated AI coding assistant that understands ABP solutions as complete systems, not just as files in folders. It is aware of ABP concepts such as modules, layers, aggregate roots, repositories, application services, DTOs, permissions, localization, event bus, distributed cache, background jobs, and module dependencies. |
|||
|
|||
ABP Agent works in three modes: Agent mode for implementation, Plan mode for read-only investigation and planning, and Ask mode for Q&A and explanations. It can use ABP Studio's analysis engine to understand the solution structure, build affected projects, start or restart applications, run tasks, generate proxies, add migrations, and inspect runtime feedback such as exceptions, logs, HTTP requests, and distributed events. |
|||
|
|||
The announcement also highlights the broader development loop around ABP Agent: solution runner integration, custom workflows, task runner support, Git and GitHub integration, AI-generated commit messages, and ABP-aware AI code review. You can read the announcement here: [Introducing ABP Studio AI Agent](https://abp.io/community/announcements/introducing-abp-studio-ai-agent-o1ni0toc). |
|||
|
|||
### New ABP Community Articles |
|||
|
|||
As always, exciting articles have been contributed by the ABP community. I will highlight some of them here: |
|||
|
|||
- [ABP in the AI Era: Surviving, Evolving, and Staying Relevant](https://abp.io/community/articles/abp-in-the-ai-era-surviving-evolving-and-staying-relevant-6gyfjfpe) by [Engincan Veske](https://abp.io/community/members/EngincanV) |
|||
- [Stop Sprinkling [RequiresFeature] Everywhere — A Centralized Feature Gate for ABP.IO](https://abp.io/community/articles/stop-sprinkling-requiresfeature-everywhere-a-centralized-7znie818) by [Mohammad AlMohammad AlMahmoud](https://abp.io/community/members/Mohammad97Dev) |
|||
- [Top AI Coding Models in 2026: Which One Should Developers Actually Use?](https://abp.io/community/articles/top-ai-coding-models-in-2026-which-one-should-developers-use-rivh8x15) by [Alper Ebiçoğlu](https://abp.io/community/members/alper) |
|||
|
|||
Thanks to the ABP Community for all the content they have published. You can also [post your ABP related (text or video) content](https://abp.io/community/posts/create) to the ABP Community. |
|||
|
|||
## About the Next Version |
|||
|
|||
The next feature version will be 10.5. You can follow the [release planning here](https://github.com/abpframework/abp/milestones). Please [submit an issue](https://github.com/abpframework/abp/issues/new) if you have any problems with this version. |
|||
|
After Width: | Height: | Size: 471 KiB |
|
After Width: | Height: | Size: 16 KiB |
|
After Width: | Height: | Size: 27 KiB |
|
After Width: | Height: | Size: 88 KiB |
|
After Width: | Height: | Size: 94 KiB |
|
After Width: | Height: | Size: 84 KiB |
|
After Width: | Height: | Size: 72 KiB |
|
After Width: | Height: | Size: 75 KiB |
|
After Width: | Height: | Size: 44 KiB |
|
After Width: | Height: | Size: 40 KiB |
|
After Width: | Height: | Size: 78 KiB |
|
After Width: | Height: | Size: 71 KiB |
|
After Width: | Height: | Size: 105 KiB |
|
After Width: | Height: | Size: 71 KiB |
@ -0,0 +1,165 @@ |
|||
# A New Look for ABP React Native: NativeWind, Modernization & Two Sample Apps |
|||
|
|||
## Introduction |
|||
|
|||
Mobile is increasingly the first surface users meet a product on, and the bar for what a mobile UI is supposed to look and feel like has moved a lot in the last few years. ABP has had a solid React Native template for a long time, but "solid" and "modern" are not the same thing — and the gap was starting to show. |
|||
|
|||
If you've been following ABP's mobile story, you know the React Native template has been useful but a bit stuck in time: a wall of `StyleSheet.create()` blocks per screen, inline color literals, a mixed `.js` / `.tsx` codebase, and a navigator tree that carried features most teams never used. This post is about what changed, why we changed it, and what's next. |
|||
|
|||
We approached the refresh in two passes: first a thorough cleanup of legacy screens, dead components, and unused locales, and then a full styling-layer rewrite around NativeWind v4 with a shadcn-style design token system. Along the way we also built two sample apps on top of the new template, so the changes aren't just theoretical — they've been exercised against real screens and real flows. |
|||
|
|||
The changes ship to both the **`react-native`** template and the **`microservice/apps/mobile/react-native`** template, so layered, single-layer (no-layers), and microservice solutions all get the same modernized mobile experience. |
|||
|
|||
## Why we modernized |
|||
|
|||
The previous template used React Native Paper plus hand-written `StyleSheet.create()` objects under every component. That works, but it has a real cost over time: |
|||
|
|||
- **No design tokens.** Spacing, radii, and colors lived as raw numbers and hex strings scattered across screens. Changing one accent color meant touching dozens of files. |
|||
- **Dark mode was a manual switch.** Every screen had to read theme colors and pass them down through `style` props — easy to forget, easy to drift. |
|||
- **Dead code accumulated.** Older tenant management, dashboard widgets, and SVG illustrations had built up — useful in 2021, but mostly noise in 2026. |
|||
- **Mixed JS/TS.** Some screens were still plain `.js`, which got in the way of type safety and consistent tooling. |
|||
|
|||
We wanted the same outcome a modern web template gives you: open a screen, see structured layout, see semantic class names, change one token in a config file and watch it ripple everywhere. NativeWind v4 lets us bring that exact feel to React Native — Tailwind CSS class names compile at build time, so the runtime stays small and predictable. |
|||
|
|||
## Part 1 — Template cleanup |
|||
|
|||
Before the styling rewrite, the template needed a serious trim. |
|||
|
|||
**Removed (legacy / unused):** |
|||
|
|||
- `Dashboard/` (HostDashboard, TenantDashboard, EditionUsageWidget, ErrorRateWidget) — these widgets were demo-only and rarely fit real apps. |
|||
- `CreateUpdateTenant/`, `CreateUpdateUser/`, `TenantsNavigator`, `UsersNavigator` — full administrative CRUD belongs in the admin UI, not on mobile. |
|||
- Long tail of one-off components: `DataList`, `DateRangePicker`, `Select`, `ListMenu`, `LoadingButton`, `TenantBox`, `AddIcon`, `CancelButton`, `NoRecordSvg`, `AnalysisSvg`. |
|||
- Hooks: `UsePermission`, `UseAuthAndTokenExchange`, `UseLocalizedTitle`, `PermissionHOC`. |
|||
- 18 of 20 locale files. Only **`en`** and **`tr`** ship by default — the rest are easy to add back per project, but bundling 20 locales no one ships was waste. |
|||
|
|||
**Added / upgraded:** |
|||
|
|||
- New **`LoginScreen.tsx`** (replacing the legacy `LoginScreen.js`), plus brand-new `RegisterScreen`, `ForgotPasswordScreen`, and `ResetPasswordScreen` — the full account flow is now first-class. |
|||
- **`AppContainer.tsx` / `AppContent.tsx`** split, so app-level providers and bootstrapping are cleanly separated from navigation. |
|||
- **`app.config.js`** replacing the static `app.json`, enabling environment-driven Expo config. |
|||
- **`scripts/tunnel.js`** — automates the Cloudflare tunnel flow we covered in [Automate Localhost Access for Expo](https://abp.io/community/articles/automate-localhost-access-for-expo-a-guide-to-dynamic-7cblqtj3). |
|||
- New docs: `docs/UPGRADE.md` and `docs/permission-guide.md`. |
|||
|
|||
The result: a smaller, sharper template that fits how teams actually use ABP on mobile today. |
|||
|
|||
## Part 2 — NativeWind v4 and a new visual system |
|||
|
|||
With the template trimmed, the styling layer got a full modernization. |
|||
|
|||
**The stack:** |
|||
|
|||
- **NativeWind v4** — Tailwind CSS for React Native. Class names compile at build time, so the runtime cost is minimal. |
|||
- **Tailwind CSS 3.4** — single source of truth for design tokens via `tailwind.config.js`. |
|||
- **shadcn-style neutral palette** — zinc-based color system with semantic tokens (`background`, `foreground`, `card`, `muted`, `accent`, `border`, `destructive`). Same vocabulary you already know from the web template. |
|||
- **React Native Paper** is still in the box, but **only for `TextInput`** (outlined mode, error states, icons). Everything else moved to NativeWind. |
|||
- **Ionicons** (`@expo/vector-icons`) replaces Paper icons across the UI. |
|||
|
|||
**What this looks like in practice:** |
|||
|
|||
```tsx |
|||
// Before — separate styles object, inline colors |
|||
<View style={styles.card}> |
|||
<Text style={styles.title}>{title}</Text> |
|||
</View> |
|||
|
|||
const styles = StyleSheet.create({ |
|||
card: { padding: 16, backgroundColor: '#fff', borderRadius: 12, /* ... */ }, |
|||
title: { fontSize: 18, fontWeight: '600', color: '#18181b' }, |
|||
}); |
|||
|
|||
// After — class names, dark mode included |
|||
<View className="p-4 bg-card rounded-xl border border-border"> |
|||
<Text className="text-lg font-semibold text-foreground">{title}</Text> |
|||
</View> |
|||
``` |
|||
|
|||
That `dark:` variant is the big quality-of-life win. Dark mode is no longer something each screen has to handle by hand — it's a config-level concern, applied through semantic tokens, and consistent across every surface. Here's the new `LoginScreen` in both modes — same code, same components, just the theme switch flipped: |
|||
|
|||
<table> |
|||
<tr> |
|||
<td align="center" width="50%"><img src="images/rn-light.png" alt="LoginScreen — light mode" /><br/><sub><b>Light</b></sub></td> |
|||
<td align="center" width="50%"><img src="images/rn-dark.png" alt="LoginScreen — dark mode" /><br/><sub><b>Dark</b></sub></td> |
|||
</tr> |
|||
</table> |
|||
|
|||
**Visual touches that come along for the ride:** |
|||
|
|||
- **Hero `HomeScreen`** with the app logo and feature cards. |
|||
- **iOS-style grouped settings cards** in `SettingsScreen`. |
|||
- **Centered card containers + logo headers** on login / register / password screens. |
|||
- `src/theme/spacing.ts` and `src/theme/shape.ts` are gone — those tokens now live in `tailwind.config.js` where they belong. |
|||
|
|||
### Navigation, rethought |
|||
|
|||
Navigation is where the template change is felt the most. The old template gave you a single drawer menu and that was it — everything lived behind a hamburger. The new template keeps the drawer but adds a proper **`BottomTabNavigator`** alongside it, plus an **`AccountNavigator`** for the user/account area. That brings the navigation in line with what users actually expect from a modern mobile app: primary destinations one tap away on the bottom tab bar, secondary destinations and global actions tucked into the drawer. |
|||
|
|||
<table> |
|||
<tr> |
|||
<td align="center" width="33%"><img src="images/rn-old-menu.png" alt="Old drawer menu" /><br/><sub><b>Before</b> — single drawer menu</sub></td> |
|||
<td align="center" width="33%"><img src="images/rn-new-drawer-menu.png" alt="New drawer menu" /><br/><sub><b>After</b> — revamped drawer</sub></td> |
|||
<td align="center" width="33%"><img src="images/rn-new-bottom-tab-menu.png" alt="New bottom tab menu" /><br/><sub><b>After</b> — new bottom tab bar</sub></td> |
|||
</tr> |
|||
</table> |
|||
|
|||
## Two sample apps we built |
|||
|
|||
To stress-test the new template and to give the community something concrete to learn from, we built **two sample apps** on top of it: |
|||
|
|||
### Habit Tracker — a minimal demo |
|||
|
|||
I built **Habit Tracker** — a single-feature demo where you keep a list of daily habits and tick them off as you go through your day. Build a habit, mark it done, watch the streak grow. That's the whole loop. |
|||
|
|||
The point here wasn't to ship a feature-rich productivity tool, it was to show the smallest meaningful surface you can build on top of the new template without losing the auth flow, theming, or navigation defaults. Everything around your one feature — login/register, drawer + bottom tab navigation, light/dark mode, localized strings — comes from the template. You add the feature, and the template carries everything else. |
|||
|
|||
<table> |
|||
<tr> |
|||
<td align="center" width="33%"><img src="images/rn-small-1.png" alt="Habit Tracker — screen 1" /></td> |
|||
<td align="center" width="33%"><img src="images/rn-small-2.png" alt="Habit Tracker — screen 2" /></td> |
|||
<td align="center" width="33%"><img src="images/rn-small-3.png" alt="Habit Tracker — screen 3" /></td> |
|||
</tr> |
|||
</table> |
|||
|
|||
### Hanova — a home-services demo |
|||
|
|||
We have also built **Hanova** that is a two-sided home-services sample where customers find local providers, request a job, negotiate the price, and chat through to confirmation. Pick a role, log in, browse open work or open requests, accept a booking, message the other party. That's basically the loop. |
|||
|
|||
The point here wasn't about shipping a full Uber-for-plumbers product, but it was to show a **realistic but focused** domain you can grow on top of the ABP single-layer template without rebuilding authentication, navigation, or theming from scratch. Everything around the marketplace — login/register, role selection, bottom-tab navigation, light/dark mode, localized strings, OAuth, and API wiring — comes from the template. You add the booking flow (discovery, job feed, negotiation, messaging), and the template carries everything else. Two pre-seeded personas (`ayse.kaya` / `mehmet.yilmaz`, password `Demo@1234`) populate every screen on first launch so you can explore both sides immediately. |
|||
|
|||
<table> |
|||
<tr> |
|||
<td align="center" width="33%"><img src="images/discovery.png" alt="Hanova — Discovery / browse providers" /></td> |
|||
<td align="center" width="33%"><img src="images/job-feed.png" alt="Hanova — Bookings / job feed" /></td> |
|||
<td align="center" width="33%"><img src="images/negotiation.png" alt="Hanova — Messages / negotiation" /></td> |
|||
</tr> |
|||
</table> |
|||
|
|||
Both apps will be available shortly — they're useful as reference implementations, and they're also useful as a kind of regression check on the template itself. |
|||
|
|||
## Try it yourself |
|||
|
|||
If you're starting fresh, you'll pick up the new template automatically. The easiest way is through **ABP Studio** — just enable the mobile platform and pick **React Native** from the wizard: |
|||
|
|||
 |
|||
|
|||
Or via CLI: |
|||
|
|||
```bash |
|||
abp new Acme.BookStore --template app-pro --mobile react-native |
|||
``` |
|||
|
|||
For the microservice solution template: |
|||
|
|||
```bash |
|||
abp new Acme.BookStore --template microservice-pro --mobile react-native |
|||
``` |
|||
|
|||
Open the generated `react-native/` (or `apps/mobile/react-native/`) folder, run `npm install`, then `npx expo start`, and you'll be looking at the new UI within seconds. |
|||
|
|||
If you're **upgrading an existing project**, check the new `docs/UPGRADE.md` in the template — it walks through the moving pieces (Babel/Metro config, the new `global.css` import, the `nativewind-env.d.ts` ambient types, and the locale trim). |
|||
|
|||
## Summary |
|||
|
|||
The ABP React Native template is in a much better place than it was a few months ago. The legacy screens and a long tail of dead components are gone, the styling layer is now a proper token-based system powered by **NativeWind v4** and a shadcn-style neutral palette, and **dark mode** is no longer something each screen has to think about — it's just there. Navigation got a real refresh too: the old single-drawer pattern is now a revamped drawer plus a `BottomTabNavigator` and `AccountNavigator`, which is the structure most modern mobile apps actually use. |
|||
|
|||
We also built **two sample apps** on top of the new template — **Habit Tracker**, a focused single-feature one, and **Hanova**, a more substantial demo — so the changes are exercised against real screens and real flows, not just template snapshots. If you create a new ABP solution with a React Native mobile app, all of this is what you get out of the box; if you're upgrading, the new `docs/UPGRADE.md` walks you through it. Try the template, build something on top of it, and share what you make — the whole point of moving to a token-based system is that it should be easy for everyone to extend, not just us. |
|||
|
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,254 @@ |
|||
## Introduction |
|||
|
|||
AI coding tools went from “cool autocomplete” to “basically your junior dev (who never sleeps)” in just a couple of years. |
|||
|
|||
In 2026, the landscape is **crowded, competitive, and honestly a bit confusing**. Every model claims to be the best at coding—but depending on what you actually *do* (APIs, frontend, DevOps, debugging), the “best” can change fast. |
|||
|
|||
So instead of hype, let’s break down the **top AI coding models in 2026**, ranked by: |
|||
|
|||
* Real-world dev usefulness |
|||
* Code quality & correctness |
|||
* Context handling |
|||
* Tooling ecosystem |
|||
|
|||
We'll check the AI models against these topics: |
|||
|
|||
 |
|||
|
|||
--- |
|||
|
|||
## 🏆 1. GPT-5.4 (OpenAI) — The All-Round Beast |
|||
|
|||
Let’s not dance around it—**GPT-5.4 is still the most versatile coding model right now.** |
|||
|
|||
### Why it’s #1 |
|||
|
|||
* Extremely strong across **all languages** |
|||
* Handles **large codebases** without losing context |
|||
* Excellent at: |
|||
|
|||
* Refactoring |
|||
* Architecture suggestions |
|||
* Debugging complex issues |
|||
|
|||
### Where it shines |
|||
|
|||
* Full-stack development |
|||
* API design |
|||
* Writing clean, production-ready code |
|||
|
|||
### Where it struggles |
|||
|
|||
* Occasionally over-engineers solutions |
|||
* Can be slower than lightweight models |
|||
|
|||
### As a result; |
|||
|
|||
If you want a **default “just works” coding AI**, this is it. |
|||
|
|||
--- |
|||
|
|||
## 🥈 2. Claude 4.7 (Anthropic) — The Clean Code Specialist |
|||
|
|||
Claude 4.7 has built a reputation for writing code that feels like it came from a senior engineer who drinks too much coffee but cares deeply about readability. |
|||
|
|||
### Strengths |
|||
|
|||
* Beautiful, readable code |
|||
* Strong reasoning for: |
|||
|
|||
* Refactoring |
|||
* Code reviews |
|||
* Documentation |
|||
|
|||
### Killer feature |
|||
|
|||
* Massive context window → great for: |
|||
|
|||
* Large repositories |
|||
* Long discussions |
|||
* System design |
|||
|
|||
### Weak spots |
|||
|
|||
* Slightly less aggressive in solving edge-case bugs |
|||
* Sometimes too “safe” in decisions |
|||
|
|||
### As a result; |
|||
|
|||
Perfect if you care about **maintainability over raw speed**. |
|||
|
|||
--- |
|||
|
|||
## 🥉 3. Gemini 3.1 (Google) — The Multimodal Powerhouse |
|||
|
|||
Gemini 3.1 is where things get interesting. |
|||
|
|||
This isn’t just a coding model—it’s a **multi-input problem solver**. |
|||
|
|||
### What makes it different |
|||
|
|||
* Understands: |
|||
|
|||
* Code |
|||
* Screenshots |
|||
* Diagrams |
|||
* Logs |
|||
|
|||
### Where it dominates |
|||
|
|||
* Debugging UI issues from screenshots |
|||
* DevOps + cloud workflows |
|||
* Cross-referencing documentation |
|||
|
|||
### Downsides |
|||
|
|||
* Code style can be inconsistent |
|||
* Sometimes less deterministic than GPT-5 |
|||
|
|||
### As a result; |
|||
|
|||
If your workflow includes **visual debugging or cloud-heavy systems**, this is insanely useful. |
|||
|
|||
--- |
|||
|
|||
## ⚡ 4. Mistral Code (Open Models) — The Speed King |
|||
|
|||
Mistral AI’s coding models are gaining serious attention. |
|||
|
|||
### Why devs love it |
|||
|
|||
* Fast |
|||
* Cheap (or free if self-hosted) |
|||
* Great for: |
|||
|
|||
* Autocomplete |
|||
* Small functions |
|||
* Local development |
|||
|
|||
### Trade-offs |
|||
|
|||
* Not as strong in deep reasoning |
|||
* Limited compared to closed models |
|||
|
|||
### As a result; |
|||
|
|||
Best choice for: |
|||
|
|||
* Privacy-sensitive environments |
|||
* Offline/local setups |
|||
* Lightweight coding tasks |
|||
|
|||
--- |
|||
|
|||
## 🧠 5. Code Llama 4 — The Open-Source Veteran |
|||
|
|||
Code Llama 4 is still very relevant, especially in enterprise setups. |
|||
|
|||
### Strengths |
|||
|
|||
* Fully open-source |
|||
* Customizable & fine-tunable |
|||
* Good baseline performance |
|||
|
|||
### Weaknesses |
|||
|
|||
* Behind top-tier models in reasoning |
|||
* Needs tuning for best results |
|||
|
|||
### As a result; |
|||
|
|||
If your company says “no cloud AI,” this is your friend. |
|||
|
|||
--- |
|||
|
|||
## 📊 Comparison Table Between AI Models |
|||
|
|||
| Model | Best For | Weakness | |
|||
| ------------ | ------------------------ | --------------------- | |
|||
| GPT-5.4 | Everything | Slightly slower | |
|||
| Claude 4.7 | Clean, maintainable code | Less aggressive fixes | |
|||
| Gemini 3.1 | Multimodal workflows | Inconsistent style | |
|||
| Mistral Code | Speed & local usage | Shallow reasoning | |
|||
| Code Llama 4 | Open-source flexibility | Needs tuning | |
|||
|
|||
Image Prompt: |
|||
A sleek table-style infographic comparing AI models with icons, performance bars, and labels like “Best for speed”, “Best for reasoning”. |
|||
|
|||
--- |
|||
|
|||
## 🤔 When to Use What (Real Scenarios) |
|||
|
|||
### Use GPT-5.4 if: |
|||
|
|||
* You’re building a full product |
|||
* You need architecture + implementation |
|||
* You want fewer “AI mistakes” |
|||
|
|||
--- |
|||
|
|||
### Use Claude 4.7 if: |
|||
|
|||
* You’re reviewing code |
|||
* You care about readability |
|||
* You’re working in a team |
|||
|
|||
--- |
|||
|
|||
### Use Gemini 3.1 if: |
|||
|
|||
* You debug using screenshots/logs |
|||
* You work with cloud infrastructure |
|||
* You want multimodal workflows |
|||
|
|||
--- |
|||
|
|||
### Use Mistral / Code Llama if: |
|||
|
|||
* You need local/private AI |
|||
* You want low cost |
|||
* You’re okay trading power for control |
|||
|
|||
--- |
|||
|
|||
## 🔌 Where ABP Framework Fits In |
|||
|
|||
If you're working with **ASP.NET Core and the ABP Framework**, these models can seriously boost productivity: |
|||
|
|||
* GPT-5.4 → Generate **application services, DTOs, and modules** |
|||
* Claude → Clean up **domain layer logic** |
|||
* Gemini → Help debug **UI + backend integration issues** |
|||
|
|||
The sweet spot? |
|||
|
|||
👉 Use AI to scaffold ABP layers, then refine manually. |
|||
That keeps your architecture clean while still saving hours. |
|||
|
|||
--- |
|||
|
|||
## 🚨 Reality Check |
|||
|
|||
AI coding models in 2026 are powerful—but: |
|||
|
|||
* They still hallucinate edge cases |
|||
* They don’t fully understand your business logic |
|||
* They can fix somewhere, break another |
|||
* They can not fix a bug even after you write 10 different prompts |
|||
|
|||
So yeah—**don’t ship blind**. |
|||
|
|||
Treat them like: |
|||
|
|||
> A fast junior dev… who needs code review. |
|||
|
|||
--- |
|||
|
|||
## TL;DR |
|||
|
|||
👉 There’s no single “winner”—just the best tool for your workflow. |
|||
|
|||
 |
|||
|
|||
--- |
|||
|
|||
If you're experimenting with these models in real projects (especially with ABP), it's worth trying **multiple models side-by-side**. The differences become obvious *fast*. |
|||
|
After Width: | Height: | Size: 268 KiB |
|
After Width: | Height: | Size: 39 KiB |
|
After Width: | Height: | Size: 660 KiB |
|
After Width: | Height: | Size: 162 KiB |
|
After Width: | Height: | Size: 6.0 MiB |
|
After Width: | Height: | Size: 869 KiB |
@ -0,0 +1,244 @@ |
|||
# Introducing ABP Studio AI Agent |
|||
|
|||
The new ABP Studio release introduces a deeply integrated set of features designed around one idea: an AI coding agent that truly understands ABP solutions, sitting inside an IDE that already knows how to build, run, monitor, and iterate on them. |
|||
|
|||
At the center is **ABP Agent**, our AI coding assistant. Around it are long-standing ABP Studio capabilities that have been brought together into a single development loop. Together they turn ABP Studio into a single place where you architect and code your ABP solutions. |
|||
|
|||
 |
|||
|
|||
--- |
|||
|
|||
## Meet ABP Agent |
|||
|
|||
 |
|||
|
|||
ABP Agent is the AI coding assistant built into ABP Studio. It operates in three modes, each tuned for a different stage of work: |
|||
|
|||
- **Agent mode**: the implementation mode. The agent reads the solution, writes and edits files, builds the affected projects, runs your apps, watches the runtime, and iterates until the change works end-to-end. |
|||
- **Plan mode**: read-only planning. The agent investigates the codebase, researches the official ABP documentation, and produces a structured implementation plan (Problem, Solution, Workflow Diagram, Files Affected, Expected Result). When you are happy with the plan, a single click promotes it into Agent mode and the implementation starts from the plan. |
|||
- **Ask mode**: read-only Q&A. The agent explains how something works, draws diagrams, and answers questions about your code without touching any files. |
|||
|
|||
The agent is **ABP-aware by default**. It is instructed to prefer ABP base classes over plain POCOs, repositories over direct `DbContext` injection, `ApplicationService` over plain services, the ABP permission system over `[Authorize(Roles=…)]`, localized strings over hardcoded text, `BusinessException`/`UserFriendlyException` over plain `Exception`, the distributed cache abstraction over raw memory cache, and background job abstractions over hand-rolled hosted services. When it is unsure about an ABP feature, it consults the official ABP documentation as a primary source of truth, not random blog posts on the web. |
|||
|
|||
--- |
|||
|
|||
## Why It Was Needed |
|||
|
|||
General-purpose AI coding tools (Cursor, Claude Code, Windsurf, opencode and similar) are excellent for horizontal, file-shaped work. They read source files, edit them, and run shell commands. That works well for small scripts or front-end apps. |
|||
|
|||
ABP solutions are different. A typical ABP solution is **system-shaped**, not just file-shaped: the important context is not only where files are located, but how modules, layers, permissions, contracts, localization, persistence, and UI pieces work together: |
|||
|
|||
- It is split across multiple modules and layers (Domain, Application, EntityFrameworkCore, HttpApi, Web, etc.) with strict dependency rules. |
|||
- It is composed of many runnable units: HTTP services, gateways, identity servers, background workers, SPAs, mobile apps, plus the Docker containers they depend on. |
|||
- It follows a strong set of conventions: aggregate roots, repositories, application services, DTOs, permissions, localization, event bus, distributed cache, background jobs. |
|||
- It is a *living* system at design time. You don't just read code, you run it, watch logs, follow distributed events, hit HTTP endpoints, and iterate. |
|||
|
|||
A generic agent has none of that vocabulary. It does not know what a module is, which project is the Domain layer, or that an `ApplicationService` should not depend on a `DbContext` directly. It cannot start "the gateway, the auth server, and the two microservices my React app talks to". It just runs `dotnet run` in some folder and hopes. It cannot tell you that the agent's latest edit caused a runtime exception in the Identity service or made the `OrderPlacedEto` event handler silently fail, because it has no concept of "running app". |
|||
|
|||
ABP Agent and the surrounding ABP Studio features were built to close exactly that gap. The agent is born inside an IDE that already understands modules, run profiles, builds, migrations, proxies, Docker containers, Kubernetes services, and distributed runtime telemetry, and it uses every one of them. |
|||
|
|||
--- |
|||
|
|||
## How ABP Agent Sees Your Application: The Analyze Engine |
|||
|
|||
 |
|||
|
|||
Before ABP Agent answers anything, it needs to *understand* your solution. This is where the **Analyze** feature does the heavy lifting. |
|||
|
|||
When you open a solution, ABP Studio analyzes every package and builds a structural map: the application's **skeleton**. It identifies what each type actually is in ABP terms: an aggregate root, an entity, a value object, a repository interface or implementation, a domain service, an application service or interface, a DTO, an integration service, a controller, an HTTP API, a background job or worker, an event handler, an ETO, a SignalR hub, a DbContext (EF Core or MongoDB), a permission/feature/setting provider, a global feature, a Mapperly or AutoMapper profile, a fluent validator, a menu contributor, a data seed contributor, an options class, an ABP module with its `[DependsOn]` chain, and many more. |
|||
|
|||
For each of these, the analyzer captures the structural information that actually matters: properties, method signatures with their line ranges, injected dependencies, base classes, the permission groups and items, the feature tree, the settings catalog, the database tables and collections, without parsing C# at runtime. |
|||
|
|||
ABP Agent receives this analyzed skeleton at the start of every session. That means: |
|||
|
|||
- The agent already knows what types exist in each project and what role each one plays, before you ask anything. |
|||
- When you say *"add a Category to my Catalog module"*, the agent already knows where the Domain project is, what the existing aggregate roots look like, which DbContext should get the new entity, where the permissions provider lives, and which application service to extend. |
|||
- When the agent needs to change an existing type, it can fetch a precise outline (base classes, properties, method signatures with exact line ranges) instead of reading thousands of lines of source. That is dramatically faster, dramatically cheaper, and dramatically more accurate. |
|||
- When you modify code, ABP Studio re-analyzes only the affected packages and refreshes the agent's understanding. |
|||
|
|||
This is what we mean by **solution-aware AI**. The agent does not "look at folders and guess"; it works from a typed, ABP-shaped index of your application. |
|||
|
|||
--- |
|||
|
|||
## Native .NET Awareness: No Shell Gymnastics |
|||
|
|||
A common pattern in generic agentic IDEs is to do everything through the terminal. Building? Run `dotnet build` in a shell. Restarting an app? Spawn a process. Adding a migration? More shell. Checking whether the build succeeded? Parse terminal output and pray. |
|||
|
|||
ABP Agent does not work through a terminal for these things. Building, running, restarting, adding migrations, generating proxies, installing client-side libraries: all of these are **first-class operations** the agent invokes directly. Build calls return structured results with errors and warnings the agent can act on immediately. Starting an application returns a structured outcome: which apps started, which failed, and a summarized error log for each failure. There is no string-scraping, no "did the spinner stop yet?" guessing. |
|||
|
|||
The agent also scopes builds intelligently. It can build a single project, a single module, or the entire solution depending on what changed. After editing a few files in your Application layer, it builds just that module (not the whole solution), and only escalates the scope when needed. |
|||
|
|||
--- |
|||
|
|||
## Solution Runner & Live Runtime Monitor |
|||
|
|||
 |
|||
|
|||
This is the half of ABP Agent that no general-purpose AI IDE can replicate, because no general-purpose AI IDE has a first-class runner for distributed .NET solutions. |
|||
|
|||
**Solution Runner** is the ABP Studio feature that knows about every runnable thing in your solution: web apps, microservices, gateways, identity servers, background workers, CLI applications, mobile and SPA front-ends, plus the Docker containers your stack depends on (databases, caches, message brokers). Apps are grouped into folders and can be launched as a coherent set under a named *run profile*. You start everything with one click; ABP Studio handles ports, dependencies, restart-on-failure, and embedded browser previews. |
|||
|
|||
ABP Agent talks to the Solution Runner directly. It can: |
|||
|
|||
- Start, stop, or restart a specific application, every application inside a folder ("Backend/API"), or all applications. |
|||
- Start or stop Docker containers separately from applications. |
|||
- Run tasks defined in your run profile (database migrations, npm scripts, custom scripts). |
|||
|
|||
When the agent starts an application that crashes on startup, it does not loop forever restarting it. It captures the recent logs from that application, summarizes the failure, returns a structured report to itself, and uses that to **fix the underlying bug in the code** before trying again. |
|||
|
|||
But starting apps is only half of it. The **runtime monitor** is the other half. When your applications run under ABP Studio, the IDE collects, in real time: |
|||
|
|||
- **Exceptions**: type, message, full stack trace, inner exceptions, source application. |
|||
- **Logs**: timestamps, log level, application, message. |
|||
- **HTTP requests**: method, URL, status code, response time. |
|||
- **Distributed events**: name, source, direction (published/received), and payload. |
|||
|
|||
ABP Agent can query all of this. The development loop becomes: |
|||
|
|||
> Generate the code → Build the affected module → Restart the affected application → Hit the endpoint or perform the action → Ask the agent to inspect the last exceptions, the failing HTTP requests, and the distributed events → Fix the bug → Repeat. |
|||
|
|||
That is the loop a generic IDE cannot do, because it cannot see your application after it starts. ABP Agent can. |
|||
|
|||
--- |
|||
|
|||
## Custom Workflows & Task Runner Integration: Determinism When You Need It |
|||
|
|||
LLMs are powerful but non-deterministic. In real teams, some steps must happen **every time** (before or after the agent works) and they must happen in a known order. That is what **Custom Workflows** are for. |
|||
|
|||
A workflow is a named sequence of deterministic steps with a *Before* phase and an *After* phase. You can configure steps such as: |
|||
|
|||
- Build (whole solution, specific modules, or specific packages) |
|||
- Start, stop, or restart applications (specific apps, an entire folder, or all) |
|||
- Start or stop containers |
|||
- Run a Task (any custom task defined in your run profile: `npm install`, custom scripts, code generators, database resets, anything your team already wired into ABP Studio's Task Runner) |
|||
- Add a database migration |
|||
- Install client-side libraries |
|||
- Generate C# or Angular client proxies for HTTP APIs |
|||
|
|||
For example, you can configure a workflow that: |
|||
|
|||
- **Before** the agent works: starts the required containers and runs a code-generation Task. |
|||
- **After** the agent works: builds the affected modules, regenerates client proxies, restarts the gateway and the SPA, and adds a database migration. |
|||
|
|||
Workflows can be **personal** to you, or **shared with your team** through the solution's run profile file, so the deterministic pre/post pipeline travels with the repository and every developer gets the same behavior. |
|||
|
|||
The result is a clean separation: the LLM handles the creative, ambiguous middle (designing the change and writing the code), while your workflow guarantees the boring, must-happen steps around it. The agent becomes more deterministic exactly where determinism matters, without losing flexibility where it doesn't. |
|||
|
|||
The Task Runner integration is what makes the *After* phase especially valuable. You can run absolutely anything as a post-step: npm scripts, custom executables, code generators, integration test runners, lint passes, database refresh scripts. If your team already runs it as part of "I just changed some code, now do X", you can run it automatically after every agent turn. |
|||
|
|||
--- |
|||
|
|||
## Git & GitHub: Reviewing and Committing Without Leaving the IDE |
|||
|
|||
 |
|||
|
|||
ABP Studio now ships a full Git client with deep GitHub integration. The goal is simple: once the agent finishes a change, you should be able to review, commit, push, branch, and respond to review feedback **without ever leaving ABP Studio**. |
|||
|
|||
The Git side covers everything you'd expect: |
|||
|
|||
- Stage and commit changes with rich, package-grouped change views. |
|||
- Create, switch, and merge branches. |
|||
- Stash and restore work, including a clear flow for stashing before switching branches. |
|||
- View commit history and create branches from any commit. |
|||
- Resolve merge conflicts with a built-in conflict editor. |
|||
- Push, pull, fetch, with seamless OAuth-based GitHub authentication. |
|||
|
|||
On the GitHub side: |
|||
|
|||
- Browse and filter Issues, view their comments, and send an issue (or just its comments) directly to ABP Agent to start working on it. |
|||
- View existing Pull Requests, see their requested changes and comments inline, and send the requested-changes feedback straight into ABP Agent so it can address the reviewer's comments. You can send the feedback into the same session you used to write the change, or start a fresh agent session. |
|||
- A one-click "Create Pull Request" action opens the new-PR page on GitHub directly from the IDE, pre-targeted at the current branch. |
|||
- Jump to any file on GitHub directly from the IDE. |
|||
|
|||
Two AI-assisted touches make this loop especially smooth: |
|||
|
|||
- **AI-generated commit messages.** Click "Generate with AI" and ABP Agent writes a Conventional Commits-style message from the staged diff. Edit it if you want, then commit. |
|||
- **AI Code Review on the diff.** Select the files you want reviewed, run AI review, and inline suggestions stream into the IDE as the analysis runs. Crucially, this is not a generic code review; it is an **ABP-aware** review. The reviewer looks for ABP-specific pattern violations: plain POCOs where ABP base classes belong, direct `DbContext` injection where a repository should be used, hardcoded strings where localization should be used, plain exceptions where `BusinessException` belongs, role-based authorization where ABP Permissions are the right answer, and so on. When the reviewer is unsure, it consults the official ABP documentation before flagging an issue. |
|||
|
|||
The result is a *closed loop*: the agent writes the change, you (or the AI reviewer agent) review the diff, you let the agent fix the comments, you commit with an AI-suggested message, you push, and you head to GitHub for the pull request, all from inside ABP Studio. |
|||
|
|||
--- |
|||
|
|||
## The End-to-End Development Loop |
|||
|
|||
Put the pieces together and ABP Studio becomes the single place where the whole development cycle happens: |
|||
|
|||
1. Open an issue from GitHub, send it to ABP Agent. |
|||
2. Switch to Plan mode; ABP Agent investigates the analyzed solution, consults the ABP docs, produces a structured plan. |
|||
3. Promote the plan to Agent mode. Implementation starts from the plan. |
|||
4. The *Before* workflow runs (start containers, run preparation tasks). |
|||
5. ABP Agent writes the code, batching edits across the affected modules, and fixes any compile errors directly. |
|||
6. The *After* workflow runs (build the affected modules, install client-side libraries, generate proxies, add a database migration, restart the impacted applications). |
|||
7. ABP Agent inspects the runtime monitor (exceptions, logs, HTTP requests, distributed events) and fixes any bug it sees. |
|||
8. You (or the AI reviewer) review the diff. Comments are sent back into the same agent session, or into a new one. |
|||
9. ABP Agent generates a commit message; you commit and push. |
|||
10. Open the new-pull-request page on GitHub with one click from ABP Studio. When reviewers leave requested changes, send them into the same agent session or start a fresh one, and iterate. |
|||
|
|||
You do not need to switch to a terminal to build. You do not need a separate tool to start your microservices. You do not need a different IDE to watch logs. You do not need a separate window for Git and GitHub. **ABP Studio is the only program you use during development, all in one.** |
|||
|
|||
--- |
|||
|
|||
## Learning Over Time |
|||
|
|||
ABP Agent also has a small but powerful feedback feature: when it makes a mistake and you (or the build, or the ABP docs) correct it, it can save that correction as a **lesson**. Lessons are short, verified notes that the agent carries forward into future turns and future sessions, so the same mistake does not happen twice. Over time, the agent gets better at the specific conventions and quirks of *your* solution, not just generic ABP. |
|||
|
|||
--- |
|||
|
|||
## Honest Comparison With Generic AI IDEs |
|||
|
|||
To be fair: Cursor, Claude Code, Windsurf and opencode are excellent products. They have semantic search, plan/agent modes, sub-agents, file editing, and shell access, and we wouldn't dispute any of that. But for ABP development specifically, here is where ABP Agent is genuinely different: |
|||
|
|||
| Capability | ABP Agent | Generic AI IDEs | |
|||
| --- | --- | --- | |
|||
| Aware of ABP roles (aggregate root, app service, repository, DTO, ETO, event handler, etc.) | Yes, structurally indexed | No (flat file/text view) | |
|||
| Knows your solution's modules, layers and dependency rules | Yes | No | |
|||
| Builds with module/package scope as a first-class operation | Yes, structured build result | No, runs `dotnet build` in a shell and parses output | |
|||
| First-class Solution Runner for distributed .NET apps + containers | Yes | No, generic shell processes | |
|||
| Restarting an application, opening its URL, waiting for it to be ready | Yes, built in | No | |
|||
| Live runtime telemetry as a tool: exceptions, logs, HTTP requests, distributed events | Yes | No | |
|||
| ABP-specific patterns checked during AI code review | Yes | Generic patterns only | |
|||
| Pre/post workflows with deterministic build / start / migrate / generate-proxies steps | Yes | No first-class concept | |
|||
| Task Runner integration for arbitrary pre/post steps owned by your team | Yes | No | |
|||
| Adding EF Core migrations as a first-class agent action | Yes | Shell only | |
|||
| Generating C#/Angular client proxies as a first-class agent action | Yes | Shell only | |
|||
| Native ABP documentation as authoritative source for the agent's decisions | Yes | Generic web search | |
|||
| Integrated Git + GitHub (issues, PR viewing, AI review) inside the same window | Yes | Partial / external | |
|||
|
|||
The pattern is consistent: **anything ABP-specific or runtime-specific belongs to ABP Agent and ABP Studio. Anything general-purpose is something everyone has.** That is the line we drew on purpose. |
|||
|
|||
--- |
|||
|
|||
## What This Means For You |
|||
|
|||
If you build with ABP Framework, this release changes how you work in three concrete ways: |
|||
|
|||
1. **You stop describing your solution to the AI.** ABP Agent already knows it. |
|||
2. **You stop bouncing between tools.** Editor, runner, runtime monitor, Git, GitHub, AI review, they all live in one window with one feedback loop. |
|||
3. **You stop accepting non-deterministic side effects.** Custom workflows + Task Runner integration make the boring steps boring again, while the agent focuses on the creative ones. |
|||
|
|||
This is the first release that brings AI assistance to ABP Studio, and we built it so that it is designed *around* the agent rather than bolted on. We think this is the natural shape of AI-assisted enterprise .NET development. |
|||
|
|||
--- |
|||
|
|||
## Short-Term Roadmap |
|||
|
|||
This release is the first step. The features below are already on our short-term roadmap and will land in upcoming releases: |
|||
|
|||
- **Debug Mode**: a dedicated mode where you and ABP Agent co-operate when debugging the solution. The agent can follow breakpoints, inspect state, propose fixes mid-session, and re-run after each change. |
|||
- **Browser control for the agent**: ABP Agent will be able to drive the embedded browser, browse pages, fill forms, and click buttons, so it can verify a UI flow end-to-end on its own and report what it observed. |
|||
- **Custom Workflows improvements**: more step types, richer conditions, finer-grained targets, and better visibility into which workflow ran for which agent turn. |
|||
- **GitHub integration improvements**: in-IDE pull request creation (no more jumping to the GitHub website), richer review handling, and more first-class issue and PR actions for the agent. |
|||
- **Git integration improvements**: more advanced day-to-day Git operations available without leaving the IDE. |
|||
- **Design helper**: ABP Agent will generate images. |
|||
- **Create a new project with the agent**: an AI-driven solution creation flow where you describe the application you want and ABP Agent helps choose the right template, modules, and configuration. |
|||
- **ABP Suite integration**: ABP Agent will be able to invoke ABP Suite for CRUD-page generation. Instead of asking the LLM to write the full set of layers for a CRUD page (which spends a lot of tokens and time), the agent will hand the task to ABP Suite, get a deterministic, production-quality result back, and continue with the parts that actually need the AI. |
|||
|
|||
## Live Demo |
|||
|
|||
We have previewed the ABP Agent in our latest community talk. Click to watch it: |
|||
|
|||
[](https://www.youtube.com/watch?v=GYVFn2lRuWw) |
|||
|
|||
### Also see |
|||
|
|||
* https://abp.io/studio/ai-agent |
|||
|
After Width: | Height: | Size: 52 KiB |
|
After Width: | Height: | Size: 246 KiB |
|
After Width: | Height: | Size: 321 KiB |
|
After Width: | Height: | Size: 249 KiB |
|
After Width: | Height: | Size: 93 KiB |
|
After Width: | Height: | Size: 162 KiB |
|
After Width: | Height: | Size: 1.3 MiB |
|
After Width: | Height: | Size: 869 KiB |
@ -0,0 +1,117 @@ |
|||
# The Antidote to Vibe Architecting: ABP Studio AI Agent |
|||
|
|||
Recent discussions in software engineering have started pointing at a quiet but critical side effect of AI-assisted development. The uncomfortable truth is simple: **AI agents no longer just write code, they make architectural decisions, yet almost no one reviews those decisions as architecture.** |
|||
|
|||
Here is a striking observation: for the *same task*, changing nothing but the wording of your prompt can produce a system whose line count and file count grow several times over. In other words, the words in your prompt shape the architecture of the system. The phenomenon even has a name: **vibe architecting**, architecture that emerges from prompts rather than from deliberate, recorded design. |
|||
|
|||
In this article I will first lay out the problem, and then show why **ABP Studio AI Agent** is designed precisely to mitigate it. |
|||
|
|||
 |
|||
|
|||
--- |
|||
|
|||
## What Is "Vibe Architecting"? |
|||
|
|||
The **vibe coding** popularized by Andrej Karpathy (describing what you want in plain language and letting the AI write the code) has moved far beyond single-line autocomplete. Today's agents spin up entire systems from a single sentence of description. And there is a further step: while writing code, the agent is also **choosing the architecture.** |
|||
|
|||
We can identify five main **mechanisms** through which agents make hidden architectural decisions: |
|||
|
|||
1. **Model selection:** Different LLMs produce structurally different code; switching the model selector is itself an architectural choice. |
|||
2. **Task decomposition:** How the agent splits work into subtasks determines the module boundaries of the system. |
|||
3. **Default configuration:** Without explicit rules, the agent drifts toward defaults inherited from its training data. |
|||
4. **Scaffolding and autonomous generation:** A single prompt folds every framework, database, auth, and deployment choice into one interaction, with no visible rationale. |
|||
5. **Integration protocols:** How the system connects to the outside world is chosen by the agent or the tool, not by the team. |
|||
|
|||
Three properties set these decisions apart from human ones: |
|||
|
|||
- **Scale:** Framework, database, authentication, and deployment are selected in a single interaction, bundled together rather than as separately reviewable choices. |
|||
- **Speed:** Decisions a team would debate for days happen in **seconds**, faster than any review process can keep up with. |
|||
- **Opacity:** The decisions are buried inside the generated code: no ADR, no design document, no recorded rationale. |
|||
|
|||
This has two concrete consequences. The first is the **speed-review gap**: the agent builds a system in minutes, while the team needs hours or days to audit it. The second is **convergence onto narrow stacks**: agent-based tools default to the same stack again and again (e.g. React/TypeScript/Tailwind), which concentrates the security attack surface. In short, these decisions take seconds, arrive bundled, and leave no record behind. |
|||
|
|||
--- |
|||
|
|||
## The Bridge: The Risk Is Far Greater in Enterprise .NET |
|||
|
|||
The examples behind these discussions usually revolve around small chatbots. But carry the same mechanisms over to an **enterprise, modular, distributed** solution and the risk multiplies. A hidden architectural decision now looks like this: |
|||
|
|||
- An `ApplicationService` depending directly on `DbContext` (a layering violation), |
|||
- Raw data access instead of a repository, |
|||
- A hand-written `[Authorize(Roles=…)]` instead of the ABP permission system, |
|||
- Hardcoded text instead of localized strings, |
|||
- A wrong module dependency, or a flawed event/flow design. |
|||
|
|||
None of these stand out in a small prototype; but in an enterprise system with dozens of modules and many services, they turn into **technical debt that piles up unseen.** And this debt starts accumulating before the code even runs, right at the moment of production. |
|||
|
|||
--- |
|||
|
|||
## The Prescription: A Three-Layer Governance Framework |
|||
|
|||
A three-layer framework that maps existing tool mechanisms onto classic software-architecture concepts is a sensible answer to this problem: |
|||
|
|||
- **Layer 1, Constraints:** Defines what the agent may and may not do. Today, instruction files (AGENTS.md, .cursorrules) and MCP configurations play this role informally; in architecture terms, the equivalent is ADLs and Attribute-Driven Design. |
|||
- **Layer 2, Conformance:** Checks the generated code against those constraints. Plan-build flows (the agent proposes before acting) and post-generation hooks are the counterpart of *fitness functions* in evolutionary architecture. |
|||
- **Layer 3, Knowledge:** Feeds architectural context back to the agent. Today, repository maps and context files; in architecture terms, ADRs and Architectural Knowledge Management. |
|||
|
|||
One caveat worth noting: tools that deliver all three layers together, proactively, are still **largely missing** today. And that is exactly where it gets interesting. |
|||
|
|||
--- |
|||
|
|||
## ABP Studio AI Agent: The Prescription, Implemented |
|||
|
|||
ABP Studio AI Agent is not a general-purpose code agent; it is an in-IDE agent that understands ABP solutions *as systems*. Look at its design and you will see it covers all three layers above with surprising clarity. |
|||
|
|||
### Layer 1, Constraints: ABP-Aware by Default |
|||
|
|||
The first layer calls for "a constraint layer that tells the agent what it may do." ABP Agent brings this as default behavior. By instruction, the agent prefers: **ABP base classes** over plain POCOs, **repositories** over direct `DbContext`, **`ApplicationService`** over plain services, the **ABP permission system** over `[Authorize(Roles=…)]`, **localized strings** over hardcoded text, **`BusinessException`/`UserFriendlyException`** over plain `Exception`, and the **distributed cache** abstraction over raw in-memory cache. When it is unsure about an ABP feature, it consults the **official ABP documentation** as the authoritative source, not random blog posts. |
|||
|
|||
On top of that, **Custom Workflows** define the deterministic steps that must run before and after every agent turn, and they can be shared with the team. So the constraints don't live in one developer's head; they live inside the solution. |
|||
|
|||
### Layer 2, Conformance: Plan Mode + ABP-Aware Review |
|||
|
|||
 |
|||
|
|||
The second layer calls for "plan-build flows and fitness-function-like checks." ABP Agent has two concrete answers to this: |
|||
|
|||
- **Plan mode:** The agent first inspects the solution in read-only mode, consults the ABP docs, and produces a structured implementation plan (Problem, Solution, Workflow Diagram, Files Affected, Expected Result). Once you approve it, the plan turns into implementation with a single click. This is exactly the "propose before acting" flow the framework asks for. |
|||
- **ABP-aware AI code review:** This is not a generic review; it catches **ABP-specific pattern violations**: POCOs in the wrong place, direct `DbContext` injection, hardcoded strings, plain exceptions, role-based authorization, and so on. When unsure, it checks the official ABP docs. This is the concrete form of a **fitness function** that audits generated code against the constraints. |
|||
|
|||
### Layer 3, Knowledge: Analyze Engine + Lessons |
|||
|
|||
 |
|||
|
|||
The third layer calls for "a knowledge layer that feeds architectural context back to the agent": repository maps, ADRs. ABP Agent's **Analyze engine** is a higher-level version of this: the moment you open a solution, it scans every package and produces a **typed, ABP-role-aware** structural map. It knows what each type actually is: an aggregate root, a repository, an application service, a DTO, an ETO, a permission provider. The agent receives this map at the start of every session; it doesn't look at folders and guess, it **knows** the structure of the solution. |
|||
|
|||
Add to that **lessons**: when the agent makes a mistake and gets corrected, it records the correction as a short, verified note and carries it into future sessions. This is a living counterpart to the ADR/AKM idea of persisting decisions and their rationale. |
|||
|
|||
--- |
|||
|
|||
## The Problem → ABP Agent's Answer |
|||
|
|||
| The problem being raised | ABP Studio AI Agent's answer | |
|||
| --- | --- | |
|||
| **Opacity:** decisions buried in code, no rationale | The Analyze engine makes the structure visible; Plan mode turns a decision into a written plan first | |
|||
| **Speed-review gap:** agent fast, review slow | Deterministic workflows + ABP-aware review close the loop inside the IDE | |
|||
| **Convergence onto narrow stacks / concentrated risk** | ABP already provides a consistent, secure, enterprise stack and conventions | |
|||
| **Governance / ADR gap** | Lessons + shared custom workflows put decisions on the record | |
|||
| **Implicit coupling:** the prompt dictates the infrastructure | Solution-awareness means infrastructure is determined by the real structure, not by guesswork | |
|||
|
|||
The pattern is consistent: everything the governance framework says "should exist" is part of ABP Agent's design. |
|||
|
|||
--- |
|||
|
|||
## An Honest Boundary |
|||
|
|||
Let's be clear: the governance framework above is a general, ABP-independent discussion; it wasn't built to promote ABP. Nor are we claiming that "academia recommends ABP." Our claim is more modest and more solid: ABP Studio AI Agent's design **overlaps remarkably** with these **principles**. Vibe architecting is a real risk, and no tool reduces it to zero; but in enterprise .NET development, ABP Agent is built to reduce that risk meaningfully. |
|||
|
|||
--- |
|||
|
|||
## Conclusion |
|||
|
|||
The real question is not whether AI agents make architectural decisions; they do, and that is now an irreversible reality. The real question is this: are those decisions **visible, governed, and reviewable**, or do they get quietly buried in the code and turn into technical debt? |
|||
|
|||
ABP Studio AI Agent is designed to answer "yes, visible and governed." It surfaces decisions instead of hiding them; it knows the structure of the solution instead of guessing; it learns and keeps a record instead of starting from scratch every time. If you build enterprise software in the age of vibe architecting, that is exactly where the difference lies. |
|||
|
|||
- **ABP Studio AI Agent:** https://abp.io/studio/ai-agent |
|||
- **Live demo (community talk):** https://www.youtube.com/watch?v=GYVFn2lRuWw |
|||
File diff suppressed because it is too large
@ -0,0 +1,159 @@ |
|||
```json |
|||
//[doc-seo] |
|||
{ |
|||
"Description": "Learn how the ABP React Native startup template is styled with NativeWind v4 (Tailwind CSS for React Native), including the semantic color tokens, dark mode and theme customization." |
|||
} |
|||
``` |
|||
|
|||
# Styling with NativeWind |
|||
|
|||
The ABP React Native startup template uses **[NativeWind v4](https://www.nativewind.dev/)** — Tailwind CSS for React Native. Most components are styled through utility `className` props that are compiled at build time, so there is almost no styling runtime cost. The design system is based on the **shadcn/ui** neutral palette and supports **light and dark themes** out of the box. |
|||
|
|||
> This page documents the styling system that ships with the template. For the general getting-started flow (installing tools, running the app, configuring the backend), see [Getting Started with React Native](index.md). |
|||
|
|||
<img width="360" src="../../../images/rn-home-screen.png" alt="HomeScreen built with NativeWind" /> |
|||
|
|||
--- |
|||
|
|||
## 1. Project Files |
|||
|
|||
NativeWind is wired in through a small set of configuration files at the root of the React Native project: |
|||
|
|||
| File | Purpose | |
|||
|------|---------| |
|||
| `tailwind.config.js` | Defines the design tokens (colors, spacing, border radius), enables `darkMode: 'class'`, and registers the NativeWind preset. This is the source of truth for the theme. | |
|||
| `global.css` | Tailwind entry point with the three base directives (`@tailwind base; @tailwind components; @tailwind utilities;`). | |
|||
| `metro.config.js` | Wraps the default Expo Metro config with `withNativeWind(...)` and points it at `global.css`. | |
|||
| `babel.config.js` | Adds the `nativewind/babel` preset and sets `jsxImportSource: 'nativewind'` on `babel-preset-expo` so JSX understands the `className` prop. | |
|||
| `nativewind-env.d.ts` | TypeScript triple-slash reference (`/// <reference types="nativewind/types" />`) that adds `className` typings to React Native components. | |
|||
|
|||
All of these files come pre-configured in the template. You normally only need to edit `tailwind.config.js` to customize the theme. |
|||
|
|||
--- |
|||
|
|||
## 2. Semantic Color Tokens |
|||
|
|||
Instead of raw color names like `bg-zinc-900`, the template exposes a small set of **semantic tokens** that follow the shadcn/ui convention. Each token has a default (light) value and a `dark` variant, and many also carry a paired `foreground` color for text/icons placed on top. |
|||
|
|||
| Token | Use it for | |
|||
|-------|-----------| |
|||
| `background` / `foreground` | Screen background and primary text. | |
|||
| `card` / `card-border` | Surface containers (settings rows, feature cards) and their 1px border. | |
|||
| `primary` / `primary-foreground` | Filled call-to-action buttons. | |
|||
| `secondary` / `secondary-foreground` | Subtle filled elements such as icon chips inside cards. | |
|||
| `muted` / `muted-foreground` | Backgrounds and text for secondary information (subtitles, helper text). | |
|||
| `accent` / `accent-foreground` | Highlighted/active state — also used as the active tint of the bottom tab bar. | |
|||
| `destructive` / `destructive-foreground` | Delete/danger actions and error states. | |
|||
| `border` | Generic separators and outline borders. | |
|||
| `input` | Border color for text inputs (Paper `TextInput` outline). | |
|||
| `ring` | Focus ring/outline color. | |
|||
|
|||
All token values live in `tailwind.config.js` under `theme.extend.colors`. Refer to that file for the exact hex values. |
|||
|
|||
The template also extends Tailwind's spacing and border-radius scales so paddings and corners stay consistent across screens: |
|||
|
|||
* **Spacing:** `xs` (4px), `sm` (8px), `md` (16px), `lg` (24px), `xl` (32px) — usable as `p-md`, `mt-lg`, `gap-sm`, etc. |
|||
* **Border radius:** `rounded-sm` (4px), `rounded-md` (8px), `rounded-lg` (12px), `rounded-xl` (16px), `rounded-2xl` (20px). |
|||
|
|||
--- |
|||
|
|||
## 3. Dark Mode |
|||
|
|||
Dark mode is enabled with `darkMode: 'class'` in `tailwind.config.js` and is driven by the device color scheme via NativeWind's `useColorScheme()` hook. Each color token has a sibling `*-dark` (and where applicable `*-dark-foreground`) variant, and components opt into it with the `dark:` prefix on their classes: |
|||
|
|||
```tsx |
|||
<View className="flex-1 bg-background dark:bg-background-dark"> |
|||
<Text className="text-foreground dark:text-foreground-dark"> |
|||
Hello |
|||
</Text> |
|||
</View> |
|||
``` |
|||
|
|||
> **Pattern note.** The token shape used in this template is `{ DEFAULT, dark }` (and `{ foreground, 'dark-foreground' }` where applicable), so the dark-mode class is `dark:bg-background-dark` — not `dark:bg-background`. Follow this convention when you add new screens so the theme switch behaves consistently across the app. |
|||
|
|||
The user can also switch themes manually from the **Settings** screen (system / light / dark), and the choice is persisted via Redux. |
|||
|
|||
<img width="360" src="../../../images/rn-home-screen.png" alt="HomeScreen with light and dark theme" /> |
|||
|
|||
--- |
|||
|
|||
## 4. The `useThemeColors` Hook |
|||
|
|||
A handful of APIs in the template do not accept a `className` — they need a *color value*. Examples: |
|||
|
|||
* `react-native-paper`'s `TextInput` (which the template still uses for outlined inputs and validation styling). |
|||
* React Navigation's `screenOptions` (header background, tab bar tint, etc.). |
|||
* The native status bar. |
|||
|
|||
For these cases the template ships a `useThemeColors` hook at `src/hooks/UseThemeColors.ts`. It returns theme-aware values that mirror the Tailwind tokens: |
|||
|
|||
```ts |
|||
const { |
|||
primaryContainer, // Paper TextInput surface |
|||
headerBg, // Navigator headers |
|||
headerText, |
|||
iconColor, // Inactive icon tint |
|||
accentColor, // Active icon tint / focused tab |
|||
destructiveColor, |
|||
inputBorderColor, |
|||
} = useThemeColors(); |
|||
``` |
|||
|
|||
**Rule of thumb:** prefer `className` with `dark:` variants whenever the component supports it; reach for `useThemeColors` only for the components listed above. |
|||
|
|||
--- |
|||
|
|||
## 5. React Native Paper |
|||
|
|||
`react-native-paper` is still in the template's `package.json`, but its usage has been narrowed down to a single component: **`TextInput`** in outlined mode (used for forms because of its strong validation/error UI). Buttons, lists, modals, drawers, and icons are all NativeWind + `@expo/vector-icons` (Ionicons) now. |
|||
|
|||
If you add new forms, follow the same split: |
|||
|
|||
* Use Paper's `TextInput` (with values from `useThemeColors`) for text fields. |
|||
* Use plain `View`/`Text`/`Pressable` with NativeWind classes for everything else. |
|||
|
|||
--- |
|||
|
|||
## 6. Customizing the Theme |
|||
|
|||
Most customization happens in `tailwind.config.js`. To introduce a brand color, extend the `colors` map and reuse the `{ DEFAULT, dark }` shape so the `dark:` variants keep working: |
|||
|
|||
```js |
|||
// tailwind.config.js |
|||
module.exports = { |
|||
// ... |
|||
theme: { |
|||
extend: { |
|||
colors: { |
|||
// ... |
|||
brand: { |
|||
DEFAULT: '#2563eb', |
|||
dark: '#3b82f6', |
|||
foreground: '#ffffff', |
|||
'dark-foreground': '#ffffff', |
|||
}, |
|||
}, |
|||
}, |
|||
}, |
|||
}; |
|||
``` |
|||
|
|||
You can then use it from any component: |
|||
|
|||
```tsx |
|||
<Pressable className="bg-brand dark:bg-brand-dark rounded-lg px-md py-sm"> |
|||
<Text className="text-brand-foreground dark:text-brand-dark-foreground font-semibold"> |
|||
Get started |
|||
</Text> |
|||
</Pressable> |
|||
``` |
|||
|
|||
If the new color also needs to be reachable from non-`className` APIs (Paper, navigators, status bar), add a matching entry to `useThemeColors` so the rest of the template stays consistent. |
|||
|
|||
--- |
|||
|
|||
## 7. Going Further |
|||
|
|||
* [NativeWind documentation](https://www.nativewind.dev/) — class reference, advanced features (variants, animations). |
|||
* [Tailwind CSS documentation](https://tailwindcss.com/docs) — utility classes, responsive design, theming. |
|||
* [shadcn/ui](https://ui.shadcn.com/) — the design system the color tokens are inspired by. |
|||
@ -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,142 @@ |
|||
```json |
|||
//[doc-seo] |
|||
{ |
|||
"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 |
|||
|
|||
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). |
|||
|
|||
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. |
|||
|
|||
## Technology Stack |
|||
|
|||
The React UI template is built with: |
|||
|
|||
| Technology | Purpose | |
|||
| --- | --- | |
|||
| [Vite](https://vite.dev/) | Build tool and dev server | |
|||
| [React](https://react.dev/) | UI framework | |
|||
| [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 | |
|||
| [OpenID Connect / OIDC](https://openid.net/connect/) | Authentication against the ABP Auth Server | |
|||
|
|||
The template also includes ABP-specific NPM packages: |
|||
|
|||
- [`@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) |
|||
|
|||
## React App and Admin Console |
|||
|
|||
A modern React solution contains two UI surfaces: |
|||
|
|||
- **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. |
|||
|
|||
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. |
|||
|
|||
See [Admin Console](./admin-console.md) for hosting, module discovery, and permission details. |
|||
|
|||
## Solution Structure |
|||
|
|||
The React app location depends on the modern 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/`. |
|||
|
|||
Typical structure: |
|||
|
|||
```text |
|||
react/ |
|||
├── dynamic-env.json |
|||
├── public/ |
|||
├── src/ |
|||
│ ├── components/ |
|||
│ ├── lib/ |
|||
│ ├── locales/ |
|||
│ ├── pages/ |
|||
│ ├── routes/ |
|||
│ └── main.tsx |
|||
├── package.json |
|||
├── vite.config.ts |
|||
└── vitest.config.ts |
|||
``` |
|||
|
|||
## Creating a Solution |
|||
|
|||
Install or update `Volo.Abp.Studio.Cli`, then create a modern solution: |
|||
|
|||
```bash |
|||
# Layered app with React UI |
|||
abp new Acme.BookStore --template app --modern --ui-framework react |
|||
|
|||
# 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 |
|||
``` |
|||
|
|||
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 |
|||
|
|||
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: |
|||
|
|||
```bash |
|||
cd react |
|||
npm install |
|||
npm run dev |
|||
``` |
|||
|
|||
For microservice templates: |
|||
|
|||
```bash |
|||
cd apps/react |
|||
npm install |
|||
npm run dev |
|||
``` |
|||
|
|||
Run tests with: |
|||
|
|||
```bash |
|||
npm run test |
|||
``` |
|||
|
|||
Build for production with: |
|||
|
|||
```bash |
|||
npm run build |
|||
``` |
|||
|
|||
## Documentation Map |
|||
|
|||
Use these pages to learn each part of the React UI: |
|||
|
|||
- [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 Studio](../../../studio/index.md) |
|||
- [ABP CLI](../../../cli/index.md) |
|||
- [Authorization](../../../framework/fundamentals/authorization/index.md) |
|||
- [Localization](../../../framework/fundamentals/localization.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) |
|||
|
Before Width: | Height: | Size: 5.4 MiB After Width: | Height: | Size: 1.6 MiB |
Some files were not shown because too many files changed in this diff
Loading…
Reference in new issue