Registry / web-framework / frappe-react-sdk

frappe-react-sdk

JSON →
library1.14.0jsnpmunverified

The `frappe-react-sdk` is a JavaScript library providing a collection of React hooks designed to simplify interaction with a Frappe Framework backend. It offers abstractions for common tasks such as user authentication (cookie-based or token-based), comprehensive database operations (fetching single documents, lists, counts, creating, updating, and deleting records), file uploads with progress tracking, and generic API calls to whitelisted backend functions. The current stable version is `1.14.0`. The library demonstrates an active release cadence, with updates typically every few weeks addressing bug fixes, dependency updates, and feature enhancements. Under the hood, it leverages `frappe-js-sdk` for Frappe API communication and `SWR` for efficient data fetching, caching, and automatic revalidation, providing a fast and reactive UI experience by default.

npm install frappe-react-sdk
INSTALL
IMPORT
SIG · FRAPPE-REACT-SDK
F
frappe-react-sdk
web-frameworkjavascriptv1.14.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

FrappeProvider
import { FrappeProvider } from 'frappe-react-sdk';
const FrappeProvider = require('frappe-react-sdk').FrappeProvider;
The primary context provider. Designed for ESM; CJS `require` is not recommended in modern React projects.
useFrappeAuth
import { useFrappeAuth } from 'frappe-react-sdk';
import useFrappeAuth from 'frappe-react-sdk/auth';
Hook for authentication logic. All hooks are named exports from the main package entry point.
useFrappeDocList
import { useFrappeDocList } from 'frappe-react-sdk';
import { useFrappeDocList } from 'frappe-react-sdk/hooks';
Hook for fetching lists of Frappe documents. All hooks are top-level named exports.
useFrappeGetCall
import { useFrappeGetCall } from 'frappe-react-sdk';
Hook for making generic GET requests to Frappe API endpoints.

Demonstrates the basic setup using `FrappeProvider` and a simple authentication flow with `useFrappeAuth`.

import { FrappeProvider, useFrappeAuth } from 'frappe-react-sdk'; import React from 'react'; function AuthStatus() { const { currentUser, login, logout, get and maintain user state } = useFrappeAuth(); const handleLogin = async () => { await login('username', 'password'); // Replace with actual credentials or user input console.log('Logged in as:', currentUser.fullname); }; const handleLogout = async () => { await logout(); console.log('Logged out'); }; return ( <div> {currentUser ? ( <p>Welcome, {currentUser.fullname || 'User'}! <button onClick={handleLogout}>Logout</button></p> ) : ( <p>Please log in. <button onClick={handleLogin}>Login</button></p> )} </div> ); } function App() { // The URL is optional if the web app is hosted on the same URL as the Frappe server. // Use process.env.FRAPPE_SERVER_URL or a similar environment variable for production. return ( <FrappeProvider url={process.env.FRAPPE_SERVER_URL ?? 'https://my-frappe-server.frappe.cloud'}> <h1>Frappe React SDK Demo</h1> <AuthStatus /> {/* Your other app components would go here */} </FrappeProvider> ); }
Debug
Known issues
breakingVersion 1.4.0 updated the underlying `frappe-js-sdk` which, in turn, updated Axios to v1. This change might introduce breaking changes in how requests are configured or responses are handled.
fix
Review Axios v1 migration guide and adjust API call parameters, headers, and error handling as necessary. Test all API interactions thoroughly.
affects: >=1.4.0
breakingVersion 1.13.0 included significant updates to `Axios`, `SWR`, and `frappe-js-sdk`. The changelog explicitly warned this 'might be a breaking change' due to deep dependency updates.
fix
Thoroughly test existing functionality after upgrading. Pay attention to data fetching, caching behavior, and any custom Axios configurations that might be affected by the dependency bumps.
affects: >=1.13.0
gotchaThe `FrappeProvider` component requires the `url` prop to be explicitly set if your React application is not hosted on the same domain as your Frappe backend. Failure to do so will result in network errors due to incorrect API endpoint resolution.
fix
Always provide the full URL to your Frappe server: `<FrappeProvider url='https://your-frappe-server.com'>`.
affects: >=1.0.0
gotchaAuthentication defaults to cookie-based sessions. If you intend to use token-based authentication (e.g., OAuth bearer tokens or Frappe API Key/Secret pairs), you must explicitly configure it in the `FrappeProvider`.
fix
Pass the `token` or `enableAuth` props to `FrappeProvider` and manage the token lifecycle (e.g., `<FrappeProvider token={myAuthToken}>` or `<FrappeProvider enableAuth={true} />` and then use `frappe.setAuthToken`).
affects: >=1.0.0
gotchaThe library extensively uses `SWR` for data fetching and caching. Developers should familiarize themselves with `SWR`'s caching strategies, revalidation options, and potential side effects of overriding `SWR` configurations to avoid unexpected data staleness or excessive re-fetches.
fix
Consult the SWR documentation regarding cache invalidation, revalidation, and API options when encountering unexpected data behavior or performance issues.
affects: >=1.0.0
Errors
Common errors & fixes
Failed to load resource: net::ERR_CONNECTION_REFUSED
The Frappe server URL is incorrect or not provided when the frontend is hosted separately, leading to failed API calls.
fix
Set the `url` prop on `FrappeProvider` to the correct address of your Frappe backend: `<FrappeProvider url="https://your-frappe-server.com">`.
TypeError: Class constructor FrappeProvider cannot be invoked without 'new'
Attempting to use CommonJS `require()` syntax to import `FrappeProvider` in an environment that expects ESM imports (typical for modern React projects).
fix
Use ES module import syntax: `import { FrappeProvider } from 'frappe-react-sdk';`
Request failed with status code 401 (Unauthorized)
API request failed due to missing or invalid authentication credentials. This can happen if not logged in, or if token-based auth is misconfigured.
fix
Ensure the user is logged in via `useFrappeAuth().login()`, or if using token-based authentication, verify that the `token` prop is correctly passed to `FrappeProvider` and is valid.
TypeError: Cannot read properties of undefined (reading 'data') when using `useFrappeGetCall`
The Frappe API endpoint called by `useFrappeGetCall` returned an error or an unexpected response structure, or the component unmounted before the data arrived.
fix
Implement robust error handling and loading states. Check the network tab for the exact API response. Ensure optional chaining (`data?.value`) is used when accessing potentially undefined properties.
Upgrade
Version history
1.14.0latest on npm
Audit
Dependencies
reactrequiredPeer dependency required for all React hook-based libraries.
Agent activity
26 hits · last 30 days
node
20
Amazon
1
OpenAI (training)
1
Resources
frappe-react-sdk — npm install frappe-react-sdk · libregistry