In an MPA project, as the number of pages grows, maintaining entry points quickly becomes a repetitive and error-prone task.

Adding a new page usually involves more than just creating a new React component. You also need to update rollupOptions.input in vite.config.ts, maintain client-side entry, server-side entry, HTML templates, and for some pages, register routes and distinguish between SSR, CSR, and streaming. When there are only a few pages, this is manageable. But once you have more than twenty pages, problems become apparent: each entry file looks similar, differing only in the imported page; configuration is scattered across several places, and missing one change can cause issues like working locally but failing in build, or routes not mounting.

This article documents a plugin-based refactoring we did in our BFF (Backend for Frontend) page system: each page only declares a config.toml file, and everything else—page discovery, template matching, virtual entry generation, route mounting, and hot reload during development—is handled by a Vite plugin.

Where the Problem Comes From

// Traditional MPA: every new page requires remembering to add to input
export default {
  build: {
    rollupOptions: {
      input: {
        cart: 'src/pages/cart/index.html',
        checkout: 'src/pages/checkout/index.html',
        account: 'src/pages/my-account/index.html',
        // ... the 21st page, do you still remember to add it?
      }
    }
  }
}

This configuration itself isn't complicated; the real hassle is the maintenance model it implies: page registration relies on manual conventions, entry files are repetitive, and SSR and CSR each have their own set of entry logic. If pages also have multiple rendering modes, duplicate code keeps growing.

We wanted the page directory itself to declaratively indicate what it is, which template it uses, and which domain and path it should be mounted on. Developers only need to focus on the page's business logic, and the build system generates the necessary entries based on those declarations.

Core Concept

The core flow is straightforward: first, scan page configurations to obtain a set of page metadata; then, based on the page type, find the appropriate template; next, register the template as a virtual module; finally, let Vite consume these virtual modules in both Dev and Build modes.

No temporary directories like .next/ or .nuxt/ are generated here. Intermediate files live in an in-memory Map<string, () => string>, and code is generated only when Vite actually requests a specific module. This keeps the working directory clean, and during development there's no need to preprocess all pages.

First, Look at Virtual Modules

Vite virtual modules are not mysterious. Essentially, a plugin "recognizes" a module that doesn't exist on disk during the compilation phase and returns some code. The minimal implementation usually requires only two hooks:

const PREFIX = '@virtual:my-plugin';
 
export default function myPlugin(): Plugin {
  return {
    name: 'my-plugin',
    
    // Intercept import requests
    resolveId(id) {
      if (id.startsWith(PREFIX)) return '\0' + id;
    },
    
    // Return dynamically generated module code
    load(id) {
      if (id.startsWith('\0' + PREFIX)) {
        return `export const data = "generated at compile time";`;
      }
    },
  };
}

The \0 prefix is a Rollup convention, marking that this ID has been resolved by a plugin and should not be treated as a normal file path by subsequent plugins.

	Dev (serve)	Build
Module path	`/@virtual:...` (via HTTP)	`@virtual:...` (in-memory resolution)
Load timing	On-demand (when browser requests)	Full (Rollup traverses dependency graph)
HMR	Must be supported	Not needed

The differences in paths between Dev and Build are the source of many implementation details later. In development, the browser requests modules via HTTP, so virtual modules need to be recognized by Vite's dev server middleware. During build, it goes through Rollup's module graph and doesn't need HTTP paths.

Pages Start with `config.toml`

Each page declares its identity using a TOML file:

# src/pages/cart/config.toml
[page]
type = "react-ssr"
 
[router]
domain = "<%=SERVER_OFFICIAL_DOMAIN%>"
# path omitted → defaults to directory name "/cart"

type = "react-ssr" determines which template set the page uses, and router determines where the page is mounted. If no path is explicitly declared, it defaults to the page directory name.

During the scanning phase, several tasks are performed: find all config.toml files, parse the page configuration, confirm that the page's entry file exists, and then resolve the template. The code can be simplified as follows:

import fg from 'fast-glob';
import * as toml from 'smol-toml';
 
