Quokka.js supports 3 sources of configuration:

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 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, and the inline settings have the highest precedence and will override any values set with other methods.

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

package.json config

To add quokka configuration options for your project, you may add the quokka object property and list the settings under it, 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 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
}

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 (or the global config folder’s node_modules).

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

TypeScript

If you are running an quokka that doesn’t import any other TypeScript files, you don’t need any configuration. You may still import other JavaScript files and node modules.

If you want to import other TypeScript files, you will need to install npm install ts-node in your project’s folder or in the global config folder.

If you are using paths in your tsconfig.json file, you will need install npm install tsconfig-paths to the same location where you have installed ts-node.

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 the order of the priority):

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

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

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

Plugins

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

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

Note that 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 jsdom-quokka-plugin plugin to the global quokka folder, you may run

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

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

Notable plugins

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": "/Users/username/.nvm/versions/node/v7.7.1/bin/node"
}

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 a src folder in your project, and components subfolder it 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 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.

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
}