Updates

README.md

@@ -153,7 +153,7 @@ bun run dev
 | Command        | Description                                                                    |
 | -------------- | ------------------------------------------------------------------------------ |
 | `bunext dev`   | Start the development server with HMR and file watching.                       |
-| `bunext build` | Bundle all pages for production. Outputs artifacts to `.bunext/public/pages/`. |
+| `bunext build` | Bundle all pages for production. Outputs artifacts to `.bunext/public/pages/`. Resolves absolute paths in the artifact maps at the configured build root — see [BUNEXT_BUILD_ROOT_DIR](#environment-variables). |
 | `bunext start` | Start the production server using pre-built artifacts.                         |
 
 ### Running the CLI
@@ -913,10 +913,21 @@ bun run server.ts
 
 ## Environment Variables
 
-| Variable           | Description                                                                                      |
-| ------------------ | ------------------------------------------------------------------------------------------------ |
-| `PORT`             | Override the server port (takes precedence over config)                                          |
-| `BUNEXT_PUBLIC_*`  | Any env var prefixed with `BUNEXT_PUBLIC_` is exposed to the client via `window.process.env`     |
+| Variable               | Description                                                                                      |
+| ---------------------- | ------------------------------------------------------------------------------------------------ |
+| `PORT`                 | Override the server port (takes precedence over config)                                          |
+| `BUNEXT_PUBLIC_*`      | Any env var prefixed with `BUNEXT_PUBLIC_` is exposed to the client via `window.process.env`     |
+| `BUNEXT_BUILD_ROOT_DIR` | Read by `bunext build` only. When set, the project root's absolute path is replaced with this value inside the artifact maps (`map.json` and `ssr-bundler-ctx-map.json`) before they are written. Use it when the project will be served from a different path than the one it was built at (e.g. building in CI at `/build/app` and running in a container mounted at `/app`). |
+
+### Build Root Directory
+
+Artifact maps store absolute filesystem paths. By default, `bunext build` records the build machine's current working directory as the root. If the project will be deployed or served from a different location, point the maps at the runtime root instead:
+
+```bash
+BUNEXT_BUILD_ROOT_DIR=/app bun run build
+```
+
+Run `bunext start` from the directory matching `BUNEXT_BUILD_ROOT_DIR` so all recorded artifact paths resolve at request time. If unset, the path is left as-is and the runtime working directory must match the build directory.
 
 ### Public Environment Variables
 
@@ -965,8 +976,9 @@ Running `bunext build`:
 
 1. Sets `NODE_ENV=production`.
 2. Runs ESBuild once with minification enabled.
-3. Writes all bundled artifacts to `.bunext/public/pages/` and the artifact map to `.bunext/public/pages/map.json`.
-4. Exits.
+3. Writes all bundled artifacts to `.bunext/public/pages/` plus the artifact maps `.bunext/public/pages/map.json` and `.bunext/public/pages/ssr-bundler-ctx-map.json`.
+4. Artifact maps store absolute paths anchored at the project root. If `BUNEXT_BUILD_ROOT_DIR` is set, every occurrence of the build directory is replaced with that value so the maps point at the deploy-time location (see [Build Root Directory](#build-root-directory)).
+5. Exits.
 
 ### Production Server