Skip to main content

Getting started

frappe-js-client is a zero-dependency TypeScript client for Frappe Framework REST APIs (v14, v15, v16). Transport is globalThis.fetch.

Install​

pnpm add frappe-js-client
# or
npm install frappe-js-client

Node 20+ (or a browser with fetch). Optional peers:

WhenInstall
Socket.IO document eventssocket.io-client (frappe-js-client/realtime)
Typed DocTypes from a live sitefrappe-codegen (dev)

Quick start​

import { createFrappeClient, tokenAuth } from 'frappe-js-client'

const frappe = createFrappeClient({
    url: 'https://frappe.example.com',
    auth: tokenAuth({ apiKey: '...', apiSecret: '...' }),
})

const user = await frappe.db.getDoc('User', 'Administrator')
const open = await frappe.db.getDocList('ToDo', {
    fields: ['name', 'description', 'status'],
    filters: [['status', '=', 'Open']],
    limit: 10,
})
await frappe.auth.ping()

Default apiVersion is 2 (/api/v2, Frappe 15+). Pass { apiVersion: 1 } for classic /api/method + /api/resource (required on Frappe 14). Login, logout, and password reset always use classic /api/method/... even on v2 — v16 /api/v2/method/login does not create a session.

Core vs extended​

The root import is the core client: auth, db, file, call, search.

Desk-adjacent modules live on frappe-js-client/extended so a CRUD-only consumer does not load them:

import { withExtended } from 'frappe-js-client/extended'

const app = withExtended(frappe)
await app.workflow.apply({ doctype: 'ToDo', name: 'TD-1' }, 'Approve')

Entry points​

ImportRole
frappe-js-clientcreateFrappeClient, auth helpers, errors, types, consoleLogger, date formatters
frappe-js-client/extendedwithExtended — permission, workflow, report, desk, site
frappe-js-client/errorsError classes (also re-exported from the root)
frappe-js-client/middlewareretry, timing, composeMiddleware, redaction helpers
frappe-js-client/typesType-only (FrappeDoc, module interfaces) — used by codegen output
frappe-js-client/testingcreateTestClient, MemoryTransport, fixtures
frappe-js-client/realtimecreateRealtime (optional socket.io-client)

See Packages for the codegen CLI as well.

Next​