{"id":15895,"library":"vibe-coding-bundler","title":"Vibe Coding Bundler","description":"Vibe Coding Bundler is a browser-based JavaScript and TypeScript bundler that leverages esbuild-wasm to perform compilation entirely within the browser environment, eliminating the need for a server. Currently at version 1.0.0, its release cadence is feature-driven as an initial offering. Key differentiators include first-class support for standard import maps, a virtual file system for in-memory bundling, and a robust plugin system with `onResolve` and `onLoad` hooks. It supports various output formats (ESM, IIFE, CJS), generates sourcemaps, and performs tree shaking. While it transpiles TypeScript and JSX, it does not perform type checking. An optional Node.js CLI is also provided for local development workflows.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/NimbleLabs/vibe-coding-bundler","tags":["javascript","bundler","esbuild","esbuild-wasm","wasm","browser","import-map","esm","typescript"],"install":[{"cmd":"npm install vibe-coding-bundler","lang":"bash","label":"npm"},{"cmd":"yarn add vibe-coding-bundler","lang":"bash","label":"yarn"},{"cmd":"pnpm add vibe-coding-bundler","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for the optional Node.js CLI functionality.","package":"commander","optional":true},{"reason":"Peer dependency required for the optional Node.js CLI functionality, likely for file system globbing.","package":"glob","optional":true}],"imports":[{"note":"Main factory function to create a new bundler instance. The package ships as ESM.","wrong":"const { createBundler } = require('vibe-coding-bundler');","symbol":"createBundler","correct":"import { createBundler } from 'vibe-coding-bundler';"},{"note":"Async function that loads and initializes esbuild-wasm. Must be called once before any bundling operations.","wrong":"require('vibe-coding-bundler').initialize();","symbol":"initialize","correct":"import { initialize } from 'vibe-coding-bundler';"},{"note":"For TypeScript projects, import types using `import type` to avoid runtime overhead.","wrong":"import { BundlerOptions } from 'vibe-coding-bundler';","symbol":"BundlerOptions","correct":"import type { BundlerOptions } from 'vibe-coding-bundler';"}],"quickstart":{"code":"import { createBundler, initialize } from 'vibe-coding-bundler';\n\nasync function runBundler() {\n  // Initialize esbuild-wasm (only needed once per application lifetime)\n  await initialize();\n\n  // Create a bundler instance with a custom fetcher for external modules\n  const bundler = createBundler({\n    fetcher: async (url) => {\n      // Example: add custom headers or caching logic\n      const response = await fetch(url);\n      if (!response.ok) {\n        throw new Error(`Failed to fetch ${url}: ${response.statusText}`);\n      }\n      return { contents: await response.text() };\n    },\n  });\n\n  // Define virtual files and an import map for resolving bare specifiers\n  const files = {\n    '/src/index.ts': `\n      import { useState } from 'react';\n      export function App() {\n        const [count, setCount] = useState(0);\n        return <button onClick={() => setCount(c => c + 1)}>{count}</button>;\n      }\n      console.log('App loaded');\n    `,\n  };\n\n  const importMap = {\n    imports: {\n      react: 'https://esm.sh/react@18',\n      'react/': 'https://esm.sh/react@18/' // Important for subpaths\n    },\n  };\n\n  // Bundle the code\n  const result = await bundler.bundle(\n    '/src/index.ts', // Entry point\n    files,           // Virtual file system\n    importMap,       // Import map configuration\n    {\n      format: 'esm',\n      minify: true,\n      sourcemap: 'inline',\n      target: 'es2020'\n    }\n  );\n\n  // Log the bundled output (typically a single output file 'index.js')\n  console.log(result.outputFiles['index.js']);\n\n  // Example: Run the bundled code in a browser context\n  const script = document.createElement('script');\n  script.type = 'module';\n  script.textContent = result.outputFiles['index.js'];\n  document.body.appendChild(script);\n}\n\nrunBundler().catch(console.error);\n","lang":"typescript","description":"This quickstart demonstrates how to set up and use the bundler in a browser environment, including initializing esbuild-wasm, providing virtual files, configuring import maps for CDN dependencies like React, and outputting a minified ESM bundle with an inline sourcemap. It also shows how to execute the bundled output."},"warnings":[{"fix":"Ensure `await initialize()` is called only once at application startup or before the first bundler usage.","message":"The `initialize()` function, which loads the esbuild-wasm module, must be called exactly once before any `createBundler` or `bundle` operations. Failing to call it will result in errors, and calling it multiple times is redundant and can cause unexpected behavior or performance issues.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Consider pre-loading the WASM module if critical for user experience, or provide a loading indicator during the `initialize()` phase. Ensure your server correctly serves WASM files with appropriate MIME types (e.g., `application/wasm`).","message":"When using `esbuild-wasm` in a browser, the initial download and compilation of the WebAssembly module can be substantial (several megabytes). This might impact the initial load time of your application. Subsequent uses are cached.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Integrate `tsc --noEmit` or a similar type checker into your project's build or linting scripts to ensure type correctness.","message":"The bundler uses esbuild for transpilation of TypeScript and JSX, but it does not perform type checking. This means syntax errors related to types will be ignored, and you will need a separate type-checking step (e.g., `tsc --noEmit`) in your development workflow if type safety is required.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Double-check import map syntax against the WICG specification and the examples provided. Use a 'resolver' utility or local testing to verify paths are correctly mapped. Pay attention to trailing slashes for directory-like imports.","message":"Import maps require careful configuration, especially for bare specifiers and subpaths. A common mistake is forgetting the trailing slash for prefix matches (e.g., `lodash/` -> `https://esm.sh/lodash-es/`) or incorrect versioning that leads to module resolution failures.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Add `await initialize();` at the very beginning of your application logic, ensuring it completes before any `createBundler` or `bundle` calls.","cause":"Attempting to create a bundler or bundle files before the esbuild-wasm module has been loaded and initialized.","error":"Error: The 'esbuild-wasm' package was not initialized. Call `await initialize()` first."},{"fix":"Verify that your `importMap` object correctly defines the bare specifier, including any necessary trailing slashes for subpath imports. Ensure the URL provided in the import map is accessible and returns valid JavaScript.","cause":"The bundler could not find a resolution for a bare module specifier (e.g., `import 'react'`) either in the provided virtual file system or via the configured import maps.","error":"Error: Could not resolve \"react\" (or similar bare specifier)"},{"fix":"Check the URL for correctness and ensure the CDN is accessible. If using a custom `fetcher`, add more robust error handling and logging. For browser usage, inspect the network tab for specific HTTP errors and check browser console for CORS warnings.","cause":"The custom `fetcher` provided to `createBundler` (or the default fetch mechanism) failed to retrieve an external module, likely due to a network issue, CORS policy, or an incorrect URL.","error":"TypeError: Failed to fetch (or similar network error)"}],"ecosystem":"npm"}