js-dos v7 is still under development and some features are not ready; for example you can't use a mouse yet. Please use js-dos 6.22 for production projects.

The new version of js-dos is more modular, you can use parts of it. It consists of:

  • js-dos bundle - universal package format that js-dos understands
  • emulators - npm package, that provide emulator backends which can run in different environments
  • emulators-ui - npm package, a set of ui and sound components to render emulator output in browser
  • js-dos - npm package that combines everything to run a DOS program in browser

js-dos bundle

Previous version (6.22) has a very simple API to run a DOS program in the browser. BUT, before starting it you need to perform some setup:

  • download game archive (usually zip)
  • extract it
  • configure dos file system
  • configure dosbox options (cycles, renderer type, etc.)
  • configure controllers (mouse, keyboard type, etc.)

Often gameplay quality depends on good configuration.

Starting from js-dos v7, the API expects a js-dos bundle that already contains all configuration needed to start the DOS program. js-dos bundle is just a ZIP archive that contains the game itself and a js-dos configuration file (same as dosbox.conf file). For example, digger.jsdos contains:

.jsdos/dosbox.conf - dosbox configuration file (required)
.jsdos/jsods.json - additional configuration (optional)
DIGGER.COM - game file

File .jsdos/dosbox.conf is required. js-dos would not start if this file does not exist.

You can generate a js-dos bundle programmatically. But, we recommend you use our bundle generator Moreover you can search our database to see if someone already uploaded a js-dos bundle for a program.

Read the guide about creating js-dos bundle.

Bundles repository

Visit our repository that contains 1500+ already created bundles of dos games. You can contribute in it.

Run jsdos file

Once you have a jsdos bundle you can easily run it in the browser. There are several options:

1. Using player hosted on dos.zone

Fastest way to embed a program on your page. You just need the url of a jsdos bundle (you can get it from our game database).


The src can be composed like this:

const src = "https://dos.zone/en/player/" + encodeURIComponent(bundleUrl);

To receive input you should focus the iframe:


Complete example:

  1. Drag with the mouse to play without a keyboard!
  2. Open top menu to type records name on mobile.

Iframe integration didn't support a fullscreen button yet, if you need it look forward.

2. Using js-dos api

To run bundle you just need a one line of code:


Dos receives HTMLDivElement and uses it to create the player UI. To run jsdos bundle just use its method run specifying the url of jsdos bundle.

To use js-dos you need to add js-dos.js script, and js-dos.css style. Also you need to specify path prefix of js-dos installation:

<script src="/v7/build/releases/latest/js-dos/js-dos.js"></script>
<link href="/v7/build/releases/latest/js-dos/js-dos.css" rel="stylesheet">
// ...
emulators.pathPrefix = "/v7/build/releases/latest/js-dos/";

Complete example:


By default, js-dos will load wasm modules relatively from current path, you should specify variable pathPrefix if you want to load them from different place:

emulators.pathPrefix = "/v7/build/releases/latest/js-dos/";

3. Using emulators-ui

From v7 js-dos npm package is only a wrapper script that combines emulators and emulators-ui packages. It didn't contains code itself. It's useful if you don't want to make customizations in UI or custom integration. js-dos package is single file solution to run DOS programs.

If you want to make customizations or something special then you need to use emulators and emulators-ui package in combination. They provide absolutely same functions as js-dos package and lot more (see threejs integration).

To change code above to use emulators-ui just change scripts imports to:

<script src="/v7/build/releases/latest/emulators/emulators.js"></script>
<script src="/v7/build/releases/latest/emulators-ui/emulators-ui.js"></script>
<link rel="stylesheet" href="/v7/build/releases/latest/emulators-ui/emulators-ui.css">

Complete example:


4. Using emulators

In case you don't want to use the browser API of js-dos project, you can use just the emulators package. Read the guide to how we use emulators to estimate js-dos performance.