async function scanPages(root: string): Promise<Map<string, IPage>> {
  const pages = new Map();
  const configs = await fg('src/pages/**/config.toml', { cwd: root });
  configs.sort(); // Ensure deterministic registration order
 
  for (const configPath of configs) {
    const raw = await fs.promises.readFile(path.join(root, configPath), 'utf-8');
    const config = toml.parse(raw);
    
    const dir = path.dirname(configPath);
    const pageId = encodeURIComponent(dir.replace('src/pages/', ''));
    
    // Entry file must exist
    const entries = await fg(path.join(root, dir, '+Page.ts'));
    if (!entries.length) continue;
    
    // Resolve template (custom > default)
    const template = await resolveTemplate(root, dir, config.page.type);
    if (!template) continue;
    
    pages.set(pageId, {
      id: pageId, dir, entry: entries[0],
      type: config.page.type,
      router: {
        domain: config.router.domain,
        path: config.router.path ?? [`/${dir.replace('src/pages/', '')}`],
      },
      template,
    });
  }
  return pages;
}

Template resolution also leaves an override entry point: a page's own templates/ directory takes priority over the global templates/{page.type}/. Most pages can reuse the default template, but a few special pages can take full control without pushing special logic back into the common template.

How to Design Virtual Module IDs

const PLUGIN_NAME = 'vite-plugin-mpa-virtual-ssr';
 
// Build: Rollup in-memory resolution
const BUILD_PREFIX  = `@virtual:${PLUGIN_NAME}`;
// Dev: HTTP path interception
const DEV_PREFIX    = `/@virtual:${PLUGIN_NAME}`;
// System modules (environment injection, etc.)
const SYS_PREFIX    = `/@virtual-sys:${PLUGIN_NAME}`;

Module ID format: {prefix}/{pageId}/{fileName}

/@virtual:vite-plugin-mpa-virtual-ssr/cart/entry-client.tsx
/@virtual:vite-plugin-mpa-virtual-ssr/cart/entry-server.tsx
/@virtual:vite-plugin-mpa-virtual-ssr/cart/index.html

ID design may seem like just naming, but it affects subsequent resolution, HMR, and build output. We embed page ID, file name, and environment prefix into the module ID, so that entry-client.tsx, entry-server.tsx, and index.html can all be treated as virtual files under the same page.

Generate Entries with Templates

Each page registers 3 to 4 virtual files. The content is not hardcoded in advance but is generated when loaded by reading a template and substituting the page entry path.

function registerVirtualFiles(ctx: PluginContext, pageId: string, page: IPage) {
  const p = prefix(); // Dev or Build prefix
  
  // Client entry: template + replace dynamic import path
  ctx.virtualFiles.set(`${p}/${pageId}/entry-client.tsx`, () => {
    const tpl = fs.readFileSync(
      path.join(page.template.page.dir, 'entry-client.tsx'), 'utf-8'
    );
    return tpl.replace('$DYNAMIC_ENTRY_IMPORT$', page.entry);
  });
  
  // Server entry: same logic
  ctx.virtualFiles.set(`${p}/${pageId}/entry-server.tsx`, () => {
    const tpl = fs.readFileSync(
      path.join(page.template.page.dir, 'entry-server.tsx'), 'utf-8'
    );
    return tpl.replace('$DYNAMIC_ENTRY_IMPORT$', page.entry);
  });
  
  // HTML template
  ctx.virtualFiles.set(`${p}/${pageId}/index.html`, () => {
    const tpl = fs.readFileSync(
      path.join(page.template.page.dir, 'index.html'), 'utf-8'
    );
    return tpl.replace('$DYNAMIC_ENTRY_IMPORT$', `${p}/${pageId}/entry-client.tsx`);
  });
}

Here, virtualFiles stores functions, not strings. The reason is simple: in development mode, not all pages are visited, so there's no need to read all templates and replace all entries at startup. When Vite actually loads a virtual module, the corresponding generation function is executed on demand.

Templates contain several types of placeholders. $DYNAMIC_ENTRY_IMPORT$ is replaced with the actual page entry when the virtual module is loaded; <%=ENV_VAR%> type environment variables are processed during configuration scanning; macros like "$DEFINE_{__isCSR__}$" are replaced at build time.

