Skip to content
Nostalgist.js
Star Nostalgist.js on GitHub if you like it! Takes only 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, and 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.

Getting Started