appframe-vite

High-level documentation for @olenbetong/appframe-vite — the Vite plugin that lets you develop and build Appframe article applications with first-class DX while matching production behavior closely.

• Development: logs in to Appframe, proxies API/static routes, serves the real article HTML while injecting your local entry, and caches i18n strings for speed.

• Build: outputs assets to Appframe file paths using the article ID, adds a manifest and sourcemaps, and can mark React as external.

See Internals.md for how each part works.

Quick start

1. Install and add the plugin to Vite:

import appframe from "@olenbetong/appframe-vite";
import { defineConfig } from "vite";

export default defineConfig({
	plugins: [appframe()],
});

1. Add appframe to your app’s package.json:

{
	"appframe": {
		"article": { "id": "my-article" },
		"deploy": { "hostname": "dev.obet.no" }
	}
}

1. Provide credentials and start dev:

export APPFRAME_LOGIN=...  # or use .env
export APPFRAME_PWD=...
pnpm --filter <app> start

Configuration reference (package.json.appframe)

• article.id: Required. Appframe article ID. Used for routing and build output paths.

• article.altNames: Optional array of alternate root names recognized by the dev server.

• deploy.hostname: Default server hostname used by dev/build if proxy.hostname is not set.

• proxy.hostname: Optional dev-only override for the proxy target hostname.

• proxy.routes: Optional list of extra regex routes to proxy.

• build.externals: Defaults to true. When true, treats react and react-dom as externals mapped to React and ReactDOM globals.

Common issues

• Missing credentials: ensure APPFRAME_LOGIN and APPFRAME_PWD are set.

• 403 in dev: the plugin refreshes login every 5 minutes; if a session still expires, restart the dev server.

• Entry resolution: the plugin tries /src/index.tsx, then /src/index.ts, then /src/index.js.