Web App Deployment

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.

During local development, your frontend application runs on localhost (e.g. http://localhost:5173 or http://localhost:3000), while your backend runs on a remote or local Kodall instance.

The @kodall/kodall-deploy development proxy suite provides native framework plugins and configuration helpers that seamlessly forward /auth, /rest, and /storage requests to your target Kodall instance with full cookie, header, and WebSocket HMR support.

Architecture Principles

Zero Child Processes & Zero Wrappers: The dev server process is managed entirely by your framework's native CLI (vite, nuxt dev, next dev, ng serve). @kodall/kodall-deploy does not spawn background child processes or custom TCP proxy daemons, eliminating port collisions and orphan processes.
Native Framework Integration: Uses the framework's native proxy layer (such as http-proxy inside Vite, Nitro, Webpack, and Next.js) so WebSocket HMR (Hot Module Replacement), streaming responses, and SSL handling work natively.
Single Source of Truth: All environment definitions and default target selections reside in kodall-webapp.config.json.

Rendering diagram...

3-Layer Proxy Architecture

The development proxy system operates across three modular layers:

Rendering diagram...

Layer 1: Core Resolver

Reads kodall-webapp.config.json, determines the active backend instance URL based on environment precedence, and merges default routes (/auth, /rest, /storage) with custom proxy_paths (e.g. /web-assets).

Layer 2: Framework Adapters

Different frontend frameworks require different JSON configurations to proxy HTTP traffic. Layer 2 formats the resolved URL and routes into the exact schema required by each framework.

Layer 3: Plugin Wrappers

Convenience wrappers that automatically hook into framework configuration lifecycles:

kodallProxy(): Automatically passes proxy rules into Vite's server.proxy hook.
kodallProxyNuxt(): Automatically injects proxy rules into Nuxt's nitro.devProxy module hook.

Target Resolution Precedence

When your development server starts, the proxy resolver determines the target instance URL following this strict precedence hierarchy:

Rendering diagram...

Priority	Resolution Source	Example
1 (Highest)	Explicit Helper Option	`kodallProxy({ instance: 'http://localhost:8080' })`
2	Environment Variables	`KODALL_INSTANCE=https://dev.kodall.io` or `KODALL_ENV=staging`
3	`default_env` in Config File	`"default_env": "staging"` in `kodall-webapp.config.json`
4 (Fallback)	First Environment Key	First entry in `environments: { ... }`

Framework Integration Guides

1. Vite (Vue 3, React, SvelteKit, SolidJS)

Option A: Vite Plugin (Recommended)

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { kodallProxy } from '@kodall/kodall-deploy/vite'

export default defineConfig({
  plugins: [
    vue(),
    // Automatically forwards /auth, /rest, and /storage based on default_env
    kodallProxy()
  ]
})

Option B: Config Helper (`getDevProxy`)

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { getDevProxy } from '@kodall/kodall-deploy'

export default defineConfig({
  plugins: [vue()],
  server: {
    proxy: getDevProxy()
  }
})

Option C: Manual `server.proxy` (Without Helper Package)

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

const BACKEND_URL = 'https://dev.kodall.yourcompany.com'

export default defineConfig({
  plugins: [vue()],
  server: {
    proxy: {
      '/auth': { target: BACKEND_URL, changeOrigin: true, secure: true },
      '/rest': { target: BACKEND_URL, changeOrigin: true, secure: true },
      '/storage': { target: BACKEND_URL, changeOrigin: true, secure: true }
    }
  }
})

2. Nuxt 3 / Nuxt 4

Option A: 1-Line Nuxt Module (Recommended)

nuxt.config.ts

import { defineNuxtConfig } from 'nuxt/config'
import { kodallProxyNuxt } from '@kodall/kodall-deploy'

export default defineNuxtConfig({
  ssr: false,
  modules: [
    kodallProxyNuxt()
  ]
})

Option B: Nitro Config Helper (`getNitroProxy`)

nuxt.config.ts

import { defineNuxtConfig } from 'nuxt/config'
import { getNitroProxy } from '@kodall/kodall-deploy'

export default defineNuxtConfig({
  ssr: false,
  nitro: {
    devProxy: getNitroProxy()
  }
})

Option C: Manual `nitro.devProxy` (Without Helper Package)

nuxt.config.ts

import { defineNuxtConfig } from 'nuxt/config'

const BACKEND_URL = 'https://dev.kodall.yourcompany.com'

export default defineNuxtConfig({
  ssr: false,
  nitro: {
    devProxy: {
      '/auth': { target: `${BACKEND_URL}/auth`, changeOrigin: true, secure: true },
      '/rest': { target: `${BACKEND_URL}/rest`, changeOrigin: true, secure: true },
      '/storage': { target: `${BACKEND_URL}/storage`, changeOrigin: true, secure: true }
    }
  }
})

Nitro requires the destination subpath appended to the target URL (e.g. ${BACKEND_URL}/auth), whereas Vite proxies forward paths relative to the base instance.

3. Next.js

Option A: Next.js Rewrites Helper (Recommended)

next.config.mjs

import { getNextRewrites } from '@kodall/kodall-deploy'

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  async rewrites() {
    return getNextRewrites()
  }
}

