Rspack Vue Loader

Common errors

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

  cause 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.

  cause 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

  cause 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)

  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.
  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.

Warnings

• breaking 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.
  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.
• breaking The `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.
• gotcha 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.
  Fix: In `rspack.config.js` (or `.ts`), ensure your rule for `.vue` files uses `loader: 'rspack-vue-loader'`, not `loader: 'vue-loader'`.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install rspack-vue-loader npm
• yarn add rspack-vue-loader yarn
• pnpm add rspack-vue-loader pnpm

Imports

• VueLoaderPlugin
  wrong:

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

  correct:

  import { VueLoaderPlugin } from '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
  wrong:

  loader: 'vue-loader'

  correct:

  loader: 'rspack-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.

Quickstart

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,
  },
});