The client entry template looks roughly like this:

// templates/react-ssr/page/entry-client.tsx
import ReactDOM from 'react-dom/client';
import React from 'react';
// @ts-expect-error - replaced at build time with actual path
import App from '$DYNAMIC_ENTRY_IMPORT$';
import * as $Template from '#/src/shared/template';
 
async function renderPage(): Promise<void> {
  const Page = $Template.getPageEntry(App);
  const meta = $Template.getSSRPageMeta(App);
  const SSR_RENDER_DATA = await $Template.requestTransformData(
    $Template.getDataFromDom<$Template.IRenderContext<{}>>('ssr-render-data', '__SSR_RENDER_DATA__') 
      ?? { fetchState: {} },
    meta.transform,
  );
 
  ReactDOM.hydrateRoot(
    document.getElementById('root')!,
    <React.StrictMode>
      <Page ctx={SSR_RENDER_DATA} />
    </React.StrictMode>,
  );
}
 
renderPage().catch(console.error);

@ts-expect-error is intentionally left. The $DYNAMIC_ENTRY_IMPORT$ in the template file is not a valid path, but at runtime it has been replaced by the plugin with the real page entry. This way, a single entry-client.tsx template can serve all pages of the same type, with the only difference being the imported page module.

Plugin Skeleton

export function createMpaVirtualSsrPlugin(options: PluginOptions): Plugin {
  const ctx: PluginContext = { pages: new Map(), virtualFiles: new Map() };
  let resolvedConfig: ResolvedConfig;
 
  return {
    name: PLUGIN_NAME,
 
    // ── Configuration phase ──────────────────────────────
    async configResolved(config) {
      resolvedConfig = config;
      ctx.pages = await scanPages(config.root);
      for (const [id, page] of ctx.pages) {
        registerVirtualFiles(ctx, id, page);
      }
    },
 
    // Build mode: automatically inject Rollup input entries
    config() {
      if (resolvedConfig?.command === 'build') {
        const input: Record<string, string> = {};
        for (const [pageId] of ctx.pages) {
          input[`${pageId}/index.html`] = `${BUILD_PREFIX}/${pageId}/index.html`;
        }
        return { build: { rollupOptions: { input } } };
      }
    },
 
    // ── Resolution phase ──────────────────────────────
    resolveId(source, importer) {
      const p = prefix();
      if (source.startsWith(p)) return '\0' + source;
      
      // Relative imports between virtual modules
      if (importer?.startsWith('\0' + p) && source.startsWith('.')) {
        const resolved = path.posix.join(path.posix.dirname(importer.slice(1)), source);
        for (const ext of ['.ts', '.tsx', '.js', '.jsx', '']) {
          if (ctx.virtualFiles.has(resolved + ext)) return '\0' + resolved + ext;
        }
      }
    },
 
    // ── Loading phase ──────────────────────────────
    async load(id) {
      const p = prefix();
      if (!id.startsWith('\0' + p)) return;
      
      const generator = ctx.virtualFiles.get(id.slice(1));
      if (!generator) return;
      
      const code = await generator();
      const ext = path.extname(id);
      
      // TSX/TS → SWC compilation
      if (ext === '.tsx' || ext === '.ts') {
        const result = transformSync(code, {
          jsc: { parser: { syntax: 'typescript', tsx: ext === '.tsx' }, target: 'es2020' },
          sourceMaps: true,
          filename: id,
        });
        return { code: result.code, map: result.map };
      }
      return code;
    },
 
    // ── HMR ──────────────────────────────────
    configureServer(server) {
      server.watcher.on('change', handleFileChange);
      server.watcher.on('add', handleFileChange);
    },
  };
}

There are two key points in this skeleton.

The first is handling relative imports between virtual modules in resolveId. Virtual modules are not disk files, so Vite doesn't know where ./foo should resolve to. Therefore, the plugin must resolve the path based on the importer and match the file extension.

