Introduction

Quokka.js is a rapid prototyping playground in your editor, with access to your project’s files, inline reporting, code coverage and rich output formatting.

Quokka.js is brought to you by the Wallaby.js team and is built on top of the same technology used in the Wallaby.js Core. If you like what you see in Quokka.js and would like the same live features for your unit tests and all files of your project, and a lot more, then definitely check out Wallaby.js.

Getting started

To get started with quokka.js in VS Code, install the extension first by clicking on the Extensions icon in the Activity Bar on the side of VS Code and searching for Quokka. Note that Quokka requires VS Code version 1.10.0 or higher.

To get started with quokka.js in JetBrains IDE, install the plugin first by using Settings - Plugins and searching for Quokka.

To get started with quokka.js in Atom, install the package first by using Settings - Install and searching for Quokka, or by running the apm install atom-quokka command.

To get started with quokka.js in Sublime Text, install the package first by using Package Control: Install Package and searching for Quokka.

Once the extension is installed, press Ctrl/Cmd + Shift + P to display the editor’s command palette, and then type Quokka to see the list of the available commands. Select and run the New JavaScript File command.

Once the extension is installed, press Ctrl/Cmd + Shift + P to display the editor’s command palette, and then type Quokka to see the list of the available commands. Select and run the Create JavaScript File command.

Once the extension is installed, press Cmd + Shift + N / Ctrl + Alt + Shift + Insert to create a new Quokka file. You may select any JavaScript file type, ECMAScript 6, TypeScript.

Once the extension is installed, press Ctrl/Cmd + Shift + P to display the editor’s command palette, and then type Quokka to see the list of the available commands. Select and run the New JavaScript File command.

Now you are ready to go, just start typing some code in your editor and see what happens next.

Live Feedback

You may create a new Quokka file, or start Quokka on an existing file. The results of the execution are displayed right in the editor. To see the full execution output, you may view the Quokka Console by invoking the Show Output command or clicking the bottom-right status bar indicator.

You may create a new Quokka file, or start Quokka on an existing file. The results of the execution are displayed right in the editor. To see the full execution output, you may view the Quokka Console by invoking the Show Output command or clicking the bottom-left output panel icon.

You may create a new Quokka file, or start Quokka on an existing file by using the Start Quokka context menu action in any opened file editor (you may also assign some shortcut to the action). The results of the execution are displayed right in the editor. To see the full execution output, you may view the Quokka Console by clicking the bottom-right status bar indicator.

If you create a new Quokka scratch file and want to save it, then you may press F5 to do so. Later on, you may open the file and run Quokka using the Start Quokka context menu action in the opened file editor.

It is recommended to memorize a couple of quokka keyboard shortcuts (you may see them when using the editor’s command palette). This way it’ll be much faster.

To open a new quokka file (Cmd/Ctrl + K, J for JavaScript, or Cmd/Ctrl + K, T for TypeScript), to (re)start it on an existing file (Cmd/Ctrl + K, Q).

Live Logging/Compare

You may use console.log or identifier expressions (i.e. just typing a variable name) to log any values.
You may also use sequence expressions to compare objects:

Note that when using identifier expressions for logging (for example, typing a to see the value of the a variable), you may hit some limits in terms of the number of displayed properties and the logged object traversal depth. In this case, you may use console.log(a) to display objects without the limitations.

Please also note that Boolean, Number and Function data types are not supported when use sequence expressions to compare objects (e.g. obj1, obj2).

Live Code Coverage

Once quokka.js is running, you can see the code coverage in the gutter of your editor. The coverage is live, so you can start changing your code and the coverage will automatically be updated, just as you type.

As you may see, there are various colored squares displayed for each line of your source code.

  • A gray square means that the source line has not been executed.
  • A green square means that the source line has been executed.
  • A yellow square means that the source line has only been partially executed. Quokka supports branch code coverage level, so if a line contains a logical expression or a ternary operator with both covered and uncovered branches, it will be displayed with yellow gutter indicator.
  • A red square means that the source line is the source of an error, or is in the stack of an error.

Value Explorer

Value Explorer allows you to inspect everything that is logged in Quokka with console.log, identifier expressions, live comments, and the Show Value command. Results are displayed in an easy-to-navigate tree view that is updated in realtime as you write your code.

