frappe/client — data-fetching v3

[netchampfaris]

frappe/client — data-fetching v3

A typed, reactive data-fetching client for Frappe Framework backends. Built on Vue 3 Composition API with a shared DocStore at the core.

---

Setup

// src/client.ts
import { createClient, createDefaultCacheAdapter } from 'frappe-ui/frappe/vue'

export const { defineDoctype, store } = createClient({
  realtime: true,
  cache: createDefaultCacheAdapter('my-app-cache'),
  onError(error) {
    toast.error(error.messages[0]?.message || error.title)
  },
})

createClient options

Option	Type	Description
baseUrl?	string	Prepended to all API requests. Defaults to ''.
realtime?	boolean	Enable live list_update / doc_rename events via Socket.IO.
cache?	CacheAdapter	Persistence adapter — see Persistent cache.
onRequest?	fn	Interceptor called before every request.
onResponse?	fn	Interceptor called after every successful response.
onError?	(error: FrappeResponseError) => void	Global error handler.

---

Defining a DocType

doctypes.ts is auto-generated from your Frappe DocType metadata via bench execute. The example below shows what the generated output looks like — you don't write this by hand.

// src/doctypes.ts  — auto-generated, do not edit
import { defineDoctype } from '@/client'

export const Tasks = defineDoctype<{
  name: string
  title: string
  status: string
  assigned_to: string
}>()({
  doctype: 'GP Task',
  docMethods: {
    markDone: { method: 'mark_done' },
  },
  controllerMethods: {
    getOverdue: { method: 'get_overdue', httpMethod: 'GET' },
  },
})

---

getDoc — single document

const task = Tasks.getDoc('TASK-001')

task.doc        // GP Task | null
task.loading    // boolean
task.error      // FrappeResponseError | null
task.reload()   // re-fetch

// Update fields
task.setValue.call({ title: 'New title' })
task.setValue.loading

// Delete
task.delete.call()

// Call a doc method
task.markDone.call()

name can be a ref, computed, or getter — changing it automatically fetches the new document.

const taskName = ref('TASK-001')
const task = Tasks.getDoc(taskName)        // refetches when taskName changes
const task = Tasks.getDoc(() => route.params.name)

Options

Option	Type	Description
enabled?	MaybeRefOrGetter<boolean>	Pause fetching when false.
transform?	(doc: T) => T	Applied to every doc read from the store.
onSuccess?	(doc: T) => void	Called after each successful fetch.
onError?	(err) => void	Suppresses the global onError handler.

---

getList — document list

const tasks = Tasks.getList({
  fields: ['name', 'title', 'status', 'assigned_to'],
  filters: { status: 'Open', assigned_to: () => currentUser.value },
  orderBy: 'modified desc',
  limit: 20,
})

tasks.data          // GP Task[]
tasks.loading
tasks.hasNextPage
tasks.next()        // fetch next page
tasks.previous()
tasks.reload()

// Insert
tasks.insert.call({ title: 'New task' })
// Insert at end
tasks.insert.call({ title: 'New task' }, { at: 'end' })

// Update a row by name
tasks.setValue.call({ name: 'TASK-001', status: 'Closed' })

// Delete a row
tasks.delete.call('TASK-001')

Filters are fully reactive — any ref, computed, or getter value is watched and triggers a debounced refetch.

const status = ref('Open')
const tasks = Tasks.getList({
  filters: { status },                         // ref — watched automatically
  filters: { status: () => activeFilter.value } // getter — same behavior
})

Options

Option	Type	Description
fields?	string[]	Fields to fetch.
filters?	ReactiveFilters | MaybeRefOrGetter<object>	Per-key or whole-object reactive filters. undefined values are omitted.
orderBy?	string	SQL order clause, e.g. 'modified desc'.
limit?	number	Page size. Defaults to 20.
start?	number	Initial offset. Defaults to 0.
debounce?	number	Debounce filter changes in ms.
enabled?	MaybeRefOrGetter<boolean>	Pause fetching when false.
transform?	(doc: T) => T	Applied to each doc.
onSuccess?	(docs: T[]) => void	Called after each successful fetch.
onError?	(err) => void	Suppresses the global onError handler.

---

newDoc — draft document

Local-only reactive document. Nothing is sent to the server until insert.call().

const draft = Tasks.newDoc({ status: 'Open' })

draft.doc.title = 'My task'   // bind to form inputs with v-model
draft.insert.call()         // POST — merges doc + any extra values

---

getCount — reactive count

const count = Tasks.getCount({
  filters: { status: 'Open' },
})

count.data     // number | null
count.loading

---

Controller methods

Methods defined in controllerMethods are exposed directly on the instance:

const result = await Tasks.getOverdue.call()
Tasks.getOverdue.loading
Tasks.getOverdue.data

---

Realtime

Subscribe to live events for a doctype:

Tasks.onUpdate((name) => {
  console.log('doc updated:', name)
})

Tasks.onRename((newName, oldName) => {
  console.log('renamed:', oldName, '->', newName)
})

Both return an unsubscribe function.

---

Bulk operations

// Delete multiple docs
Tasks.bulkDelete.call(['TASK-001', 'TASK-002'])

// Update multiple docs
Tasks.bulkUpdate.call([
  { name: 'TASK-001', status: 'Closed' },
  { name: 'TASK-002', status: 'Closed' },
])

---

Optimistic updates

All mutations expose .callOptimistic() alongside .call(). The store is updated immediately and rolled back automatically if the request fails.

getDoc mutations

const task = Tasks.getDoc('TASK-001')

// Applies status change to the store instantly; reverts on error
await task.setValue.callOptimistic({ status: 'Closed' })

// Custom updater — apply any store change optimistically
await task.setValue.callOptimistic(
  { status: 'Closed' },
  (store) => store.set({ ...store.get('GP Task', task.doc.name), status: 'Closed', closedAt: Date.now() }),
)

// Remove from store immediately
await task.delete.callOptimistic()

getList mutations

const tasks = Tasks.getList({ fields: ['name', 'title', 'status'] })

// Update a row optimistically
await tasks.setValue.callOptimistic({ name: 'TASK-001', status: 'Closed' })

// Remove from list + store immediately
await tasks.delete.callOptimistic('TASK-001')

// Insert with a visible placeholder during the round-trip
await tasks.insert.callOptimistic(
  { title: 'New task', status: 'Open' },          // values sent to server
  { name: 'temp', title: 'New task', status: 'Open' }, // tempDoc shown in list
  { at: 'start' },                                // position
)

---

File upload

import { uploadFile } from 'frappe-ui/frappe/vue'

const upload = uploadFile({
  file: event.target.files[0],
  doctype: 'GP Task',
  name: 'TASK-001',
  fieldname: 'attachment',
})

upload.call()
upload.progress   // 0–100
upload.loading
upload.data       // Frappe File doc on success
upload.abort()    // cancel

---

Persistent cache

Pass a cache adapter to createClient() to persist the DocStore to IndexedDB. On the next page load, docs are hydrated instantly before any network requests fire — no loading flash.

import { createClient, createDefaultCacheAdapter } from 'frappe-ui/frappe/vue'

createClient({
  cache: createDefaultCacheAdapter('my-app-cache'),
})

createDefaultCacheAdapter uses IndexedDB in browsers and falls back to in-memory in non-browser environments. Each app should pass a unique dbName to avoid collisions.