Riot Tag Loader

2.1.0 verified Sat May 09 auth: no javascript

Webpack loader for compiling Riot.js tag files (.tag). The official loader maintained by the Riot team. Current stable version is v9.0.1, with v10.0.0 in alpha requiring Riot v10 and Node >=22. Handles parsing of Riot tags into JavaScript modules, supports hot module replacement via riot-hot-reload, and offers sourcemap configuration. Key differentiator: tightly coupled with riot-compiler, supports webpack 5, ESM-first from v9. Breaking changes: dropped webpack <=4 and Node <18 in v9, migrated from CJS to ESM. Release cadence: major version bumps with Riot compiler releases.

Common errors

error Error: Cannot find module 'riot-compiler' ↓

cause Missing peer dependency riot-compiler is not installed.

fix

Run npm install riot-compiler --save-dev.

error Module parse failed: Unexpected token (1:0) You may need an appropriate loader to handle this file type. ↓

cause webpack is not configured to use riot-tag-loader for .tag files.

fix

Add a rule in webpack config: { test: /\.tag$/, use: ['riot-tag-loader'] }.

error export default ... is not a function or cannot be resolved ↓

cause Using CJS require() with ESM-only v9+ of riot-tag-loader.

fix

Use import statement instead of require().

Warnings

breaking v10 drops support for Node <22. Ensure your Node version is >=22. ↓

fix Upgrade Node to version 22 or later.

breaking v9 drops support for webpack <=4. Use webpack 5 or later. ↓

fix Upgrade webpack to version 5.

breaking v9 migrates from CommonJS to ESM. require('riot-tag-loader') will fail. ↓

fix Use import syntax or dynamic import. If you must use CJS, stick to v8.x.

breaking v6 requires riot-compiler v6. Compatible compiler version must match loader major version. ↓

fix Install riot-compiler@^6.0.0 alongside.

gotcha The 'hot' option must be false if you are not using HMR. Setting it to true without riot-hot-reload causes errors. ↓

fix Set hot: false in loader options unless you have installed and imported riot-hot-reload.

Install

npm install riot-tag-loader

yarn add riot-tag-loader

pnpm add riot-tag-loader

Imports

default (loader)
wrong
```
const riotTagLoader = require('riot-tag-loader')
```
correct
```
import riotTagLoader from 'riot-tag-loader'
```
ESM-only since v9; CJS require() will fail. Use dynamic import if needed.

webpack config (module.rules)

wrong

module.exports = { module: { loaders: [ { test: /\.tag$/, loader: 'riot-tag-loader' } ] } }

correct

module.exports = { module: { rules: [ { test: /\.tag$/, use: ['riot-tag-loader'] } ] } }

webpack >=4 uses rules and use array, not loaders object. The old syntax works only for webpack <=3.

hot reload import
wrong
```
import riot from 'riot'; import 'riot-hot-reload'; // correct but must be after riot import
```
correct
```
import 'riot-hot-reload'
```
Must be imported after riot to augment the riot API with riot.reload(). Only needed if HMR is enabled.

Quickstart

Shows a minimal webpack 5 configuration using riot-tag-loader with ESM syntax, targeting .tag files.

// webpack.config.js
import path from 'path';
import { fileURLToPath } from 'url';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
export default {
  entry: './src/index.js',
  output: { path: path.resolve(__dirname, 'dist'), filename: 'bundle.js' },
  module: {
    rules: [
      {
        test: /\.tag$/,
        exclude: /node_modules/,
        use: [
          {
            loader: 'riot-tag-loader',
            options: { hot: false }
          }
        ]
      }
    ]
  }
};