Esbuild Plugin Webgl

ESBuild plugin to load WebGL shaders from .glsl files.

Please consider starring this repository and sharing it with your friends.

Overview

This ESBuild plugin streamlines the process of loading WebGL shaders in your JavaScript or TypeScript projects. By allowing you to import GLSL shader files directly into your project, it ensures a seamless development experience for WebGL applications. This approach promotes better separation of concerns by eliminating the need to hard code GLSL shader code into your JS or TS files. Additionally, it compresses the shader code, helping you to deliver a smaller minified bundle for your library.

Key Features

• Easy Integration: Easily integrate GLSL shaders into your ESBuild workflow.
• TypeScript Support: Full support for TypeScript, making it easier to work with shaders in a type-safe environment.
• Lightweight: Minimal footprint, ensuring your build times remain fast.
• Flexible Configuration: Compatible with various build tools and configurations, including tsup and standard esbuild setups.

Getting Started

Follow these steps to get started with the ESBuild Plugin WebGL:

Installation

You can install the plugin using your preferred package manager:

Using pnpm:

$ pnpm add esbuild-plugin-webgl

Using npm:

$ npm install esbuild-plugin-webgl

Using yarn:

$ yarn add esbuild-plugin-webgl

Note: If you are using a monorepo or workspaces, you can install this plugin at the root using the -w option or to a specific workspace using --filter your-package or --scope your-package for pnpm or yarn workspaces, respectively.

Usage

With tsup

To use the plugin with tsup, add it to your tsup.config.ts or tsup.config.js file:

// tsup.config.ts or tsup.config.js
import { defineConfig } from "tsup";
import { webglPlugin } from "esbuild-plugin-webgl";

export default defineConfig((options) => ({
    ...
    esbuildPlugins: [webglPlugin()],
}));

With esbuild

To use the plugin directly with esbuild, include it in your build configuration:

import { webglPlugin } from "esbuild-plugin-webgl";

esbuild.build({
    ...
    plugins: [webglPlugin()],
});

Example Usage

Here's a quick example of how you can import and use a GLSL shader in your project:

import vertexShader from "./shaders/vertex.glsl";
import fragmentShader from "./shaders/fragment.glsl";

// Initialize WebGL context and use the imported shaders
const gl = canvas.getContext("webgl");
const vertexShader = gl.createShader(gl.VERTEX_SHADER);
gl.shaderSource(vertexShader, vertexShaderSource);
gl.compileShader(vertexShader);

const fragmentShader = gl.createShader(gl.FRAGMENT_SHADER);
gl.shaderSource(fragmentShader, fragmentShaderSource);
gl.compileShader(fragmentShader);

IDE and TypeScript Support

To prevent IDE or TypeScript errors, create a declaration file in the project's root directory.

declare module "*.glsl" {
  const value: string;
  export default value;
}

For users of Vitest, you can import the raw file by appending ?raw to the import statement:

import fragSource from "frag.glsl?raw";

To resolve IDE issues, add the following to your declarations.d.ts file:

declare module "*.glsl?raw" {
  const value: string;
  export default value;
}

Contributing

Contributions are welcome! If you find a bug or have a feature request, please open an issue. For major changes, please open a discussion first to discuss what you would like to change.

License

This library is licensed under the MPL-2.0 open-source license. See the LICENSE file for more details.

Please consider enrolling in our courses or sponsoring our work.

---

with 💖 by Mayank Kumar Chaudhari