Runtime

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

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
}

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.

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"
}

Node process reuse

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

{
  ...
  "recycle": true
}

ES modules and top-level await

Note that if you are using Babel or TypeScript and are compiling your ES modules to CommonJs, then the documentation section below is not relevant to you.

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).