Registry / storage / frappe-js-sdk

frappe-js-sdk

JSON →
library1.13.0jsnpmunverified

TypeScript/JavaScript client library for Frappe Framework REST API, currently at v1.13.0. Actively maintained as of 2026. Provides authentication (cookie-based login, token-based with Bearer/token), database operations (CRUD, list, count, get), file uploads, and custom API calls. Uses Axios for HTTP requests. Ships TypeScript definitions. Differentiated by being the official community SDK for Frappe backend interaction, supporting both cookie and token auth, and offering full CRUD with built-in auth flows like forgot password. Released as weekly patches on npm.

npm install frappe-js-sdk
INSTALL
IMPORT
SIG · FRAPPE-JS-SDK
F
frappe-js-sdk
storagejavascriptv1.13.0
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

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

FrappeApp
import { FrappeApp } from 'frappe-js-sdk'
const FrappeApp = require('frappe-js-sdk')
Package is ESM-first. Using require() may cause issues in Node.js without esModuleInterop.
Auth
const auth = frappe.auth()
import { Auth } from 'frappe-js-sdk'
Auth is not a named export; it's obtained by calling the auth() method on FrappeApp instance.
FrappeDB
const db = frappe.db()
import { FrappeDB } from 'frappe-js-sdk'
FrappeDB is not directly exported; instantiate via frappe.db().
FileUpload
const fileUpload = frappe.fileUpload()
import { FrappeFileUpload } from 'frappe-js-sdk'
FileUpload instance is obtained from frappe.fileUpload(), not a direct export.
FrappeCall
const call = frappe.call()
import { FrappeCall } from 'frappe-js-sdk'
Call instance is obtained from frappe.call().

Initializes FrappeApp with optional token-based auth, logs in via credentials, performs CRUD operations on DocType documents, and calls a custom Frappe method.

import { FrappeApp } from 'frappe-js-sdk'; // Initialize with token-based auth (e.g., API key/secret or OAuth) const frappe = new FrappeApp('https://your-frappe-site.com', { useToken: true, token: () => localStorage.getItem('auth_token') ?? '', // custom function to get token type: 'Bearer' // or 'token' }); // Or use cookie-based login: const auth = frappe.auth(); auth.loginWithUsernamePassword({ username: 'admin', password: 'password' }) .then(() => console.log('Logged in')) .catch(err => console.error(err)); // Fetch a document by name from the 'Customer' DocType const db = frappe.db(); db.getDoc('Customer', 'CUST-00001') .then(doc => console.log('Document:', doc)) .catch(err => console.error(err)); // Get a list of documents with filters const filters = [['status', '=', 'Open']]; db.getDocList('ToDo', { fields: ['*'], filters, limit: 10 }) .then(list => console.log('List:', list)) .catch(err => console.error(err)); // Create a new document db.createDoc('ToDo', { description: 'Test todo', status: 'Open' }) .then(doc => console.log('Created:', doc)) .catch(err => console.error(err)); // Update a document db.updateDoc('ToDo', 'TODO-00001', { status: 'Closed' }) .then(doc => console.log('Updated:', doc)) .catch(err => console.error(err)); // Delete a document db.deleteDoc('ToDo', 'TODO-00001') .then(() => console.log('Deleted')) .catch(err => console.error(err)); // Call a custom Frappe method const call = frappe.call(); call.post('frappe.client.get_value', { doctype: 'User', fieldname: 'email', filters: { name: 'Administrator' } }).then(res => console.log(res));
Debug
Known issues
breakingIn v1.x, the constructor token option expects a string or a function returning a string. Prior to v1.7.0, token was required to be a string. If using a function that returns a promise, it must be resolved before calling APIs.
fix
Update to v1.7.0+ and pass a function that returns a string synchronously, or upgrade to latest.
affects: >=1.0.0 <1.7.0
breakingThe auth.loginWithUsernamePassword() method returns a promise that resolves with the Axios response object. In versions before 1.2.0, the promise resolved with the data property directly.
fix
Update to v1.2.0+ and access response.data for the payload.
affects: >=1.0.0 <1.2.0
deprecatedThe db.getDocList() method's 'order_by' parameter is deprecated in favor of 'orderBy' (camelCase). Using 'order_by' still works but logs a deprecation warning.
fix
Replace 'order_by' with 'orderBy' in getDocList calls.
affects: >=1.10.0
gotchaWhen using token-based auth with useToken: true, the token is sent as a custom header 'Authorization'. Ensure your Frappe server has the 'Allow Token Auth' setting enabled and CORS configured.
fix
Enable 'Allow Token Auth' in Frappe System Settings and configure CORS whitelist.
affects: >=1.0.0
gotchaThe library uses Axios, which may cause issues in some browser environments if Axios is not polyfilled for older browsers (e.g., Internet Explorer).
fix
Include Axios shims or use a polyfill service if targeting legacy browsers.
affects: >=1.0.0
gotchaFor session-based authentication, the loginWithUsernamePassword method sets cookies via the response. Ensure your Frappe backend is on the same domain or configured for cross-origin cookies (withCredentials: true).
fix
Use token-based auth for cross-origin scenarios, or configure CORS and same-site cookies properly.
affects: >=1.0.0
Errors
Common errors & fixes
Cannot find module 'frappe-js-sdk' or its corresponding type declarations.
Package not installed or TypeScript compiler cannot resolve types.
fix
Run 'npm install frappe-js-sdk' and ensure tsconfig.json includes 'node_modules' in typeRoots or skipLibCheck.
FrappeApp is not a constructor
CommonJS require() imported the module incorrectly; the default export is an object with FrappeApp property.
fix
Use ES6 import: import { FrappeApp } from 'frappe-js-sdk'
TypeError: Cannot read properties of undefined (reading 'getDoc')
frappe.db() was called before FrappeApp was fully initialized (e.g., missing base URL).
fix
Ensure new FrappeApp('https://your-site.com') is called with a valid URL before using db().
AxiosError: Request failed with status code 403
Token auth used but the token is invalid, expired, or missing in the request headers.
fix
Check that useToken is true and token function returns a valid token string. Verify Frappe server settings.
Upgrade
Version history
1.13.0latest on npm
Audit
Dependencies
axiosrequiredHTTP client used for all API calls to Frappe backend
Agent activity
23 hits · last 30 days
node
20
Amazon
1
OpenAI (training)
1
Resources