Skip to content
Select theme
Select languageEnglish

Backend

An app can have a backend: a module that exports fetch, or any Node.js / Bun server that calls listen() (Express, Hono, Fastify, ...). Pages reach it with a plain fetch('/api/…').

App backends run on macOS, Linux and Windows. On Windows the runtime reaches the backend in another way; see On Windows.

The server.ts generated by acdev new my-app --backend:

export default {
fetch(request: Request): Response {
const url = new URL(request.url)
if (url.pathname === '/api/hello') return Response.json({ hello: 'world', at: new Date().toISOString() })
return new Response('not found', { status: 404 })
},
}

In the page:

const answer = await (await fetch('/api/hello')).json()

export default { fetch } works on both Bun and Node.js. On Node.js, acdev's preload runs it with node:http; requests and responses are WHATWG Request / Response objects with streaming bodies. (There's no WebSocket upgrade on Node.js.)

You can also listen yourself:

import { createServer } from 'node:http'
createServer((req, res) => res.end('hi')).listen(3000)

To have the backend render the pages themselves (server-side HTML with Hono, JSX, templates, ... without a framework acdev recognizes), set the entry to /:

{ "type": "app", "id": "my-app", "label": "My app", "icon": "app", "entry": "/" }

The window then opens / from the backend, and every page it navigates to (links, location.href, forms) comes from the backend too; public/ is still served at the app root. Without a backend, acdev check and acdev build stop with an error; / is the only entry ending in / that is accepted. Frameworks that render on the server (Next.js, Nuxt, SvelteKit, ...) are set up this way automatically; see Frameworks.

Without a backend field, acdev uses the first of these that exists:

server.ts server.js src/server.ts src/server.js server/index.ts server/index.js backend/index.ts backend/index.js

To set it explicitly, or turn it off:

{ "backend": { "entry": "api/main.ts", "port": 8080 } }
{ "backend": false }

port defaults to 3000; it's the port the backend thinks it's listening on.

An app's backend doesn't open TCP ports on the host. At build time, acdev puts a preload (acde-listen.js) next to the backend that replaces listen(P) in Bun.serve, Bun.listen, and net / http / https / tls / http2 with a unix socket at <app's socket directory>/P.sock. If no port is given, it uses PORT / BUN_PORT / NODE_PORT, and otherwise 3000.

As a result:

  • Two apps can both listen(3000) without conflict.
  • Requests from the page to same-origin paths (/api/x) or to http://localhost:<port>/… (and 127.0.0.1, [::1], 0.0.0.0) all go to the app's own backend.
  • UDP bind to a specific port is rejected (EACCES); ports opened by native extensions on their own aren't covered.

The same build runs on Windows, and there too the backend opens no TCP port and no named pipe. How the runtime reaches it depends on what runs it:

  • Bun: as on macOS and Linux, listen(P) becomes a socket file P.sock. Its directory (ACDE_APP_SOCKETS) is made anew each time the backend starts, and only the current user and the system can open it.
  • Node.js: Node.js cannot listen on a socket file on Windows, so nothing listens at all. The preload keeps the server that called listen(P), and the runtime hands it every connection (HTTP requests and WebSocket upgrades) through a private pipe to the backend process. The backend gets ACDE_APP_CHANNEL=fd and no ACDE_APP_SOCKETS. A backend built by an acdev from before this is not started on Windows; the log says not started: acde-listen.js does not support the Windows channel (built by an older acde: acdev build it again).

To stop a backend on Windows the runtime asks it to shut down: it takes no new connections, finishes the requests in progress and exits; after 3 seconds the runtime ends it together with the processes it started.

acdev build bundles the backend into a single ES module, backend/server.js (target node): npm packages are bundled in, while Node built-in modules and bun / bun:* stay as imports. The same output runs on both Bun and Node.js.

  • The backend starts when the app's first window opens and stops when its last window closes (on macOS and Linux with SIGTERM, then SIGKILL after 3 seconds; for Windows see above). After the 4th crash within a minute, it's no longer restarted automatically.
  • It runs on Bun if bun is on PATH, otherwise on Node.js (≥ 22.3). acdev dev picks based on the project's JavaScript runtime.
  • The environment is built from scratch: ACDE_APP_ID, ACDE_APP_DATA, ACDE_APP_SOCKETS, PORT, NODE_ENV=production, plus the session's HOME, PATH, LANG, and so on, and the proxy variables below. Nothing else is inherited from your terminal.
  • Proxy settings are passed on. If the session sets any of http_proxy, https_proxy or all_proxy, the backend gets http_proxy, https_proxy, all_proxy and no_proxy as the session has them (on macOS and Linux under both the lower-case and the upper-case names, as set; on Windows, where variable names ignore case, under the upper-case names). If none is set, the backend gets the system's manual proxy, the same settings pages use. Only Windows and macOS have one: on Windows the HTTP proxy from the user's Internet settings (a socks= entry becomes all_proxy=socks4a://host:port), set under the upper-case names; on macOS the HTTP, HTTPS and SOCKS proxies from the network settings (SOCKS becomes socks5h://host:port), set under both the lower-case and the upper-case names. no_proxy then holds the session's no_proxy, the system's exceptions in no_proxy form (*.example.com becomes .example.com, 192.168.* becomes 192.168.0.0/16; other wildcards, Windows' <local> and macOS's "exclude simple hostnames" have no no_proxy form and are left out), and localhost,127.0.0.1,::1. A proxy auto-config script or automatic proxy discovery answers per URL and can't be expressed as variables, so with those the backend gets no system proxy (on Windows, "Automatically detect settings" alone still passes the manual proxy). The settings are read each time a backend starts. Linux has no system proxy setting to read: only the session's variables count there. Your HTTP client still has to honour these variables (Bun's fetch and many npm clients do; Node.js's built-in fetch does not by default).
  • The working directory is $XDG_DATA_HOME/acde/apps/<id>/; the app can keep its own data here.
  • On macOS and Linux the sockets are in a directory of the session's runtime (ACDE_APP_SOCKETS). Each session has its own, <runtime pid>/<id> in acdev's runtime directory, removed when the backend stops: $TMPDIR/acde-<uid> on macOS, and acde/ in XDG_RUNTIME_DIR (/run/user/<uid> on Linux when it is not set). A socket path longer than the system allows (104 bytes on macOS, 108 on Linux) is not started; the log says so.
  • Backend output goes to the runtime's log, prefixed with [<id>#backend]. acdev dev prints it in your terminal.

To debug the built backend on its own, without the runtime, give it a socket directory and load the preload that acdev build put next to it (the commands are for macOS and Linux):

Terminal window
acdev build
cd .acde/backend
ACDE_APP_SOCKETS=/tmp/my-app-sockets bun --preload ./acde-listen.js server.js
curl --unix-socket /tmp/my-app-sockets/3000.sock http://localhost/api/hello