# vue-sfc-transformer

> Tools for minimal TypeScript transpilation of Vue SFCs

Latest version **0.3.0** (published 2026-08-31) · MIT license · 0 weekly downloads

## Install

```sh
npm install vue-sfc-transformer
pnpm add vue-sfc-transformer
yarn add vue-sfc-transformer
bun add vue-sfc-transformer
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.3.0 |
| Published | 2026-08-31 |
| First published | 2025-04-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.0.0 |
| Dependencies | 1 |
| Unpacked size | 48.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| Maintainers | danielroe |

## Links

- npm: https://www.npmjs.com/package/vue-sfc-transformer
- Repository: https://github.com/nuxt-contrib/vue-sfc-transformer
- Homepage: https://github.com/nuxt-contrib/vue-sfc-transformer#readme
- Issues: https://github.com/nuxt-contrib/vue-sfc-transformer/issues
- npm.io page: https://npm.io/package/vue-sfc-transformer

## Dependencies (1)

- [tinyglobby](https://npm.io/package/tinyglobby.md) ^0.2.16

## Recent versions

- 0.3.0 (latest) — 2026-08-31
- 0.2.5 — 2026-07-27
- 0.2.3 — 2026-05-25
- 0.2.1 — 2026-05-22
- 0.2.0 — 2026-05-22
- 0.1.17 — 2025-09-12
- 0.1.16 — 2025-05-21
- 0.1.15 — 2025-05-06
- 0.1.14 — 2025-04-24
- 0.1.13 — 2025-04-22
- 0.1.12 — 2025-04-22
- 0.1.11 — 2025-04-16
- 0.1.10 — 2025-04-09
- 0.1.9 — 2025-04-08
- 0.1.8 — 2025-04-08
- … 11 more at https://npm.io/package/vue-sfc-transformer/versions

## README

# vue-sfc-transformer

[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![Github Actions][github-actions-src]][github-actions-href]
[![Codecov][codecov-src]][codecov-href]

> Tools for minimal TypeScript transpilation of Vue SFCs

## Usage

Install package:

```sh
# npm
npm install vue-sfc-transformer vue @vue/compiler-core

# pnpm
pnpm install vue-sfc-transformer vue @vue/compiler-core
```

A TypeScript transpiler is needed to strip types from script blocks and template expressions. `rolldown` and `esbuild` are both optional peer dependencies; install whichever suits your setup. The `mkdist` loader uses `rolldown/utils` when it is available, and `esbuild` otherwise (or when mkdist's `esbuild` options are set).

```js
import { parse as parseSFC } from '@vue/compiler-sfc'
import { transform } from 'rolldown/utils'

import { preTranspileScriptSetup, transpileVueTemplate } from 'vue-sfc-transformer'

const src = `
<template>
  <div v-if="test as any" />
</template>

<script setup lang="ts">
defineProps<{
  test?: string
}>()
</script>
`

const sfc = parseSFC(src, {
  filename: 'test.vue',
  ignoreEmpty: true,
})

// transpile template block
const templateBlockContents = await transpileVueTemplate(
  sfc.descriptor.template.content,
  sfc.descriptor.template.ast,
  sfc.descriptor.template.loc.start.offset,
  async (code) => {
    const res = await transform('__sfc.ts', code, {
      lang: 'ts',
      sourcemap: false,
      typescript: { onlyRemoveTypeImports: true },
    })
    return res.code
  },
)
console.log(templateBlockContents)
// <div v-if="test" />

