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 .babelrc 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, 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 the .babelrc file or want to completely override the settings in your .babelrc file, 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.

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

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.

Community 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:

{
    "node": "/path/to/your/node"
}