Registry / web-framework / vue-sfc-parser

vue-sfc-parser

library0.1.2jsnpmunverified

vue-sfc-parser is a utility library for parsing Vue.js Single File Components (SFCs) specifically designed for static analysis workflows. It provides a structured representation of an SFC, similar to `vue-template-compiler`'s `parseComponent` function, but enhances it with additional helper methods on `SFCBlock` objects, such as `calcGlobalOffset` and `calcGlobalRange`, to facilitate mapping block-specific positions back to the overall file position. Currently at version 0.1.2, the library also includes a `createDiffWatcher` API for efficiently detecting changes within individual SFC blocks, enabling sophisticated hot-reloading or analysis tools. Its release cadence is ad-hoc, reflecting its early development stage. A key differentiator is its focus on providing precise positional data and change detection, which is crucial for linters, language servers, and build tools that operate on Vue SFCs.

web-framework testing

npm install vue-sfc-parser

github ↗package ↗

INSTALL

IMPORT

SIG · VUE-SFC-PARSER

vue-sfc-parser

web-frameworkjavascriptv0.1.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parseComponent

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

✗ const { parseComponent } = require('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

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

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

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

SFCDescriptor

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

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

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

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); }

Debug

Known issues

breakingAs 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.

affects: <1.0.0

gotchaThe `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`.

affects: >=0.1.0

gotchaWhile 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');`.

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: parseComponent is not a function

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'.

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`.

Upgrade

Version history

0.1.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ktsn/vue-sfc-parser ↗

packagehttps://www.npmjs.com/package/vue-sfc-parser ↗