Configuration

Quokka supports 4 sources of configuration (in addition to editor extension UI related settings):

The settings in the global config file are applied to all Quokka files, no matter if you are running Quokka in an opened project or not.

The settings in a package.json file are applied to all Quokka files opened in the context of the opened project.

The settings in a .quokka file are applied to all Quokka files opened in the context of the opened project.

The inline settings in your Quokka file are applied only to the opened file.

The settings in the package.json file override the settings in the global config, settings in the .quokka file override the settings in the package.json file, and the inline settings have the highest precedence and will override any values set with other methods.

If you change your settings, you must restart your Quokka files to use the updated settings.

Inline config

To add Quokka configuration right in the Quokka file, you may start the file with the object expression that defines the settings:

({
    babel: true
})

var abc = 123;

abc

// the rest of your Quokka file

.quokka file config

To add Quokka configuration options for your project, you may add the .quokka JSON file in your project and add Quokka settings directly to the root object, for example:

{
    "babel": true
}

Note that settings in the .quokka file override the settings in the package.json file, so if you have some team settings for Quokka in the package.json file, and would like to override them with your personal settings, then you should add these settings to the .quokka file.

package.json config

To add Quokka configuration options for your project, you may add a quokka object property and provide your settings within that property, for example:

{
  "name": "my-project",
  "quokka": {
    "babel": true
  }
}

The configuration samples below describe the content of the quokka object property.

Global config file

When Quokka.js starts for the first time, it creates the global Quokka.js settings folder:

On Mac OSX and Linux: ~/.quokka

On Windows: %USERPROFILE%\.quokka

The global config JSON file is the config.json file in the folder. You may add Quokka settings directly to the root object, for example:

{
    "babel": true
}

The configuration samples below describe the content of the root object property.

Babel

The simplest way to configure Quokka to use Babel is to specify:

{
    babel: true
}

in your Quokka configuration.

This configuration expects that you have a .babelrc file (or a "babel": {...} section in your package.json) in your project (or the global config folder), as well the babel-core and the used presets in the project’s node_modules.

If you want to use the same version of babel for all projects and scratch files outside of any project context, you may install babel-core and required presets into the global ~/.quokka/node_modules folder.

Environment

If you are using different environment settings in your .babelrc file (or the "babel": {...} section in your package.json), then you may need to pass the desired env setting so that the required presets/plugins are applied.

{
    babel: {
        env: "dev"
    }
}

(the default env value is test)

Babel path

If you have babel-core installed somewhere else, you may specify the path (absolute or relative to the project’s folder):

{
    babel: {
        path: "...babel-core"
    }
}

Babel polyfill

If you want to use babel-polyfill:

{
    babel: {
        polyfill: true
    }
}

Overriding babel settings

If you don’t have a .babelrc file (or a "babel": {...} section in your package.json) or want to completely override the settings in your .babelrc file (or the "babel": {...} section in your package.json), you may specify them in the babel configuration object:

{
    babel: {
        presets: ["es2015", "react"]
    }
}

Note that in this case the babel settings are only applied for the Quokka file compilation. The files that you import/require from your Quokka file will be compiled using .babelrc file (or "babel": {...} section in your package.json).

Overriding Babel Configuration File Location

If you are running a mono-repo or have a complex project structure and need to load your Babel configuration from a different location than Babel defaults (i.e. your project root .babelrc or babel.config.js) then you may specify Babel’s config loading options in your project’s Quokka configuration settings (either package.json or .quokka file). For example, your project .quokka file will look something like this:

{
  "babel": {
    "configFile": "./sub-directory/custom.babel.config.js"
  }
}

Please note that any Babel paths that you specify in your global config file will use your project folder as the root folder for resolution of relative paths.

Using Babel to compile TypeScript

If you want to use Babel to compile TypeScript files then an additional configuration option, ts is required to override Quokka’s default use of the TypeScript compiler. When using Babel to compile TypeScript files, Quokka will run your code using node instead of ts-node. An example configuration is shown below:

{
  "babel": {
    "ts": true,
    "plugins": ["@babel/plugin-transform-typescript"]
  }
}

TypeScript

Most times if you are using TypeScript, no configuration is required. Quokka uses ts-node with swc to run your TypeScript files.

Overriding Quokka’s TypeScript Dependencies

