Kodall
Web App Deployment

kodall-deploy Tooling & CLI

npmGitHub
Developer deployment tooling and CLI reference for hosting static Single Page Applications in Kodall with multi-environment management, auto-detection, and configuration schema.

The @kodall/kodall-deploy CLI tool provides an automated deployment pipeline for hosting any static web application bundle directly inside a Kodall instance. While it natively deploys assets generated by any frontend toolchain or vanilla HTML/JS, it includes dedicated auto-detection adapters and local dev proxy integrations tailored for popular frameworks (such as Nuxt, Vue 3, React, Next.js, Angular, SvelteKit, SolidJS, Remix, and Astro).

Together with the @kodall/kodall-client runtime SDK, your frontend runs on the exact same origin as your backend API, eliminating CORS preflights and enabling automatic session cookie propagation.

Local Dev Proxy Suite

Configure local Vite, Nuxt, Next.js, and Angular dev proxies to forward API calls to your Kodall instance.

CI/CD & Automation

Automate deployments with GitHub Actions, GitLab CI, Bitbucket, instant rollbacks, and the Programmatic TypeScript API.


Installation

Install @kodall/kodall-deploy as a development dependency in your frontend project:

BASH
npm install -D @kodall/kodall-deploy

Quickstart (--init)

Initialize Configuration

Generate a kodall-webapp.config.json configuration file using the interactive setup wizard:

BASH
npx kodall-deploy --init

The wizard prompts you to specify:

  • Application Name: Display name for the web application entity in Kodall (e.g. "Customer Portal").
  • Web App Path: Route prefix where Kodall will serve the application (e.g. "/" or "/portal").
  • Build Directory (dist_path): Output directory containing your compiled static assets (e.g. ./dist, ./out, ./.output/public).
  • Target Environments: Instance URLs and authentication API keys for dev, staging, or prod.

Build Your Application

Compile your production frontend bundle using your framework's build script:

BASH
npm run build

Deploy to Kodall

Upload and activate your application on your target instance:

BASH
# Deploy to default environment
npx kodall-deploy

# Deploy to a specific environment
npx kodall-deploy -e prod

Framework Auto-Detection

@kodall/kodall-deploy automatically detects popular frameworks and configures build output directories without manual path specifications:

FrameworkAuto-Detected Build DirectoryDetection Signature
Vite (Vue, React, SolidJS)./distvite.config.*
Next.js (Static Export)./outnext.config.*
Nuxt 3/4./.output/publicnuxt.config.*
Angular (17+)./dist/<project-name>/browserangular.json
SvelteKit (Adapter Static)./buildsvelte.config.*
Remix (SPA Mode)./build/clientremix.config.* or vite.config.*
Astro (Static)./distastro.config.*
Static HTML./public or ./distindex.html in dedicated output directory
Project Root Deployment Protection: For security reasons, deploying the project or repository root directly (dist_path: ".") is strictly rejected. This prevents inadvertent exposure of source code, .git, .env secrets, and node_modules. Always specify a dedicated build or public folder. Furthermore, sensitive files (.env*, .git, .github, .gitlab, .vscode, node_modules) are automatically excluded by the archiver even if present in the build directory.
Custom build directories can always be specified via the "dist_path" property in kodall-webapp.config.json or by passing the --dist <path> CLI option.

Environment Management Suite

@kodall/kodall-deploy provides dedicated commands to manage environments in kodall-webapp.config.json directly from the terminal:

Switching the Active Default Environment (use)

Switch the active default environment directly or open an interactive selector:

BASH
# Switch default environment directly:
npx kodall-deploy use staging
npx kodall-deploy use dev
npx kodall-deploy use local

# Interactive environment picker:
npx kodall-deploy use

Listing Configured Environments (-l / --list-envs)

Display all configured target instances and their URLs:

BASH
npx kodall-deploy -l

Switching Active Local Dev Proxy (use / switch)

Switch local development proxy target without mutating kodall-webapp.config.json (stored in gitignored .kodall-deploy/active-env):

BASH
npx kodall-deploy use staging
# or interactive selector:
npx kodall-deploy use

Setting Default Deployment Target (--set-default)

Update global default_env in kodall-webapp.config.json for deployment commands:

BASH
npx kodall-deploy --set-default prod

Clearing Local Dev Proxy Override (--clear-active)