Expression paths and values can be copied using the tree node’s context menu.

Note that while Value Explorer is available for both Community and Pro editions, in Community edition only 2 levels of the explorer’s tree can be expanded.

Auto-Expand Value Explorer Objects

Identifier Expressions and Live Comments can be provided with an additional hint to automatically expand objects when they are logged to Value Explorer. Inserting the special comment /*?+*/ after any expression will expand your object and its properties within the Value Explorer tree.

Use this feature with small- to medium-sized objects when you want to expand all properties in Value Explorer. Having the properties expanded also helps when using the ‘Copy Data’ action on the Value Explorer tree node, because it only copies expanded properties’ data.

Note that automatically expanded objects have the following limitations:

  • Cyclic Depedencies are not automatically expanded
  • Functions are not automatically expanded
  • Strings beyond 8192 characters are not automatically expanded
  • Only the first 100 properties on a single object will be expanded
  • Only the first 100 elements of an array will be expanded
  • Only the first 10 levels of nested properties will be expanded
  • Only the first 5000 properties across all objects will be expanded

VS Code Live Share Integration

When Microsoft’s VS Code plugin for Live Share is installed alongside Quokka, Quokka provides software developers with the ability to interactively collaborate on the same code at the same time. This feature adds a new dimension to real-time instructor-led training as well as interactive prototyping/debugging and works best when guests and host use Live Share’s follow participant command.

How does it work?

When the host and client both have Quokka plugin installed during a Live Share collaboration, when code changes are made and Quokka is running, Quokka will execute the code changes on the host and immediately send the display values to all collaboration participants. Before sharing the Quokka session with clients, the host will be prompted to either Allow or Deny sharing Quokka with the Live Share collaboration.

Members of the Live Share collaboration see the same Quokka display values when they are visible to the host. If the Live Share session is configured to be read-only, only the host can edit code but collaborators will see all of the Quokka execution results. If the Live Share session is editable by other collaborators, as non-host code edits are made, Quokka will evaluate the changes on the host and send the execution results to all collaborators.

Live Comments

While console.log may do the great job for displaying values, sometimes you may need to see the value right in the middle of an expression. For example, given a chain of a.b().c().d(), you may want to inspect the result of a.b().c() before .d() is called.

The most powerful way to log any expression is to use a special comment right after the expression you want to log.