The second is compiling TS/TSX in the load phase. When templates are finally consumed by Vite, they still need to return executable JavaScript and a sourcemap.

How the Server Consumes Virtual Modules

The SSR template also contains a server-side Handle. It doesn't directly care about the disk path of the page file; instead, it loads the current page's server-side entry via ctx.loadFileModule('entry-server.tsx'):

// templates/react-ssr/server/index.ts (production code)
import { Page, Utils, Flags, type Types } from '@reolink-web/bff-pages-server-core';
import serialize from 'serialize-javascript';
import * as $Template from '#/src/shared/template';
 
interface ServerModule<T = unknown> {
  render: (ctx: $Template.IRenderContext<T>, url: string) => Types.PromiseOrValue<string>;
  default: $Template.IEntrySSRModule<T>;
}
 
export default Page.defineHandle({
  htmlBuildInSlots: async (ctx) => {
    const module = await ctx.loadFileModule<ServerModule>('entry-server.tsx');
    const meta = $Template.getSSRPageMeta(module.default);
    return {
      '<!--meta-build-in-->': Utils.serializeTags(await meta.metaBuildIn?.()),
    };
  },
 
  htmlRuntimeSlots: async (ctx) => {
    const module = await ctx.loadFileModule<ServerModule>('entry-server.tsx');
    const meta = $Template.getSSRPageMeta(module.default);
 
    return Flags.createFlagsChainTask(
      async () => (await meta.fetch?.(Page.extraHandleRuntimeInnerContext(ctx))) ?? null,
    )
      .chain(async (fetchState) => {
        const renderContext: $Template.IRenderContext = { fetchState };
        const pageMeta = Utils.serializeTags(await meta.meta?.(renderContext, ctx));
        return [pageMeta, renderContext] as const;
      })
      .chain(async ([meta, context]) => ({
        '<!--meta-runtime-->': meta,
        '<!--app-head-->': `<script id="ssr-render-data">window.__SSR_RENDER_DATA__=${serialize(context)};</script>`,
        '<!--app-html-->': await module.render(context, ctx.routerContext.originalUrl),
        '<!--lang-->': ctx.handleContext.lang || 'en',
      }));
  },
});

This step connects the whole chain: config.toml declares the page, the plugin generates virtual entries, the Handle loads entry-server.tsx, and then executes the page's own fetch, meta, and render.

HMR Can't Just Do Full Reload

When a page entry changes, configuration changes, a new page is added, or a page is deleted, the impact on the system varies. If we do a full reload for everything, the logic is simplest, but the developer experience is rough. If we use module hot replacement for everything, we can't handle route and template changes.

So we implement layered watching based on file type:

When +Page.ts content is updated, virtual module HMR can handle it. When config.toml is updated, a simple module replacement isn't enough, because it may change the route, page type, or template. In that case, the old page must be unloaded, re-registered, and routes rebuilt. When a config file is deleted, the page must be removed; when a config file is added, there's an additional challenge: that file was not in any registered watch scope before.

New pages are handled by a Dynamic Matcher:

triggerScope.addTriggerDynamicMatcher(
  async (filePath, event) => {
    if (event !== 'create') return false;
    // Confirm that it's a config.toml under the pages directory
    const allConfigs = await fg('src/pages/**/config.toml');
    if (!allConfigs.includes(filePath)) return false;
    // Only trigger if TOML format is valid (developer may still be typing)
    try {
      toml.parse(await fs.promises.readFile(filePath, 'utf-8'));
      return true;
    } catch {
      return false; // Format invalid, wait for update event
    }
  },
  [(event, hooks) => hooks.reload()]
);

We deliberately wait until the TOML can be parsed correctly before triggering a reload. When a developer first creates a file, the content may not be complete. If we rebuild the page every time a half-finished configuration is saved, the dev server will produce many meaningless errors.

CSS Dependencies Under SSR

SSR has another easily overlooked point: React components will normally import './style.css', but during server-side rendering, we don't actually need to execute CSS. What we need is to record which CSS files are depended on, and finally inject the corresponding <link> tags into the HTML.

