shader-loader

1.3.1 verified Sat Apr 25 auth: no javascript maintenance

A Webpack loader for GLSL shader files (.glsl, .vs, .fs) that supports shader chunk/inclusion syntax ($xxx). Current version 1.3.1, last updated 2017, no active development. Works with Webpack 2 and 3 (not Webpack 4+). Differentiates from raw-loader or glslify by allowing inclusion of GLSL chunks via $include syntax directly in shader source, inspired by cabbibo's ShaderLoader. Suitable for legacy projects using Three.js or similar with Webpack 2/3.

Common errors

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

cause Shader file is not being processed by shader-loader; webpack config missing or incorrect rule.

fix

Ensure webpack config includes { test: /\.(glsl|vs|fs)$/, loader: 'shader-loader' } and loader is installed.

error ERROR in ./src/shader.vs Module build failed: Error: ENOENT: no such file or directory, open '.../glsl/chunks/snoise.glsl' ↓

cause Chunk include ($snoise) cannot find the file in the specified chunkPath.

fix

Create the chunk file (e.g., snoise.glsl) in the directory specified by chunkPath option.

error throw new Error('shader-loader only supports webpack 2 and 3'); ↓

cause Trying to use shader-loader with Webpack 4 or 5.

fix

Downgrade to webpack@3 or use an alternative loader like raw-loader.

Warnings

breaking Incompatible with Webpack 4+ due to loader API changes. ↓

fix Use raw-loader or glslify for Webpack 4+; or stick with Webpack 2/3.

deprecated Package has not been updated since 2017 and is no longer maintained. ↓

fix Consider migrating to glslify, raw-loader, or webpack-glsl-loader.

gotcha Shader chunks must be placed in the configured chunkPath directory; otherwise $include will silently fail. ↓

fix Set chunkPath in options and ensure chunk files (e.g., noise.glsl) exist there.

gotcha The loader only supports Webpack 2 and 3; not tested with Webpack 1. ↓

fix Use appropriate version of webpack (2.x or 3.x).

Install

npm install shader-loader

yarn add shader-loader

pnpm add shader-loader

Imports

default
wrong
```
const vertexShader = require('shader.vs');
```
correct
```
import vertexShader from 'shader.vs';
```
ESM import works with Webpack 2/3 + babel or TypeScript; require works in CJS context.

none (loader)

wrong

module.exports = { module: { rules: [ { test: /\.glsl$/, loader: 'shader-loader' } ] } };

correct

module.exports = { module: { rules: [ { test: /\.(glsl|vs|fs)$/, loader: 'shader-loader', options: { glsl: { chunkPath: 'path/to/chunks' } } } ] } };

Options are required for chunk resolution; without chunkPath, $include will fail.

none (chunk syntax)
wrong
```
void main() { #include "noise.glsl" }
```
correct
```
void main() { $noise }
```
Uses $filename syntax, not C-style #include. File must be in chunkPath directory.

Quickstart

Sets up Webpack config to load .glsl/.vs/.fs files with shader-loader, including chunk path. Then imports a vertex shader in JavaScript.

// webpack.config.js
const path = require('path');
module.exports = {
  entry: './src/index.js',
  output: { path: path.resolve(__dirname, 'dist'), filename: 'bundle.js' },
  module: {
    rules: [
      {
        test: /\.(glsl|vs|fs)$/,
        loader: 'shader-loader',
        options: {
          glsl: {
            chunkPath: path.resolve(__dirname, 'glsl/chunks')
          }
        }
      }
    ]
  }
};

// src/vertex.vs
void main() { gl_Position = vec4(position, 1.0); }

// src/index.js
import vertexShader from './vertex.vs';
console.log(vertexShader);