OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add base44/skills --skill base44-sdk
The base44 SDK is the library to communicate with base44 services. In projects, you use it to communicate with remote resources (entities, backend functions, realtime actors, ai agents) and to write backend functions and actors. This skill is the place for learning about available modules and types, including actors — the realtime/WebSocket primitive for multiplayer, collaborative boards, presence and live cursors, in-room chat, and live auctions. When you plan or implement a feature, you must learn this skill
npx skills add base44/skills --skill base44-sdk
Build apps on the Base44 platform using the Base44 JavaScript SDK.
This skill activates on ANY mention of "base44" or when a base44/ folder exists. DO NOT read documentation files or search the web before acting.
Your first action MUST be:
base44/config.jsonc exists in the current directoryUse base44-sdk when:
base44/config.jsonc already exists in the project@base44/sdk)DO NOT USE base44-sdk for:
base44-cli instead)npx base44 create, npx base44 deploy, npx base44 login (use base44-cli)Skill Dependencies:
base44-sdk assumes a Base44 project is already initializedbase44-cli is a prerequisite for base44-sdk in new projectsbase44-cli firstState Check Logic: Before selecting this skill, verify:
base44/config.jsonc exists):
→ Use base44-cli (project initialization needed)Before writing ANY Base44 code, verify method names against this table or QUICK_REFERENCE.md.
Base44 SDK has unique method names. Do NOT assume patterns from Firebase, Supabase, or other SDKs.
| ❌ WRONG (hallucinated) | ✅ CORRECT |
|---|---|
signInWithGoogle() | loginWithProvider('google') |
signInWithProvider('google') | loginWithProvider('google') |
auth.google() | loginWithProvider('google') |
signInWithEmailAndPassword(email, pw) | loginViaEmailPassword(email, pw) |
signIn(email, pw) | loginViaEmailPassword(email, pw) |
createUser() / signUp() | register({email, password}) |
onAuthStateChanged() | me() (no listener, call when needed) |
currentUser | await auth.me() |
| ❌ WRONG (hallucinated) | ✅ CORRECT |
|---|---|
functions.call('name', data) | functions.invoke('name', data) |
functions.run('name', data) | functions.invoke('name', data) |
callFunction('name', data) | functions.invoke('name', data) |
httpsCallable('name')(data) | functions.invoke('name', data) |
| ❌ WRONG (hallucinated) | ✅ CORRECT |
|---|---|
ai.generate(prompt) | integrations.Core.InvokeLLM({prompt}) |
openai.chat(prompt) | integrations.Core.InvokeLLM({prompt}) |
llm(prompt) | integrations.Core.InvokeLLM({prompt}) |
sendEmail(to, subject, body) | integrations.Core.SendEmail({to, subject, body}) |
email.send() | integrations.Core.SendEmail({to, subject, body}) |
uploadFile(file) | integrations.Core.UploadFile({file}) |
storage.upload(file) | integrations.Core.UploadFile({file}) |
Exception: an OpenAI-compatible client (e.g. the Vercel AI SDK) is correct when pointed at
base44.aiGateway.connection()— that's how you build code agents (agent loops with tools). UseInvokeLLMonly for a single call with no tools. See ai-gateway.md.
| ❌ WRONG (hallucinated) | ✅ CORRECT |
|---|---|
actors.connect('ChatRoom', roomId) | actors.ChatRoom(roomId).connect() |
actors.ChatRoom.connect(roomId) | actors.ChatRoom(roomId).connect() |
actors.ChatRoom(roomId).subscribe(cb) | subscribe on the connection: const conn = actors.ChatRoom(roomId).connect(); conn.subscribe(cb) |
room.on('message', cb) | room.subscribe(cb) (one callback receives every message) |
room.emit(data) | room.send(data) |
new WebSocket(...) for app realtime | base44.actors.<Name>(id).connect() |
const unsub = room.subscribe(cb); unsub() | const sub = room.subscribe(cb); sub.unsubscribe() |
The two
subscribe()methods return different shapes.Connection.subscribe()(actors) returns an object —sub.unsubscribe().entities.<Name>.subscribe()returns the unsubscribe function itself —unsub(). Don't carry one convention to the other.
| ❌ WRONG (hallucinated) | ✅ CORRECT |
|---|---|
entities.Task.find({...}) | entities.Task.filter({...}) |
entities.Task.findOne(id) | entities.Task.get(id) |
entities.Task.insert(data) | entities.Task.create(data) |
entities.Task.remove(id) | entities.Task.delete(id) |
entities.Task.onChange(cb) | entities.Task.subscribe(cb) |
| Module | Purpose | Reference |
|---|---|---|
entities | CRUD operations on data models | entities.md |
auth | Login, register, user management | auth.md |
agents | AI conversations and messages | base44-agents.md |
functions | Backend function invocation | functions.md |
actors | Realtime rooms over WebSockets (multiplayer, collaboration, presence) | actors.md |
integrations | AI, email, file uploads, custom APIs | integrations.md |
aiGateway | Connect an OpenAI-compatible SDK to Base44's AI gateway | ai-gateway.md |
analytics | Track custom events and user activity | analytics.md |
appLogs | Log user activity in app | app-logs.md |
users | Invite users to the app | users.md |
asServiceRole.connectors | App-scoped OAuth tokens (service role only) | connectors.md |
asServiceRole.sso | SSO token generation (service role only) | sso.md |
For client setup and authentication modes, see client.md.
Each reference file includes a "Type Definitions" section with TypeScript interfaces and types for the module's methods, parameters, and return values.
Getting typed entities, functions, actors, and agents: The Base44 CLI generates types from your project resources (entities, functions, actors, agents), including augmentations to EntityTypeRegistry, FunctionNameRegistry, ActorNameRegistry, and AgentNameRegistry, and wires them into your project so you get autocomplete and type checking without manual setup. For how to generate types, use the base44-cli skill.
Manual augmentation: You can instead augment the registries yourself in a .d.ts file; see the Type Definitions sections in entities.md, functions.md, actors.md, and base44-agents.md. Actor message types are always hand-authored — augment ActorRegistry so the actor and its clients share one definition.
Install the Base44 SDK:
Important: Never assume or hardcode the @base44/sdk package version. Always install without a version specifier to get the latest version.
When creating a client in external apps, ALWAYS use appId as the parameter name:
Required parameter: appId (string) - Your Base44 application ID
Optional parameters:
token (string) - Pre-authenticated user tokenoptions (object) - Configuration options
options.onError (function) - Global error handlerExample with error handler:
Working with app data?
entitiesentities.importEntities()entities.EntityName.subscribe()User management?
authauth.me()auth.updateMe()users.inviteUser()AI features?
agents (requires logged-in user)agents.createConversation()agents.getConversations()integrations.Core.InvokeLLM()integrations.Core.GenerateImage()aiGateway (see ai-gateway.md)Custom backend logic?
functions.invoke()base44.asServiceRole.functions.invoke()Realtime shared session?
actors.<Name>(roomId).connect() (see actors.md)entities.EntityName.subscribe(), not an actorExternal services?
integrations.Core.SendEmail()integrations.Core.UploadFile()integrations.custom.call()asServiceRole.connectors.getConnection() (backend only)Tracking and analytics?
analytics.track()appLogs.logUserInApp()Use asServiceRole in backend functions for admin-level operations. Actors expose this.client.asServiceRole for validated, room-owned work such as persisting canonical results; use verified conn.identity.userId from an authenticated connection for explicit user attribution. See actors.md.
| Capability | Frontend | Backend |
|---|---|---|
entities (user's data) | Yes | Yes |
auth | Yes | Yes |
agents | Yes | Yes |
functions.invoke() | Yes | Yes |
functions.fetch() | Yes | Yes |
actors (connect to a room) | Yes | No — the actor is the server side |
integrations | Yes | Yes |
aiGateway | No | Yes |
analytics | Yes | Yes |
appLogs | Yes | Yes |
users | Yes | Yes |
asServiceRole.* | No | Yes |
asServiceRole.connectors (app OAuth) | No | Yes |
asServiceRole.sso | No | Yes |
Backend functions export default an async request handler and use createClientFromRequest(req) to get a properly authenticated client.*
// External apps
import { createClient } from "@base44/sdk";
// IMPORTANT: Use 'appId' (NOT 'clientId' or 'id')
const base44 = createClient({ appId: "your-app-id" });
await base44.auth.loginViaEmailPassword("user@example.com", "password");npm install @base44/sdkimport { createClient } from "@base44/sdk";
// ✅ CORRECT
const base44 = createClient({ appId: "your-app-id" });
// ❌ WRONG - Do NOT use these:
// const base44 = createClient({ clientId: "your-app-id" }); // WRONG
// const base44 = createClient({ id: "your-app-id" }); // WRONGconst base44 = createClient({
appId: "your-app-id",
options: {
onError: (error) => {
console.error("Base44 error:", error);
}
}
});const pendingTasks = await base44.entities.Task.filter(
{ status: "pending", assignedTo: userId }, // query
"-created_date", // sort (descending)
10, // limit
0 // skip
);const user = await base44.auth.me();
if (!user) {
// Navigate to your custom login page
navigate('/login', { state: { returnTo: window.location.pathname } });
return;
}// Frontend
// ⚠️ invoke() returns the RAW axios response — your function's JSON is on `.data`,
// NOT the top-level object. It also THROWS on non-2xx (error body at err.response.data).
const res = await base44.functions.invoke("processOrder", {
orderId: "123",
action: "ship"
});
const result = res.data; // ✅ e.g. res.data.success (res itself is { data, status, headers, … })
// Backend function
import { createClientFromRequest } from "npm:@base44/sdk";
export default async function (req) {
const base44 = createClientFromRequest(req);
const { orderId, action } = await req.json();
// Process with service role for admin access
const order = await base44.asServiceRole.entities.Orders.get(orderId);
return Response.json({ success: true });
}// Frontend — connect inside useEffect and always clean up
useEffect(() => {
const room = base44.actors.ChatRoom(roomId).connect();
const sub = room.subscribe((msg) => {
if (msg.type === "message") setMessages((prev) => [...prev, msg]); // switch on type; drop unknowns
});
return () => { sub.unsubscribe(); room.close(); }; // NOTE: actors return { unsubscribe() },
}, [roomId]); // entities.subscribe() returns the function itself
// Actor — base44/actors/ChatRoom/entry.ts
import { Actor } from "base44:runtime/actors";
export default class ChatRoom extends Actor {
handleConnect(conn) { conn.send({ type: "welcome" }); } // one client
handleMessage(conn, msg) {
// Always validate: the payload is attacker-controlled and msg can even be null.
if (msg?.type !== "message" || typeof msg.text !== "string") return;
this.broadcast({ type: "message", text: msg.text.slice(0, 2000) }); // everyone
}
handleClose(conn) {}
}// User mode - respects permissions
const myTasks = await base44.entities.Task.list();
// Service role - full access (backend only)
const allTasks = await base44.asServiceRole.entities.Task.list();
const token = await base44.asServiceRole.connectors.getAccessToken("slack");