a5c-ai/babysitter / library/specializations/ai-agents-conversational/skills/single-file-bundling
single-file-bundling
VerifiedConfigure Vite with vite-plugin-singlefile for mandatory single-file HTML bundling of MCP Apps. All assets (JS, CSS, images, fonts) must be inlined into a single HTML file for sandboxed iframe compatibility.
SKILL.md
View on GitHub---
name: single-file-bundling
description: Configure Vite with vite-plugin-singlefile for mandatory single-file HTML bundling of MCP Apps. All assets (JS, CSS, images, fonts) must be inlined into a single HTML file for sandboxed iframe compatibility.
allowed-tools: Read, Write, Edit, Bash
graph:
domains: [domain:software-engineering]
specializations: [specialization:ai-agents-conversational]
skillAreas: [skill-area:mcp-server-implementation, skill-area:mcp-tool-design]
roles: [role:backend-engineer, role:fullstack-engineer]
workflows: [workflow:feature-development]
---
# single-file-bundling
Configure Vite with vite-plugin-singlefile to produce a single self-contained HTML file for MCP Apps running in sandboxed iframes.
## Overview
MCP Apps run in sandboxed iframes with no same-origin server. This means:
- **No relative asset URLs** -- `<script src="./main.js">` will not resolve
- **No CSS file imports** -- `<link href="./styles.css">` will not load
- **No image/font paths** -- relative paths to assets will fail
- The **entire UI must be a single HTML file** with all JS, CSS, images, and fonts inlined
`vite-plugin-singlefile` handles this by inlining all assets into one HTML file during the Vite build. This is **mandatory** for MCP Apps -- without it, the app will show a blank iframe.
## Capabilities
### Vite Configuration
- Configure Vite with `vite-plugin-singlefile`
- Set correct `base`, `build.outDir`, and entry point
- Handle framework-specific Vite plugins (React, Vue, Svelte, Preact, Solid)
### Single HTML File Output
- All JavaScript inlined as `<script>` tags
- All CSS inlined as `<style>` tags
- All images converted to data URIs
- All fonts converted to base64
### Two-Phase Build Setup
- Phase 1: Vite bundles UI into `dist/mcp-app.html`
- Phase 2: TypeScript compiles server into `dist/server.js`
- Combined build script orchestrates both phases
### Hybrid Build Pipelines
- Add MCP build alongside existing standalone build
- Separate Vite configs for MCP and standalone if needed
- Separate HTML entry points (`mcp-app.html` vs `index.html`)
## Usage
### Basic Vite Configuration
```typescript
// vite.config.ts
import { defineConfig } from 'vite';
import { viteSingleFile } from 'vite-plugin-singlefile';
export default defineConfig({
plugins: [viteSingleFile()],
build: {
outDir: 'dist',
// Entry point for the MCP App UI
rollupOptions: {
input: 'mcp-app.html',
},
},
});
```
### React Vite Configuration
```typescript
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { viteSingleFile } from 'vite-plugin-singlefile';
export default defineConfig({
plugins: [react(), viteSingleFile()],
build: {
outDir: 'dist',
rollupOptions: {
input: 'mcp-app.html',
},
},
});
```
### Vue Vite Configuration
```typescript
// vite.config.ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { viteSingleFile } from 'vite-plugin-singlefile';
export default defineConfig({
plugins: [vue(), viteSingleFile()],
build: {
outDir: 'dist',
rollupOptions: {
input: 'mcp-app.html',
},
},
});
```
### Svelte Vite Configuration
```typescript
// vite.config.ts
import { defineConfig } from 'vite';
import { svelte } from '@sveltejs/vite-plugin-svelte';
import { viteSingleFile } from 'vite-plugin-singlefile';
export default defineConfig({
plugins: [svelte(), viteSingleFile()],
build: {
outDir: 'dist',
rollupOptions: {
input: 'mcp-app.html',
},
},
});
```
### HTML Entry Point
```html
<!-- mcp-app.html -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>My MCP App</title>
</head>
<body>
<div id="root"></div>
<script type="module" src="/src/main.ts"></script>
</body>
</html>
```
For React (`.tsx` entry):
```html
<!-- mcp-app.html -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>My MCP App</title>
</head>
<body>
<div id="root"></div>
<script type="module" src="/src/main.tsx"></script>
</body>
</html>
```
### Package.json Build Scripts
```json
{
"scripts": {
"build:ui": "vite build",
"build:server": "tsc --project tsconfig.server.json",
"build": "npm run build:ui && npm run build:server",
"dev": "concurrently \"vite\" \"tsx watch src/server.ts\"",
"serve": "tsx src/server.ts"
}
}
```
### Server Reading the Bundled HTML
```typescript
import fs from 'fs';
import path from 'path';
import { registerAppResource, RESOURCE_MIME_TYPE } from '@modelcontextprotocol/ext-apps';
// Read the single-file bundle produced by Vite
const bundledHtml = fs.readFileSync(
path.join(__dirname, '../dist/mcp-app.html'),
'utf-8'
);
registerAppResource(server, {
uri: 'app:///my-app',
name: 'My App',
mimeType: RESOURCE_MIME_TYPE,
async read() {
return {
contents: [{
uri: 'app:///my-app',
mimeType: RESOURCE_MIME_TYPE,
text: bundledHtml,
}],
};
},
});
```
### Hybrid Build Pipeline (MCP + Standalone)
When converting a web app that already has its own build:
```typescript
// vite.config.mcp.ts -- MCP-specific build config
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { viteSingleFile } from 'vite-plugin-singlefile';
export default defineConfig({
plugins: [react(), viteSingleFile()],
build: {
outDir: 'dist/mcp',
rollupOptions: {
input: 'mcp-app.html', // Separate entry from index.html
},
},
});
```
```json
{
"scripts": {
"build:standalone": "vite build",
"build:mcp:ui": "vite build --config vite.config.mcp.ts",
"build:mcp:server": "tsc --project tsconfig.server.json",
"build:mcp": "npm run build:mcp:ui && npm run build:mcp:server",
"build:all": "npm run build:standalone && npm run build:mcp"
}
}
```
### Installing Dependencies
```bash
# Required dev dependencies
npm install -D vite vite-plugin-singlefile
# Framework-specific (pick one)
npm install -D @vitejs/plugin-react # React
npm install -D @vitejs/plugin-vue # Vue
npm install -D @sveltejs/vite-plugin-svelte # Svelte
```
## Common Pitfalls
1. **Forgetting vite-plugin-singlefile**: Without it, Vite produces separate JS/CSS files that won't load in the sandboxed iframe.
2. **Wrong entry point**: The `rollupOptions.input` must point to the MCP App HTML file, not the standalone `index.html`.
3. **Large bundle size**: Inline images and fonts increase HTML file size. Consider optimizing assets or using CSP `resourceDomains` for large external resources.
4. **TypeScript server in Vite output**: The server should be compiled separately (Phase 2), not included in the Vite bundle.
5. **Missing `type="module"`**: The `<script>` tag in the HTML entry must have `type="module"` for Vite to process it.
## Verification Checklist
- [ ] `vite-plugin-singlefile` in devDependencies
- [ ] `vite.config.ts` imports and uses `viteSingleFile()`
- [ ] `rollupOptions.input` points to `mcp-app.html` (not `index.html`)
- [ ] `mcp-app.html` entry point exists with `<script type="module">`
- [ ] `npm run build:ui` produces `dist/mcp-app.html`
- [ ] `dist/mcp-app.html` is self-contained (no external `src=` or `href=` to files)
- [ ] Build scripts defined: `build:ui`, `build:server`, `build`
- [ ] Server reads from `dist/mcp-app.html` at runtime
- [ ] Framework-specific Vite plugin included (if applicable)
## Task Definition
```javascript
const singleFileBundlingTask = defineTask({
name: 'single-file-bundling',
description: 'Configure Vite with vite-plugin-singlefile for MCP App',
inputs: {
framework: { type: 'string', required: true },
entryPoint: { type: 'string', default: 'mcp-app.html' },
outDir: { type: 'string', default: 'dist' },
hybrid: { type: 'boolean', default: false }
},
outputs: {
viteConfigCreated: { type: 'boolean' },
entryPointCreated: { type: 'boolean' },
buildScriptsAdded: { type: 'boolean' },
artifacts: { type: 'array' }
},
async run(inputs, taskCtx) {
return {
kind: 'skill',
title: `Configure single-file bundling (${inputs.framework})`,
skill: {
name: 'single-file-bundling',
context: {
framework: inputs.framework,
entryPoint: inputs.entryPoint,
outDir: inputs.outDir,
hybrid: inputs.hybrid,
instructions: [
'Install vite and vite-plugin-singlefile',
'Create vite.config.ts with framework plugin and singlefile',
'Create mcp-app.html entry point',
'Add build scripts to package.json',
inputs.hybrid ? 'Create separate MCP Vite config alongside existing build' : null,
'Build and verify single-file output'
].filter(Boolean)
}
},
io: {
inputJsonPath: `tasks/${taskCtx.effectId}/input.json`,
outputJsonPath: `tasks/${taskCtx.effectId}/result.json`
}
};
}
});
```
## Applicable Processes
- create-mcp-app.js
- add-app-to-mcp-server.js
- convert-web-app-to-mcp.js
## External Dependencies
- Vite (build tool)
- vite-plugin-singlefile (asset inlining)
- Framework-specific Vite plugins (@vitejs/plugin-react, @vitejs/plugin-vue, etc.)
## References
- [vite-plugin-singlefile](https://github.com/nicogulo/vite-plugin-singlefile)
- [Vite Documentation](https://vitejs.dev/)
- [MCP Apps SDK Examples](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples)
## Related Skills
- mcp-app-scaffolding
- mcp-tool-resource-pattern
- mcp-app-verification
## Related Agents
- mcp-app-architect
- mcp-ui-developer
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |