This page is part of an AI coding agent skill and is written for agents, not humans. For the human-readable Base44 docs, see the developer documentation.

Creating Functions

Base44 functions are serverless backend functions. They are defined locally in your project and deployed to the Base44 backend.

Function Directory

All function definitions must be placed in the base44/functions/ folder in your project. The simplest function is a folder with an entry.ts or entry.js file inside it. Example structure:

my-app/
  base44/
    functions/
      process-order/
        entry.ts
      send-notification/
        entry.ts

How to Create a Function

Create a new directory in base44/functions/ with your function name (use kebab-case)
Create entry.ts (or entry.js) in that directory
Deploy the function using the CLI

Function Discovery

The CLI discovers functions from entry.ts or entry.js files. A folder that contains one of those files is a function:

base44/
  functions/
    process-order/
      entry.ts

The function name is the path from the functions root to that folder. For example:

File	Function name
`base44/functions/process-order/entry.ts`	`process-order`
`base44/functions/orders/process/entry.ts`	`orders/process`

Rules:

entry.ts or entry.js must be inside a named subfolder, not directly in base44/functions/
all *.js, *.ts, *.json, and *.jsonc files under the function folder are included when deploying
function paths with a dot in any path segment are ignored

Entry Point File

Functions export a default request handler. Use the npm: prefix to import npm packages.

import { createClientFromRequest } from "npm:@base44/sdk";

export default async function (req: Request): Promise<Response> {
  // Get authenticated client from request
  const base44 = createClientFromRequest(req);

  // Parse input
  const { orderId, action } = await req.json();

  // Your logic here
  const order = await base44.entities.Orders.get(orderId);

  // Return response
  return Response.json({
    success: true,
    order: order
  });
}

Request Object

The function receives a standard Request object:

req.json() - Parse JSON body
req.text() - Get raw text body
req.headers - Access request headers
req.method - HTTP method

Response Object

Return using Response.json() for JSON responses:

// Success response
return Response.json({ data: result });

// Error response with status code
return Response.json({ error: "Something went wrong" }, { status: 400 });

// Not found
return Response.json({ error: "Order not found" }, { status: 404 });

Complete Example

Directory Structure

base44/
  functions/
    process-order/
      entry.ts

entry.ts

import { createClientFromRequest } from "npm:@base44/sdk";

export default async function (req: Request): Promise<Response> {
  try {
    const base44 = createClientFromRequest(req);
    const { orderId } = await req.json();

    // Validate input
    if (!orderId) {
      return Response.json(
        { error: "Order ID is required" },
        { status: 400 }
      );
    }

    // Fetch and process the order
    const order = await base44.entities.Orders.get(orderId);
    if (!order) {
      return Response.json(
        { error: "Order not found" },
        { status: 404 }
      );
    }

    return Response.json({
      success: true,
      orderId: order.id,
      processedAt: new Date().toISOString()
    });

  } catch (error) {
    return Response.json(
      { error: error.message },
      { status: 500 }
    );
  }
}

Using Service Role Access

For admin-level operations, use asServiceRole:

import { createClientFromRequest } from "npm:@base44/sdk";

