Getting Started

This guide explains how to install and use @nanoforge-dev/schematics to scaffold NanoForge game engine projects.

Prerequisites

Node.js version 25 or later
A package manager: npm, yarn, pnpm, or bun

Installation

Install the schematics package globally or as a project dependency:

# npm
npm install -g @nanoforge-dev/schematics

# pnpm
pnpm add -g @nanoforge-dev/schematics

# yarn
yarn global add @nanoforge-dev/schematics

# bun
bun add -g @nanoforge-dev/schematics

Creating a New Application

Use the application schematic to scaffold a complete NanoForge project:

schematics @nanoforge-dev/schematics:application my-game

This creates a my-game/ directory with the full project structure including package.json, linter configuration, and a README.

Options

You can customize the generated project with the following flags:

schematics @nanoforge-dev/schematics:application my-game \
  --language=ts \
  --packageManager=pnpm \
  --server=true \
  --author="Your Name" \
  --version="1.0.0" \
  --description="My NanoForge game"

Flag	Description
`--language`	`ts` (default) or `js`
`--packageManager`	`npm` (default), `yarn`, `pnpm`, or `bun`
`--server`	Set to `true` to include server configuration
`--strict`	Set to `false` to disable strict mode (default `true`)
`--author`	Author name for package.json
`--version`	Initial version (default `0.0.0`)
`--description`	Project description for package.json
`--directory`	Custom output directory (defaults to project name)

Generating Configuration

Create or update the nanoforge.config.json file:

schematics @nanoforge-dev/schematics:configuration my-game

With server support:

schematics @nanoforge-dev/schematics:configuration my-game --server=true

If a nanoforge.config.json already exists in the directory tree, the schematic deep-merges new values into the existing configuration rather than overwriting it.

Generating Client/Server Base Code

Use the part-base schematic to scaffold the directory structure for a client or server part:

# Generate client base
schematics @nanoforge-dev/schematics:part-base my-game --part=client

# Generate server base
schematics @nanoforge-dev/schematics:part-base my-game --part=server

With lifecycle init functions:

schematics @nanoforge-dev/schematics:part-base my-game \
  --part=client \
  --initFunctions=true

This generates example components, example systems, and (optionally) six lifecycle hook functions in the init/ directory.

Generating the Main Entry Point

Use the part-main schematic to generate a main.ts file from a .nanoforge/<part>.save.json metadata file:

# Generate client main file
schematics @nanoforge-dev/schematics:part-main my-game --part=client

# Generate server main file
schematics @nanoforge-dev/schematics:part-main my-game --part=server

# With init functions
schematics @nanoforge-dev/schematics:part-main my-game \
  --part=client \
  --initFunctions=true

# Custom save file location
schematics @nanoforge-dev/schematics:part-main my-game \
  --part=client \
  --saveFile=custom/path/save.json

The save file defines which libraries, components, systems, and entities should be wired into the main entry point. See part-main for the save file format.

Typical Workflow

A typical workflow for creating a new NanoForge game project:

Scaffold the project:

schematics @nanoforge-dev/schematics:application my-game --server=true

Install dependencies:
```
cd my-game
npm install
```

Generate client base:

schematics @nanoforge-dev/schematics:part-base my-game \
  --part=client --initFunctions=true

Generate server base (if using server):

schematics @nanoforge-dev/schematics:part-base my-game \
  --part=server --initFunctions=true

Edit the save files to define your libraries, components, systems, and entities in .nanoforge/client.save.json and .nanoforge/server.save.json.

Generate main entry points:

schematics @nanoforge-dev/schematics:part-main my-game \
  --part=client --initFunctions=true
schematics @nanoforge-dev/schematics:part-main my-game \
  --part=server --initFunctions=true

Start developing your game logic by editing the generated components, systems, and init functions.