Nostalgist.js

Become a sponsor

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

> [!tip]
> Nostalgist.js is for developers. If you are a player rather than a developer planning to build something, you may want to try another open-source project RetroAssembly.

A Quick Glance

Website

Checkout nostalgist.js.org for more online examples and documentation.

Features

+ Launch a retro game with RetroArch emulator in a browser

``js
import { Nostalgist } from 'nostalgist'

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

Related API: launch
+ Save the state of the game, then load it later

`js
import { Nostalgist } from 'nostalgist'

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

Related APIs: saveState, loadState
+ Customize any RetroArch config before launching
`js
import { Nostalgist } from 'nostalgist'

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

Related API: launch#retroarchConfig
+ Access low level APIs of Emscripten

`js
import { Nostalgist } from 'nostalgist'

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

Related APIs: getEmscriptenModule, getEmscriptenFS`

Motivation

Nostalgist.js is built on top of RetroArch Emscripten builds. We love RetroArch to run in browsers because that's portable and convenient. Although there is already an official instance, RetroArch 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.

APIs

Please refer to nostalgist.js.org/apis.

Related

$3

> [!note]
> Feel free to add yours by sending a pull request.

| Project | Description |
| ------- | ----------- |
| RetroAssembly | The personal retro game collection cabinet in your browser. |
| vme | Virtual Machine / Emulator - multi emulator web app |
| ultimate-homebrew-extensions | Runs an emulator to test ROMs inside of VS Code |
| NextCloud Nostalgist | Run emulators of retro consoles directly in NextCloud via Nostalgist.js. |
| Nostalbit | A retro web emulator with Next.js, Tailwind, TypeScript |
| AstroEmu | Famicom and Super Famicom on the web |
| Koin.js | The high-performance, preservation-focused netflix style emulation engine powered by Nostalgist. |
| Foxol | Foxol is a modern emulator platform with multiplayer, cloud saves, cheats, and deep customization across every device. |

$3

+ These are the fundamental dependencies of Nostalgist.js.
+ RetroArch and its friends(the emulators/cores)
+ Emscripten

+ We are using ROMs here for the purpose of demonstration.
+ retrobrews and the authors of the homebrew games.

+ By default, our ROMs and cores are all loaded from this free CDN service.
+ jsDelivr

$3

+ EmulatorJS

Another JavaScript library for emulation inside browsers.

It's more powerful and more sophisticated. It includes many custom cores and has a friendly user interface. It can be used inside mobile browsers with touch support.

It's not that friendly towards modern frontend development.

Caveat

> [!caution]
> + Nostalgist.js DOES NOT provide any pirated content, like copyrighted ROM files or BIOS files.
> + And it DOES NOT encourage that.

License

MIT