@olenbetong/appframe-vite

Tools to develop and build Vite applications that run inside Appframe articles.

• Provides a Vite plugin you add in vite.config.*.
• Proxies API and static routes to an Appframe server during pnpm start.
• Logs in automatically and refreshes the session on an interval.
• Serves real article HTML from Appframe in dev, but swaps production assets for your local entry.
• Caches i18n strings locally to speed up development loads.
• Shapes production builds to Appframe paths and filenames, with optional React externals.

Installation

pnpm add -D @olenbetong/appframe-vite

Usage (Vite)

// vite.config.mjs or vite.config.ts
import appframe from "@olenbetong/appframe-vite";
import { defineConfig } from "vite";

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

Then run your app:

pnpm --filter <app> start

Make sure your Appframe credentials are available as environment variables:

• APPFRAME_LOGIN: username
• APPFRAME_PWD: password

On first run, the plugin logs in, configures Vite’s proxy for Appframe routes, and serves the article HTML with your local entry injected.

Project configuration (package.json)

This package reads package.json.appframe to know what to proxy and how to build.

{
	"appframe": {
		"article": {
			"id": "my-article",            // Required
			"altNames": ["my-article-dev"]   // Optional: alternate root paths
		},
		"deploy": { "hostname": "dev.obet.no" }, // Default server if proxy not set
		"proxy": {
			"hostname": "dev.obet.no",       // Optional override for dev proxy
			"routes": ["^/custom/.*"]         // Optional: extra proxied routes
		},
		"build": {
			"externals": true                // Map React and ReactDOM to globals
		}
	}
}

What it does (at a glance)

• Dev server
  • Proxies Appframe routes (e.g. /api, /file, /lib, etc.) to the configured hostname.
  • Performs an initial login and refreshes the session every 5 minutes to prevent 403 errors.
  • Serves the real article HTML from Appframe, but removes production assets and injects your local entry (/src/index.*).
  • Caches localized strings under node_modules/.appframe/localizeCache.json and injects them into the page to avoid many small HTTP 1.1 requests.
• Build
  • Enables manifest and sourcemap.
  • Writes filenames to Appframe paths, using the article ID, e.g.:
    • file/article/script/<ARTICLE_ID>/main.[hash].min.js
    • file/article/style/<ARTICLE_ID>/style.[hash].min.css
  • Optionally treats react and react-dom as externals and maps them to React and ReactDOM globals.
  • Adds a Rollup visualizer report at dist/stats.html.
• Resolve
  • Adds the alias ~/ to /src/ so imports like ~/components/Button resolve to src/components/Button.

Exported helpers

Although most users only need the default plugin, the package also exports:

• addAppframeBuildConfig(config): applies the Appframe build defaults (paths, externals, visualizer).
• createDevMiddleware(server): serves transformed article HTML and injects cached i18n strings.

See docs/reference/appframe-vite/ for a deeper dive into internals and configuration.