RunKit - Script Runner for VS Code

A powerful VS Code extension for managing and running Angular applications, libraries, and custom commands. Perfect for monorepo workflows and library development.

✨ Key Features

🚀 Run & manage applications - Start/stop/restart apps with one click
📦 Library development - Build, watch, copy, and link Angular libraries
⚡ Parallel builds - Build multiple libraries simultaneously
🔗 Advanced linking - Link libraries to apps or other libraries
💻 Custom commands - Run saved terminal commands with dynamic paths
🎯 Smart UI - Context-aware actions, visual indicators, inline buttons

🚀 Quick Start

Create a config.json file (see examples below)
Click settings icon in RunKit sidebar → Import Configuration
Start using:
- Click ▶️ to run applications
- Click 🚀 to build & copy libraries
- Click 🔗 to link libraries
- Click ▶️ to run custom commands

🧩 Zed Editor support (portable)

Zed can't run VS Code extensions directly, but you can use a Zed task runner version of RunKit included in this repo:

Copy .zed/runkit.json.example → .zed/runkit.json and edit paths/commands.
In Zed, run Tasks → Spawn and choose a RunKit: task.

Notes:

The Zed version runs in the integrated terminal and uses interactive CLI pickers (since Zed tasks don't support native pick-lists yet).
VS Code–specific UI features (activity bar tree views, inline buttons, decorations) are not replicated in Zed.

📝 Configuration Examples

Minimal Example

{
  "Command": {
    "Check_Version": {
      "directory_location": "${workspaceFolder}",
      "command": "npm --version"
    }
  },
  "Application": {
    "MyApp": {
      "directory_location": "/path/to/my-app",
      "runCommand": "ng serve --port=4200"
    }
  },
  "Library": {
    "SharedLib": {
      "directory_location": "/path/to/shared-lib",
      "libPath": "node_modules/@my/shared-lib",
      "linkPath": "/path/to/shared-lib/dist",
      "libName": "@my/shared-lib"
    }
  }
}

Dynamic Paths Example

Use dynamic variables in directory_location for workspace-relative commands:

{
  "Command": {
    "Build_Current": {
      "directory_location": "${workspaceFolder}",
      "command": "npm run build",
      "icon": "tools"
    },
    "Test_Current": {
      "directory_location": "${workspaceFolder}",
      "command": "npm test",
      "icon": "beaker"
    }
  }
}

Merge Request Example

{
  "MergeRequest": {
    "jiraBaseUrl": "https://jira.com/browse"
  }
}

Supported Variables:

${workspaceFolder} - Root folder of current workspace
${workspaceRoot} - Alias for workspaceFolder
${cwd} - Current working directory (same as workspaceFolder)

Use Case: When you have multiple workspace instances open, ${workspaceFolder} resolves to the active workspace, allowing the same command to work across different projects.

Custom Icons: Commands support custom VS Code codicons. Popular choices:

beaker - Testing commands
tools - Build commands
rocket - Deployment
database - Database operations
bug - Debugging
package - Package management
Browse all icons: VS Code Icon Reference

📚 Configuration Reference

Command

Field	Required	Description	Example
`directory_location`	✅	Working directory (supports `${workspaceFolder}`)	`"${workspaceFolder}"` or `"/path/to/dir"`
`command`	✅	Shell command to execute	`"npm test"`
`icon`	❌	VS Code icon name (codicon)	`"beaker"`, `"tools"`, `"rocket"`

MergeRequest

Field	Required	Description	Example
`jiraBaseUrl`	❌	Jira browse base URL for ticket links in MR output	`"https://jira.com/browse"`

Application

Field	Required	Description	Example
`directory_location`	✅	Path to application directory	`"/path/to/my-app"`
`runCommand`	✅	Command to run the application	`"ng serve --port=4200"`
`main-branch`	❌*	Base branch used by MR command	`"dev"`
`linkPath`	❌	Path for npm link (defaults to directory_location)	`"/path/to/my-app"`
`envPath`	❌	Path to environment file for quick access	`"src/environments/environment.local.ts"`

Library

Field	Required	Description	Example
`directory_location`	✅	Path to library directory	`"/path/to/my-lib"`
`libPath`	✅	Target path in node_modules	`"node_modules/@my/library"`
`main-branch`	❌*	Base branch used by MR command	`"master"`
`linkPath`	❌	Path for npm link (usually dist folder)	`"/path/to/my-lib/dist"`
`libName`	❌	NPM package name for linking	`"@my/library"`
`build-assets`	❌	Custom command for building assets	`"npm run build-assets"`
`custom-build-watch`	❌	Custom watch command (defaults to `npx ng build --watch`)	`"npm run watch"` or `"vite build --watch"`

* Required only for RunKit: Create Merge Requests. Repositories without main-branch are excluded from MR selection.

🎯 Common Workflows

Running Applications

1. Click ▶️ play button next to app
2. App runs in integrated terminal
3. Click ⏹️ to stop, or 🔄 to restart

Building & Copying Libraries

Single library:
1. Click 🚀 rocket icon on library
2. Select destinations (use Space to multi-select)
3. Library builds once, copies to all destinations

Multiple libraries (parallel):
1. Click 🚀 in Libraries toolbar
2. Select multiple source libraries
3. Select multiple destinations
4. Each library builds in parallel ⚡

Linking Libraries

Single library:
1. Right-click library → "NPM Link"
2. Select applications to link to
3. Library links globally, then to each app

Multiple libraries:
1. Click 🔗 in Libraries toolbar
2. Select multiple libraries
3. Select multiple destinations (apps/libs)
4. All libraries link to all destinations

Creating Merge Requests

1. Run "RunKit: Create Merge Requests" from Command Palette
2. Enter branch name (example: feature/pp-123123)
3. Select repositories (only items with main-branch are shown)
4. RunKit opens terminal and runs git + glab automation
5. Output includes:
   - Hi team please review
   - Ticket: <configured jiraBaseUrl>/<TICKET> (or plain ticket if not configured)
   - <RepoName>: <MR_LINK>

Prerequisites:

git installed
glab installed and authenticated (glab auth login)

🎨 Link Visualization: After linking, expand an application to see all libraries linked to it, or expand a library to see where it's linked. Color-coded icons make relationships easy to identify at a glance. The description shows the link count (e.g., "2 linked").

Custom Commands

1. Configure commands with ${workspaceFolder}
2. Click ▶️ next to command
3. Runs in the current workspace context

💡 Tips

Multi-select: Use Space key in selection dialogs
Watch mode: Auto-rebuild libraries during development (👁️ icon)
Custom watch: Use custom-build-watch for non-Angular libraries (React, Vite, etc.)
Library chains: Link library A → library B → app
Parallel builds: Build multiple libraries simultaneously for speed
Dynamic paths: Use ${workspaceFolder} for workspace-relative commands
Command palette: Cmd+Shift+P → type "RunKit"
Link visualization: Expand apps to see linked libraries, or expand libraries to see destinations 🎨

License

MIT

RunKit - Script Runner

Sabik Abtahee