Skip to content
Star Nostalgist.js on GitHub if you like it! Takes you a few seconds, means a lot for me.

Nostalgist.js

Nostalgist.js logo


nostalgist.js.org badgeGitHub badgeNPM badge


Nostalgist.js is a JavaScript library that allows you to run emulators of retro consoles like NES and Sega Genesis, within web browsers.

Getting StartedAPI reference

A Quick Glance

console demo

If you want to have a quick try, open the DevTools of your browser(maybe Ctrl + Shift + J on Windows/Linux and + + J on macOS), then type this code and press Enter, an NES emulator will appear in your browser like above (though it’s not Super Mario Bros. 😐)!

await Nostalgist.nes('flappybird.nes')

Controls: D-Pad: Start: Enter Select: Shift B: Z A: X

Features

Launch

Launch a retro game with RetroArch emulator in a browser

import { Nostalgist } from 'nostalgist'
await Nostalgist.launch({
core: 'fceumm',
rom: 'flappybird.nes',
})

Related API: launch

Save & Load

Save the state of the game, then load it later

import { Nostalgist } from 'nostalgist'
const nostalgist = await Nostalgist.nes('flappybird.nes')
const { state } = await nostalgist.saveState()
await nostalgist.loadState(state)

Related API: saveState, loadState

Customize

Customize any RetroArch config before launching

import { Nostalgist } from 'nostalgist'
const nostalgist = await Nostalgist.launch({
core: 'fceumm',
rom: 'flappybird.nes',
retroarchConfig: {
rewind_enable: true,
},
retroarchCoreConfig: {
fceumm_turbo_enable: 'Both',
},
})

Hack

Access low level APIs of Emscripten

import { Nostalgist } from 'nostalgist'
const rom = 'https://example.com/zelda.sfc'
const nostalgist = await Nostalgist.snes(rom)
const FS = nostalgist.getEmscriptenFS()
FS.readdir('/')

Related API: getEmscriptenFS

Here is a simple live example.

Motivation

Nostalgist.js is built on top of RetroArch Emscripten builds. Although there is an official RetroArch’s web player, and some third-party ones like webretro, it’s still not that easy to launch RetroArch in a browser programmatically.

The purpose of Nostalgist.js is to simplify the process of launching an emulator to play a game, via RetroArch, in browsers. Given a ROM and a core, the game should be launched without any additional configuration.