Vue In-Browser Compiler Independent Utilities

Common errors

• TypeError: Cannot read properties of undefined (reading 'script')

  cause The `compile` function might have failed or returned an unexpected structure, often due to malformed Vue code input or an incompatible compiler configuration.
  fix Verify that the input `vueComponentCode` is valid and well-formed. Ensure any configuration passed to `compile` (e.g., `BubleConfig`) is correct and compatible with the code. Log the full output of `compile` to inspect the actual return value.

• SyntaxError: Unexpected token '<'

  cause This usually occurs when trying to directly execute a string containing HTML/Vue template syntax as JavaScript. The browser or Node.js runtime expects pure JavaScript, not template code. This package's `compile` output is JavaScript, but the raw input is not.
  fix Do not execute raw Vue component strings directly. Use `isCodeVueSfc` to identify Vue code, and then `compile` it into executable JavaScript. The `script` property of the `compile` output should then be used appropriately, often `new Function(compiledResult.script)()` to get component options.

Warnings

• breaking Major version upgrades of `vue-inbrowser-compiler-independent-utils` may introduce breaking changes, particularly if underlying parsing or compilation logic, or supported Vue versions (e.g., Vue 2 to Vue 3 syntax), are updated. Always review the full changelog for the `vue-styleguidist` monorepo.
  Fix: Consult the `vue-styleguidist` GitHub repository for specific migration guides. Changes in Vue's reactivity system (Vue 2 vs Vue 3) or template compilation can often lead to breakage in tools that parse Vue code.
• gotcha This package, despite its name, is designed to work in conjunction with the broader `vue-inbrowser-compiler` ecosystem. While it is 'Vue independent' in its direct runtime dependencies, its utilities are tailored for Vue-specific code processing. Misunderstanding its scope can lead to incorrect usage in non-Vue contexts or expecting it to fully compile Vue components without the `vue-inbrowser-compiler` parent package.
  Fix: Ensure you understand the role of this package within the `vue-styleguidist` toolchain. For full in-browser compilation and execution of Vue components, you typically need `vue-inbrowser-compiler` itself, which leverages these utilities.
• gotcha When using `compile` or other code transformation utilities, be aware that the output might depend on the target Vue version (Vue 2 vs Vue 3) and the internal compiler configuration. Syntax changes between Vue major versions (e.g., `v-model` usage, functional components, render function API) can significantly alter compilation results.
  Fix: Provide appropriate configuration to the compiler functions, if available, to match your target Vue version. Test compilation thoroughly against your specific Vue runtime environment. Consider using `@vue/compat` for Vue 2 to Vue 3 migrations.

Install

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

Imports

• compile
  wrong:

  const { compile } = require('vue-inbrowser-compiler-independent-utils')

  correct:

  import { compile } from 'vue-inbrowser-compiler-independent-utils'

  Primarily designed for ESM usage. The `compile` function from this package (or its parent `vue-inbrowser-compiler`) is used to convert Vue code strings into executable JavaScript component options.
• isCodeVueSfc
  wrong:

  import isCodeVueSfc from 'vue-inbrowser-compiler-independent-utils'

  correct:

  import { isCodeVueSfc } from 'vue-inbrowser-compiler-independent-utils'

  This utility function detects if a given code string represents a Vue Single File Component (SFC) by checking for <template> or <script> tags. It is a named export.
• addScopedStyle
  wrong:

  import { AddScopedStyle } from 'vue-inbrowser-compiler-independent-utils'

  correct:

  import { addScopedStyle } from 'vue-inbrowser-compiler-independent-utils'

  Used for processing and adding scoped CSS styles, a common task in Vue component compilation. It's a named export, ensure correct casing.

Quickstart

This quickstart demonstrates how to use `isCodeVueSfc` to detect Vue SFCs and `compile` to process Vue component code strings into script and style parts suitable for in-browser compilation.

import { compile, isCodeVueSfc } from 'vue-inbrowser-compiler-independent-utils';

// Example Vue component code as a string
const vueComponentCode = `
<template>
  <div class="message">
    <h1>{{ msg }}</h1>
    <button @click="increment">Count: {{ count }}</button>
  </div>
</template>

<script lang="ts">
export default {
  name: 'MyComponent',
  data() {
    return {
      msg: 'Hello from Independent Utils!',
      count: 0
    };
  },
  methods: {
    increment() {
      this.count++;
    }
  }
};
</script>

<style scoped>
.message {
  color: #42b983;
  font-family: Arial, sans-serif;
  border: 1px solid #ddd;
  padding: 20px;
  border-radius: 8px;
  text-align: center;
}
h1 {
  margin-bottom: 15px;
}
button {
  background-color: #3498db;
  color: white;
  padding: 10px 20px;
  border: none;
  border-radius: 5px;
  cursor: pointer;
  font-size: 16px;
}
button:hover {
  background-color: #2980b9;
}
</style>
`;

// Check if it's an SFC
const isSFC = isCodeVueSfc(vueComponentCode);
console.log(`Is the code a Vue SFC? ${isSFC}`);

if (isSFC) {
  // Compile the Vue component code (this will typically return script and style strings)
  // Note: The 'compile' function in this context usually prepares the code for a runtime Vue environment,
  // often returning a function body or object that Vue can then instantiate.
  try {
    const compiledResult = compile(vueComponentCode, {}); // Pass an empty config or specific BubleConfig if needed
    console.log('Compiled Script:\n', compiledResult.script.substring(0, 200) + '...');
    console.log('Compiled Style:\n', compiledResult.style.substring(0, 100) + '...');

    // In a real browser environment with Vue loaded, you would then execute 'compiledResult.script'
    // and dynamically mount the component.
    // const componentOptions = new Function(compiledResult.script)();
    // new Vue({ el: '#app', render: h => h(componentOptions) });
    console.log('Code successfully processed by independent utilities.');
  } catch (error) {
    console.error('Error during compilation:', error);
  }
} else {
  console.log('The provided code is not a valid Vue Single File Component.');
}