{"id":11965,"library":"rspack-vue-loader","title":"Rspack Vue Loader","description":"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`.","status":"active","version":"17.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/rstackjs/rspack-vue-loader","tags":["javascript","typescript"],"install":[{"cmd":"npm install rspack-vue-loader","lang":"bash","label":"npm"},{"cmd":"yarn add rspack-vue-loader","lang":"bash","label":"yarn"},{"cmd":"pnpm add rspack-vue-loader","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for Rspack functionality.","package":"@rspack/core","optional":false}],"imports":[{"note":"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.","wrong":"const { VueLoaderPlugin } = require('rspack-vue-loader');","symbol":"VueLoaderPlugin","correct":"import { VueLoaderPlugin } from 'rspack-vue-loader';"},{"note":"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.","wrong":"loader: 'vue-loader'","symbol":"Loader configuration string","correct":"loader: 'rspack-vue-loader'"},{"note":"While not directly part of `rspack-vue-loader`, `defineConfig` from `@rspack/cli` is crucial for type-safe Rspack configurations, especially when working with TypeScript.","symbol":"defineConfig","correct":"import { defineConfig } from '@rspack/cli';"}],"quickstart":{"code":"import { defineConfig } from '@rspack/cli';\nimport { VueLoaderPlugin } from 'rspack-vue-loader';\nimport path from 'path';\n\nexport default defineConfig({\n  mode: process.env.NODE_ENV === 'production' ? 'production' : 'development',\n  entry: {\n    main: './src/main.ts',\n  },\n  resolve: {\n    extensions: ['.ts', '.tsx', '.js', '.jsx', '.vue', '.json'],\n  },\n  module: {\n    rules: [\n      {\n        test: /\\.vue$/,\n        loader: 'rspack-vue-loader',\n        options: {\n          // Enable inline matchResource for better rule matching\n          experimentalInlineMatchResource: true,\n        },\n      },\n      {\n        test: /\\.ts$/,\n        exclude: [/node_modules/],\n        loader: 'builtin:swc-loader',\n        options: {\n          jsc: {\n            parser: {\n              syntax: 'typescript',\n            },\n            // Target ESNext for modern browsers\n            target: 'esnext',\n          },\n        },\n      },\n      {\n        test: /\\.css$/,\n        // Rspack natively supports CSS, so basic setup can be simple\n        // For preprocessors or advanced needs, use specific loaders like 'less-loader' or 'sass-loader'\n        type: 'css',\n      },\n      {\n        test: /\\.(png|jpe?g|gif|webp|svg)$/,\n        type: 'asset/resource',\n        generator: {\n          filename: 'assets/[name][ext]'\n        }\n      }\n    ],\n  },\n  plugins: [\n    // Make sure to include the VueLoaderPlugin!\n    new VueLoaderPlugin(),\n  ],\n  output: {\n    filename: '[name].js',\n    path: path.resolve(__dirname, 'dist'),\n    clean: true,\n  },\n  devServer: {\n    port: 8080,\n    hot: true,\n    historyApiFallback: true,\n  },\n});\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Starting 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.","severity":"breaking","affected_versions":">=17.4.5"},{"fix":"Replace `refSugar: true` with `reactivityTransform: true` in your `rspack-vue-loader` options if you wish to use Vue's reactivity transform feature.","message":"The `refSugar` option, used for Vue's experimental ref sugar, was removed in `v16+`. Its functionality has been replaced by `reactivityTransform`.","severity":"breaking","affected_versions":">=16.0.0"},{"fix":"In `rspack.config.js` (or `.ts`), ensure your rule for `.vue` files uses `loader: 'rspack-vue-loader'`, not `loader: 'vue-loader'`.","message":"It 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"While `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.","severity":"gotcha","affected_versions":">=16.8"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=16.0.0"},{"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.","message":"Rspack 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install `@rspack/core` in your project: `npm install @rspack/core` or `pnpm install @rspack/core` or `yarn add @rspack/core`.","cause":"The `@rspack/core` peer dependency is missing.","error":"Error: \"rspack-vue-loader\" requires \"@rspack/core\" to be installed. Please install it with the appropriate package manager (e.g., `npm install @rspack/core`)."},{"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.","cause":"Rspack is attempting to process a `.vue` file but no loader rule is configured for it.","error":"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."},{"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.","cause":"The `VueLoaderPlugin` was not imported or instantiated correctly in the Rspack configuration.","error":"ReferenceError: VueLoaderPlugin is not defined"},{"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.","cause":"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.","error":"TypeError: this.getOptions is not a function (while processing a CSS preprocessor loader like `sass-loader` or `less-loader` within a .vue file)"}],"ecosystem":"npm"}