{"id":15917,"library":"vue-sfc-parser","title":"Vue SFC Parser","description":"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.","status":"active","version":"0.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/ktsn/vue-sfc-parser","tags":["javascript","Vue.js","component","parser","single file component","static analysis","typescript"],"install":[{"cmd":"npm install vue-sfc-parser","lang":"bash","label":"npm"},{"cmd":"yarn add vue-sfc-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-sfc-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { parseComponent } = require('vue-sfc-parser')","symbol":"parseComponent","correct":"import { parseComponent } from 'vue-sfc-parser'"},{"note":"Use named imports for ESM. This function is for advanced use cases like file watchers and language services.","wrong":"const { createDiffWatcher } = require('vue-sfc-parser')","symbol":"createDiffWatcher","correct":"import { createDiffWatcher } from 'vue-sfc-parser'"},{"note":"SFCDescriptor is a TypeScript interface; use `import type` to avoid bundling issues in some environments.","wrong":"import { SFCDescriptor } from 'vue-sfc-parser'","symbol":"SFCDescriptor","correct":"import type { SFCDescriptor } from 'vue-sfc-parser'"}],"quickstart":{"code":"import { parseComponent } from 'vue-sfc-parser';\n\nconst code = `\n<template>\n  <p>Hello from SFC!</p>\n</template>\n\n<script lang=\"ts\">\nexport default {\n  data() {\n    return { msg: 'world' };\n  }\n}\n</script>\n\n<style scoped>\np {\n  color: blue;\n}\n</style>\n`;\n\nconst sfcDescriptor = parseComponent(code);\n\nif (sfcDescriptor.template) {\n  console.log('Template content:', sfcDescriptor.template.content);\n  // Calculate global offset for 'Hello' (5 chars into template content)\n  const templateOffset = sfcDescriptor.template.content.indexOf('Hello');\n  const globalOffset = sfcDescriptor.template.calcGlobalOffset(templateOffset);\n  console.log(`Global offset for 'Hello': ${globalOffset}`);\n}\n\nif (sfcDescriptor.script) {\n  console.log('Script content:', sfcDescriptor.script.content);\n  const scriptOffset = sfcDescriptor.script.content.indexOf('msg');\n  const globalOffset = sfcDescriptor.script.calcGlobalOffset(scriptOffset);\n  console.log(`Global offset for 'msg': ${globalOffset}`);\n}\n\nif (sfcDescriptor.styles.length > 0) {\n  console.log('First style content:', sfcDescriptor.styles[0].content);\n}","lang":"typescript","description":"Demonstrates parsing a Vue SFC, accessing its blocks, and using `calcGlobalOffset` to map block-relative positions to global file positions."},"warnings":[{"fix":"Pin exact versions (e.g., `\"vue-sfc-parser\": \"0.1.2\"`) or use caret (`^0.1.2`) with caution, testing thoroughly after updates.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Implement explicit null checks, e.g., `if (sfcDescriptor.template) { /* ... */ }` or use optional chaining `sfcDescriptor.template?.content`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use `import { parseComponent } from 'vue-sfc-parser';` instead of `const { parseComponent } = require('vue-sfc-parser');`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"Attempting to use `parseComponent` in a CommonJS context when expecting a named export, or an incorrect named import in an ESM context.","error":"TypeError: parseComponent is not a function"},{"fix":"Add a null check before accessing the block: `if (sfcDescriptor.script) { console.log(sfcDescriptor.script.content); }` or use optional chaining: `sfcDescriptor.script?.content`.","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`.","error":"TS2531: Object is possibly 'null'."}],"ecosystem":"npm"}