load(id, options) {
  if (options?.ssr && isCSSRequest(id)) {
    ctx.ssrCssImportIds.add(id);        // Record dependency
    if (cssModuleRE.test(id)) {
      ctx.ssrCssModuleImportIds.add(id); // Additional tracking for CSS Modules
    }
  }
  // ...
}

In the build output, based on the collected results, automatically inject:

<link rel="stylesheet" href="/assets/cart-a1b2c3.css">
<link rel="stylesheet" href="/assets/shared-d4e5f6.css">

This way, page developers don't need to manually maintain a style manifest; they just import CSS as they normally do in their components. The plugin collects these dependencies during the SSR compilation phase.

Dev and Build Forks

if (envMode === 'dev') {
  // Wrap with async wrapper to support HMR + environment flags
  systemVirtualFiles[fileId] = () => `
    globalThis.__isServerSide__ = false;
    globalThis.__isClientSide__ = true;
    async function main() { return import('${escapedPageEntry}'); }
    main().catch(console.error);
  `;
}
 
if (envMode === 'build') {
  // Directly collect into Rollup input
  const input = {};
  for (const [pageId] of ctx.pages) {
    input[`${pageId}/index.html`] = `${BUILD_PREFIX}/${pageId}/index.html`;
  }
  rollupOptions.input = input;
}

The same set of page metadata is consumed differently in Dev and Build modes.

Dev mode cares more about "on-demand" and "reloadable", so the entry is wrapped in an async wrapper that sets environment flags and carries HMR. Build mode focuses on the static dependency graph; the plugin collects all page HTML virtual entries into Rollup input so the build phase can traverse them completely.

Differences from Framework-Generated Directories

Frameworks like Next.js and Nuxt also perform page scanning, entry generation, and route registration, but they usually output intermediate artifacts to directories like .next/ or .nuxt/.

Our scenario is more of an internal BFF page system within a project, where we don't need to create a full framework. So we chose virtual modules. The advantage is a smaller surface area for refactoring, and the working directory stays clean without a bunch of generated files. The trade-off is that the plugin must handle engineering details like ID design, relative imports, HMR, and CSS dependencies on its own.

A Minimal Version

If we only look at the core mechanism, it can start with this small plugin:

import fg from 'fast-glob';
import type { Plugin } from 'vite';
 
export function miniMpaPlugin(): Plugin {
  const pages = new Map<string, string>();
 
  return {
    name: 'mini-mpa',
    async configResolved(config) {
      const configs = await fg('src/pages/*/config.toml', { cwd: config.root });
      for (const f of configs) {
        const id = path.basename(path.dirname(f));
        pages.set(id, path.join(config.root, path.dirname(f), 'index.tsx'));
      }
    },
    resolveId(id) {
      if (id.startsWith('virtual:page/')) return '\0' + id;
    },
    load(id) {
      if (!id.startsWith('\0virtual:page/')) return;
      const pageId = id.replace('\0virtual:page/', '');
      const entry = pages.get(pageId);
      if (!entry) return;
      return `
        import { createRoot } from 'react-dom/client';
        import App from '${entry}';
        createRoot(document.getElementById('root')).render(<App />);
      `;
    }
  };
}

It does only three things: scan pages, recognize virtual modules, and return entry code. In a real project, you would gradually add SSR templates, placeholder replacement, HMR watch, CSS tracking, and multiple rendering modes.

Summary

Virtual modules themselves are not complex; the core is that resolveId recognizes the module and load hands the code to Vite. The real effort lies in the engineering challenges that follow: how to name module IDs stably, how to resolve relative paths between virtual modules, how to trigger appropriate granularity of reloads on configuration changes, and how to collect CSS dependencies under SSR.

Once these issues are bundled into the plugin, page development becomes much lighter. Adding a new page only requires placing a config.toml and the business entry, and the build system will complete the rest—entries, templates, routes, and runtime loading logic—based on the declaration. This is the most practical aspect of virtual modules in an MPA project: they take the repetitive entry maintenance out of page code and centralize it into an evolvable plugin.

0 Comments

Leave a Comment