Revert local active dev proxy override back to configuration file defaults:

BASH
npx kodall-deploy --clear-active

Adding New Environments (--add-env)

Add a new deployment target directly to kodall-webapp.config.json:

BASH
npx kodall-deploy --add-env uat --instance https://uat.kodall.company.com

Cloning Existing Environments (--clone-env)

Duplicate an existing environment configuration with a new target instance URL:

BASH
npx kodall-deploy --clone-env dev staging --instance https://staging.kodall.company.com

Configuration Reference (kodall-webapp.config.json)

The deployment and proxy behaviors are configured via kodall-webapp.config.json in your project root:

kodall-webapp.config.json
{
  "web_app_name": "Analytics Dashboard",
  "web_app_path": "/",
  "dist_path": "./dist",
  "default_env": "dev",

  "proxy_paths": [
    "/web-assets",
    "/media"
  ],

  "environments": {
    "dev": {
      "type": "dev",
      "instance": "https://dev.kodall.yourcompany.com",
      "api_key": "dev-api-key-here"
    },
    "staging": {
      "type": "staging",
      "instance": "https://staging.kodall.yourcompany.com",
      "api_key": "staging-api-key-here"
    },
    "prod": {
      "type": "prod",
      "instance": "https://kodall.yourcompany.com",
      "api_key": "prod-api-key-here"
    }
  }
}

Configuration Properties

PropertyTypeDefaultDescription
web_app_namestringRequiredDisplay name of the web application in Kodall Cloud Console.
web_app_pathstring"/"URL route prefix assigned to this application (e.g. "/" or "/portal").
dist_pathstringAuto-detectedRelative path to the production build output directory.
default_envstringFirst environmentActive default environment used when -e is omitted.
proxy_pathsstring[][]Additional URL prefixes to proxy to the backend during development.
environmentsobjectRequiredMap of target environments (dev, staging, prod).
environments.<name>.instancestringRequiredBase URL of the target Kodall instance.
environments.<name>.api_keystringundefinedOptional secret API key for deployment authentication.
environments.<name>.proxy_pathsstring[][]Environment-specific custom proxy prefixes.

CLI Options Reference

The kodall-deploy command accepts the following flags:

BASH
npx kodall-deploy [options]
OptionDescription
-e, --env <name>Target environment key defined in kodall-webapp.config.json. Supports comma-separated targets (e.g. -e dev,staging) and equals syntax (-e=prod).
-i, --instance <url>Override backend instance URL directly.
-k, --api-key <key>API key token for stateless authentication.
-t, --token <token>OIDC / OAuth2 bearer token for authentication.
-u, --user <username>Kodall username for interactive password login.
-p, --password <pwd>Kodall password for non-interactive credential login.
-d, --dist <path>Override path to build output directory (project root . is prohibited).
--path <route>Override web application URL route prefix.
--name <name>Override web application display name.
--buildRun the framework build script before deployment. Can also be run standalone: kodall-deploy build.
--build-cmd <cmd>Specify a custom build command to execute.
--initRun the interactive configuration setup wizard.
--use [env]Switch active local development proxy environment.
--set-default <env>Set the default environment in kodall-webapp.config.json.
--clear-activeClear active local proxy override and revert to default.
-l, --list-envsList configured environments with default and active proxy indicators.
--add-env <name>Add a new target environment to configuration.
--update-env <name>Update an existing target environment configuration.
--clone-env <src> <dst>Clone an existing environment configuration (automatically strips API keys and secrets).
--statusInspect remote server status, active storage IDs, and response latency across environments.
--rollback [id]Rollback deployment to a prior storage version or relative step (e.g. -1, -2, --steps 2, or specific storage file ID).
--init-ciGenerate CI/CD workflow files for GitHub, GitLab, Bitbucket, Azure, Jenkins, CircleCI, AWS CodeBuild.
--dry-runValidate configuration, build files, and authentication without uploading.
--non-interactiveDisable all interactive terminal prompts (fails fast in headless CI environments).
-f, --forceBypass stale build and missing directory warnings.
-h, --helpDisplay the CLI help manual.
-v, --versionDisplay the installed package version.
CLI options can precede subcommands (e.g. npx kodall-deploy -c custom.json use dev or npx kodall-deploy --config prod.json build).

