{"id":41128,"library":"frappe-js-sdk","title":"frappe-js-sdk","description":"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.","status":"active","version":"1.13.0","language":"javascript","source_language":"en","source_url":"https://github.com/The-Commit-Company/frappe-js-sdk","tags":["javascript","Frappe","typescript"],"install":[{"cmd":"npm install frappe-js-sdk","lang":"bash","label":"npm"},{"cmd":"yarn add frappe-js-sdk","lang":"bash","label":"yarn"},{"cmd":"pnpm add frappe-js-sdk","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"HTTP client used for all API calls to Frappe backend","package":"axios","optional":false}],"imports":[{"note":"Package is ESM-first. Using require() may cause issues in Node.js without esModuleInterop.","wrong":"const FrappeApp = require('frappe-js-sdk')","symbol":"FrappeApp","correct":"import { FrappeApp } from 'frappe-js-sdk'"},{"note":"Auth is not a named export; it's obtained by calling the auth() method on FrappeApp instance.","wrong":"import { Auth } from 'frappe-js-sdk'","symbol":"Auth","correct":"const auth = frappe.auth()"},{"note":"FrappeDB is not directly exported; instantiate via frappe.db().","wrong":"import { FrappeDB } from 'frappe-js-sdk'","symbol":"FrappeDB","correct":"const db = frappe.db()"},{"note":"FileUpload instance is obtained from frappe.fileUpload(), not a direct export.","wrong":"import { FrappeFileUpload } from 'frappe-js-sdk'","symbol":"FileUpload","correct":"const fileUpload = frappe.fileUpload()"},{"note":"Call instance is obtained from frappe.call().","wrong":"import { FrappeCall } from 'frappe-js-sdk'","symbol":"FrappeCall","correct":"const call = frappe.call()"}],"quickstart":{"code":"import { FrappeApp } from 'frappe-js-sdk';\n\n// Initialize with token-based auth (e.g., API key/secret or OAuth)\nconst frappe = new FrappeApp('https://your-frappe-site.com', {\n  useToken: true,\n  token: () => localStorage.getItem('auth_token') ?? '', // custom function to get token\n  type: 'Bearer' // or 'token'\n});\n\n// Or use cookie-based login:\nconst auth = frappe.auth();\nauth.loginWithUsernamePassword({ username: 'admin', password: 'password' })\n  .then(() => console.log('Logged in'))\n  .catch(err => console.error(err));\n\n// Fetch a document by name from the 'Customer' DocType\nconst db = frappe.db();\ndb.getDoc('Customer', 'CUST-00001')\n  .then(doc => console.log('Document:', doc))\n  .catch(err => console.error(err));\n\n// Get a list of documents with filters\nconst filters = [['status', '=', 'Open']];\ndb.getDocList('ToDo', { fields: ['*'], filters, limit: 10 })\n  .then(list => console.log('List:', list))\n  .catch(err => console.error(err));\n\n// Create a new document\ndb.createDoc('ToDo', { description: 'Test todo', status: 'Open' })\n  .then(doc => console.log('Created:', doc))\n  .catch(err => console.error(err));\n\n// Update a document\ndb.updateDoc('ToDo', 'TODO-00001', { status: 'Closed' })\n  .then(doc => console.log('Updated:', doc))\n  .catch(err => console.error(err));\n\n// Delete a document\ndb.deleteDoc('ToDo', 'TODO-00001')\n  .then(() => console.log('Deleted'))\n  .catch(err => console.error(err));\n\n// Call a custom Frappe method\nconst call = frappe.call();\ncall.post('frappe.client.get_value', {\n  doctype: 'User',\n  fieldname: 'email',\n  filters: { name: 'Administrator' }\n}).then(res => console.log(res));","lang":"typescript","description":"Initializes FrappeApp with optional token-based auth, logs in via credentials, performs CRUD operations on DocType documents, and calls a custom Frappe method."},"warnings":[{"fix":"Update to v1.7.0+ and pass a function that returns a string synchronously, or upgrade to latest.","message":"In 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.","severity":"breaking","affected_versions":">=1.0.0 <1.7.0"},{"fix":"Update to v1.2.0+ and access response.data for the payload.","message":"The 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.","severity":"breaking","affected_versions":">=1.0.0 <1.2.0"},{"fix":"Replace 'order_by' with 'orderBy' in getDocList calls.","message":"The db.getDocList() method's 'order_by' parameter is deprecated in favor of 'orderBy' (camelCase). Using 'order_by' still works but logs a deprecation warning.","severity":"deprecated","affected_versions":">=1.10.0"},{"fix":"Enable 'Allow Token Auth' in Frappe System Settings and configure CORS whitelist.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Include Axios shims or use a polyfill service if targeting legacy browsers.","message":"The library uses Axios, which may cause issues in some browser environments if Axios is not polyfilled for older browsers (e.g., Internet Explorer).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use token-based auth for cross-origin scenarios, or configure CORS and same-site cookies properly.","message":"For 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).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'2026':20 'activ':16 'api':12,42 'auth':68,77 'authent':22 'axio':45 'backend':61 'base':25,29 'bearer/token':31 'built':75 'built-in':74 'call':43 'client':6 'communiti':57 'cooki':24,65 'cookie-bas':23 'count':36 'crud':34,72 'current':13 'custom':41 'databas':32 'definit':51 'differenti':52 'file':38 'flow':78 'forgot':80 'framework':10 'frapp':2,9,60,89 'frappe-js-sdk':1 'full':71 'get':37 'http':47 'interact':62 'javascript':88 'js':3 'librari':7 'like':79 'list':35 'login':26 'maintain':17 'npm':87 'offer':70 'offici':56 'oper':33 'password':81 'patch':85 'provid':21 'releas':82 'request':48 'rest':11 'sdk':4,58 'ship':49 'support':63 'token':28,67 'token-bas':27 'typescript':50,90 'typescript/javascript':5 'upload':39 'use':44 'v1.13.0':15 'week':84","created_at":"2026-06-04T18:50:54.705626+00:00","updated_at":"2026-06-04T18:50:54.705626+00:00","problems":[{"fix":"Run 'npm install frappe-js-sdk' and ensure tsconfig.json includes 'node_modules' in typeRoots or skipLibCheck.","cause":"Package not installed or TypeScript compiler cannot resolve types.","error":"Cannot find module 'frappe-js-sdk' or its corresponding type declarations."},{"fix":"Use ES6 import: import { FrappeApp } from 'frappe-js-sdk'","cause":"CommonJS require() imported the module incorrectly; the default export is an object with FrappeApp property.","error":"FrappeApp is not a constructor"},{"fix":"Ensure new FrappeApp('https://your-site.com') is called with a valid URL before using db().","cause":"frappe.db() was called before FrappeApp was fully initialized (e.g., missing base URL).","error":"TypeError: Cannot read properties of undefined (reading 'getDoc')"},{"fix":"Check that useToken is true and token function returns a valid token string. Verify Frappe server settings.","cause":"Token auth used but the token is invalid, expired, or missing in the request headers.","error":"AxiosError: Request failed with status code 403"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/The-Commit-Company/frappe-js-sdk#readme","github":"https://github.com/The-Commit-Company/frappe-js-sdk","docs":null,"changelog":null,"pypi":null,"npm":"frappe-js-sdk","openapi_spec":null,"status_page":null,"smithery":null,"categories":["storage","security"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-04","next_check":"2026-09-02","install_tag":null}}