Vue In-Browser Compiler Utilities

Common errors

• ReferenceError: Vue is not defined

  cause The compiled Vue component code is trying to access a global `Vue` object or specific Vue APIs, but they are not available in the current execution context (e.g., in a `script` tag without Vue loaded, or within `evaluate` without `Vue` passed in).
  fix Ensure Vue is loaded in the global scope (e.g., via a `<script>` tag before your compiled code) or explicitly pass the `Vue` instance into the context object when using `evaluate`.

• TypeError: Cannot read properties of undefined (reading 'script') (or similar for 'template')

  cause The `parseComponent` function received an invalid or malformed string that could not be parsed as a Vue Single File Component (SFC), resulting in an incomplete `parsed` object.
  fix Verify that the input string passed to `parseComponent` is a well-formed Vue SFC, including `<template>` and `<script>` tags, and that there are no syntax errors preventing basic parsing.

• SyntaxError: Unexpected token '<' (or 'JSX element 'div' has no corresponding closing tag')

  cause JSX syntax within your component's `<script>` or render function is not being correctly transpiled by `buble` (the underlying JSX compiler used by `vue-inbrowser-compiler`). This often indicates a missing or misconfigured JSX compilation step.
  fix Ensure your `vue-inbrowser-compiler` configuration correctly enables JSX processing via `buble`. If using a build tool, confirm that `vue-inbrowser-compiler`'s internal JSX handling is active and not being overridden by another preprocessor.

Warnings

• gotcha This package is tightly coupled with `vue-inbrowser-compiler` and the broader `vue-styleguidist` ecosystem. While it provides utilities, its core function is to support the in-browser compilation process, and it's not typically used in isolation for general Vue development.
  Fix: Ensure `vue-inbrowser-compiler` is also installed and correctly configured when using this package for its intended purpose of in-browser compilation.
• gotcha Compatibility with Vue 3.x is maintained, with explicit fixes for `vue@3.3.2` and later versions. However, users employing older Vue 3 releases or specific edge cases in Vue 2 might encounter subtle compatibility issues.
  Fix: Always use the latest patch version of `vue-inbrowser-compiler-utils` and its companion `vue-inbrowser-compiler`. Verify compatibility with your specific Vue version, especially when encountering unexpected runtime errors.
• gotcha JSX compilation is handled via `buble` within the `vue-inbrowser-compiler`. This means it supports a specific flavor of JSX (Buble's JSX transform), which may have differences or limitations compared to Babel's JSX or Vue's official compiler transforms. Advanced JSX features or specific Babel plugins might not be supported out-of-the-box.
  Fix: Review `buble` documentation for supported JSX features. For complex JSX needs, consider alternative compilation strategies or adjust your JSX usage to fit `buble`'s capabilities.
• gotcha The `evaluate` function requires a runtime Vue instance in its context to properly render components. In a browser environment, this typically means `Vue` must be globally available. In server-side rendering or isolated environments, `Vue` must be explicitly passed into the context object.
  Fix: When calling `evaluate`, ensure that `Vue` (or the necessary `createApp` function for Vue 3) is correctly provided in the `context` object to allow the component to initialize and render.

Install

• npm install vue-inbrowser-compiler-utils npm
• yarn add vue-inbrowser-compiler-utils yarn
• pnpm add vue-inbrowser-compiler-utils pnpm

Imports

• parseComponent
  wrong:

  const { parseComponent } = require('vue-inbrowser-compiler-utils');

  correct:

  import { parseComponent } from 'vue-inbrowser-compiler-utils';

  Primarily an ESM module. CommonJS require() is generally not recommended and might require specific transpilation for older Node.js versions.
• cleanVueSrc
  wrong:

  import cleanVueSrc from 'vue-inbrowser-compiler-utils/cleanVueSrc';

  correct:

  import { cleanVueSrc } from 'vue-inbrowser-compiler-utils';

  CleanVueSrc is a named export. Direct path imports for specific utilities are not the standard approach for this package.
• evaluate
  wrong:

  import { runCode } from 'vue-inbrowser-compiler-utils';

  correct:

  import { evaluate } from 'vue-inbrowser-compiler-utils';

  The `evaluate` function, while re-exported from `vue-inbrowser-compiler-eval-utils`, is a key utility for running compiled code in a browser context. Ensure the global `Vue` object or a specific `Vue` instance is available in the evaluation context.

Quickstart

This quickstart demonstrates how to parse a Vue SFC string (potentially with JSX) using `parseComponent` from `vue-inbrowser-compiler-utils` and then compile it with `vue-inbrowser-compiler` for in-browser evaluation.

import { parseComponent, evaluate } from 'vue-inbrowser-compiler-utils';
import { compile } from 'vue-inbrowser-compiler'; // vue-inbrowser-compiler is a companion package

// Simulate a Vue component string, potentially with JSX in the render function
const vueComponentSrc = `
<template>
  <div>Hello from {{ name }}!</div>
</template>

<script setup>
import { ref } from 'vue';

const name = ref('Quickstart');

// Example of JSX usage in a render function (requires compilation configuration)
const render = () => (<div class="jsx-example">JSX says Hi!</div>);
</nscript>

<style scoped>
.jsx-example { color: blue; }
</style>
`;

// Step 1: Parse the Vue component using vue-inbrowser-compiler-utils
const parsed = parseComponent(vueComponentSrc);

console.log('Parsed Component Script:', parsed.script);
console.log('Parsed Component Template:', parsed.template);

// Step 2: (Optional, if you want to clean up the source further)
// const cleanedScript = cleanVueSrc(parsed.script);

// Step 3: Compile the parsed component (this step uses vue-inbrowser-compiler)
// In a real browser environment, 'Vue' must be globally available or injected.
const compiledCode = compile(parsed.script, parsed.template, { 
  is         : parsed.scriptLang === 'ts' ? 'ts' : 'js',
  templateLang: parsed.templateLang,
  // Ensure buble is configured for JSX if needed, e.g., via compilerOptions
  compilerOptions: {
    isTS: parsed.scriptLang === 'ts',
    // other options for buble/jsx compilation
  }
});

console.log('Compiled Code:', compiledCode.script);

// Step 4: Evaluate the compiled code in a browser-like environment
// This is typically done in the browser; for Node.js, it simulates.
// In a browser, you would typically mount this result.
try {
  const componentInstance = evaluate(compiledCode.script, compiledCode.template, { 
    // context for the evaluation, e.g., global Vue instance
    Vue: typeof Vue !== 'undefined' ? Vue : {} // Provide Vue if available
  });
  console.log('Component evaluation successful (check browser for full effect).');
  // In a real browser app, you would now mount componentInstance
} catch (e) {
  console.error('Error during evaluation:', e);
}