Web App Deployment

kodall-deploy Tooling & CLI

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

BASH

pnpm add -D @kodall/kodall-deploy

BASH

yarn add -D @kodall/kodall-deploy

BASH

bun add -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:

Framework	Auto-Detected Build Directory	Detection Signature
Vite (Vue, React, SolidJS)	`./dist`	`vite.config.*`
Next.js (Static Export)	`./out`	`next.config.*`
Nuxt 3/4	`./.output/public`	`nuxt.config.*`
Angular (17+)	`./dist/<project-name>/browser`	`angular.json`
SvelteKit (Adapter Static)	`./build`	`svelte.config.*`
Remix (SPA Mode)	`./build/client`	`remix.config.` or `vite.config.`
Astro (Static)	`./dist`	`astro.config.*`
Static HTML	`.`	`index.html` in root

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

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

Property	Type	Default	Description
`web_app_name`	`string`	Required	Display name of the web application in Kodall Cloud Console.
`web_app_path`	`string`	`"/"`	URL route prefix assigned to this application (e.g. `"/"` or `"/portal"`).
`dist_path`	`string`	Auto-detected	Relative path to the production build output directory.
`default_env`	`string`	First environment	Active default environment used when `-e` is omitted.
`proxy_paths`	`string[]`	`[]`	Additional URL prefixes to proxy to the backend during development.
`environments`	`object`	Required	Map of target environments (`dev`, `staging`, `prod`).
`environments.<name>.instance`	`string`	Required	Base URL of the target Kodall instance.
`environments.<name>.api_key`	`string`	`undefined`	Optional secret API key for deployment authentication.
`environments.<name>.proxy_paths`	`string[]`	`[]`	Environment-specific custom proxy prefixes.

CLI Options Reference

The kodall-deploy command accepts the following flags:

BASH

npx kodall-deploy [options]

Option	Shorthand	Description
`--env <name>`	`-e <name>`	Target environment key defined in `kodall-webapp.config.json`.
`--instance <url>`	`-i <url>`	Override backend instance URL directly.
`--api-key <key>`	`-k <key>`	API key token for stateless authentication.
`--token <token>`	`-t <token>`	OIDC / OAuth2 bearer token for authentication.
`--user <username>`	`-u <username>`	Kodall username for interactive password login.
`--password <pwd>`	`-p <pwd>`	Kodall password for non-interactive credential login.
`--dist <path>`	`-d <path>`	Override path to build output directory.
`--path <route>`		Override web application URL route prefix.
`--name <name>`		Override web application display name.
`--init`		Run the interactive configuration setup wizard.
`--use [env]`		Switch active default environment interactively or by name.
`--list-envs`	`-l`	List all configured deployment environments.
`--status`		Inspect remote server status, active storage IDs, and response latency.
`--rollback [id]`		Rollback deployment to a prior storage version without rebuilding.
`--init-ci`		Generate CI/CD workflow files for GitHub, GitLab, Bitbucket, Azure, etc.
`--dry-run`		Validate configuration, build files, and authentication without uploading.
`--non-interactive`		Disable all interactive terminal prompts (required for CI/CD).
`--force`	`-f`	Bypass stale build and missing directory warnings.
`--help`	`-h`	Display the CLI help manual.
`--version`	`-v`	Display the installed package version.

Overview

Architecture guide and technical overview for building and hosting static frontend Single Page Applications directly inside a Kodall instance.

Local Dev Proxy Suite

Native development proxy suite and Vite plugin with tailored adapters for Vite, Nuxt, Next.js, and Angular with automatic instance resolution and custom proxy paths.