Inserting the special comment /*?*/ after some expression (or just //? after a statement) will log just the value of that expression.

For example,

a.b()/*?*/.c().d()

will output the result of a.b() expression, and

a.b().c().d() /*?*/
// or just
a.b().c().d() //?

will output the result of the full a.b().c().d() expression.

You may also write any JavaScript code right in the comment to shape the output. The code has the access to the $ variable which is the expression that the comment is appended to. The executed code is within a closure, so it also has the access to any objects that you may access from within the current lexical environment.

Note that there’s no constraints in terms of what the comment code can do. For example, the watch comment below is incrementing d.e value, and returning $, which points to the expression that the comment is appended to (a.b).

Also, unlike console logging, the special comment logging has some built-in smarts. For example, when you place the comment after an expression that is a promise, the resolved value of the promise is logged. Similarly, if an expression is an observable, then its values are displayed. So you don’t need to insert a .then function to just inspect the resolved value of the promise or a forEach/subscribe function to inspect the observable values.

Live comment snippet

To save some time on typing the comment when you need it, you may:

Live Value Display

While the Live Comments feature provides an excellent way to log expression values and will keep displaying values when you change your code, sometimes you may want to display or capture expression values without modifying code. The Show Value and Copy Value features allow you to do exactly that.

To use these features, the expression being logged either needs to be selected, or the cursor position needs to be right after the expression when the command is invoked. It works just as if you were inserting a live comment where your cursor is located. After you use Show Value or Copy Value and make changes to your code, the Live Value Display will be removed.

Show Value

If you want to quickly display some expression value, but without modifying your code, Live Value Display allows you to do it with a special command (Show Value command, or with the Cmd + K, V keyboard shortcut).

If you want to quickly display some expression value, but without modifying your code, Live Value Display allows you to do it with a special intention action (Alt+Enter & select the Show Value action).

Copy Value

If you want to copy an expression value to your clipboard without modifying your code, Live Value Display allows you to do it with a special command (Show Value command, or with the Cmd + K, X keyboard shortcut).

If you want to copy an expression value to your clipboard without modifying your code, Live Value Display allows you to do it with a special intention action (Alt+Enter & select the Copy Value action).

Project Files Import

Quokka ‘Community’ edition allows you to import any locally installed node modules to a Quokka file. In addition to that, Quokka ‘Pro’ edition also allows to import any files from your project:

  • with Babel or TypeScript compilation if required;
  • also Quokka will watch project files for changes and automatically update when dependent files change.

Quick Package Install

The feature allows to quickly install any node package, via npm or yarn, without switching away from your editor, even without having to type the package name - there is enough information in your code already. The package may be installed just for the active quokka session, so that when you are just playing with things, your node_modules folder is not trashed. Having said that, you may also target the project’s node_modules, if you want to do it.

You may install missing packages via intention actions (Alt+Enter), or via the links in the quokka output.

You may install missing packages by using the hover message, or with the Cmd + K, I keyboard shortcut (whenever there’s a missing package), via command palette (Quokka.js: Install Missing Package ... commands), or via the links in the quokka output.

By default quokka is using the npm install {packageName} command. You may change it to yarn add {packageName} by setting the installPackageCommand value in your quokka config:

{
    "installPackageCommand": "yarn add {packageName}"
}

Live Performance Testing

The feature allows to quickly see how various parts of your code perform. It can be very helpful for identifying possible bottlenecks in your app and for doing the performance optimization, or just for experimenting to see how different things perform.

Inserting the special comment /*?.*/ after any expression will report how much time it took to execute the expression.

Adding the comment to an expression that gets executed multiple times, for example inside a loop, will make the tool to display total execution time, average execution time (total execution time divided by number of times the expression had been executed), minimum and maximum execution time.

You may also use the execution time reporting comment and add to it any expression that you may use in live comments to display both an expression execution time and execution result.

For example,

a() //?. $

displays a() execution time and result.

Run on Save/Run Once

Choose how and when quokka should run on your files. In addition to the community edition’s Automatic mode, you can start quokka to Run on Save or to just Run Once. This feature is helpful for using quokka to run slow-running scripts, or scripts with side-effects.

The Run on Save and Run Once actions are available along-side other Quokka commands, in your IDE’s list of commands. If you use these commands often, you can improve your productivity by adding key-bindings.

Runtime

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

To simulate browser environment, you may use this plugin.

By default Quokka is using esm module for JavaScript, so ES imports and top level await are supported with zero configuration.

Configuration

Quokka.js doesn’t need any configuration by default. It will run your code using your system’s node.js. It may also run your TypeScript code without any configuration, if you are not importing any external TypeScript modules.

If you would like to use Babel/React JSX, or to import other TypeScript files from your project in your Quokka file, or to override tsconfig.json settings, you may configure quokka.js.

If you are using VS Code, you can override our editor display settings with VS Code User Setting overrides. You can view the overridable settings in the VS Code Settings editor under Settings -> Extensions -> Quokka.

If you are using VS Code, you can override the coverage indicator colors in the VS Code user settings (settings.json file). The snippet below shows the config with Quokka’s default colors.

{
    ...

    "quokka.colors": {
        "covered": "#62b455",
        "errorPath": "#ffa0a0",
        "errorSource": "#fe536a",
        "notCovered": "#cccccc",
        "partiallyCovered": "#d2a032"
    }
}

If you are using VS Code, you can change your Quokka console output to compact mode by updating your VS Code setting quokka.compactMessageOutput to true.

Plugins

Quokka.js supports the plugins setting, that allows to specify a file or a node module with some code to execute at various stages of the quokka.js code running workflow. You may also find more information about how to write quokka plugin in the Extensibility docs section.

Examples

Because Quokka.js runs your code using node.js, sometimes a little more configuration is required to match your project’s runtime configuration. If the examples below aren’t relevant for your project, search our support repository for an existing configuration.

Questions and issues

If you found an issue, please report it in our support repository.