# 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](#on-windows).

## Write a backend

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

```ts
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:

```js
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:

```ts
import { createServer } from 'node:http'

createServer((req, res) => res.end('hi')).listen(3000)
```

## Pages from the backend

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

```jsonc
{ "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](https://docs.dopame.ai/guide/frameworks.md).

## Discovery

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:

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

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

## No TCP ports

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.

## On Windows

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.

## Bundling

`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.

## Running

- 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](#on-windows)). 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.

## Running it directly

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):

```sh
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
```
