Configuration file

Overview

Every NanoForge workspace, project, or lib has a nanoforge.config.ts (or .js) at its root, exporting its configuration wrapped in defineConfig from @nanoforge-dev/config. The CLI reads this file to know how to build and start your game, and — for a workspace root — to discover the projects and libs it contains. Commands accept -c, --config <directory> to point at a different directory to read the config from (default: the current directory). The CLI looks for nanoforge.config.ts in that directory first, falls back to nanoforge.config.js when no .ts file exists, and fails if neither is present.

`type`

A config’s type field discriminates between four shapes:

workspace — a monorepo root listing its packages.
lib — a shared library consumed by clients/servers.
client — a browser-side NanoForge app.
server — a server-side NanoForge app.

The config at the root directory the CLI is pointed at must be a workspace or a client/server project — a bare lib config is not valid there. Inside a workspace, none of the packages it resolves may themselves be of type workspace; nesting workspaces isn’t supported.

Defining a config

Wrap your config in defineConfig to get type-checking and editor autocompletion on its fields:

import { defineConfig } from "@nanoforge-dev/config";

export default defineConfig({
  type: "client",
  entryFile: "src/main.ts",
  libs: ["../../libs/my-lib"],
});

defineConfig is an identity function — it returns its argument unchanged.

`workspace`

Field	Type	Default	Description
`packages`	`string[]`	`[]`	, each expected to hold its own `client`, `server`, or `lib` config.

A directory matched by a pattern but missing a nanoforge.config.ts/.js is skipped without error. A pattern that matches no project or lib at all only logs a warning, rather than failing the whole resolution. A matched directory whose config is itself of type workspace throws.

Example

import { defineConfig } from "@nanoforge-dev/config";

export default defineConfig({
  type: "workspace",
  packages: ["apps/*", "libs/*"],
});

`lib`

Field	Type	Default	Description
`dir.assets`	`string`	`assets`	Where assets live.
`dir.shared`	`string`	`shared`	Where shared code lives.
`dir.components`	`string`	`shared/components`	Used by the editor only.
`dir.systems`	`string`	`shared/systems`	Used by the editor only.
`dir.scenes`	`string`	`shared/scenes`	Used by the editor only.

Example

import { defineConfig } from "@nanoforge-dev/config";

export default defineConfig({ type: "lib" });

`client` / `server`

client and server share the exact same fields and defaults — type is the only thing that tells them apart.

Field	Type	Default	Description
`entryFile`	`string`	`src/main.ts`	Entry file.
`out.dir`	`string`	`dist`	Build output directory.
`out.mainFile`	`string`	`main.js`	Build output entry file name.
`dir.assets`	`string`	`assets`	Where assets live.
`dir.packages`	`string`	`nf_modules`	Where downloaded package dependencies are installed.
`dir.components`	`string`	`src/components`	Used by the editor only.
`dir.systems`	`string`	`src/systems`	Used by the editor only.
`dir.scenes`	`string`	`src/scenes`	Used by the editor only.
`libs`	`string[]`	`[]`	Relative paths to shared libs this project depends on.

Example

import { defineConfig } from "@nanoforge-dev/config";

export default defineConfig({
  type: "server",
  entryFile: "src/main.ts",
  dir: { assets: "static" },
  libs: ["../../libs/shared"],
});

Resolving defaults

Missing fields are filled in with the defaults for the config’s type, deep-merging nested objects like dir and out:

import { resolveConfig } from "@nanoforge-dev/config";

const resolved = resolveConfig({ type: "client", dir: { assets: "static" } });
// resolved.dir.assets === "static"
// resolved.dir.packages === "nf_modules" (default, not overridden)

Array fields (packages, libs) are replaced wholesale by an override rather than concatenated with the defaults.

Errors

ConfigNotFoundError — thrown by the CLI when neither nanoforge.config.ts nor nanoforge.config.js exists in the directory it was pointed at.
ConfigParseError (from @nanoforge-dev/config) — thrown while loading or validating a config file’s default export. Its code identifies the failure: not-found, load-failed, no-default-export, or invalid-type.

Commands

Configuration

Getting-Started

Loader

Schematics

Configuration file

Overview

`type`

Defining a config

`workspace`

Example

`lib`

Example

`client` / `server`

Example

Resolving defaults

Errors

​Overview

​type

​Defining a config

​workspace

​Example

​lib

​Example

​client / server

​Example

​Resolving defaults

​Errors

Overview

`type`

Defining a config

`workspace`

Example

`lib`

Example

`client` / `server`

Example

Resolving defaults

Errors