kodall-deploy-vscode

A lightweight Visual Studio Code extension for Kodall Deploy to package, build, deploy, monitor, and roll back web applications directly from your editor with multi-environment management, live health checks, and zero workspace pollution.
Official Documentation
Explore the complete guides and API reference at docs.kodall.com:
Table of Contents
- Features
- Requirements & Installation
- Quick Start
- Sidebar Views
- Local Development Proxy
- Smart Build Execution & Stale Build Detection
- Deployment History & Instant Rollback
- Command Palette Reference
- Extension Settings
- Configuration Reference (
kodall-webapp.config.json)
- Development & Contributing
- License
Features
- Workspace Auto-Detection: Activates automatically when
kodall-deploy is detected in package.json dependencies or when kodall-webapp.config.json is present.
- Multi-Environment Sidebar: Live HTTP availability, status codes, and latency indicators. Visual indicators for active dev proxy (
▶) and default deploy target (★). Inline action buttons for Deploy, Dry Run, Open WebApp, Clone, Edit, and Set Default.
- Decoupled Dev Proxy & Local Isolation: Switch active proxy target instances on the fly without workspace pollution. Local overrides are saved to untracked
.kodall-deploy/active-env, keeping kodall-webapp.config.json clean in source control. Clear local overrides at any time to fall back to configuration defaults.
- Smart Package Manager Resolution: Auto-detects
pnpm, yarn, bun, or npm from workspace lockfiles (pnpm-lock.yaml, yarn.lock, bun.lockb, package-lock.json) to execute build and CLI commands without configuration drift.
- Custom Build Commands & Stale Build Detection: Configure root and per-environment
build_command. Inspects source files and flags when code was modified after the last build, offering one-click "Build & Deploy" using the detected package manager.
- Multi-Framework Live Dev Proxy Adapters: Ready-to-use proxy configurations and copyable snippets for Vite (
kodallProxy()), Nuxt 3/4 (kodallProxyNuxt()), Next.js App Router (createNextProxyHandler), Next.js Pages Router (getNextRewrites), Angular CLI (getAngularProxy()), and Webpack (getDevProxy()).
- Remote Server History & 1-Click Rollback: Automatically queries remote
web_app_log via /rest/fetch and merges with local deployment logs. Roll back instantly to any historical storage build with zero re-upload.
- Interactive Visual Wizards: Add, clone, and edit environments or configure global webapp metadata (
web_app_name, web_app_path, dist_path, build_command) directly from VS Code modals.
- Secure Authentication: Supports API Key tokens, VS Code SecretStorage (
context.secrets), and session cookie authentication with CSRF tokens against Kodall instances.
- CI/CD Pipeline Generator: Generate ready-to-run automated pipeline files for GitHub Actions, GitLab CI, Bitbucket Pipelines, Azure DevOps, Jenkins, and CircleCI.
- JSON Schema IntelliSense: Built-in schema validation, autocomplete, and documentation tooltips for
kodall-webapp.config.json including build_command and default_proxy_env.
- Status Bar Integration: Displays active default target environment and local proxy override badges (
Kodall: [env] (proxy: [target])) with instant quick action picker.
↑ back to top
Requirements & Installation
The extension integrates with the kodall-deploy CLI in your workspace:
Global CLI
npm install -g kodall-deploy
In Project (devDependency)
npm install -D kodall-deploy
Works automatically via local node_modules/.bin/kodall-deploy or fallback npx kodall-deploy.
↑ back to top
Quick Start
1. Open a Kodall Project
Open any web application workspace that includes kodall-deploy in package.json or contains a kodall-webapp.config.json file. The Kodall Deploy icon will automatically appear in the VS Code Activity Bar.
2. Initialize Configuration (if new project)
If no configuration file exists, click Initialize Configuration in the sidebar welcome view to launch the interactive framework detection wizard, or run:
npx kodall-deploy --init
3. Build or Deploy
- Click the Play button on any environment in the Environments view.
- Or run
Kodall Deploy: Deploy (Default Environment) from the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
- Or click the Kodall status bar item at the bottom of VS Code.
↑ back to top
The extension contributes a dedicated Activity Bar container (kodall-deploy-sidebar) with four views:
Environments View
Displays all configured target instances (dev, staging, prod) with live health badges:
- Status Badges: Shows HTTP response status and ping latency in milliseconds. Active dev proxy targets are badged with
▶, and default deploy targets are badged with ★.
- Inline Actions:
- Deploy: Deploy directly to target environment.
- Dry Run: Validate build and test authentication without mutating files.
- Open Live Web App: Launch deployed web app URL in default browser.
- Set Default: Set environment as active default deployment target in configuration.
- Clone Environment: Duplicate environment with custom overrides.
- Edit Environment: Modify instance URL, type, build command, or keys.
- Remove Environment: Remove environment from configuration.
Quick Actions View
Structured action tree organized into four operational groups:
- Core Actions: Deploy Default, Deploy to Environment, Dry Run, Rollback Deployment, Check Remote Health & Status.
- Dev Proxy & Local Development: Switch Active Dev Proxy Target, Clear Active Proxy Target Override, Configure Dev Proxy Paths, Dev Proxy Snippets & Info.
- Advanced Deployment: Deploy by Category Type (
prod, staging, dev), Deploy to All Environments, Build Web Application (CLI), Run Project Build.
- Configuration & Setup: Configure WebApp (Name, Path, Dist, Build Command), Open Configuration File, Re-initialize Configuration Wizard, Generate CI/CD Pipeline.
Deployment History & Rollback View
- Fetches remote
web_app_log records from the active Kodall instance via /rest/fetch and merges with .kodall-deploy/history.json.
- Displays historical build IDs, relative timestamps, duration, author, and SHA256 hashes.
- Hover over any record and click Rollback to instantly revert the active deployment to that specific build ID without rebuilding or re-uploading.
Documentation & Resources View
Direct shortcuts to the official SDK overview guide (https://docs.kodall.com/sdk/web-app-deployment/overview), the GitHub repository, and the issue tracker.
↑ back to top
Local Development Proxy
Route API requests (/auth, /rest, /storage) from your local frontend dev server directly to your active remote Kodall instance with zero CORS issues.
Decoupled Active Proxy Isolation
Starting in CLI v1.2.3+, switching dev proxy targets via kodall.switchEnv (kodall-deploy use <env>) writes to local untracked .kodall-deploy/active-env.
- Zero Git Pollution: Your team's shared
kodall-webapp.config.json stays clean in source control.
- Independent Targeting: Point your dev proxy to a feature test instance or local sandbox without altering production or staging deploy targets (
default_env).
- Clear Anytime: Run
kodall.clearActiveEnv (kodall-deploy --clear-active) to remove the local override and fall back to default_proxy_env or default_env.
1. Vite (vite.config.ts)
import { defineConfig } from "vite";
import { kodallProxy } from "@kodall/kodall-deploy/vite";
export default defineConfig({
plugins: [kodallProxy()],
});
2. Nuxt 3 / Nuxt 4 (nuxt.config.ts)
import { defineNuxtConfig } from "nuxt/config";
import { kodallProxyNuxt } from "@kodall/kodall-deploy";
export default defineNuxtConfig({
ssr: false,
modules: [kodallProxyNuxt()],
});
3. Next.js App Router (src/app/api/[...kodall]/route.ts)
import { createNextProxyHandler } from "@kodall/kodall-deploy";
const handler = createNextProxyHandler();
export { handler as GET, handler as POST, handler as PUT, handler as DELETE, handler as PATCH };
4. Next.js Pages Router (next.config.mjs)
import { getNextRewrites } from "@kodall/kodall-deploy";
/** @type {import('next').NextConfig} */
const nextConfig = {
output: "export",
async rewrites() {
return getNextRewrites();
},
};
export default nextConfig;
5. Angular CLI (proxy.conf.js)
const { getAngularProxy } = require("@kodall/kodall-deploy");
module.exports = getAngularProxy();
6. Webpack DevServer (webpack.config.js)
const { getDevProxy } = require("@kodall/kodall-deploy");
module.exports = {
devServer: {
proxy: getDevProxy(),
},
};
Tip: Switch target instances instantly via the status bar or the Kodall Deploy: Switch Active Dev Proxy Target (Local Override)... command.
↑ back to top
Smart Build Execution & Stale Build Detection
Before initiating any deployment, the extension automatically inspects the workspace:
- Package Manager Resolution: Automatically detects whether your workspace uses
pnpm, bun, yarn, or npm by inspecting lockfiles (pnpm-lock.yaml, yarn.lock, bun.lockb, package-lock.json).
- Build Command Resolution: Resolves custom
build_command overrides defined at the environment or root level of kodall-webapp.config.json, or detects the framework-specific build script (build, generate, etc.).
- Freshness Verification: Compares source file timestamps (
.ts, .js, .vue, .svelte, .jsx, .tsx, .html, .css, etc.) against dist/index.html.
- Prompted Rebuild: If source files were modified after the last build, prompts you to choose "Run Build & Deploy", "Deploy As Is", or "Cancel".
- Standalone Execution: You can trigger
Kodall Deploy: Build Web Application (CLI) at any time from the sidebar or Command Palette.
↑ back to top
Deployment History & Instant Rollback
Every deployment is tracked in the Kodall deployment log on the remote server (web_app_log) and merged with .kodall-deploy/history.json locally:
- View all previous deployment records including timestamp, target environment, storage build ID, duration, and triggering user.
- Roll back instantly by selecting Rollback Deployment... from Quick Actions or clicking the rollback button next to any historical entry in the Deployment History view.
- Remote server rollbacks re-point the live web application entity to the specified historical storage archive with zero upload latency.
↑ back to top
Command Palette Reference
All commands are available in the Command Palette (Ctrl+Shift+P / Cmd+Shift+P):
| Command |
Title |
Description |
kodall.deploy |
Deploy (Default Environment) |
Deploy to active default environment target |
kodall.deployEnv |
Deploy to Environment... |
Pick specific target environment from QuickPick |
kodall.deployType |
Deploy by Category Type... |
Batch deploy all environments matching type (dev, staging, prod) |
kodall.deployAll |
Deploy to All Environments |
Sequentially deploy to all configured environments |
kodall.dryRun |
Dry Run (Test Config & Auth) |
Test configuration and authentication without mutating |
kodall.rollback |
Rollback Deployment... |
Interactive rollback wizard (1 step back, history picker, or manual ID) |
kodall.status |
Check Remote Health & Status |
Ping all instances and report latency & version |
kodall.switchEnv |
Switch Active Dev Proxy Target (Local Override)... |
Set local proxy target in .kodall-deploy/active-env without dirtying git |
kodall.clearActiveEnv |
Clear Active Dev Proxy Target Override |
Remove .kodall-deploy/active-env and revert proxy target to config default |
kodall.configureProxyPaths |
Configure Dev Proxy Paths... |
Edit global or per-env proxy path routes (/auth, /rest, /storage) |
kodall.showProxyConfig |
Show Dev Proxy Configuration & Snippets |
View active proxy endpoints and copy Vite/Nuxt/Next/Angular/Webpack snippets |
kodall.loginEnv |
Authenticate / Login to Environment... |
Log in with credentials or save API key in SecretStorage |
kodall.init |
Initialize Configuration |
Launch interactive framework detection & config wizard |
kodall.initCI |
Generate CI/CD Pipeline Workflow |
Generate pipeline templates (GitHub, GitLab, Bitbucket, Azure, etc.) |
kodall.addEnv |
Add Environment |
Interactively register a new deployment environment |
kodall.cloneEnv |
Clone Environment... |
Duplicate an existing environment configuration |
kodall.editEnv |
Edit Environment... |
Modify instance URL, type, app name, build command, or API key |
kodall.editProjectSettings |
Configure WebApp (Name, Path, Dist, Build Command)... |
Interactive wizard to update global webapp metadata |
kodall.setDefaultEnv |
Set Default Deploy Environment (Config) |
Change active default deploy environment target in configuration |
kodall.removeEnv |
Remove Environment |
Remove an environment from configuration |
kodall.openConfigFile |
Open Configuration File |
Open kodall-webapp.config.json in editor |
kodall.openWebAppUrl |
Open Live Web App in Browser |
Open deployed web app URL in default browser |
kodall.copyUrl |
Copy Instance URL |
Copy instance URL to clipboard |
kodall.refresh |
Refresh Environments & History |
Re-read configurations and query remote logs |
kodall.clearHistory |
Clear Deployment History |
Reset local deployment history records |
kodall.build |
Build Web Application (CLI) |
Execute kodall-deploy build [env] with detected package manager |
kodall.runBuild |
Run Project Build (Package Manager) |
Trigger detected package manager build script in integrated terminal |
↑ back to top
Extension Settings
Configure the extension in VS Code Settings (Ctrl+, / Cmd+, → search for kodallDeploy):
| Setting |
Type |
Default |
Description |
kodallDeploy.alwaysShow |
boolean |
false |
Always show the Kodall Deploy sidebar tab even if package.json does not declare kodall-deploy. |
kodallDeploy.autoCheckHealthOnLoad |
boolean |
true |
Automatically ping and check instance health when opening the workspace. |
kodallDeploy.cliBinary |
string |
"" |
Custom command or path to run kodall-deploy CLI (defaults to local node_modules or npx kodall-deploy). |
↑ back to top
Configuration Reference (kodall-webapp.config.json)
The extension reads and manages kodall-webapp.config.json in your workspace root:
{
"web_app_name": "my-portal",
"web_app_path": "/my-portal",
"dist_path": "./dist",
"build_command": "build",
"default_env": "dev",
"default_proxy_env": "dev",
"proxy_paths": [
"/auth",
"/rest",
"/storage"
],
"environments": {
"dev": {
"type": "dev",
"instance": "https://dev.instance.kodall.ro"
},
"staging": {
"type": "staging",
"instance": "https://staging.instance.kodall.ro",
"build_command": "build:staging",
"api_key": "staging-secret-api-key"
},
"prod": {
"type": "prod",
"instance": "https://app.kodall.ro",
"build_command": "build:prod",
"api_key": "prod-secret-api-key"
}
}
}
Configuration Fields
| Field |
Type |
Description |
Required |
web_app_name |
string |
WebApp entity name in Kodall. |
Yes |
web_app_path |
string |
URL route where web app is served (auto-prefixed with /). |
Yes |
dist_path |
string |
Local folder containing build assets. Must contain index.html. |
Optional (default: ./dist) |
build_command |
string |
Clean package.json script reference (e.g. "build", "generate") or custom command. Package manager is auto-detected. |
Optional |
default_env |
string |
Default deployment environment target if --env is omitted. |
Optional (default: dev) |
default_proxy_env |
string |
Default dev proxy target environment if .kodall-deploy/active-env is unset. |
Optional |
proxy_paths |
string[] |
Array of route prefixes forwarded to Kodall instance (["/auth", "/rest", "/storage"]). |
Optional |
environments |
object |
Map of target environment definitions (dev, staging, prod, etc.). |
Yes |
environments[name].instance |
string |
Base URL of Kodall instance (e.g. https://app.domain.com). |
Yes |
environments[name].type |
string |
Category of environment: "dev", "staging", "prod", "test". |
Optional |
environments[name].api_key |
string |
API Key for authentication (bypasses username and password prompt). |
Optional |
environments[name].web_app_path |
string |
Environment-specific URL route override. |
Optional |
environments[name].dist_path |
string |
Environment-specific build directory override. |
Optional |
environments[name].build_command |
string |
Environment-specific build script reference (inherits root build_command if omitted). |
Optional |
environments[name].proxy_paths |
string[] |
Environment-specific proxy path overrides. |
Optional |
JSON Schema Autocomplete & Validation
The extension bundles schemas/kodall-webapp.schema.json, providing automatic validation, autocompletion, and hover documentation whenever you edit kodall-webapp.config.json or config_web_app.json.
↑ back to top
Development & Contributing
# 1. Clone repository
git clone https://github.com/kodall-app/kodall-deploy.git
# 2. Install dependencies
npm install
# 3. Build bundle
npm run build
# 4. Typecheck
npm run typecheck
# 5. Run & Debug
# Press F5 in VS Code to launch an Extension Development Host window.
↑ back to top
License
MIT
| |