Quokka is installed with four dependencies that are required to execute TypeScript files:

  • TypeScript (used to compile your TypeScript files)
  • ts-node (used to import other TypeScript files from your project)
  • swc (used to compile your TypeScript imports)
  • tsconfig-paths (used for TypeScript’s module resolution)

Depending on your project and the version of Quokka that you are using, you may want to use a different version of these dependencies. You may override the version for any (or all) of these by installing the dependency either as a project dependency or in your global quokka ~/.quokka/node_modules folder. Quokka will attempt to find each dependency first in the project folder, then in the global ~/.quokka/node_modules folder; if the dependency is not found in the project or global folder, Quokka will use its own version.

Please note: When using Quokka’s embedded version of ts-node, ts-node will be started in “fast” mode using process.env.TS_NODE_TRANSPILE_ONLY = true. You may override this behavior by installing ts-node in your project or global folder.

Compiler version

Unless the path to the desired TypeScript version is specified in the Quokka settings

{
    "ts": {
        "path": "...typescript"
    }
}

Quokka.js will try to use TypeScript from the following places (in priority order):

  1. local project’s node_modules,
  2. global config folder’s node_modules,
  3. editor’s embedded TypeScript version (if any),
  4. Quokka.js embedded TypeScript version, if nothing was found up to this point.

Compiler settings

If you need to override some compiler options from the project’s tsconfig.json, or if you don’t have a tsconfig.json file, but need to specify some settings:

{
    "ts": {
        "compilerOptions": {
            "target": "es6",
            ...
        }
    }
}

Using SWC for dependency compilation

Quokka uses ts-node with swc to compile TypeScript dependencies because it is significantly faster than using the TypeScript compiler. If for some reason, you do not want to use swc to compile your Quokka file dependencies, you may do so by specifying the "swc": false settings in your Quokka configuration:

{
    "ts": {
        "swc": false
        ...
    }
}

JSDOM

To emulate a browser-like environment, you may use JSDOM. You may install JSDOM as either a global Quokka dependency to make it available for all Quokka projects, or else as a dependency in your project.

npm install jsdom

To use JSDOM, you must add the built-in jsdom-quokka-plugin to the plugins section of your Quokka configuration:

{
    "plugins": ["jsdom-quokka-plugin"]
}

If you need to, you may pass additional configuration options:

{
    "plugins": ["jsdom-quokka-plugin"],
    "jsdom": {
        "file": "/html/file/path"
        "html": "...",
        "userAgent": "...",
        "config": {...}
    }
}

The jsdom.file setting allows to specify a path to any HTML file.

The jsdom.html setting allows to specify any HTML as a string.

The jsdom.config setting is the jsdom options setting.

If jsdom.file and jsdom.html is not provided, Quokka will attempt to load html for a file that has the same folder and base filename as your Quokka file with an .html extension. If no {quokkaFile}.html file exists, Quokka will attempt to load html from index.html in the same folder as your Quokka file. If no index.html is found, Quokka will set the document’s body to a single div with id of root (<div id="root"></div>).

Quokka jsdom default settings are shown below:

{
  "plugins": ["jsdom-quokka-plugin"],
  "jsdom": {
      "userAgent": "quokka.js",
      "config": {
        "pretendToBeVisual": true,
        "runScripts": "dangerously",
        "url": "http://localhost/"
      }
  }
}

Inline Config Example

Quokka Scratch File

({
  plugins: ['jsdom-quokka-plugin'],
  jsdom: {html: `<div id="testDiv">Hello</div>`}
})

const testDiv = document.getElementById('testDiv');

console.log(testDiv.innerHTML);

Loading from HTML file Example

Html File (/test.html)

<html>
  <head>
    <title>This is my sample page.</title>
  </head>
  <body>
    <p id="testDiv">Hello World</p>
  </body>
</html>

Quokka Scratch File

({
  "plugins": ["jsdom-quokka-plugin"],
  "jsdom": {"file": "test.html"} // Located in project root
})

const testDiv = document.getElementById('testDiv');

console.log(testDiv.innerHTML);

Web Canvas API

If you want to use HTMLCanvasElement objects with Quokka and jsdom then you must also install the canvas package in the same location as jsdom.

npm install canvas

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.

By default, Quokka uses esm module for JavaScript files, allowing ES imports and top level await to be used with zero configuration.

