​
Getting Started

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

​
Prerequisites

  • Node.js 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

​
Create 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 project structure, package metadata, and base configuration files.

​
Options

schematics @nanoforge-dev/schematics:application my-game \
  --language=ts \
  --packageManager=pnpm \
  --server=true \
  --author="Your Name" \
  --version="1.0.0" \
  --description="My NanoForge game"
FlagDescription
--languagets (default) or js
--packageManagernpm (default), yarn, pnpm, or bun
--serverSet to true to include server configuration
--strictSet to false to disable strict mode
--authorAuthor name for package.json
--versionInitial version
--descriptionProject description for package.json
--directoryCustom output directory

​
Generate 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.

​
Generate Client or 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.

​
Generate 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.

​
Typical Workflow

  1. Scaffold the project. 
    schematics @nanoforge-dev/schematics:application my-game --server=true
  2. Install dependencies. 
    cd my-game
npm install
  3. Generate the client base. 
    schematics @nanoforge-dev/schematics:part-base my-game --part=client --initFunctions=true
  4. Generate the server base if you are using server support. 
    schematics @nanoforge-dev/schematics:part-base my-game --part=server --initFunctions=true
  5. Edit the save files in .nanoforge/client.save.json and .nanoforge/server.save.json.
  6. Generate the main entry points.
  7. Start developing your game logic in the generated components, systems, and init functions.