Registry / web-framework / rspack-vue-loader

rspack-vue-loader

library17.5.0jsnpmunverified

rspack-vue-loader is the official Rspack loader for processing Vue Single-File Components (SFCs), enabling developers to leverage Vue's component authoring format within an Rspack build pipeline. As of version `17.5.0`, it focuses exclusively on Rspack compatibility, explicitly removing dependencies on Webpack. The library is actively maintained with frequent fixes and contributions, demonstrating a stable yet evolving release cadence. Key features include the ability to apply other Rspack loaders to individual SFC blocks (e.g., Sass for <style>, Pug for <template>), support for custom blocks, automatic handling of static assets referenced in templates and styles as module dependencies, simulated scoped CSS, and state-preserving hot-reloading for an efficient development experience. It provides a dedicated and robust solution for integrating Vue.js 3 with Rspack, differentiating itself from its Webpack counterpart, `vue-loader`.

web-framework serialization

npm install rspack-vue-loader

github ↗package ↗

INSTALL

IMPORT

SIG · RSPACK-VUE-LOADER

rspack-vue-loader

web-frameworkjavascriptv17.5.0

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.

VueLoaderPlugin

✓ import { VueLoaderPlugin } from 'rspack-vue-loader';

✗ const { VueLoaderPlugin } = require('rspack-vue-loader');

Used in Rspack configuration plugins array. While CommonJS `require` might work in some setups, ESM `import` is the recommended and cleaner approach in modern Rspack configurations, especially with TypeScript.

Loader configuration string

✓ loader: 'rspack-vue-loader'

✗ loader: 'vue-loader'

When configuring the loader in your Rspack rules, use the literal string 'rspack-vue-loader'. Do not confuse it with 'vue-loader', which is for Webpack.

defineConfig

✓ import { defineConfig } from '@rspack/cli';

While not directly part of `rspack-vue-loader`, `defineConfig` from `@rspack/cli` is crucial for type-safe Rspack configurations, especially when working with TypeScript.

This Rspack configuration demonstrates how to set up `rspack-vue-loader` for Vue 3 Single-File Components, including TypeScript support via Rspack's built-in SWC loader, and basic asset handling. It highlights the use of `VueLoaderPlugin` and the loader string in module rules.

