Quokka supports 4 sources of configuration (in addition to editor extension UI related settings):
- global config file,
- project’s
package.json
file, - project’s
.quokka
file, - inline code in your Quokka file.
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):
- local project’s
node_modules
, - global config folder’s
node_modules
, - editor’s embedded TypeScript version (if any),
- 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.
For a selected variable, or specific use of console.log
the log limit is 100 values. You may change this behavior with the logLimit
setting, for example:
{
...
"logLimit": 200
}
Default overall limit for all code logs is 1000 values. You may change this behavior with the maxConsoleMessages
setting, for example:
{
...
"maxConsoleMessages": 2000
}
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:
- Open a WSL terminal for your installed Linux distribution and type
code .
- Start VS Code, Press
Ctrl+Shift+P
and selectRemote-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
- Plugin to load
.env
environment variables. - Plugin to automatically import
reflect-metadata
for Angular projects. - Plugin for providing module import aliases.
- Plugin for providing module import aliases via Babel.
- Plugin for resolving
node_module
imports from subdirectories (great for monorepo kind of scenarios). - Plugin to run any command before each Quokka file execution.
- Plugin to load jQuery before each Quokka file execution.
- Plugin for exploring API endpoints to identify function signatures and API property types via signet.
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
}