TypeScript

Most times if you are using TypeScript, no configuration is required. By default, Quokka uses bundled versions of ts-node with swc to run your TypeScript files. However, if either tsx or @swc-node/register is available from your project or ~/.quokka folder, they will be used instead (details below).

Compiler / Runtime Selection

Quokka supports three TypeScript packages: tsx, @swc-node/register, and ts-node. Quokka will search for these packages first in your project folder, then in your ~/.quokka folder, and finally in its own bundled installation location. It will use the first tool it finds during this search. If multiple packages are found in a location, the order of preference is tsx, then @swc-node/register, then ts-node.

To use tsx or @swc-node/register as your global default, navigate to your ~/.quokka folder and run:

• tsx: npm install tsx
• swc: npm install @swc-node/register

You can override which compiler is used by specifying it using the ts.compiler setting, e.g.:

{
  "ts": {
    "compiler": "@swc-node/register"
  }
}

When a specific compiler is configured in this way, Quokka will not fall back to other compilers if the specified one is not found. Valid values are tsx, @swc-node/register, swc (shorthand for the previous value), and ts-node.

Multiple compilers can be specified, e.g.:

{
  "ts": {
    "compiler": ["swc", "tsx"]
  }
}

The above configuration example effectively means:

1. Use @swc-node/register from your project’s node_modules folder
2. Otherwise, use tsx from your project’s node_modules folder
3. Otherwise, use @swc-node/register from your ~/.quokka/node_modules folder
4. Otherwise, Use tsx from your ~/.quokka/node_modules folder
5. Otherwise, error out (as neither @swc-node-register or tsx are bundled with Quokka)

While tsx and @swc-node/register are effectively self-contained, ts-node works in conjunction with other packages (described below) that can be further configured or replaced.

Overriding Quokka’s Built-In TypeScript Dependencies (ts-node only)

Quokka is installed with four dependencies that can be used 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. Note: this is not @swc-node/register)
• 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 (ts-node only)

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 are using ts-node and need 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",
            ...
        }
    }
}

tsx and @swc-node/register register will use your project’s local tsconfig.json if present. In some cases, @swc-node/register will not work unless a project-level tsconfig.json is present.

Using SWC for dependency compilation (ts-node only)

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