How to Build a Custom Portal in Frappe Framework Using Vue or React

If you've built anything with ERPNext or Frappe, you already know how much the framework provides out of the box: data modeling, permissions, workflows, REST APIs, and a ready-to-use interface.

For internal operations, that built-in UI is often enough.

But when you need to give customers, vendors, students, dealers, or partners a branded, modern, self-service experience, the standard Frappe interface can feel limiting. That raises an important question:

Can you keep Frappe as the backend while building a custom frontend with Vue or React?

Yes. In fact, this is a well-established approach.

This guide explains why you might choose a custom portal, when it's worth the investment, and how to build one using Frappe as the backend and Vue or React as the frontend.

Why Build a Custom Frappe Portal?

A portal can turn an internal ERP system into a customer-facing digital product that drives revenue.

Consider a few examples:

• Dealer portal: Dealers can place and track orders without relying on sales representatives.
• Student portal: Students and parents can view grades, attendance, and fees through a branded interface.
• Customer portal: Customers can track orders, invoices, and service requests.
• Vendor portal: Suppliers can submit quotations and track purchase orders.
• Service portal: Customers can manage requests themselves, reducing support workload.

In all these cases, Frappe/ERPNext can continue handling the underlying data and business logic. The custom frontend simply determines how that information is presented and what users can access.

The standard Frappe UI is designed primarily for administrative and internal workflows. A customer-facing portal often requires a different experience: simpler navigation, responsive layouts, stronger branding, and workflows designed specifically around external users.

However, a custom portal is a real software project, not simply a configuration change. You need to account for design, frontend development, authentication, deployment, security, and ongoing maintenance.

Why Decouple the Frontend from Frappe?

The Limitation of Frappe's Native UI

Frappe's Desk and Portal features are excellent when speed and functionality are the priority. Define a DocType and you immediately have forms, lists, filters, permissions, and other functionality.

The trade-off is customization.

If you need completely different layouts, interactions, navigation patterns, or branding, heavily modifying the standard interface can become increasingly difficult.

What a Separate Frontend Provides

Separating the frontend (Vue or React) from the backend (Frappe) gives you:

• Complete UI/UX control: Build the experience around your users and brand.
• Modern frontend tooling: Use component libraries, responsive layouts, animations, and modern development workflows.
• Broader developer availability: React and Vue developers are widely available and far easier to find than developers who specialize in Frappe's UI internals.
• Independent releases: Frontend and backend changes can be deployed independently.
• Product-level flexibility: The portal can evolve into a complete customer-facing application.

When You Should Not Decouple

Decoupling isn't always the right answer.

If you're building an internal-only application, such as a warehouse dashboard or accounting workflow, Frappe's existing interface may already provide most of what you need.

A custom frontend makes more sense when:

• External users will access the system.
• Branding and user experience are important.
• The workflow doesn't fit an administrative interface.
• The portal is strategically important to the business.

If none of these apply, the additional development and maintenance cost may not be justified.

Frappe as an API-First Backend

This is the technical foundation that makes the whole approach possible.

The biggest advantage of this architecture is that you don't have to rebuild your ERP logic in JavaScript.

Frappe provides a REST-style API for DocTypes. For example:

GET /api/resource/Customer
GET /api/resource/Customer/CUST-0001
POST /api/resource/Customer
PUT /api/resource/Customer/CUST-0001

For more complex operations, you can expose custom Python functions using @frappe.whitelist():

@frappe.whitelist()
def get_dealer_dashboard_summary(dealer_id):
  orders = frappe.get_all(
    "Sales Order",
    filters={"dealer": dealer_id}
  )

  return {
    "total_orders": len(orders),
    "pending_orders": len(
      [o for o in orders if o.status == "Pending"]
    )
  }

The frontend can call this endpoint just like any other API. This same API layer is also what powers ERPNext integrations with e-commerce platforms, payment gateways, and CRMs, a custom portal is really just another consumer of it.

Importantly, Frappe's permission system remains part of the architecture. You aren't required to create an entirely separate authorization model for the portal.

This is what makes the approach practical: Frappe continues to manage your business logic and data while Vue or React handles the user experience.

Authentication Strategies for a Decoupled Frappe Frontend

Once the frontend is separated from Frappe, authentication needs to be planned carefully.

Common approaches include:

Approach	How It Works	Best For
Session/Cookie-based	Frappe creates a session cookie that the frontend uses	Frontends served from the same domain
API key + Secret	Credentials authenticate API requests	Server-to-server integrations, not end-user logins
Token-based (OAuth-style)	A token is issued after authentication and sent with requests	SPAs hosted on separate domains/subdomains

With session-based authentication, CSRF protection also needs to be handled correctly, particularly when the frontend and backend operate across different origins.

Authentication is also where important security decisions need to be made. Customer users should generally have significantly narrower permissions than internal employees.

For regulated environments or applications handling sensitive information, security and compliance requirements should be considered before development begins.

Preparing Frappe for a Headless Frontend

A decoupled frontend typically requires several backend considerations:

• Configure CORS if the frontend is hosted on a different origin.
• Define DocType permissions carefully for portal users and internal employees.
• Create custom whitelisted endpoints for complex business operations.
• Configure authentication and CSRF protection according to your deployment architecture.
• Avoid exposing unnecessary data or methods simply because they are available through the API.

The goal isn't just to make Frappe accessible through an API. It is to expose only the functionality the portal actually needs.