const { content: scriptBlockContents } = await preTranspileScriptSetup(sfc.descriptor, 'test.vue')
console.log(scriptBlockContents)
// defineProps({
//   test: { type: String, required: false }
// })
```

If you are using `mkdist`, `vue-sfc-transformer` exports a loader you can use:

```ts
import { vueLoader } from 'vue-sfc-transformer/mkdist'
```

> `mkdist` will automatically use the loader from `vue-sfc-transformer` when you pass `vue` to the `loaders` option and have this package installed.

## Rolldown plugin

`vue-sfc-transformer/rolldown` ships a [rolldown](https://github.com/rolldown/rolldown) plugin that transpiles `<script lang="ts">` and template expressions, then emits a `<name>.d.vue.ts` declaration for each SFC under `srcDir`. That's the form `vue-tsc` / `@vue/language-core` / `@volar/typescript` (since 2.4.19) resolve for `import './Foo.vue'`. Pass `emitLegacyDeclarationAlias: true` to also emit the older `<name>.vue.d.ts` form, which plain `tsc` resolves but vue-tsc does not.

Script blocks are transpiled with `verbatimModuleSyntax` semantics: only explicit `import type` statements and inline `type` specifiers are removed. A type-only import written without the `type` keyword (`import { Props } from './types'`) survives into the emitted SFC as a runtime import and will fail to resolve at runtime; make sure to write `import type` for types.

Works with anything that runs rolldown plugins: [tsdown](https://github.com/rolldown/tsdown), [obuild](https://github.com/unjs/obuild) or rolldown directly.

```sh
pnpm add -D rolldown @volar/typescript @vue/language-core typescript
```

```ts
// tsdown.config.ts
import { defineConfig } from 'tsdown'
import { vueSfcPlugin } from 'vue-sfc-transformer/rolldown'

export default defineConfig({
  entry: ['src/index.ts'],
  plugins: [vueSfcPlugin({ srcDir: 'src' })],
})
```

Declarations are cached on disk under `<cwd>/node_modules/.cache/vue-sfc-dts/`, keyed by a content hash that incorporates the SFC source, the installed versions of `vue-sfc-transformer` / `@vue/language-core` / `@volar/typescript` / `typescript`, and a hash of the resolved `vueCompilerOptions`. The TS program is by far the dominant build cost; a full cache hit skips it entirely.

Pass `cache: false` to disable. Pass `cacheVersion: '<your-string>'` to namespace the cache under your control on top of the auto-derivation.

The `cache` option is structurally compatible with the `getItem` / `setItem` subset of [unstorage](https://github.com/unjs/unstorage)'s `Storage`, so you can hand it an unstorage instance directly:

```ts
import { createStorage } from 'unstorage'
import redisDriver from 'unstorage/drivers/redis'
import { vueSfcPlugin } from 'vue-sfc-transformer/rolldown'

vueSfcPlugin({
  srcDir: 'src',
  cache: createStorage({ driver: redisDriver({ url: 'redis://…' }) }),
})
```

## 💻 Development

- Clone this repository
- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`
- Install dependencies using `pnpm install`
- Run interactive tests using `pnpm dev`

## Credits

This package was based on the work of contributors to [`mkdist`](https://github.com/unjs/mkdist), and in particular this PR by [**@Teages**](https://github.com/teages): [unjs/mkdist#300](https://github.com/unjs/mkdist/pull/300).

## License

Made with ❤️

Published under [MIT License](./LICENCE).

<!-- Badges -->

[npm-version-src]: https://npmx.dev/api/registry/badge/version/vue-sfc-transformer
[npm-version-href]: https://npmx.dev/package/vue-sfc-transformer
[npm-downloads-src]: https://npmx.dev/api/registry/badge/downloads/vue-sfc-transformer
[npm-downloads-href]: https://npm.chart.dev/vue-sfc-transformer
[github-actions-src]: https://img.shields.io/github/actions/workflow/status/nuxt-contrib/vue-sfc-transformer/ci.yml?branch=main&style=flat-square
[github-actions-href]: https://github.com/nuxt-contrib/vue-sfc-transformer/actions?query=workflow%3Aci
[codecov-src]: https://img.shields.io/codecov/c/gh/nuxt-contrib/vue-sfc-transformer/main?style=flat-square
[codecov-href]: https://codecov.io/gh/nuxt-contrib/vue-sfc-transformer

---
_Source: https://npm.io/package/vue-sfc-transformer · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._