npm package: @olenbetong/appframe-vite
Description: Tools to use and deploy Vite applications to Appframe
Author: Bjørnar Vister Hansen
Latest version: 6.0.3

# @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

```sh
pnpm add -D @olenbetong/appframe-vite
```

## Usage (Vite)

```ts
// 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:

```sh
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.

```jsonc
{
	"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.