📄 usePluginApi – Plugin API Access Composable

The usePluginApi composable is the entry point to all plugin APIs.

It provides access to:

• $data → backend communication
• $store → state management
• $socket → real-time events
• $eventbus → internal/global communication
• $log → structured logging

---

🧠 Core Concept

const { $data, $store, $socket, $eventbus, $log } = usePluginApi()

• Automatically resolves the current plugin context
• Returns scoped API instances
• Can access other plugins
• Allows custom query identification via actionId

---

🔧 Basic Usage

import { usePluginApi } from "@raclettejs/core/orchestrator/composables"

const { $data } = usePluginApi()

---

🔁 Multiple Instances

const { $data } = usePluginApi()
const { $data: $globalData } = usePluginApi("raclette__core")

---

🌍 Accessing Other Plugins

const { $data: $globalData } = usePluginApi("raclette__core")

$globalData.tag.getAll({
  params: { isDeleted: false },
})

Behavior

• Uses API of another plugin
• Keeps your $log context
• Prevents unintended cross-plugin side effects

---

⚙️ Parameters

usePluginApi(params)

Type

type PluginApiParams = {
  actionId?: string
  $data?: boolean
  $store?: boolean
  $eventbus?: boolean
  $socket?: boolean
  pluginKey?: string
}

---

🧩 Parameter Usage

pluginKey

If you only provide a string as param to usePluginApi, it will be interpreted as a pluginKey

usePluginApi("raclette__core")

or

usePluginApi({ pluginKey: "raclette__core" })

---

🆔 actionId – Query Identification (Part 1)

The actionId defines a base identifier for all $data queries executed from this API instance.

---

🔍 Default Query ID

Without actionId, a query ID looks like:

plugin-pacifico__example-todo-116-todo-getAll-b84N

Structure:

plugin-<pluginKey>-<instanceId>-<model>-<action>-<nanoId>

Example:

plugin-raclette__core-116-tag-getAll-U5Rs

---

✏️ With actionId

const { $data } = usePluginApi({
  actionId: "test",
})

Result:

plugin-pacifico__example-todo-test-p5EF

What changes?

• Replaces:

  • instanceId
  • model
  • action

• Becomes a custom base identifier

• Still appends a random nanoId

---

🆔 id in $data Calls – Query Identification (Part 2)

To fully control the query ID, you must also set id in the $data call.

$data.example.getAll({
  params: {...},
  id: "myFixedId",
})

---

🎯 Final Query ID Behavior

Setup	Result
no actionId, no id	fully auto-generated
actionId only	custom base + random nanoId
actionId + id	fully controlled query ID

---

✅ Fully Controlled Example

const { $data } = usePluginApi({
  actionId: "todoList",
})

$data.todo.getAll({
  params: { isDeleted: true },
  id: "archive",
})

Result:

plugin-pacifico__example-todo-todoList-archive

---

🎯 Why This Matters

Stable Query IDs

• predictable store entries
• easier debugging

---

Shared Queries

Multiple components can reference the same query

---

Cache Control

Avoid duplicate or fragmented cache entries

---

Debugging

Readable and meaningful identifiers:

plugin-myPlugin-todoList-main

---

⚠️ Important Notes

• actionId affects all queries from this API instance
• id overrides the final nanoId
• Without id, randomness still exists
• Use both together for full control

---

🧠 Mental Model

• usePluginApi → defines query namespace
• actionId → defines query group
• id → defines specific query instance

---

🔁 Typical Patterns

Default usage

const { $data } = usePluginApi()

---

Stable queries

const { $data } = usePluginApi({
  actionId: "todoList",
})

$data.todo.getAll({
  id: "main",
})

---

Cross-plugin with control

const { $data } = usePluginApi({
  pluginKey: "raclette__core",
  actionId: "coreTags",
})

$data.tag.getAll({
  id: "all",
})

---

⚖️ When to Use actionId + id

Use them when you need:

• stable query identifiers
• shared queries across components
• precise cache control
• better debugging

---

🚫 Important Constraints

• Must be used inside setup()
• Overusing fixed IDs can cause collisions
• Default behavior is fine for most cases

---

🧠 Key Takeaway

usePluginApi gives you access to all plugin APIs

👉 actionId + id give you full control over how your queries are identified, cached, and shared