Release History & Changelog

Security

  • Project Root Deployment Protection: validateDistDirectory strictly rejects deploying the repository or project root (dist_path: "."), requiring a genuine build directory to prevent inadvertent exposure of source code, .git, .env, and node_modules.
  • Sensitive File Exclusion in Archiver: Added strict filters in createArchive (isSensitiveArchiveEntry) excluding .env*, .git, .github, .gitlab, .vscode, node_modules, and credentials even if placed inside the distribution directory.
  • OAuth PKCE Loopback Hardening: Non-OAuth requests (e.g. /favicon.ico or port scanners) return HTTP 404, authorization codes are exchanged before rendering browser success, and idle sockets are closed with closeIdleConnections.
  • Credential Sanitization & Secret Stripping: Stripped HTTP Basic Auth credentials from target URLs in error logs, and automatically stripped api_key and secrets when cloning environments (cloneEnvironment).

Added

  • Added client.delete() to KodallNodeClient supporting automatic handling of HTTP 204 No Content responses.
  • Added deleteCookie() method to CookieStore.

Fixed

  • Monorepo Ancestor Workspace Resolution: Traverses ancestor directories up to the filesystem root to detect pnpm-workspace.yaml, turbo.json, lerna.json, and root lockfiles when executing inside nested package folders.
  • Nuxt / Nitro DevProxy Path Duplication: Added prependPath: false to prevent Nitro from duplicating route prefixes, and stripped hop-by-hop headers in proxy forwarding.
  • Rollback Engine & Negative Steps: Added support for negative step syntax (e.g. -R -1 or --steps 2), comma-separated environments (-e dev,staging), and safe rollback metadata recording.
  • CLI Argument Routing & Equals Syntax: Handled options preceding subcommands (kodall-deploy -c custom.json use dev), short options with equals syntax (-e=dev, -R=137), and bare --add-env interactive prompts.
  • Headless & CI Guards: Added non-interactive fail-fast guards across interactive commands to prevent hanging on CI runners.

Added

  • Dynamic Nitro & Nuxt Server Proxy Handlers: Exported createNitroProxyHandler and createNuxtProxyHandler for zero-restart dynamic per-request proxying in Nuxt 3/4 server routes (server/routes/[...proxy].ts or server/middleware/proxy.ts).
  • Streaming Node http/https and Web Standard Request/Response fetch proxying with real-time environment resolution.

Fixed

  • Nuxt Dev Proxy Live Reload & Active-Environment Watching: Updated kodallProxyNuxt module to auto-watch .kodall-deploy/active-env and .kodall-deploy/ alongside kodall-webapp.config.json.
  • Added Nuxt builder:watch hook to trigger immediate dev server restart when npx kodall-deploy use <env> or --clear-active is executed.

Added

  • Dedicated kodall-deploy build CLI Runner with pre-deployment packaging pipelines.
  • Auto-detection for pnpm, bun, yarn, and npm package managers with script filtering.
  • Support for environment aliases and target routing overrides during local builds.

Fixed

  • Resolved build artifact directory resolution for nested monorepos and custom outDirs.

Added

  • Live proxy adapters for Vite, Nuxt, Next.js, and Webpack dev servers.
  • .kodall-deploy/active-env isolation to keep local switches isolated without modifying shared team configs.
  • --set-default and --clear-active CLI commands for immediate environment switching.
  • Dynamic backend route proxying for REST, GraphQL, and WebSocket streams.

Added

  • Native dev server proxy middleware helpers for zero-configuration local development against remote instances.
  • Interactive use and switch terminal commands with fuzzy matching.
  • Vitest unit and integration test suite with complete coverage for proxy routing and HTTP headers.

Fixed

  • Preserved executable binary file permissions (chmod +x) across Unix, macOS, and Windows npm distributions.
  • Exported dual ESM and CJS type definitions for TypeScript projects without bundling errors.

Added

  • Complete TypeScript rewrite with strict type checking and zero runtime dependencies.
  • Multi-environment schema supporting dev, staging, prod, and custom clusters.
  • Live server status diagnostics (--status) with latency and active storage checks.
  • Instant rollback support (--rollback [id]) to switch versions in milliseconds without re-uploading.
  • Interactive browser PKCE OAuth login flow and headless CI/CD workflow generator (--init-ci).