Vue SFC Parser

Common errors

• TypeError: parseComponent is not a function

  cause Attempting to use `parseComponent` in a CommonJS context when expecting a named export, or an incorrect named import in an ESM context.
  fix Ensure you are using `import { parseComponent } from 'vue-sfc-parser';` for ESM, or if strictly CommonJS, verify the export structure. If using TypeScript, check `tsconfig.json` for module resolution settings.

• TS2531: Object is possibly 'null'.

  cause Trying to access a property (e.g., `content`) or method (e.g., `calcGlobalOffset`) on an `SFCBlock` (like `sfcDescriptor.script`) without first verifying that the block is not `null`.
  fix Add a null check before accessing the block: `if (sfcDescriptor.script) { console.log(sfcDescriptor.script.content); }` or use optional chaining: `sfcDescriptor.script?.content`.

Warnings

• breaking As a pre-1.0 release (currently 0.1.2), the API surface of `vue-sfc-parser` is subject to breaking changes without adherence to semantic versioning. Minor or patch releases may introduce breaking changes.
  Fix: Pin exact versions (e.g., `"vue-sfc-parser": "0.1.2"`) or use caret (`^0.1.2`) with caution, testing thoroughly after updates.
• gotcha The `SFCDescriptor` properties like `template`, `script`, or `styles` can be `null` if the corresponding block is not present in the parsed SFC. Always perform null checks before accessing their properties or helper methods.
  Fix: Implement explicit null checks, e.g., `if (sfcDescriptor.template) { /* ... */ }` or use optional chaining `sfcDescriptor.template?.content`.
• gotcha While the README examples show CommonJS `require()` syntax, the library ships with TypeScript types and is intended for modern JavaScript/TypeScript environments. For new projects, prefer ESM `import` statements.
  Fix: Use `import { parseComponent } from 'vue-sfc-parser';` instead of `const { parseComponent } = require('vue-sfc-parser');`.

Install

• npm install vue-sfc-parser npm
• yarn add vue-sfc-parser yarn
• pnpm add vue-sfc-parser pnpm

Imports

• parseComponent
  wrong:

  const { parseComponent } = require('vue-sfc-parser')

  correct:

  import { parseComponent } from 'vue-sfc-parser'

  For modern TypeScript or ESM projects, use named imports. The CommonJS example in the README is provided for context but not recommended for new projects.
• createDiffWatcher
  wrong:

  const { createDiffWatcher } = require('vue-sfc-parser')

  correct:

  import { createDiffWatcher } from 'vue-sfc-parser'

  Use named imports for ESM. This function is for advanced use cases like file watchers and language services.
• SFCDescriptor
  wrong:

  import { SFCDescriptor } from 'vue-sfc-parser'

  correct:

  import type { SFCDescriptor } from 'vue-sfc-parser'

  SFCDescriptor is a TypeScript interface; use `import type` to avoid bundling issues in some environments.

Quickstart

Demonstrates parsing a Vue SFC, accessing its blocks, and using `calcGlobalOffset` to map block-relative positions to global file positions.

import { parseComponent } from 'vue-sfc-parser';

const code = `
<template>
  <p>Hello from SFC!</p>
</template>

<script lang="ts">
export default {
  data() {
    return { msg: 'world' };
  }
}
</script>

<style scoped>
p {
  color: blue;
}
</style>
`;

const sfcDescriptor = parseComponent(code);

if (sfcDescriptor.template) {
  console.log('Template content:', sfcDescriptor.template.content);
  // Calculate global offset for 'Hello' (5 chars into template content)
  const templateOffset = sfcDescriptor.template.content.indexOf('Hello');
  const globalOffset = sfcDescriptor.template.calcGlobalOffset(templateOffset);
  console.log(`Global offset for 'Hello': ${globalOffset}`);
}

if (sfcDescriptor.script) {
  console.log('Script content:', sfcDescriptor.script.content);
  const scriptOffset = sfcDescriptor.script.content.indexOf('msg');
  const globalOffset = sfcDescriptor.script.calcGlobalOffset(scriptOffset);
  console.log(`Global offset for 'msg': ${globalOffset}`);
}

if (sfcDescriptor.styles.length > 0) {
  console.log('First style content:', sfcDescriptor.styles[0].content);
}