Quokka Alias

quokka-alias is a Visual Studio Code extension that automatically updates your .quokka file with aliases used in the imports of the current TypeScript file. It reads aliases from the nearest tsconfig.json file in the project directory tree and adds them to the .quokka file.

Example:

import { foo } from '@/bar';
// ...

The .quokka file, after running the command:

{
  "aliases": {
    "@/bar": "./bar"
  }
}

Features

• Automatically include aliases from imports in the .quokka file based on your tsconfig.json file.
• Compatible with TypeScript files.

Getting Started

• Install the Quokka.js extension if you haven't already.
• Install the alias-quokka-plugin if you haven't already.
  • yarn add -D alias-quokka-plugin
  • pnpm add -D alias-quokka-plugin
  • npm install --save-dev alias-quokka-plugin
• Make sure you have a .quokka file and a tsconfig.json file higher up in the project directory tree than the current file and that the .quokka file includes the alias-quokka-plugin plugin.
• Install the quokka-alias extension (this extension).

Your .quokka file should look something like this:

{
  "plugins": [
    "alias-quokka-plugin",
    // Other plugins (optional)
    ],
  "alias": {
    // Your existing aliases (optional)
  },
  // Other settings (optional)
}

Usage

To use the command, make sure the typescript file is the currently active file and run the command Include aliases from imports in the current file in .quokka from the command palette. After running the command, the .quokka file will be updated with the aliases used in the current file based on the tsconfig.json.

Since Quokka needs to restart for this to take effect, you can use the runCommands functionality to simplify this (introduced in VSCode 1.77). If you use the Quokka.js Run once for Current File command, consider replacing your current keybinding with the following by opening the shortcuts JSON using the command: Preferences: Open Keyboard Shortcuts (JSON).

{
  "key": "cmd+r", // replace with your preferred keybinding
  "command": "runCommands",
  "args": {
    "commands": [
      "quokka-alias.include-aliases",
      "quokka.stopCurrent",
      "quokka.runOnce"
    ]
  },
  "when": "editorLangId == typescript"
},

For the interactive Quokka.js mode, you can use this:

{
  "key": "cmd+k shift+i", // replace with your preferred keybinding
  "command": "runCommands",
  "args": {
    "commands": [
      "quokka-alias.include-aliases",
      "quokka.stopCurrent",
      "quokka.makeQuokkaFromExistingFile"
    ]
  },
  "when": "editorLangId == typescript"
},

Alternatively, to set a keybinding for the command alone use the following:

{
  "key": "cmd+k shift+i", // replace with your preferred keybinding
  "command": "quokka-alias.include-aliases",
  "when": "editorLangId == typescript"
},

Examples

Given a tsconfig.json file like this:

{
  "paths": {
    "@/*": [
      "./*",
    ]
  }
}

And a file opened in the editor:

import { foo } from '@/bar';

If your .quokka file initially contains an alias like this:

{
  "aliases": {
    "@/qux": "./qux"
  }
}

After running the command, the .quokka file will be updated with the new alias:

{
  "aliases": {
    "@/bar": "./bar",
    "@/qux": "./qux"
  }
}

Note: The extension does not check for dangling aliases. If an alias is removed or no longer needed, you must manually remove it from the .quokka file.

Requirements

• Quokka.js extension
• A tsconfig.json file higher up in the project directory tree than the current file
• A .quokka in the same directory as the tsconfig.json file

Known Issues

The extension currently only handles the first entry for each alias in the paths object in tsconfig.json. For example:

{
  "paths": {
    "@/*": [
      "./*", // included
      "second_path/*" // not included
    ],
    "src/*": [
      "./src/*", // included
      "second_path/*" // not included
    ]
  }
}

Motivation

The alias-quokka-plugin does not currently handle aliases for some setups. This extension serves as a workaround for that issue.

Release Notes

0.2.0

• Now uses the nearest tsconfig.json and .quokka to resolve aliases
• Now traverses the entire import tree to resolve aliases

0.1.0

• Initial release.
• Adds the command quokka-alias.add-aliases: Include aliases from imports in the current file in .quokka