How to package React UI in an ABP module (modern template) — module contributing pages/routes to the host React app #10753

7 Answer(s)

• 

  0

  AI-Bot created 3 months ago

  Support Team ABP Agent

  • There is no official “module ships React UI that auto-plugs into the host React app” pattern in ABP 10.4 (modern React). The modern React UI is intentionally source-owned (the generated React app contains the actual pages/components in the app itself, not pulled from framework-owned npm packages). So abp new-module --modern not generating a frontend project is expected with this approach.
  • In ABP 10.4’s modern React architecture you effectively have two separate UI surfaces:
    1. Your React application (your business/product UI, owned by the solution)
    2. ABP Admin Console (a pre-built React administration UI delivered via Volo.Abp.AdminConsole and hosted under /admin-console/* in layered/single-layer solutions, or as a separate app in microservice solutions)

  So, for your questions:

  1. Official/recommended pattern to package React UI inside an ABP module

  • Not available as a built-in ABP mechanism in 10.4 comparable to Angular module UI packaging/route contribution. ABP’s modern React direction is to keep app UI code inside the app repo, while administrative pages live in the Admin Console app.

  2. Should the module ship an npm package? What does integration look like?

  • ABP does not document or provide a standard integration contract for “module npm package contributes routes/menus into the host React app” in 10.4.
  • If you choose to do this yourself, it would be a custom convention in your organization (e.g., exporting route definitions, menu definitions, or components from an npm package and having the host import/register them). ABP does not provide the equivalent of a standardized “React module UI plug-in API” in the official 10.4 React UI docs.

  3. ABP-provided mechanism like Angular forRoot() / forChild() for routes/menu

  • No, not for the host React app in the way Angular does it. The ABP 10.4 React UI documentation emphasizes that React UI is source-owned in the app itself rather than being assembled from module UI packages.

  4. Add content to the Admin Console rather than the public site

  • The Admin Console is the place ABP provides for module administration pages in the modern React world. It is hosted under /admin-console/* (or as a separate admin-console app in microservices).
  • However, an official extensibility story for third-party modules to inject their own Admin Console pages is not something that’s described in the referenced official docs/articles for 10.4. (So: Admin Console is the correct target conceptually, but the “how to plug in your module’s pages” part is not documented as a supported mechanism here.)

  5. Commercial modules’ React source to reference

  • The Admin Console is delivered as a NuGet package (Volo.Abp.AdminConsole). The publicly available ABP docs/article above explain that it’s pre-built and upgradeable, but they don’t provide a public “reference React source code for commercial modules” workflow in the provided verified sources.
  • Therefore: No verified source available (in the official docs/pages retrieved here) that points to commercial modules’ React source as a concrete example for third-party UI packaging.

  Links (verified):

  • https://abp.io/docs/10.4/framework/ui/react
  • https://abp.io/docs/10.4/framework/ui/react/admin-console
  • https://abp.io/docs/10.4/framework/ui/react/components/
  • https://abp.io/community/articles/7rfmgb2v

  ---

  This response was generated by AI. If it didn’t solve your problem, feel free to post a new answer — our support team will jump in to help you soon.

  Markdown supported.

  Copy, paste, or drag & drop images and files (max 100 MB per file, 100 MB total per post)

  Save Cancel
• 

  0

  dshapiro created 3 months ago

  I'm awaiting a response from a human and hoping the AI response is based on limited documentation rather than the intended direction. The response as presented is disappointing.

  Although my read may be incorrect, given the relabeling of React as "modern" and Angular as "classic", it seems reasonable to assume that React is intended to become the primary UI stack going forward. If that's the case, I would expect the React ecosystem to support a proper module integration model, including the ability to build and deliver self-contained modules with both backend and frontend pieces. ABP itself already does this with modules like Text Templating, CMS Kit, Identity, etc., so it would be surprising if custom modules could not follow a similar pattern. Expecting module consumers to build their own frontend for each reusable module feels like a significant limitation and weakens the value of ABP's modular architecture.

  Additionally, the public React app / Admin Console split is a great direction and solves a real pain point. However, based on the current documentation and AI response, it seems like custom module management pages may need to be added to the public React app rather than contributed into the Admin Console. If that is accurate, I think that is a mistake. It is common to need both a public site and an admin site, and module-provided UI should be targetable to either the public or admin console as needed.

  So the main question is: is the modern React UI intended to support true frontend modularity for custom modules? If yes, it would be helpful to understand the planned extension points. If no, that has significant implications for anyone building reusable ABP modules on the modern React stack.

  Markdown supported.

  Copy, paste, or drag & drop images and files (max 100 MB per file, 100 MB total per post)

  Save Cancel
• 

  0

  maliming created 3 months ago

  Support Team Fullstack Developer

  Hi,

  You're reading it right. In the modern (React) stack there's no "a module ships its React UI and it plugs into the host app" mechanism today, the way the classic Angular template does it. That's not something wrong with your setup, it's where the modern React UI currently stands, and it's a gap the team has on the roadmap. Let me answer each question with the current state, show the pattern that works today, and then point you at the direction.

  1 and 3) There's no official packaging or forRoot()/forChild()-style mechanism for React. Routing in the template is hand-written with TanStack Router in src/routes/router.tsx, and the menu is a static routeConfig array in src/lib/routing/route-config.ts that the sidebar reads. There's no provider/registry layer a module can register into, so the host adds routes and menu items explicitly. For contrast: the module template does generate UI for MVC, Blazor and Angular, and Angular even ships the provideXxx() route-provider plus npm packages you're thinking of. React just isn't one of the module-template UI options yet, which is exactly why abp new-module produces no React frontend.

  2. Shipping a React npm package alongside your NuGet packages is the practical approach today, but it's your own convention rather than a standardized ABP contract. Keep the package "dumb": export the page components plus a small menu-metadata array, and let the host do the route registration (the route tree, rootRoute, and the permission guards are host-local, so the package shouldn't import host internals). This is the same "add a page" / "add a sidebar item" flow the customization docs describe:

  // In your module's npm package, e.g. @acme/product-management-react
  export { ProductsPage } from './pages/ProductsPage'
  
  export const productMenuItems = [
    {
      path: '/products',
      nameKey: 'ProductManagement::Products',
      requiredPolicy: 'ProductManagement.Products',
    },
  ]
  

  The host wires the route in src/routes/router.tsx:

  import { ProductsPage } from '@acme/product-management-react'
  
  const productsRoute = createRoute({
    getParentRoute: () => rootRoute,
    path: '/products',
    component: ProductsPage,
    beforeLoad: createPermissionGuard('ProductManagement.Products'),
  })
  
  const routeTree = rootRoute.addChildren([
    indexRoute,
    forbiddenRoute,
    accountRoute,
    identityRoute,
    productsRoute, // your module's route
  ])
  

  and the menu item in src/lib/routing/route-config.ts:

  import { productMenuItems } from '@acme/product-management-react'
  
  export const routeConfig: RouteConfigItem[] = [
    // ...existing items
    ...productMenuItems,
  ]
  

  A few things to keep the package portable:

  • Set react, react-dom, @tanstack/react-router, @tanstack/react-query, react-i18next (and lucide-react if you use icons) as peerDependencies so you don't pull a second copy into the host.
  • Your localization keys (nameKey) need to reach the host's i18n. Ship them with the package and have the host merge them into its resources.
  • For API calls, reuse the host's configured Axios/api layer rather than a standalone client in your package. The template's Axios already handles auth tokens, the current tenant, language headers and 401/403 behavior, and a separate client would miss all of that. After your module's HTTP API is added, the host runs npm run generate-proxy (abp generate-proxy -t js) to get the typed client. The proxy isn't generated from the NuGet package automatically.

  4. The Admin Console is a separate, pre-built React app delivered as the Volo.Abp.AdminConsole NuGet package and served at /admin-console. It decides which module pages to show by checking the backend services present in the host, but the page set is built-in and there's no supported way for a third-party module to inject its own pages into it. So your module's management pages go into your own React app instead. You can put them behind an auth/permission layout (like the generated IdentityLayout) to make them admin-style.

  5. We don't currently publish per-module React UI packages/source the way the classic Angular template did. In the modern stack the commercial modules' admin UI is bundled inside the pre-built Admin Console, not distributed as referenceable React source. The closest reference you have is the Identity management UI the template generates into your own app under src/pages/identity and src/components/identity — that's the same pattern to follow for your module's pages.

  On the direction, which is the part you actually care about: the source-owned model is deliberate for your app's own pages, but modules contributing UI into the host for React is a recognized gap, and it's tracked on the public roadmap. The way ABP thinks about a UI-framework integration is in three parts: framework-level integration (auth, permissions, localization, settings), the theme/component stack, and reusable module UI. For React the first two are in place as of 10.4; the third — module UI that a module can contribute into another app — is the missing piece. The plan to address it is the Hybrid UI System: reusing a module's UI across technologies so it doesn't have to be re-implemented natively for every stack. The public roadmap lists foundational "Hybrid UI / page embedding infrastructure" under v10.6, and the broader direction is tracked in the issue below. It's still a backlog item, so please take it as the direction being worked toward, not a committed React module-UI package or a specific version:

  • https://abp.io/docs/latest/release-info/road-map
  • https://github.com/abpframework/abp/issues/23102

  That issue is worth following and commenting on — your exact scenario (a distributable module shipping both backend and frontend, targetable to the app or an admin surface) is the use case it's meant to solve, and feedback there directly shapes the design.

  Thanks

  Markdown supported.

  Copy, paste, or drag & drop images and files (max 100 MB per file, 100 MB total per post)

  Save Cancel
• 

  0

  dshapiro created 3 months ago

  Thank you, Liming!

  Just to confirm I understood the proxy guidance correctly: historically, distributable modules were responsible for their own app services and proxy layer. The app services for the module would exist within their own module (per /api/abp/api-definition), and the Angular frontend package would ship with the appropriate proxies to communicate with that app service layer. In your React example, you mentioned that the host application, not the distributed module, would be responsible for generating the proxies. Does this mean that, for the modern React stack, the distributed module's app service layer should be exposed through the main application module? This could complicate things if we need to support both an Angular UI (where the app services and proxies are owned by the module) and a React UI (where the app services may need to be merged into the main app module).

  Secondly, it is important for me to understand ABP’s direction before I commit my company to an approach. Can you confirm whether ABP’s new naming scheme — Angular = classic, React = modern — signals that ABP is committing to a shift away from Angular and toward a new React-based frontend? Or, with the pending Hybrid UI infrastructure, is ABP’s long-term direction more that UI modules should eventually be framework-neutral? If the latter, I would suggest reconsidering the classic/modern naming, since it implies an intended migration path from Angular to React.

  The practical reason I’m asking is that we need to decide how to build reusable modules today. It would be useful to know whether the recommended path forward is Angular or React, or whether this is something we should wait on until the Hybrid UI spec is more clearly defined.

  Markdown supported.

  Copy, paste, or drag & drop images and files (max 100 MB per file, 100 MB total per post)

  Save Cancel
• 

  0

  maliming created 3 months ago

  Support Team Fullstack Developer

  Hi,

  Good questions, let me take them in order.

  On the proxy and app-service ownership: the backend doesn't change between Angular and React, and you don't need to move your module's app services into the main application module. Your module keeps its own .Application.Contracts, .Application and .HttpApi layers exactly as before. When the host references your module's packages and depends on its module class, ABP brings the module's services and HTTP APIs into the host at runtime — that's the normal module dependency mechanism, and it's identical whether the host UI is Angular or React. So /api/abp/api-definition still exposes your module's endpoints the same way.

  Where it's not symmetric is the frontend packaging. In the Angular world your module ships an npm package that includes the generated proxies and a provideXxx() provider, so the consumer gets the client and the routes from that package. React doesn't have that built-in module pipeline yet. On the React side the API layer is source-owned under src/lib/api on a shared Axios instance, and you regenerate the typed client from the running host (the template's generate-proxy script) rather than from a per-module package. You can still publish a React npm package that ships its own API client, but that's a custom convention you own, not an ABP-provided module integration contract. So: backend symmetry yes, frontend packaging symmetry no, and nothing needs to be merged into the main app module.

  On the naming and direction: "classic" and "modern" refer to the solution template system, not an Angular-to-React migration. The classic family is the Single-Layer / Layered templates; the modern family is the ABP Studio wizard architectures (Simple Monolith, Layered Monolith, Modular Monolith, Microservice). React is available only in the modern template system, which is where the "Angular = classic, React = modern" impression comes from, but it isn't a signal that Angular is being retired. Angular is actively maintained — the roadmap includes Angular UI fixes and proxy generation improvements, and Angular SSR is already documented.

  React was added as an additional first-class UI option, not a replacement. The longer-term "framework-neutral module UI" idea you're describing matches the public Hybrid UI System backlog item: re-using a module's UI across technologies so a module doesn't have to re-implement a native UI for each stack. I'd read that as the direction being explored rather than a committed plan, and it's the right place to weigh in:

  • https://github.com/abpframework/abp/issues/23102

  On what to build today: if your priority is shipping a reusable module with an officially-supported frontend integration right now, Angular is the safer choice — it has the mature module-UI packaging story (module project, dev-app, npm package, provideXxx() provider, generated proxies). React is a great choice for application-owned UI, and you can make a module's React UI work with the custom npm convention from my previous reply, but ABP doesn't yet provide the same module frontend packaging/injection for React.

  I wouldn't block your backend/module design on the Hybrid UI work, since it's still a backlog item with no committed version. The backend module is the same either way, so you can build it cleanly now and pick the UI packaging based on what you need to deliver — Angular if you need a distributable module frontend today, React (with the custom convention) if the UI is mainly for your own app.

  Thanks

  Markdown supported.

  Copy, paste, or drag & drop images and files (max 100 MB per file, 100 MB total per post)

  Save Cancel
• 

  0

  dshapiro created 2 months ago

  Thanks Liming, I think I see where my confusion was.

  I was thinking of generate-proxy as only targeting the default app module, but I've been reminded that proxies can be generated for a specific module key (if listed in /api/abp/api-definition).

  So if I understand correctly, the distributed modulecan remain structured normally, with its API surface exposed under its own module key. Then, on the React side, the consuming host would generate proxies for both its own app module and for my distributed module, unless we create our own convention for shipping/generated API clients inside our React npm package.

  That answers my question. Thanks for clarifying.

  Markdown supported.

  Copy, paste, or drag & drop images and files (max 100 MB per file, 100 MB total per post)

  Save Cancel
• 

  0

  maliming created 2 months ago

  Support Team Fullstack Developer

  Hi,

  Exactly right — the module keeps its normal structure and its own module key, and the host generates proxies per module key (its own app plus your module), unless you ship a pre-generated client in your React package.

  Glad it's clear now. Reach out anytime if more comes up as you build it.

  Thanks

  Markdown supported.

  Copy, paste, or drag & drop images and files (max 100 MB per file, 100 MB total per post)

  Save Cancel