Runtime

Quokka.js supports running your code with both Node.js and Bun for its runtime environment.

By default, Quokka.js uses your system’s Node.js to run your code. You may also configure Quokka to use a specific node version, if you are using nvm for example.

For projects that use Bun within at least one of their package.json scripts, Quokka will ask whether you would like to use Bun to run your code. Similarly to Node.js, you may also configure Quokka to use a specific Bun version.

You may configure Quokka’s runtime selection behavior (whether to use Node or Bun) using the bun.usageMode setting.

Node Runtime

When Quokka starts and your project type is not module (not set, or set to CommonJs), then it uses stdEsm module for JavaScript files, allowing ES module imports and top level await to be used with zero configuration.

When Quokka starts and your project type is module, then it uses native ECMAScript modules, allowing ES module imports.

You may also force Quokka to not use stdEsm and/or use native ECMAScript modules by using the following settings in your Quokka config:

{
  ...
  "stdEsm": false,
  "nativeEsm": true
}

Node flags

If you need to specify some node flags or v8 options (you can get the full list of them by running node --v8-options in your terminal), you may do it via the env.param.runner setting by passing space-separated node process flags. For example:

{
  ...
  "env": {
    "params": {
      "runner": "--expose_gc"
    }
  }
}

Node.js version

By default Quokka runs the node command to run your code. If you would like to use a custom node.js version (for example if you are using nvm), you may specify the path to the node executable in your global Quokka config.json file, for example:

{
  "node": "~/.nvm/current/bin/node"
}

or

{
  "node": "/Users/username/.nvm/versions/node/v7.7.1/bin/node"
}

Bun Configuration

If you are using Bun within your package.json scripts, Quokka will ask whether you would like to use Bun to run your code the first time you start a Quokka file on that project.

You can configure how Quokka behaves when Bun is available with the bun.usageMode setting in your global Quokka config.json file:

• prompt (default) - Quokka will ask whether you would like to use Bun to run your code when at least one package.json script uses bun.
• autoUse - Quokka will use Bun when at least one package.json script uses bun.
• alwaysUse - Quokka will always use Bun to run your code.
• neverUse - Quokka will never use Bun (always use Node) to run your code.

{
  "bun": {
    "usageMode": "autoUse"
  }
}

Note: these settings can be overridden with a project-specific Quokka configuration file (<projectDir>/.quokka).

You may also configure Quokka to use a specific Bun version by specifying the path to the Bun executable using the bun.bunPath setting, for example:

{
  "bun": {
    "bunPath": "/Users/username/.bun/bin/bun"
  }
}

Process reuse

When (re)running your code on changes, Quokka by default tries to re-use previously created Node/Bun process(es) to make your code run faster. Sometimes you may need to re-create node process on every run, in this case you may use the recycle: true setting in your Quokka config:

{
  ...
  "recycle": true
}

Environment variables

If you need to specify some environment variables, such as BABEL_ENV or NODE_ENV, you may do it via the env.param.env setting by passing semicolon-separated node process environment variables. For example:

{
  ...
  "env": {
    "params": {
      "env": "BABEL_ENV=test;NODE_PATH=abc"
    }
  }
}

If you would like to load environment variables from a .env file, you may use the dotenv-quokka-plugin Quokka.js plugin.

ES modules and top-level await

Note: this section is not relevant if you are using Bun, or if you are using Babel or TypeScript and are compiling your ES modules to CommonJs

When Quokka starts and your project type is not module (not set, or set to CommonJs), then it uses stdEsm module for JavaScript files, allowing ES module imports and top level await to be used with zero configuration.

When Quokka starts and your project type is module, then it uses native ECMAScript modules, allowing ES module imports.

You may also force Quokka to not use stdEsm and/or use native ECMAScript modules by using the following settings in your Quokka config:

{
  ...
  "stdEsm": false,
  "nativeEsm": true
}

You may also consider adding --experimental-specifier-resolution=node to be able to import files without extensions:

  ...
  "nativeEsm": true,
  "env": {
    "params": {
      "runner": "--experimental-specifier-resolution=node"
    }
  }

Additionally, the settings above will also work for TypeScript files because Quokka integrates with ts-node's experimental ES modules support.

To use native top-level await your nodejs version must be 14.3.0 or higher.

Running delay

By default, Quokka runs your code immediately as you type. You may use the delay setting to specify a number of milliseconds to wait after your last code change before running the code.

{
  "delay": 1500
}

Module import

Absolute paths

If you are using absolute paths for modules import, with Webpack resolve.modules or Jest moduleDirectories, you may configure Quokka to resolve modules the same way using the NODE_PATH environment variable.

For example, if you have an src folder in your project, a components subfolder in it, and you are importing your components from other files like import ... from 'components/myComponent', then you may configure Quokka like this:

{
  ...
  "env": {
    "params": {
      "env": "NODE_PATH=./src"
    }
  }
}

Alias

If you have a Webpack configuration specifying alias for modules, for example:

// in webpack.config.dev
resolve: {
  alias: {
    appconfig: 'path/to/appconfig/dev';
  }
}

and want Quokka to resolve modules the same way, you may use Quokka alias plugin or Quokka babel-alias plugin (will work even if you’re not using babel).