vite-plugin-office-addin-bun

Office Add-ins development using Vite with Bun and Node.js support.

Build your Office Add-in with blazing-fast performance. This plugin automatically copies and transforms manifest.xml files to your build output with intelligent runtime detection for optimal performance.

Note: This project is based on and extends vite-plugin-office-addin by Jozef Izso, adding dual runtime support for both Bun and Node.js environments.

✨ Features

• 🚀 Dual Runtime Support - Works seamlessly with both Bun and Node.js
• ⚡ Bun-First Optimization - Uses native Bun APIs when available for maximum performance
• 🔄 Automatic Runtime Detection - Intelligently switches between Bun and Node.js file operations
• 🌍 Cross-Platform - Works on Windows, macOS, and Linux
• 🎯 URL Replacement - Automatically replaces development URLs with production URLs
• 📁 Flexible Manifest Paths - Support for custom manifest file locations
• 🔧 Environment Variables - Configure URLs through environment variables
• 📝 TypeScript Support - Full TypeScript definitions included

📋 Requirements

• Bun (latest) or Node.js ≥18.0.0
• Vite ≥7.0.6

🚀 Getting Started

Install the vite-plugin-office-addin-bun to your Office Add-in project.

With Bun (Recommended)

bun install --save-dev vite-plugin-office-addin-bun

With npm/yarn/pnpm

npm install --save-dev vite-plugin-office-addin-bun
# or
yarn add --dev vite-plugin-office-addin-bun
# or
pnpm add --save-dev vite-plugin-office-addin-bun

Configure Vite

Use the plugin in your vite.config.js file:

// vite.config.js
import { defineConfig } from 'vite'
import officeAddin from 'vite-plugin-office-addin-bun'

export default defineConfig({
  plugins: [officeAddin()]
})

⚡ Runtime Compatibility

This plugin automatically detects your runtime environment and optimizes accordingly:

🔥 Bun Runtime (Recommended)

When running with Bun, the plugin uses:

• Bun.resolveSync() for ultra-fast path resolution
• Bun.file() for native file operations
• Zero Node.js dependencies for maximum performance

🟢 Node.js Runtime

When running with Node.js, the plugin gracefully falls back to:

• node:path module for path operations
• node:fs/promises for file operations
• Dynamic imports to minimize bundle size

Performance Tip: For the best development experience, use Bun as your runtime. The plugin will automatically leverage Bun's native APIs for significantly faster file operations.

🔧 Advanced Usage

🔄 URL Replacement

Transform your development URLs to production URLs automatically during build. The plugin supports both direct configuration and environment variables.

Using Plugin Configuration

// vite.config.js
import { defineConfig } from 'vite'
import officeAddin from 'vite-plugin-office-addin-bun'

export default defineConfig({
  plugins: [officeAddin({
    devUrl: 'https://localhost:3000',
    prodUrl: 'https://office-addin.contoso.com'
  })]
})

Using Environment Variables

Configure URLs through environment variables for different deployment environments:

// vite.config.js + .env files
import { defineConfig } from 'vite'
import officeAddin from 'vite-plugin-office-addin-bun'

export default defineConfig({
  plugins: [officeAddin()]
})

# .env.production
ADDIN_DEV_URL=https://localhost:3000
ADDIN_PROD_URL=https://office-addin.contoso.com

# .env.staging  
ADDIN_DEV_URL=https://localhost:3000
ADDIN_PROD_URL=https://staging.office-addin.contoso.com

Configuration Priority: Plugin options take precedence over environment variables. Use plugin configuration for static setups and environment variables for dynamic deployments.

When you run vite build, the generated manifest.xml file will have production addresses automatically replaced.

📁 Custom Manifest Paths

If your manifest.xml file is not in the project root, specify a custom path:

// vite.config.js
import { defineConfig } from 'vite'
import officeAddin from 'vite-plugin-office-addin-bun'

export default defineConfig({
  plugins: [officeAddin({
    path: 'src/other-folder/manifest.xml'
  })]
})

📄 Multiple Manifests

Copy multiple manifest files for different Office applications or environments:

// vite.config.js
import { defineConfig } from 'vite'
import officeAddin from 'vite-plugin-office-addin-bun'

export default defineConfig({
  plugins: [
    officeAddin({ path: 'manifests/excel-addin.xml' }),
    officeAddin({ path: 'manifests/word-addin.xml' }),
    officeAddin({ path: 'manifests/powerpoint-addin.xml' }),
  ]
})

📚 API Reference

Plugin Options

interface Options {
  /**
   * Path to the manifest file relative to project root
   * @default "manifest.xml"
   */
  path?: string;
  
  /**
   * Development URL to be replaced in the manifest
   * Takes precedence over ADDIN_DEV_URL environment variable
   */
  devUrl?: string;
  
  /**
   * Production URL to replace the development URL
   * Takes precedence over ADDIN_PROD_URL environment variable  
   */
  prodUrl?: string;
}

Environment Variables

| Variable | Description | Example | |----------|-------------|---------| | ADDIN_DEV_URL | Development server URL | https://localhost:3000 | | ADDIN_PROD_URL | Production deployment URL | https://office-addin.contoso.com |

💡 Examples

Basic Excel Add-in Setup

// vite.config.js
import { defineConfig } from 'vite'
import officeAddin from 'vite-plugin-office-addin-bun'

export default defineConfig({
  plugins: [
    officeAddin({
      devUrl: 'https://localhost:3000',
      prodUrl: 'https://excel-addin.contoso.com'
    })
  ],
  server: {
    port: 3000,
    https: true
  }
})

Multi-Environment Setup

// vite.config.js
import { defineConfig } from 'vite'
import officeAddin from 'vite-plugin-office-addin-bun'

export default defineConfig(({ mode }) => ({
  plugins: [
    officeAddin({
      path: `manifests/manifest.${mode}.xml`
    })
  ]
}))

🔧 Troubleshooting

Common Issues

Q: Plugin doesn't replace URLs in my manifest

• Ensure devUrl and prodUrl are both configured
• Check that the URLs in your manifest exactly match the devUrl value
• Verify the manifest file exists at the specified path

Q: Build fails with "manifest.xml file does not exist"

• Check the path option points to the correct manifest location
• Ensure the manifest file exists relative to your project root
• Verify file permissions allow reading the manifest

Q: Performance seems slow

• Consider using Bun runtime for optimal performance
• The plugin automatically uses the fastest available APIs for your runtime

Debug Mode

Set the environment variable to enable verbose logging:

ADDIN_DEBUG=1 bun run build

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

🙏 Acknowledgments

This project is based on vite-plugin-office-addin by Jozef Izso. We extend our gratitude for the foundational work that made this Bun-enhanced version possible.

📝 License

Licensed under MIT License. Copyright © 2024 Sebastian Jara