Native windows, 2D graphics and audio for Node.js, built on SFML 3.1.0.

English · 简体中文 · 日本語 · 한국어

Build desktop multimedia applications in JavaScript or TypeScript: draw sprites, shapes and text, handle window events, play and record audio, and exchange data through SFML-style networking APIs.

Website · Quick start · Guides · Type reference · Examples

What is included

Module	Capabilities
System	Typed vectors, angles, time, clocks, Unicode boundaries and seekable input streams
Window	Native windows, typed events, keyboard, mouse, joystick, clipboard and OpenGL contexts
Graphics	Sprites, shapes, Unicode text, cameras, shaders, vertex buffers and off-screen rendering
Audio	Sound effects, streaming music, recording, spatial audio and Worker-based processing
Network	TCP, UDP, packets, DNS, TLS, HTTP, FTP and SFTP through Node.js transports

TypeScript declarations are included. Numeric values and resource views use typed arrays; rendering records state snapshots and submits commands in batches. See core concepts for ownership, asynchronous loading and rendering behavior.

Installation

npm install sfml.js

Installation compiles a native addon and downloads the matching SFML libraries. Prepare Python and a C++20 toolchain before installing:

Platform	Download targets	Build tools
macOS 13+	x64, arm64	Xcode Command Line Tools
Linux	x64	GCC or Clang, make, X11, OpenGL and audio development libraries
Windows	x64, ia32	Visual Studio 2022 C++ Build Tools

The package declares Node.js ^18.19.0 || >=20.5.0; CI is configured for Node.js 20 and 22 on Linux, macOS and Windows. Download targets are not a claim that every architecture and device is tested. See installation instructions for platform commands.

Your first window

Save this as hello.cjs and run node hello.cjs:

const sf = require('sfml.js');

const window = new sf.RenderWindow(
  new sf.VideoMode(new sf.Vector2u(800, 600)),
  'Hello, sfml.js',
);
const circle = new sf.CircleShape({ radius: 80 });
circle.setPosition(new sf.Vector2f(320, 220));
circle.setFillColor(new sf.Color(76, 190, 110));
window.setFramerateLimit(60);

function frame() {
  window.handleEvents({
    Closed: () => window.close(),
    KeyPressed: event => {
      if (event.code === sf.Keyboard.Key.Escape) window.close();
    },
  });
  if (!window.isOpen()) return;

  window.clear(new sf.Color(24, 28, 32));
  window.draw(circle);
  window.display();
  setImmediate(frame);
}

frame();

The example creates a native desktop window. Run it in a graphical session. setImmediate() lets Node.js process I/O between frames; display() is synchronous and can wait for the frame limit or vertical sync.

For TypeScript, use named imports such as import { RenderWindow, Vector2u } from 'sfml.js'. File loading uses promises:

async function loadSprite(filename) {
  const texture = new sf.Texture();
  if (!await texture.loadFromFile(filename)) {
    throw new Error(`Cannot load texture: ${filename}`);
  }
  return new sf.Sprite(texture);
}

Documentation

The README and guides are available in English, Simplified Chinese, Japanese and Korean. English is the default.

Start here	Continue with
Quick start	Installation, imports and your first window
Core concepts	Values, resource lifetime, promises and draw snapshots
API guide	System, Window, Graphics, Audio and Network navigation
Examples	Runnable programs and their controls
Development	Building, testing and contributing

TypeDoc provides generated signatures and source comments. SFML's C++ documentation explains the upstream API; the guides here document JavaScript-specific behavior.

Run the examples

Captured from breakout.cjs, a playable game using shapes, keyboard input and a JavaScript game loop. Move with Left/Right or A/D, launch with Space, and exit with Esc.

git clone https://github.com/XadillaX/node-sfml.git
cd node-sfml
npm ci
node examples/breakout.cjs
node examples/all-types.cjs --frames=120
node examples/network.cjs

Feature examples · Official examples · Games and applications

node-sfml-demos contains Bomberman, Breakout, Tetris, Doodle Jump and Arkanoid implementations using sfml.js. See game setup for installation and launch commands.

16-sfml.js-games-ported ports all 16 games from jsyqrt/games, originally written in C++ with SFML, to ClojureScript with sfml.js. See 16 games for the game list and nbb launch commands.

play-nes — a desktop NES emulator built with sfml.js and JSNES.

Contributing

Use the development guide to prepare your environment. Pull requests for fixes, documentation and examples are welcome. Include a runnable reproduction with bug reports, together with the Node.js version, operating system and architecture.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Khaidi Chu 🚧 💻

NuriYuri 💻

Hanz 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

License

MIT.