Internals

This document explains, at a high level, what the plugin does internally and why.

Overview

The default export is a Vite plugin that:

• Enhances dev: proxies Appframe endpoints, logs in and refreshes the session, serves the real article HTML with your local entry injected, and caches i18n strings.

• Enhances build: shapes Rollup output to Appframe’s expected file locations and names, builds a manifest and sourcemaps, and optionally treats React as external.

It also exports two helpers: addAppframeBuildConfig(config) and createDevMiddleware(server).

Dev server flow

Files: src/index.ts, src/devServer.ts, src/proxy.ts, src/localization.ts

• Login and session refresh (proxy.ts)

  • On dev startup, the plugin reads appframe.proxy.hostname (or appframe.deploy.hostname) from package.json using importJson.

  • It logs in with APPFRAME_LOGIN and APPFRAME_PWD (required). The HTTPS request captures AppframeWebAuth and AppframeWebSession cookies and caches them per-host.

  • A timer renews the login every 5 minutes to minimize 403 errors due to expired sessions.

• Proxying routes (index.ts, devServer.ts)

  • The plugin builds a regex list of routes to proxy to Appframe, e.g. ^/api/.*, ^/file/.*, ^/lib/.*, plus any appframe.proxy.routes.

  • Vite’s native proxy is configured so requests to these paths forward to https://<hostname>.

  • For each proxied request, the plugin attaches the cached auth cookies and sets Origin to the remote hostname (Appframe rejects local origins).

• Serving article HTML (devServer.ts)

  • To keep dev close to prod, the plugin fetches the article HTML from the Appframe server and then transforms it:

    • Removes production JS/CSS (article assets) and adds your local module entry (/src/index.tsx → /src/index.ts → /src/index.js).

    • Removes Bugsnag and Web Vitals scripts, and skips service worker registration.

    • Injects a script that merges locally cached i18n strings into af.article.i18n.

    • Rewrites absolute links that don’t point to the article root to include the server hostname.

  • The raw HTML is cached at node_modules/.appframe/index.html for up to 3 hours (unless the request has Cache-Control: no-cache).

  • The final HTML passes through vite.transformIndexHtml so HMR and module graph behave normally.

• i18n localization cache (localization.ts)

  • Dev can trigger many small localization requests over HTTP/1.1, which slows startup. The plugin adds a middleware for /api/user/localize/new/<article> that forwards the request with cookies and caches the response.

  • The cache is stored at node_modules/.appframe/localizeCache.json (writes are debounced) and injected into the page during article HTML transform to warm the client cache.

Build configuration

File: src/build.ts

• The helper addAppframeBuildConfig is applied automatically in build mode by the plugin, but is also exported for custom usage.

• Key behaviors:

  • Enables build.manifest and build.sourcemap by default.

  • Determines the app entry by checking /src/index.tsx, then /src/index.ts, then /src/index.js.

  • Writes output to Appframe file paths using the article ID:

    • JS: file/article/script/<ARTICLE_ID>/main.[hash].min.js (and chunk variants)

    • CSS: file/article/style/<ARTICLE_ID>/[name].[hash].min.css

  • Adds Rollup visualizer to write dist/stats.html.

  • When appframe.build.externals !== false, uses vite-plugin-externals to treat react and react-dom as externals mapped to React and ReactDOM (and sets Rollup output.globals accordingly).

Miscellaneous

• Module resolution: Adds alias { find: "~/", replacement: "/src/" } so ~/... maps to project src.

• Logging: Login progress uses chalk and interactive terminal updates when supported.

• JSON import helper: importJson reads JSON off disk because Node ESM JSON import is not used here.