Local development setup

Set up the Base44 dev server and connect your frontend to it

Local development runs two processes side by side: the Base44 dev server for your backend, and your usual frontend dev server for the UI. Your frontend talks to the local backend through the SDK.

Prerequisites

If your project has backend functions, you need to install Deno to run them locally.

Configure your frontend client

If your project has a frontend that uses the SDK, you need to tell it where to send requests and where to redirect for auth. By default, the SDK uses Base44’s hosted backend. To use the local dev server in development, set both serverUrl and appBaseUrl to "http://localhost:4400" when calling createClient(). In production, omit them so the SDK uses its defaults.

Choose one of the two patterns below. The env-var pattern is simplest if base44 dev spawns your frontend via site.serveCommand and you use a Vite-based build. The manual detection pattern works in any setup.

Env-var pattern

When base44 dev spawns your frontend via site.serveCommand, it sets two Vite env vars in the frontend process: VITE_BASE44_APP_ID (your app id) and VITE_BASE44_APP_BASE_URL (the local dev URL). Read them when creating the client, using the URL for both serverUrl and appBaseUrl:

import { createClient } from "@base44/sdk";

const base44 = createClient({
  appId: import.meta.env.VITE_BASE44_APP_ID ?? "your-app-id",
  serverUrl: import.meta.env.VITE_BASE44_APP_BASE_URL,
  appBaseUrl: import.meta.env.VITE_BASE44_APP_BASE_URL,
});

The serverUrl option is where the SDK sends API requests. The appBaseUrl option is where it redirects for auth flows like login. In local development, both point at your local dev server.

In production builds, the env vars are undefined and both options fall back to the SDK’s defaults.

Apps created via Base44’s GitHub integration use the @base44/vite-plugin, which sets serverUrl and appBaseUrl automatically. You only need this manual setup for projects that don’t run the plugin.

Manual detection pattern

Use this pattern if you start your frontend in a separate terminal, or if your build tool isn’t Vite. Detect whether your code is running in development, then set serverUrl conditionally.

1. Detect development mode

   Use the pattern that matches your environment:

   Vite

   const isDev = import.meta.env.DEV;
   

   const isDev = process.env.NODE_ENV !== "production";
   

   const isDev = __DEV__;
   

   const isDev = Deno.env.get("DENO_ENV") !== "production";
   
2. Pass serverUrl conditionally

   When creating the client, include serverUrl only in development:

   import { createClient } from "@base44/sdk";
   
   const base44 = createClient({
     appId: "your-app-id",
     ...(isDev && {
       serverUrl: "http://localhost:4400",
       appBaseUrl: "http://localhost:4400",
     }),
   });
   

   • In development, isDev is true and both serverUrl and appBaseUrl point at localhost:4400
   • In production builds, isDev is false, both options are omitted, and the SDK uses its defaults

Run the dev servers

How you start the dev environment depends on whether your project defines site.serveCommand in base44/config.jsonc.

With site.serveCommand (recommended)

Run dev from your project directory:

base44 dev

This starts the local backend on http://localhost:4400, then spawns your frontend dev server using site.serveCommand. The CLI injects VITE_BASE44_APP_ID and VITE_BASE44_APP_BASE_URL into the frontend’s environment, which the env-var client configuration pattern above reads to point the SDK at the local backend. Both processes’ output is streamed to the same terminal, prefixed with [backend] and [frontend], and a single Ctrl-C shuts them down together.

Without site.serveCommand

If site.serveCommand isn’t set, run the two processes in separate terminals.

1. Start the backend

   In one terminal, run dev from your project directory:

   base44 dev
   

   This starts the local backend on http://localhost:4400.

2. Start the frontend

   In a second terminal, start your frontend dev server as you normally would. For example, with Vite:

   npm run dev
   

   All SDK calls from your frontend now go to the local Base44 dev server.

See also

• Local development overview: What runs locally, what’s forwarded, and how it works
• dev: CLI command reference with flags
• serverUrl: SDK client configuration