{"id":12573,"library":"vue-sfc-transformer","title":"Vue SFC Transformer","description":"vue-sfc-transformer provides low-level utilities for transpiling Vue Single File Components (SFCs), specifically focusing on TypeScript syntax within `<script setup>` blocks and template expressions. It aims for minimal transformation, leveraging `esbuild` for the actual code transpilation. The current stable version is `0.1.17`, indicating a pre-1.0 status where API changes might occur in minor releases. This package is actively maintained, receiving frequent bug fixes and minor feature additions as evidenced by its release history, with its last publish being 4 months ago. It is part of the `nuxt-contrib` organization, suggesting its role in the Nuxt ecosystem for build tooling. Its key differentiators include its granular control over SFC block transformation, reliance on `esbuild` for performance, and specific support for handling TypeScript within Vue templates and `script setup` blocks, making it suitable for bundler integrations and custom build pipelines.","status":"active","version":"0.1.17","language":"javascript","source_language":"en","source_url":"https://github.com/nuxt-contrib/vue-sfc-transformer","tags":["javascript"],"install":[{"cmd":"npm install vue-sfc-transformer","lang":"bash","label":"npm"},{"cmd":"yarn add vue-sfc-transformer","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-sfc-transformer","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for parsing Vue SFCs and template compilation.","package":"@vue/compiler-core","optional":false},{"reason":"Required for JavaScript/TypeScript transpilation of script and template expressions.","package":"esbuild","optional":false},{"reason":"Core Vue library, necessary for the context of Vue SFCs.","package":"vue","optional":false}],"imports":[{"note":"This package is ESM-only and requires import statements.","wrong":"const { preTranspileScriptSetup } = require('vue-sfc-transformer')","symbol":"preTranspileScriptSetup","correct":"import { preTranspileScriptSetup } from 'vue-sfc-transformer'"},{"note":"It is a named export, not a default export.","wrong":"import transpileVueTemplate from 'vue-sfc-transformer'","symbol":"transpileVueTemplate","correct":"import { transpileVueTemplate } from 'vue-sfc-transformer'"},{"note":"The `vueLoader` utility for `mkdist` is exported from a subpath.","wrong":"import { vueLoader } from 'vue-sfc-transformer'","symbol":"vueLoader","correct":"import { vueLoader } from 'vue-sfc-transformer/mkdist'"}],"quickstart":{"code":"import { parse as parseSFC } from '@vue/compiler-sfc'\nimport { transform } from 'esbuild'\nimport { preTranspileScriptSetup, transpileVueTemplate } from 'vue-sfc-transformer'\n\nconst src = `\n<template>\n  <div v-if=\"test as any\" />\n</template>\n\n<script setup lang=\"ts\">\ndefineProps<{\n  test?: string\n}>()\n</script>\n`\n\nasync function processSFC() {\n  const sfc = parseSFC(src, {\n    filename: 'test.vue',\n    ignoreEmpty: true,\n  })\n\n  // Transpile the template block\n  const templateBlockContents = await transpileVueTemplate(\n    sfc.descriptor.template.content,\n    sfc.descriptor.template.ast,\n    sfc.descriptor.template.loc.start.offset,\n    async (code) => {\n      const res = await transform(code, { loader: 'ts', target: 'esnext' })\n      return res.code\n    },\n  )\n  console.log('Transpiled Template:\\n', templateBlockContents)\n  // Expected output (roughly): <div v-if=\"test\" />\n\n  // Pre-transpile the script setup block\n  const { content: scriptBlockContents } = await preTranspileScriptSetup(sfc.descriptor, 'test.vue')\n  console.log('Transpiled Script Setup:\\n', scriptBlockContents)\n  // Expected output (roughly): defineProps({\\n//   test: { type: String, required: false }\\n// })\n}\n\nprocessSFC().catch(console.error)\n","lang":"typescript","description":"This quickstart demonstrates how to use `vue-sfc-transformer` to pre-transpile `<script setup lang=\"ts\">` and transform a template block using `esbuild` for a Vue SFC."},"warnings":[{"fix":"Run `npm install vue @vue/compiler-core esbuild` or `pnpm install vue @vue/compiler-core esbuild` in your project.","message":"This package requires explicit installation of its peer dependencies: `vue`, `@vue/compiler-core`, and `esbuild`. These are not automatically installed and must be added to your project's dependencies.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Always review the release notes when upgrading to new minor versions of `vue-sfc-transformer` and thoroughly test your build pipeline.","message":"As a package in the `0.x.x` version range, API stability is not guaranteed. Breaking changes may be introduced in minor (`0.x.y`) versions without a major version bump, requiring careful review of changelogs during upgrades.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Ensure your Node.js environment is updated to version 18.0.0 or later.","message":"The package strictly requires Node.js version 18.0.0 or higher, as specified in its `engines` field. Using older Node.js versions will lead to runtime errors.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Install `esbuild` and ensure you pass a configured `esbuild.transform` function to the `transpileVueTemplate` utility, or manage `esbuild` output for `preTranspileScriptSetup`.","message":"Users are responsible for integrating and configuring `esbuild` for the actual JavaScript/TypeScript transpilation. `vue-sfc-transformer` provides the Vue-specific parsing and transformation logic but delegates the underlying code transformation to an `esbuild` instance provided by the user.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install all necessary peer dependencies: `npm install vue @vue/compiler-core esbuild`.","cause":"One or more required peer dependencies (`vue`, `@vue/compiler-core`, `esbuild`) are not installed.","error":"Error: Cannot find module 'vue' or '@vue/compiler-core' or 'esbuild'"},{"fix":"Ensure your project is configured for ES Modules (e.g., add `\"type\": \"module\"` to your `package.json` or use `.mjs` file extension) and use `import` statements.","cause":"Attempting to use `require()` for this ESM-only package or running an ESM file in a CommonJS context.","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Ensure `@vue/compiler-sfc` is installed (`npm install @vue/compiler-sfc`) and correctly imported, e.g., `import { parse as parseSFC } from '@vue/compiler-sfc'`.","cause":"The `@vue/compiler-sfc` package was not imported, installed, or `parseSFC` failed to produce a valid descriptor.","error":"TypeError: Cannot read properties of undefined (reading 'content') or similar errors related to SFC descriptor."},{"fix":"Upgrade your Node.js installation to version 18.0.0 or higher.","cause":"Running `vue-sfc-transformer` on an unsupported Node.js version (below 18.0.0).","error":"(node:...) V8: API mismatch: argument #1 to V8::HandleScope::Create should be a v8::Isolate."}],"ecosystem":"npm"}