@vue/compiler-sfc
Advanced tools
Package description
The @vue/compiler-sfc package is designed for pre-compiling Vue Single File Components (SFCs). It provides parsing and compiling functionalities for Vue components, allowing developers to compile template syntax to render functions, extract custom blocks, and handle scoped CSS, among other things.
Parsing Single File Components
This feature allows you to parse Vue SFCs into an object descriptor that contains the structure of the component, including its template, script, and styles.
const { parse } = require('@vue/compiler-sfc');
const { descriptor } = parse('<template><div>Hello World</div></template>');Compiling Template to Render Function
This feature compiles the template part of a Vue SFC into a JavaScript render function, which can be used by Vue to render the component.
const { compileTemplate } = require('@vue/compiler-sfc');
const { code } = compileTemplate({ source: '<div>{{ message }}</div>', filename: 'example.vue' });Handling Scoped CSS
This feature processes the style part of a Vue SFC, adding scoping attributes to the styles to ensure they only apply to the current component.
const { compileStyle } = require('@vue/compiler-sfc');
const { code } = compileStyle({ source: '.example { color: red; }', filename: 'example.vue', scoped: true });Extracting Custom Blocks
This feature allows you to extract custom blocks from a Vue SFC, which can be used for documentation, testing, or other purposes.
const { parse } = require('@vue/compiler-sfc');
const { descriptor } = parse('<custom-block>Some content</custom-block>');
const customBlockContent = descriptor.customBlocks[0].content;This package is similar to @vue/compiler-sfc but is specific to Vue 2. It compiles Vue 2 templates into render functions but does not handle Vue 3's composition API or the newer SFC syntax.
Svelte is a compiler for Svelte components, which are similar to Vue SFCs. It compiles Svelte components into efficient JavaScript at build time, but it is for a different framework and has a different syntax and API.
Part of the Create React App setup, react-scripts includes functionality to compile React components, including JSX transformation. While it serves a similar purpose for React as @vue/compiler-sfc does for Vue, it is tailored to the React ecosystem.
Changelog
3.4.1 (2023-12-30)
Read this blog post for an overview of the release highlights.
To fully leverage new features in 3.4, it is recommended to also update the following dependencies when upgrading to 3.4:
If using TSX with Vue, check actions needed in Removed: Global JSX Namespace.
Make sure you are no longer using any deprecated features (if you are, you should have warnings in the console telling you so). They may have been removed in 3.4.
once option to watch (#9034) (a645e7a)using syntax (#8786) (5b2bd1d)defineModel support local mutation by default, remove local option (f74785b), closes /github.com/vuejs/rfcs/discussions/503#discussioncomment-7566278__VUE_PROD_HYDRATION_MISMATCH_DETAILS__ feature flag (#9550) (bc7698d)FunctionalComponent (#8644) (927ab17)AriaAttributes type (#8909) (fd0b6ba)ObjectPlugin and FunctionPlugin types (#8946) (fa4969e), closes #8577DefineProps type (096ba81)PublicProps type (#2403) (44135dc)h with native elements (#9756) (a625376)ComponentInstance type (#5408) (bfb8565)Starting in 3.4, Vue no longer registers the global JSX namespace by default. This is necessary to avoid global namespace collision with React so that TSX of both libs can co-exist in the same project. This should not affect SFC-only users with latest version of Volar.
If you are using TSX, there are two options:
Explicitly set jsxImportSource to 'vue' in tsconfig.json before upgrading to 3.4. You can also opt-in per file by adding a /* @jsxImportSource vue */ comment at the top of the file.
If you have code that depends on the presence of the global JSX namespace, e.g. usage of types like JSX.Element etc., you can retain the exact pre-3.4 global behavior by explicitly referencing vue/jsx, which registers the global JSX namespace.
Note that this is a type-only breaking change in a minor release, which adheres to our release policy.
app.config.unwrapInjectedRef has been removed. It was deprecated and enabled by default in 3.3. In 3.4 it is no longer possible to disable this behavior.@vnodeXXX event listeners in templates are now a compiler error instead of a deprecation warning. Use @vue:XXX listeners instead.v-is directive has been removed. It was deprecated in 3.3. Use the is attribute with vue: prefix instead.Readme
Lower level utilities for compiling Vue Single File Components
Note: as of 3.2.13+, this package is included as a dependency of the main vue package and can be accessed as vue/compiler-sfc. This means you no longer need to explicitly install this package and ensure its version match that of vue's. Just use the main vue/compiler-sfc deep import instead.
This package contains lower level utilities that you can use if you are writing a plugin / transform for a bundler or module system that compiles Vue Single File Components (SFCs) into JavaScript. It is used in vue-loader and @vitejs/plugin-vue.
The API is intentionally low-level due to the various considerations when integrating Vue SFCs in a build system:
Separate hot-module replacement (HMR) for script, template and styles
Leveraging the tool's plugin system for pre-processor handling. e.g. <style lang="scss"> should be processed by the corresponding webpack loader.
In some cases, transformers of each block in an SFC do not share the same execution context. For example, when used with thread-loader or other parallelized configurations, the template sub-loader in vue-loader may not have access to the full SFC and its descriptor.
The general idea is to generate a facade module that imports the individual blocks of the component. The trick is the module imports itself with different query strings so that the build system can handle each request as "virtual" modules:
+--------------------+
| |
| script transform |
+----->+ |
| +--------------------+
|
+--------------------+ | +--------------------+
| | | | |
| facade transform +----------->+ template transform |
| | | | |
+--------------------+ | +--------------------+
|
| +--------------------+
+----->+ |
| style transform |
| |
+--------------------+
Where the facade module looks like this:
// main script
import script from '/project/foo.vue?vue&type=script'
// template compiled to render function
import { render } from '/project/foo.vue?vue&type=template&id=xxxxxx'
// css
import '/project/foo.vue?vue&type=style&index=0&id=xxxxxx'
// attach render function to script
script.render = render
// attach additional metadata
// some of these should be dev only
script.__file = 'example.vue'
script.__scopeId = 'xxxxxx'
// additional tooling-specific HMR handling code
// using __VUE_HMR_API__ global
export default script
In facade transform, parse the source into descriptor with the parse API and generate the above facade module code based on the descriptor;
In script transform, use compileScript to process the script. This handles features like <script setup> and CSS variable injection. Alternatively, this can be done directly in the facade module (with the code inlined instead of imported), but it will require rewriting export default to a temp variable (a rewriteDefault convenience API is provided for this purpose) so additional options can be attached to the exported object.
In template transform, use compileTemplate to compile the raw template into render function code.
In style transform, use compileStyle to compile raw CSS to handle <style scoped>, <style module> and CSS variable injection.
Options needed for these APIs can be passed via the query string.
For detailed API references and options, check out the source type definitions. For actual usage of these APIs, check out @vitejs/plugin-vue or vue-loader.
FAQs
@vue/compiler-sfc
The npm package @vue/compiler-sfc receives a total of 5,082,688 weekly downloads. As such, @vue/compiler-sfc popularity was classified as popular.
We found that @vue/compiler-sfc demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Polyfill.io has been serving malware for months via its CDN, after the project's open source maintainer sold the service to a company based in China.
Security News
OpenSSF is warning open source maintainers to stay vigilant against reputation farming on GitHub, where users artificially inflate their status by manipulating interactions on closed issues and PRs.
Security News
A JavaScript library maintainer is under fire after merging a controversial PR to support legacy versions of Node.js.