{"id":10921,"library":"frappe-react-sdk","title":"Frappe React SDK","description":"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.","status":"active","version":"1.14.0","language":"javascript","source_language":"en","source_url":"https://github.com/The-Commit-Company/frappe-react-sdk","tags":["javascript","Frappe","React","hooks","typescript"],"install":[{"cmd":"npm install frappe-react-sdk","lang":"bash","label":"npm"},{"cmd":"yarn add frappe-react-sdk","lang":"bash","label":"yarn"},{"cmd":"pnpm add frappe-react-sdk","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for all React hook-based libraries.","package":"react","optional":false}],"imports":[{"note":"The primary context provider. Designed for ESM; CJS `require` is not recommended in modern React projects.","wrong":"const FrappeProvider = require('frappe-react-sdk').FrappeProvider;","symbol":"FrappeProvider","correct":"import { FrappeProvider } from 'frappe-react-sdk';"},{"note":"Hook for authentication logic. All hooks are named exports from the main package entry point.","wrong":"import useFrappeAuth from 'frappe-react-sdk/auth';","symbol":"useFrappeAuth","correct":"import { useFrappeAuth } from 'frappe-react-sdk';"},{"note":"Hook for fetching lists of Frappe documents. All hooks are top-level named exports.","wrong":"import { useFrappeDocList } from 'frappe-react-sdk/hooks';","symbol":"useFrappeDocList","correct":"import { useFrappeDocList } from 'frappe-react-sdk';"},{"note":"Hook for making generic GET requests to Frappe API endpoints.","symbol":"useFrappeGetCall","correct":"import { useFrappeGetCall } from 'frappe-react-sdk';"}],"quickstart":{"code":"import { FrappeProvider, useFrappeAuth } from 'frappe-react-sdk';\nimport React from 'react';\n\nfunction AuthStatus() {\n  const { currentUser, login, logout, get and maintain user state } = useFrappeAuth();\n\n  const handleLogin = async () => {\n    await login('username', 'password'); // Replace with actual credentials or user input\n    console.log('Logged in as:', currentUser.fullname);\n  };\n\n  const handleLogout = async () => {\n    await logout();\n    console.log('Logged out');\n  };\n\n  return (\n    <div>\n      {currentUser ? (\n        <p>Welcome, {currentUser.fullname || 'User'}! <button onClick={handleLogout}>Logout</button></p>\n      ) : (\n        <p>Please log in. <button onClick={handleLogin}>Login</button></p>\n      )}\n    </div>\n  );\n}\n\nfunction App() {\n  // The URL is optional if the web app is hosted on the same URL as the Frappe server.\n  // Use process.env.FRAPPE_SERVER_URL or a similar environment variable for production.\n  return (\n    <FrappeProvider url={process.env.FRAPPE_SERVER_URL ?? 'https://my-frappe-server.frappe.cloud'}>\n      <h1>Frappe React SDK Demo</h1>\n      <AuthStatus />\n      {/* Your other app components would go here */}\n    </FrappeProvider>\n  );\n}","lang":"typescript","description":"Demonstrates the basic setup using `FrappeProvider` and a simple authentication flow with `useFrappeAuth`."},"warnings":[{"fix":"Review Axios v1 migration guide and adjust API call parameters, headers, and error handling as necessary. Test all API interactions thoroughly.","message":"Version 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.","severity":"breaking","affected_versions":">=1.4.0"},{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=1.13.0"},{"fix":"Always provide the full URL to your Frappe server: `<FrappeProvider url='https://your-frappe-server.com'>`.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`).","message":"Authentication 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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Consult the SWR documentation regarding cache invalidation, revalidation, and API options when encountering unexpected data behavior or performance issues.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Set the `url` prop on `FrappeProvider` to the correct address of your Frappe backend: `<FrappeProvider url=\"https://your-frappe-server.com\">`.","cause":"The Frappe server URL is incorrect or not provided when the frontend is hosted separately, leading to failed API calls.","error":"Failed to load resource: net::ERR_CONNECTION_REFUSED"},{"fix":"Use ES module import syntax: `import { FrappeProvider } from 'frappe-react-sdk';`","cause":"Attempting to use CommonJS `require()` syntax to import `FrappeProvider` in an environment that expects ESM imports (typical for modern React projects).","error":"TypeError: Class constructor FrappeProvider cannot be invoked without 'new'"},{"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.","cause":"API request failed due to missing or invalid authentication credentials. This can happen if not logged in, or if token-based auth is misconfigured.","error":"Request failed with status code 401 (Unauthorized)"},{"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.","cause":"The Frappe API endpoint called by `useFrappeGetCall` returned an error or an unexpected response structure, or the component unmounted before the data arrived.","error":"TypeError: Cannot read properties of undefined (reading 'data') when using `useFrappeGetCall`"}],"ecosystem":"npm"}