import { defineConfig } from '@rspack/cli'; import { VueLoaderPlugin } from 'rspack-vue-loader'; import path from 'path'; export default defineConfig({ mode: process.env.NODE_ENV === 'production' ? 'production' : 'development', entry: { main: './src/main.ts', }, resolve: { extensions: ['.ts', '.tsx', '.js', '.jsx', '.vue', '.json'], }, module: { rules: [ { test: /\.vue$/, loader: 'rspack-vue-loader', options: { // Enable inline matchResource for better rule matching experimentalInlineMatchResource: true, }, }, { test: /\.ts$/, exclude: [/node_modules/], loader: 'builtin:swc-loader', options: { jsc: { parser: { syntax: 'typescript', }, // Target ESNext for modern browsers target: 'esnext', }, }, }, { test: /\.css$/, // Rspack natively supports CSS, so basic setup can be simple // For preprocessors or advanced needs, use specific loaders like 'less-loader' or 'sass-loader' type: 'css', }, { test: /\.(png|jpe?g|gif|webp|svg)$/, type: 'asset/resource', generator: { filename: 'assets/[name][ext]' } } ], }, plugins: [ // Make sure to include the VueLoaderPlugin! new VueLoaderPlugin(), ], output: { filename: '[name].js', path: path.resolve(__dirname, 'dist'), clean: true, }, devServer: { port: 8080, hot: true, historyApiFallback: true, }, });

Debug

Known issues

breakingStarting with `v17.4.5`, `rspack-vue-loader` no longer supports Webpack 4. It is designed exclusively for Rspack environments. Attempting to use it with Webpack 4 or older versions will result in build failures.

fix

Ensure your project uses Rspack (version 1.0.0 or 2.0.0-0, as per peer dependencies) for bundling. If you are using Webpack, use `vue-loader` instead.

affects: >=17.4.5

breakingThe `refSugar` option, used for Vue's experimental ref sugar, was removed in `v16+`. Its functionality has been replaced by `reactivityTransform`.

fix

Replace `refSugar: true` with `reactivityTransform: true` in your `rspack-vue-loader` options if you wish to use Vue's reactivity transform feature.

affects: >=16.0.0

gotchaIt is critical to specify the loader as `'rspack-vue-loader'` in your Rspack configuration's module rules. The `vue-loader` string is for Webpack and will not work correctly with Rspack.

fix

In `rspack.config.js` (or `.ts`), ensure your rule for `.vue` files uses `loader: 'rspack-vue-loader'`, not `loader: 'vue-loader'`.

affects: >=1.0.0

gotchaWhile `enableTsInTemplate` defaults to `true` (allowing TypeScript expressions in templates with `lang="ts"` scripts), using `ts-loader` for TypeScript compilation can sometimes disrupt Hot Module Replacement (HMR) for templates. Rspack's `builtin:swc-loader` or `esbuild-loader` are generally faster and avoid this HMR issue.

fix

Consider using `builtin:swc-loader` (Rspack's default recommendation) or `esbuild-loader` for TypeScript transpilation instead of `ts-loader` to improve HMR stability. If sticking with `ts-loader` and experiencing issues, you might set `enableTsInTemplate: false` in `rspack-vue-loader` options and avoid TS expressions in templates.

affects: >=16.8

gotchaThe `customElement` option, which transforms SFCs into custom elements, defaults to processing files ending with `.ce.vue` (`/\.ce\.vue$/`). Setting it to `true` will process *all* `.vue` files in custom element mode, which might have unintended side effects if not all components are meant to be custom elements.

fix

Carefully manage the `customElement` option. Use the default regex for specific custom element files, or explicitly provide a more precise `RegExp` if needed. Only set `customElement: true` if you intend for all `.vue` files to be treated as custom elements.

affects: >=16.0.0

gotchaRspack offers native CSS handling, which can sometimes interact with `rspack-vue-loader`'s internal CSS processing. For advanced CSS setups (e.g., preprocessors like Less/Sass, CSS Modules with custom options, or `vue-style-loader`), you may need to explicitly configure CSS rules and potentially disable Rspack's `experiments.css` option if conflicts arise.

fix

When using CSS preprocessors (e.g., Less, Sass), ensure you have the corresponding loaders configured (e.g., `less-loader`, `sass-loader`) and set `type: 'css'` or a chain with `vue-style-loader` if needed. For specific CSS Module behavior or when encountering issues, consult Rspack documentation on `experiments.css` and `vue-loader`'s CSS processing.

affects: >=1.0.0

Errors

Common errors & fixes

Error: "rspack-vue-loader" requires "@rspack/core" to be installed. Please install it with the appropriate package manager (e.g., `npm install @rspack/core`).

The `@rspack/core` peer dependency is missing.

fix

Install `@rspack/core` in your project: `npm install @rspack/core` or `pnpm install @rspack/core` or `yarn add @rspack/core`.

Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type, currently no loaders are configured to process .vue files.

Rspack is attempting to process a `.vue` file but no loader rule is configured for it.

fix

Add a rule to your `rspack.config.js` (or `.ts`) for `.vue` files, specifying `loader: 'rspack-vue-loader'`. Also ensure `new VueLoaderPlugin()` is in your `plugins` array.

ReferenceError: VueLoaderPlugin is not defined

The `VueLoaderPlugin` was not imported or instantiated correctly in the Rspack configuration.

fix

Ensure you have `import { VueLoaderPlugin } from 'rspack-vue-loader';` at the top of your Rspack config file and `new VueLoaderPlugin()` in the `plugins` array.

TypeError: this.getOptions is not a function (while processing a CSS preprocessor loader like `sass-loader` or `less-loader` within a .vue file)

This often occurs when Webpack-specific loader options or context are expected, or when Rspack's native CSS handling interferes with the expected loader chain. This can happen if using an older preprocessor loader version, or mixing Rspack's `type: 'css'` with `vue-loader`'s specific CSS processing requirements.

fix

Ensure your CSS preprocessor loaders are compatible with Rspack. If encountering this, try configuring `experiments: { css: false }` in your Rspack config and explicitly using `vue-style-loader` and `css-loader` in your rules for `css` or preprocessor files within `.vue` components.

Upgrade

Version history

17.5.0latest on npm

Audit

Dependencies

@rspack/corerequiredRequired peer dependency for Rspack functionality.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/rstackjs/rspack-vue-loader ↗

packagehttps://www.npmjs.com/package/rspack-vue-loader ↗