Quokka supports ES modules and top-level await via ECMAScript module loader and via native ECMAScript Modules. For the purpose of supporting wider range of nodejs versions by default Quokka uses ECMAScript module loader, however if you’re using nodejs 12 or higher, then you may change your Quokka config to switch to native ECMAScript modules:

{
  ...
  "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.

Auto Log

Quokka ‘Pro’ allows users to change the behavior of Quokka to use Show Value to automatically show the runtime value for every line of code. This behavior can be changed after starting Quokka using the Toggle Auto Log command.

By default, this behavior is disabled but may be changed using the autoLog configuration setting:

{
  ...
  "autoLog": true
}

Logging Limits

By default, Quokka limits how many runtime values are logged for a specific piece of code (e.g. selected variable, or specific use of console.log) to no more than 100 times. You may change this behavior with the logLimit setting:

{
  ...
  "logLimit": 200
}

Windows Subsystem for Linux (WSL)

For Microsoft Windows environments, Quokka can be configured to run using WSL. WSL1 can be used with any editor while WS2 is only supported in VS Code. To find out which version you are using, run the terminal command wsl --list --verbose.

WSL 2

WSL2 is only supported if you use VS Code. You must first install Microsoft’s VS Code Remote WSL extension. Quokka will automatically use WSL2 when a remote WSL session is available.

There are two ways to start a VS Code WSL session:

  1. Open a WSL terminal for your installed Linux distribution and type code .
  2. Start VS Code, Press Ctrl+Shift+P and select Remote-WSL: New Window

After starting a remote WSL session, you must install the Quokka extension for your WSL distribution from the Extensions view. If you have a Quokka PRO license then you will also need to apply your license to your remote WSL distribution.

Please note that your Quokka global settings are not shared between your main desktop and your WSL distribution.

WSL 1

This configuration option is only available for your global Quokka config.json file. To use WSL, you must set useWsl to true, for example:

{
    "useWsl": true
}

This setting is ignored on non-Windows environments. If configuring a custom version of node, the path must refer to a version of node on your Linux installation.

Plugins

If you want to extend Quokka.js default runtime, you may use the plugins setting:

{
  "plugins": [
    "./my-plugin",
    "dotenv-quokka-plugin"
  ]
}

Note that this may either install node modules plugins locally to your project or to the global Quokka folder, if you don’t like to pollute your project’s node modules. For example, to install the dotenv-quokka-plugin plugin to the global Quokka folder, you may run

cd ~/.quokka
npm install dotenv-quokka-plugin

You may find out how to write a Quokka.js plugin in the Extensibility docs section.

Notable plugins

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
}

Show Value on Selection

Quokka ‘Pro’ can show the runtime value of an expression when an expression is selected in your editor. To enable the feature you may use the showValueOnSelection setting (off by default).

{
  "showValueOnSelection": true
}

Show All Selected Values

By default, Quokka ‘Pro’ shows only the runtime value for one last selected expression or one last Show Value command usage. You may set the showSingleInlineValue setting to false to turn this behavior off and display multiple values. The setting is only available for VSCode and JetBrains IDEs.

{
  "showSingleInlineValue": false
}

Resolve Getters

By default, Quokka will not resolve getters when showing runtime values. This is because getters may contain executable code and if Quokka resolves them when showing a runtime value then your program execution flow may change. You may change this behavior by setting resolveGetters to true.

{
  "resolveGetters": true
}

JetBrains Editor Scratch files

By default, when using a JetBrains editor, Quokka will automatically start on any JavaScript/TypeScript scratch file when it is first opened. This behavior can be disabled by adding a Global Quokka configuration setting scratchAutoStart with a value of false.

{
  "scratchAutoStart": false
}

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

Create React App

If your project uses create-react-app, Quokka will automatically configure itself to launch in an environment that is very similar the enviornment that jest uses when it runs your create-react-app tests.

If you need to render components into the DOM, please refer to the create-react-app section of our How does Quokka work? documentation.

When using create-react-app Quokka’s configuration will be set to:

{
  "plugins": ["jsdom-quokka-plugin"],
  "babel": {
    "ts": true,
    "presets": ["react-app"]
  }
}

You may disable Quokka’s automatic configuration for create-react-app projects by adding an autoDetect Quokka setting with a value of false as shown below:

{
  "autoDetect": false
}