> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nanoforge.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# Client loader

> The web server that serves the loading page and the client build

## What it does

The client loader (`@nanoforge-dev/loader-client`) is a Bun web server. [`nf start`](https://docs.nanoforge.eu/docs/cli/commands/start)
starts one for each client app, pointed at the app's build folder. It serves:

* the [loading page](https://docs.nanoforge.eu/docs/loader/website.md), at `/`;
* the list of game files, at `/manifest`;
* the client's environment variables, at `/env`;
* the game files themselves, at `/game/<path>`.

It prints `Client started on url http://localhost:3000/` when it is ready.

## What nf start passes to it

| `nf start` option or config field | Client loader option |
| - | - |
| the client build folder (`out.dir`) | `-d, --dir <dir>` (required) |
| `--port`, or `port` (default `3000`) | `-p, --port <port>` |
| `--watch` (set by `nf dev`) | `--watch` |
| the server build folder, with `--watch` and one server app | `--watch-server-dir <dir>` |
| `--cert` and `--key`, or `tls` | `--cert <file>`, `--key <file>` |

The client loader also has `--watch-port <port>` for the live-reload WebSocket. `nf start` doesn't
set it, so the WebSocket takes a free port.

## Routes worth knowing when you debug

Open them in the browser next to the game:

| Route | Returns |
| - | - |
| `/manifest` | JSON: each file of the build with its path, SHA-256 hash and size, a version, and the live-reload WebSocket URL when `--watch` is on. |
| `/env` | JSON: the variables the client gets, without the `NANOFORGE_` prefix, plus `tlsEnabled`. |
| `/game/<path>` | One file of the build, for example `/game/main.js`. |

Only files inside the build folder are served at `/game/<path>`, and only files of the loading page at
the other paths. Any other path returns a 404.

`/manifest` lists the build folder each time it is requested, so files added by a rebuild show up
on the next page load. A hash is computed again only when a file's size or modification time
changes.

## Live reload

With `--watch`, the client loader watches the build folder and sends `update` on its WebSocket
when a file changes. The loading page then reloads. Changes closer than 100 ms count as one. When
`nf start` passes `--watch-server-dir`, a change in the server build reloads the page too, 100 ms
later, to give the server time to restart.

## HTTPS

With `--cert` and `--key`, the client loader serves HTTPS, and `/env` returns `tlsEnabled: true`.
You need HTTPS as soon as players open the game on an address other than `localhost`: see
[secure context](https://docs.nanoforge.eu/docs/loader/website.md#secure-context).

The live-reload WebSocket stays plain `ws://`, on `localhost`. Live reload works only in a browser
on the machine that runs the loader.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.