export default nextConfig

Option B: Manual `rewrites` Array (Without Helper Package)

next.config.mjs

const BACKEND_URL = 'https://dev.kodall.yourcompany.com'

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  async rewrites() {
    return [
      { source: '/auth/:path*', destination: `${BACKEND_URL}/auth/:path*` },
      { source: '/rest/:path*', destination: `${BACKEND_URL}/rest/:path*` },
      { source: '/storage/:path*', destination: `${BACKEND_URL}/storage/:path*` }
    ]
  }
}

export default nextConfig

4. Angular CLI

Option A: Dynamic Proxy Helper in `proxy.conf.js` (Recommended)

proxy.conf.js

const { getAngularProxy } = require('@kodall/kodall-deploy')

module.exports = getAngularProxy()

Reference the proxy in angular.json:

angular.json

"serve": {
  "builder": "@angular-devkit/build-angular:dev-server",
  "options": {
    "proxyConfig": "proxy.conf.js"
  }
}

Option B: Manual `proxy.conf.json` (Without Helper Package)

proxy.conf.json

{
  "/auth": {
    "target": "https://dev.kodall.yourcompany.com",
    "secure": true,
    "changeOrigin": true
  },
  "/rest": {
    "target": "https://dev.kodall.yourcompany.com",
    "secure": true,
    "changeOrigin": true
  },
  "/storage": {
    "target": "https://dev.kodall.yourcompany.com",
    "secure": true,
    "changeOrigin": true
  }
}

Reference in angular.json:

angular.json

"serve": {
  "builder": "@angular-devkit/build-angular:dev-server",
  "options": {
    "proxyConfig": "proxy.conf.json"
  }
}

Custom Proxy Paths (`proxy_paths`)

By default, the proxy automatically forwards /auth, /rest, and /storage. When your backend provides custom microservices or static asset folders (such as /web-assets or /media), define proxy_paths in kodall-webapp.config.json:

kodall-webapp.config.json

{
  "web_app_name": "Enterprise Portal",
  "web_app_path": "/",
  "dist_path": "./dist",
  "default_env": "dev",

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

  "environments": {
    "dev": {
      "type": "dev",
      "instance": "https://dev.kodall.yourcompany.com"
    },
    "staging": {
      "type": "staging",
      "instance": "https://staging.kodall.yourcompany.com",
      "proxy_paths": [
        "/staging-mock-data"
      ]
    }
  }
}

Environment-level proxy_paths are merged with root-level proxy_paths. All configured framework proxy helpers automatically include these extra paths.

Ad-Hoc Environment Overrides

Switch backend targets during local development without editing files:

BASH

# Override active environment
KODALL_ENV=staging npm run dev

# Override backend instance URL directly
KODALL_INSTANCE=https://dev.kodall.io npm run dev

`ProxyOptions` Reference

Passing options is completely optional (options?: ProxyOptions). When called with no arguments (e.g. kodallProxy(), kodallProxyNuxt(), getNextRewrites(), getAngularProxy()), all helpers automatically locate kodall-webapp.config.json in your project root and resolve the target instance from default_env.

When you need to override the default behavior programmatically, pass an optional ProxyOptions object:

TYPESCRIPT

export interface ProxyOptions {
  /** Working directory containing kodall-webapp.config.json (default: process.cwd()) */
  cwd?: string

  /** Target environment key from config (e.g. 'dev', 'staging', 'prod') */
  env?: string

  /** Direct backend instance URL override (bypasses config resolution) */
  instance?: string

  /** Custom path to configuration file */
  configPath?: string

  /** Extra proxy routes to include (e.g. ['/web-assets', '/media']) */
  proxyPaths?: string[]

  /** Change the origin of the host header to the target URL (default: true) */
  changeOrigin?: boolean

  /** Verify SSL/TLS certificates (default: true) */
  secure?: boolean
}

Option	Type	Default	Description
`env`	`string`	`default_env` in config	Target environment name to resolve from `kodall-webapp.config.json`.
`instance`	`string`	Resolved from config	Explicit backend instance URL. Overrides config file resolution.
`proxyPaths`	`string[]`	`[]`	Additional URL prefixes to proxy to the backend.
`changeOrigin`	`boolean`	`true`	Rewrites the `Host` header to match the backend instance.
`secure`	`boolean`	`true`	Verifies SSL/TLS certificates for HTTPS instances.
`cwd`	`string`	`process.cwd()`	Directory where `kodall-webapp.config.json` is located.
`configPath`	`string`	`undefined`	Absolute or relative path to a custom configuration file.

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.

CI/CD & Automation

Automate frontend deployments to Kodall with ready-to-run CI/CD pipelines, live health checks, instant rollbacks, and the Programmatic TypeScript API.