Choosing the Frontend: Vue vs React for a Frappe Portal

Both Vue and React can work effectively with Frappe's REST APIs and custom endpoints.

The choice usually depends more on your team than on Frappe itself.

Choose Between React vs Vue Based on:

• Existing expertise: Use the framework your developers already know well.
• Hiring: React generally has a larger developer pool.
• Maintainability: Your team will need to maintain a separate frontend codebase over the long term.
• Development speed: Existing component libraries and internal expertise can significantly reduce development time.

Frappe also provides Frappe UI, a Vue-based component library intended for building custom interfaces around Frappe. If your team is comfortable with Vue, it can provide a useful starting point instead of building every component from scratch.

Core Steps to Build the Portal

Building the portal involves:

• Set up the frontend: Create a Vite-based Vue or React application, separate from your Frappe app's codebase.
• Connect to Frappe APIs: Fetch DocType data with filtering, sorting, and pagination.
• Build forms and workflows: Create and update records while respecting server-side validation.
• Handle file uploads: Integrate Frappe's document attachment functionality.
• Add real-time updates: Use Frappe's Socket.IO capabilities where live updates are required.
• Work with DocType metadata: Where appropriate, use Frappe metadata to generate forms dynamically rather than hardcoding every field.

Dynamic metadata can reduce duplication, although highly customized interfaces may still benefit from explicitly designed frontend forms.

Deployment Architecture

A production setup commonly separates the frontend and backend while keeping them within the same overall infrastructure.

For example:

    Users → Nginx / CDN → Custom Portal (Vue / React) → Frappe/ERPNext Backend → Database / APIs
    

Typical considerations include:

• Nginx routing for the frontend and Frappe APIs.
• Separate frontend and backend deployment pipelines.
• Environment-specific API configuration.
• SSL configuration.
• CDN and static asset caching.
• Separate staging and production environments.

The frontend could be hosted on a subdomain such as portal.yourcompany.com, while the ERP remains at erp.yourcompany.com.

Common Challenges and How to Solve Them

A custom portal provides flexibility, but it also introduces ongoing technical responsibilities.

1. Authentication and CSRF Issues

Cross-origin authentication can be tricky, particularly with session-based authentication.

• Solution: Decide on the authentication architecture early and test it across development, staging, and production.

2. Frontend and DocTypes Becoming out of Sync

If frontend forms are hardcoded, backend DocType changes may require corresponding frontend updates.

• Solution: Use Frappe metadata where appropriate and establish a process for coordinating backend schema changes with frontend releases.

3. Performance at Scale

Large DocType datasets can make portal list views slow if requests aren't properly filtered or paginated.

• Solution: Use server-side filtering, pagination, and efficient API endpoints.

4. Frappe/ERPNext Upgrades

Custom APIs, field names, and backend assumptions can be affected by framework or ERPNext upgrades or migration.

• Solution: Treat the portal as an actively maintained application rather than a one-time development project.

Cost and Timeline Considerations: What to Budget For

A custom Frappe portal involves more than frontend development.

Your budget should account for:

• UI/UX design
• Frontend development
• Backend API development
• Authentication and security
• Deployment and CI/CD
• Testing and quality assurance
• Ongoing maintenance
• Frappe/ERPNext upgrades

The initial development cost is only part of the total cost of ownership. A portal tightly coupled to frequently changing backend structures can require significantly more maintenance over time.

If budget or launch time is limited, evaluate Frappe's built-in Portal functionality or Frappe UI before committing to a completely custom Vue/React application.

Frappe Portal vs Frappe UI vs Custom Vue/React

	Frappe Website/Portal	Frappe UI	Custom Vue/React
Cost	Lowest	Moderate	Highest
Launch Time	Fastest	Moderate	Longest
Customization	Limited	High, within Frappe UI's patterns	Very high
Best for	Simple, standard portals with light branding needs	Teams wanting speed and a custom look, comfortable with Vue	Products where the portal is a core, differentiated part of the business

The right choice depends on how important the portal is to your business and how much control you need over the user experience.

Real-World Frappe Portal Use Cases

Customer Self-Service Portal

Customers can view order status, invoices, and support tickets without contacting your team. Directly reduces support ticket volume and response time.

Vendor/Supplier Portal

Vendors can submit quotations, view purchase orders, and update fulfillment status directly, cutting the manual back-and-forth that usually happens over email or phone.

→ ERPNext for Manufacturing

Student/LMS portal

Students and parents can get a clean, engaging interface to access grades, attendance, fees, and other academic information, an area where user experience directly affects adoption and satisfaction.

Dealer/Distributor Portal

Dealers can place orders, track fulfillment, and manage their relationship with the business without relying entirely on sales staff. This typically increases order volume simply by making ordering easier.

→ ERPNext for retail and distribution

Choosing the Right Frappe Portal Approach

Building a custom Vue or React frontend on top of Frappe/ERPNext is a practical way to combine Frappe's powerful backend capabilities with a modern, branded user experience.

The real question isn't whether it can be built. It's whether your use case justifies the additional investment and ongoing maintenance.

For customer-facing products, dealer portals, vendor platforms, and other experiences where usability and branding matter, a custom frontend can be a strong choice.

For simpler internal applications, Frappe's built-in interface or Frappe UI may deliver the required functionality with significantly less effort.

Need a custom portal built on Frappe? At Softices, we can help you choose the right architecture before you commit your development budget.