export default async function (req: Request): Promise<Response> {
  const base44 = createClientFromRequest(req);

  // Check user is authenticated
  const user = await base44.auth.me();
  if (!user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  // Use service role for admin operations
  const allOrders = await base44.asServiceRole.entities.Orders.list();

  return Response.json({ orders: allOrders });
}

Using Secrets

Read secrets configured in the app dashboard with secrets.get() from the base44:runtime module. BASE44_APP_ID is pre-populated; set everything else in app settings → environment variables.

import { secrets } from "base44:runtime";

export default async function (req: Request): Promise<Response> {
  // Read a secret (configured in app settings)
  const apiKey = secrets.get("STRIPE_API_KEY");

  const response = await fetch("https://api.stripe.com/v1/charges", {
    headers: {
      "Authorization": `Bearer ${apiKey}`
    }
  });

  return Response.json(await response.json());
}

Post-Response Work

For work that should finish after the response is sent (analytics pings, non-critical logging), pass the promise to waitUntil() from base44:runtime. The response returns immediately and the function stays alive until the promise settles.

import { waitUntil } from "base44:runtime";

export default async function (req: Request): Promise<Response> {
  waitUntil(fetch("https://hooks.example.com/ping", { method: "POST" }));
  return Response.json({ ok: true });
}

Naming Conventions

Directory name: Use kebab-case (e.g., process-order, send-notification)
Function name: Comes from the directory path under base44/functions/
- Valid: process-order, orders/process, send_notification, myFunction
- Invalid: process.order, send.notification.v2
Entry file: Use entry.ts or entry.js

Deploying Functions

After creating your function, deploy it to Base44:

npx base44 functions deploy

For more details on deploying, see functions-deploy.md.

Notes

Use npm: prefix for npm packages (e.g., npm:@base44/sdk), always with a pinned version
Use createClientFromRequest(req) to get a client that inherits the caller’s auth context
Configure secrets via app dashboard for API keys, and read them with secrets.get() from base44:runtime
Crypto is the async Web Crypto API — for Stripe webhooks use await stripe.webhooks.constructEventAsync(...); the synchronous constructEvent() throws “SubtleCryptoProvider cannot be used in a synchronous context”
Make sure to handle errors gracefully and return appropriate HTTP status codes

Multi-File Functions

A function is not limited to entry.ts. Any .js, .ts, .json, or .jsonc file in the function’s folder is uploaded on deploy and can be imported from entry.ts with a relative path.

base44/
  functions/
    process-order/
      entry.ts       ← import { validate } from "./validate.ts";
      validate.ts    ←   import { Order } from "./types.ts";
      types.ts
      config.json

Rules:

Import files in the same folder with ./, including the extension (e.g. ./validate.ts).
The entire function folder ships on every deploy; anything the entry does not import is dropped from the bundle, so extra files are harmless.

To share code across functions, put it in base44/shared/ — the one directory outside a function folder that the CLI uploads. Its full contents are bundled with every function.

base44/
  shared/
    response.ts    ← shared helpers
  functions/
    greet/
      entry.ts     ← import { ok } from "../../shared/response.ts";
    farewell/
      entry.ts     ← import { ok } from "../../shared/response.ts";

Rules:

Shared code must live in base44/shared/. Files elsewhere outside the function folder are not uploaded.
A relative import can reach a sibling (./util.ts) or base44/shared/ (../../shared/util.ts) — but nothing further out. An import that escapes base44/ (e.g. ../../../src/utils.ts) fails at deploy time; move the file into base44/shared/ instead.
For external packages use npm: specifiers, not relative paths.

Common Mistakes

Wrong	Correct	Why
`base44/functions/myFunction.js` (single file)	`base44/functions/my-function/entry.ts`	Functions must live in a named subdirectory
`base44/functions/entry.ts`	`base44/functions/my-function/entry.ts`	The function name comes from the subdirectory path
`import { ... } from "@base44/sdk"`	`import { ... } from "npm:@base44/sdk"`	npm packages must use the `npm:` prefix
`MyFunction` or `myFunction` directory	`my-function` directory	Use kebab-case for directory names
`import { x } from "../../../src/utils.ts"`	`import { x } from "../../shared/utils.ts"`	Imports outside `base44/` are blocked — move shared code to `base44/shared/`

​Creating Functions

​Function Directory

​How to Create a Function

​Function Discovery

​Entry Point File

​Request Object

​Response Object

​Complete Example

​Directory Structure

​entry.ts

​Using Service Role Access

​Using Secrets

​Post-Response Work

​Naming Conventions

​Deploying Functions

​Notes

​Multi-File Functions

​Sharing Code Between Functions

​Common Mistakes

Creating Functions

Function Directory

How to Create a Function

Function Discovery

Entry Point File

Request Object

Response Object

Complete Example

Directory Structure

entry.ts

Using Service Role Access

Using Secrets

Post-Response Work

Naming Conventions

Deploying Functions

Notes

Multi-File Functions

Sharing Code Between Functions

Common Mistakes