Build your first web game.

NanoForge requires Node.js 25+ and a package manager. We recommend pnpm, but npm, yarn, and bun all work.

Install the NanoForge CLI globally:

Pass --editor to nf new to scaffold a project that includes the editor entry points and save file at .nanoforge/.

The --editor flag adds editor-specific dependencies and generates the .nanoforge/editor/ entry points alongside your regular client/ source.

Run nf editor from inside your project directory. The editor is a web app that opens at http://localhost:4000.

Load your project

The editor opens on the project loader page. You have two options:

Recent projects are cached in the browser so you can reopen them with a single click.

Inside the workspace, use the scene hierarchy to spawn entities and the component inspector to attach data.

1. 1

   In the hierarchy panel, click + New entity and choose a name. A blank entity appears.

2. 2

   Select the entity. In the inspector on the right, click Add component and pick Position. Set x: 400, y: 300.

3. 3

   Add a second component: Velocity. Set vx: 120, vy: 0.

4. 4

   The editor writes automaticaly modifications in .nanoforge/client.save.json.

// .nanoforge/client.save.json - written by the editor on File › Save
{
  "entities": [
    {
      "id": "entity_42",
      "components": [
        { "type": "Position", "x": 400, "y": 300 },
        { "type": "Velocity", "vx": 120, "vy": 0 }
      ]
    }
  ]
}

Then let's build and start the game. nf dev generate the entry point, builds and serves the client - the game reflects your latest editor changes:

When you're ready to share your game, push it to GitHub and connect it to the Project Manager. It handles builds, versioning, and hosting so your players always get the latest version.

NanoForge requires Node.js 25+ and a package manager. We recommend pnpm, but npm, yarn, and bun all work.

Install the NanoForge CLI globally:

Run nf new to scaffold a new project. The interactive wizard will ask you a few questions about your setup.

You can also pass flags to skip the wizard:

nf new generates the following layout. All your game logic lives in client/ (browser) and optionally server/ (for multiplayer).

my-game/
├── client/                  # browser-side entry point
│   └── main.ts
├── server/                  # node.js server (multiplayer)
│   └── main.ts
├── nanoforge.config.json    # build & runtime config
├── package.json
└── tsconfig.json

The generated client/main.ts exports a main() function that NanoForge calls to boot your game:

import { type IRunOptions } from '@nanoforge-dev/common';
import { NanoforgeFactory } from '@nanoforge-dev/core';

export async function main(options: IRunOptions) {
  const app = NanoforgeFactory.createClient();

  // register libraries, then init and run
  await app.init(options);
  await app.run();
}

NanoForge uses an Entity-Component-System (ECS) architecture. Everything in your game — players, projectiles, tiles — is an entity made of components, processed by systems.

Let's build a moving square. First, define two components to describe an entity's position and velocity:

export class Position {
  constructor(
    public x: number,
    public y: number,
  ) {}
}

export class Velocity {
  constructor(
    public vx: number = 0,
    public vy: number = 0,
  ) {}
}

Then write a system that reads those components and moves entities each tick. The getZipper call returns only entities that have all the listed components:

import type { Registry, Context } from '@nanoforge-dev/ecs-client';
import { Position, Velocity } from '../components';

export function moveSystem(registry: Registry, ctx: Context) {
  const entities = registry.getZipper([Position, Velocity]);

  for (const entity of entities) {
    entity.Position.x += entity.Velocity.vx * ctx.deltaTime;
    entity.Position.y += entity.Velocity.vy * ctx.deltaTime;
  }
}

Register the ECS library, then spawn an entity and attach components in your main() function. The registry is the entry point for all entity and system management:

import { ECSClientLibrary } from '@nanoforge-dev/ecs-client';
// ... other imports

export async function main(options: IRunOptions) {
  const app = NanoforgeFactory.createClient();
  const ecs = new ECSClientLibrary();
  app.useComponentSystem(ecs);

  await app.init(options);

  const registry = ecs.registry;

  const player = registry.spawnEntity();
  registry.addComponent(player, new Position(400, 300));
  registry.addComponent(player, new Velocity(120, 0));
  registry.addSystem(moveSystem);

  await app.run();
}

To render the entity, add a draw system using the @nanoforge-dev/graphics-2d library:

import { Graphics2DLibrary, Rect } from '@nanoforge-dev/graphics-2d';
import type { Registry, Context } from '@nanoforge-dev/ecs-client';
import { Position } from '../components';

export function drawSystem(registry: Registry, ctx: Context) {
  const graphics = ctx.libs.getGraphics<Graphics2DLibrary>();
  const entities = registry.getZipper([Position]);

  for (const entity of entities) {
    const rect = new Rect({
      x: entity.Position.x,
      y: entity.Position.y,
      width: 32,
      height: 32,
      fill: '#7c3aed',
    });
    graphics.stage.add(rect);
  }
}

nf dev compiles your project, starts both client and server, and watches for changes with hot reload.

The NanoForge Registry hosts ready-to-use components, systems, and templates. Install them with nf install:

Once installed, packages are imported like any TypeScript module. The CLI also generates stubs for components and systems so you can start using them immediately.

When you're ready to ship, build your project and start the production server:

You can also manage deployments directly from the Project Manager — a web dashboard where you can monitor builds, manage multiple projects, and invite collaborators.