val-loader

6.0.0 verified Sat Apr 25 auth: no javascript

A webpack loader that executes a given module at build-time and returns the result as the module's code. Current stable version is 6.0.0 (2024-01-15). It allows custom loader logic without writing a full loader; the target module receives (options, loaderContext) and must return an object with at least a 'code' property. Supports returning source maps, AST, dependencies, and context dependencies. Requires webpack 5.x and Node.js >= 18.12.0. Releases follow semver, with breaking changes only for Node.js and webpack version bumps. Key differentiator: simplifies creating loaders for static value generation or compile-time computation.

Common errors

error 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 this file. ↓

cause The target file is not matching the test pattern in webpack config, or val-loader is not applied.

fix

Ensure the webpack rule test matches the target file and that use: 'val-loader' is specified.

error TypeError: loaderContext.addDependency is not a function ↓

cause Using an outdated version of webpack or the loader context does not support addDependency.

fix

Upgrade to webpack 5 and val-loader v3+.

error Error: The 'val-loader' loader doesn't return an object with a 'code' property. ↓

cause The target function returned an object without the required 'code' property.

fix

Ensure the target function returns { code: '...' }.

error Module not found: Error: Can't resolve 'val-loader' in ... ↓

cause val-loader is not installed as a devDependency.

fix

Run 'npm install val-loader --save-dev' or equivalent.

Warnings

breaking Node.js version 18.12.0 or higher is required. Older versions are not supported. ↓

fix Upgrade Node.js to >=18.12.0

breaking webpack version 5.x is required. Not compatible with webpack 4. ↓

fix Upgrade webpack to 5.x

breaking Node.js version 14.15.0 or higher is required for val-loader v5. ↓

fix Upgrade Node.js to >=14.15.0 or use val-loader v4

gotcha The target module must export a function via module.exports; ES module exports (export default) will not work. ↓

fix Use module.exports = (options, loaderContext) => { ... }

gotcha The return object must include a 'code' property; omitting it will cause an error. ↓

fix Always return { code: '...' } from the target function.

gotcha The executableFile option requires an absolute path. Using a relative path may resolve incorrectly. ↓

fix Use path.resolve(__dirname, 'file.js') to provide an absolute path.

Install

npm install val-loader

yarn add val-loader

pnpm add val-loader

Imports

val-loader
wrong
```
import valLoader from 'val-loader'
```
correct
```
module.exports = { module: { rules: [ { test: /\.js$/, use: 'val-loader' } ] } }
```
val-loader is a webpack loader, not a JavaScript module. It is configured in webpack config, not imported in source code.
target module function
wrong
```
export default (options, loaderContext) => { ... }
```
correct
```
module.exports = (options, loaderContext) => { return { code: '...' }; }
```
The target file must use CommonJS (module.exports) because webpack loaders expect a function exported via module.exports.
executableFile
wrong
```
options: { executableFile: './exec.js' }
```
correct
```
options: { executableFile: path.resolve(__dirname, 'exec.js') }
```
The executableFile option expects an absolute path. Relative paths may fail silently.

Quickstart

Shows how to configure val-loader with options and a target module that uses those options to generate code.

// target-file.js
module.exports = (options, loaderContext) => {
  return { code: 'module.exports = ' + JSON.stringify(options) + ';' };
};

// webpack.config.js
const path = require('path');
module.exports = {
  module: {
    rules: [
      {
        test: /\.val\.js$/,
        use: [
          {
            loader: 'val-loader',
            options: { greeting: 'Hello, world!' }
          }
        ]
      }
    ]
  }
};

// input.val.js
module.exports = (options, loaderContext) => {
  return { code: `module.exports = "${options.greeting}";` };
};

// entry.js
const greeting = require('./input.val.js');
console.log(greeting); // 'Hello, world!'