vite-utopian

A Vite post-processing tool that enhances your existing build with a sustainable alternative. It creates an additional optimized mini build with externalized dependencies loaded from esm.sh CDNs using import maps, then updates your index.html to conditionally load the based on the sustainable-extension-loaded attribute on the html document. This ensures the mini build is only loaded when the sustainable browser extension is installed.

Features

�️ Dual Build System - Creates both standard and optimized builds in a single step
🌍 Smart Loading - Automatically selects build based on window.__SUSTAINABLE_BUILD__ flag
📦 Import Maps - Generates HTML import maps with exact dependency versions from lock files
⚡ CDN Externalization - Reduces bundle size by loading dependencies from extension
🔧 Customizable - Configure CDN mappings and exclusions per project
🚀 Post-Build Processing - Runs after your normal Vite build completes

Installation

npm install -D vite-utopian

Note:

• Install as a dev dependency (-D flag)
• Requires Vite 4+ as a peer dependency
• This is a post-processing tool that runs after your normal Vite build

Usage

As a Post-Processing Tool (Recommended)

Add to your package.json scripts:

{
  "scripts": {
    "build": "vite build",
    "postbuild": "vite-utopian"
  }
}

Then run your normal build:

npm run build
# vite-utopian runs automatically after build completes

CLI Options

# With custom options
npx vite-utopian --outDir dist --exclude react,react-dom

Configuration

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | root | string | process.cwd() | Root directory of the project | | outDir | string | 'dist' | Output directory for builds | | exclude | string[] | [] | Packages to exclude from externalization |

CDN Mappings

Create a cdn-mappings.json file to define which packages should be loaded from CDNs:

{
  "react": "https://esm.sh/react@{version}",
  "react-dom": "https://esm.sh/react-dom@{version}",
  "framer-motion": "https://esm.sh/framer-motion@{version}",
  "clsx": "https://esm.sh/clsx@{version}"
}

The {version} placeholder will be replaced with the exact version from your lock file.

How It Works

1. Runs After Build - Processes your existing Vite build output
2. Dependency Analysis - Reads lock files to find exact versions of all dependencies
3. Mini Build Creation - Creates optimized build with CDN-mapped dependencies in dist/mini/
4. Import Map Generation - Injects import maps for externalized dependencies
5. Index.html Enhancement - Updates your index.html with conditional loading:
   • When window.__SUSTAINABLE_BUILD__ is true: loads standard build
   • Otherwise: loads mini build with CDN dependencies
6. Original Backup - Keeps your original index.html as index.original.html

Example Output

After running the post-processor, your dist/ directory will contain:

dist/
├── index.html          # Smart loader with conditional loading
├── assets/            # Standard build files
│   ├── index-xxxxx.js
│   └── index-xxxxx.css
└── mini/              # Optimized build files
    └── index-xxxxx.js

The generated index.html includes:

<script type="importmap">
  {
    "imports": {
      "react": "https://esm.sh/[email protected]",
      "react-dom": "https://esm.sh/[email protected]"
    }
  }
</script>

<script type="module">
  await Promise.resolve(
    setTimeout(async () => {
      if (document.documentElement.hasAttribute('sustainable-extension-loaded')) {
        await import("/assets/index-xxxxx.js");
      } else {
        await import("/mini/index-xxxxx.js");
      }
    }, 10)
  );
</script>

Benefits

👶 Reduced Bundle Size

Dependencies are externalized and loaded from a browser extension.

🌿 Sustainable Web

The more applications use this plugin, the more dependencies can be cached across domains and the more energy will be saved.

Requirements

• Vite 4+
• Node.js 18+
• Modern browsers with import maps support

License

MIT © Ludwig Schubert

Contributing

Issues and pull requests are welcome on GitHub.