gltf-loader

A comprehensive Webpack loader for glTF files.

Rationale

TL;DR: I wanted my glTF assets loaded the same as all my other image assets. 🙃

By design, glTF files are comprised of multiple assets representing the various components of a 3D scene. Typically, these files contain external references to binary files for geometries and animations, and image files for textures.

When using a module bundler such as Webpack, image assets can be optimized, versioned, and then referenced in JavaScript by importing them directly. However, if you're using something like Three.js to import glTF files, its assets are requested during runtime and thus won't have any of the optimizations or versioning applied to them in the way they would if they were handled by Webpack.

This loader fixes that problem by iterating through glTF JSON data and loading its assets automatically, replacing any uri references with the asset's final output URI.

You can read more about the glTF 2.0 specification here.

Installation

npm install gltf-loader

Configuration

All loader options are typed, documented, and available in the declaration file here.

webpack.config.js

module.exports = {
  // ...
  module: {
    rules: [
      {
        test: /\.(gltf)$/,
        loader: "gltf-loader",
        /**
         * @type {import("gltf-loader").GLTFLoaderOptions}
         */
        options: {
          // ...
        },
      },
      {
        test: /\.(bin|png|jpe?g)$/,
        type: "asset/resource",
      },
    ],
  },
};

If you're using a meta-framework such as Next.js (like me), you could configure this loader as such:

next.config.js

/** 
 * @type {import("next").NextConfig} 
 */
module.exports = {
  // ...
  webpack: (config) => {
    config.module.rules.push(
      {
        test: /\.(gltf)$/,
        loader: "gltf-loader",
        /**
         * @type {import("gltf-loader").GLTFLoaderOptions}
         */
        options: {
          uriResolver: (module) => {
            let result = module.default ?? module;
            // Use the "src" property returned by the `next-image-loader` if present:
            if (typeof result === "object" && "src" in result) result = result.src;
            return result;
          },
        },
      },
      {
        test: /\.(bin)$/,
        type: "asset/resource",
      }
    );
    return config;
  },
};

As a path

By default, the loader injects the glTF file path during import. This is especially useful when using Three.js:

import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
import myModel from "../assets/my-model.gltf"; // e.g. /dist/static/media/my-model.a1b2c3d4.gltf

const loader = new GLTFLoader();
loader.load(myModel, (gltf) => {
  // ...
});

As JSON data

Alternatively, you can set the loader option inline: true if you wish to import the raw JSON data instead:

import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
import myModel from "../assets/my-model.gltf"; // JSON data

const loader = new GLTFLoader();
loader.parse(JSON.stringify(myModel), window.location.origin + "/", (gltf) => {
  // ...
});

TypeScript

For TypeScript users, adding the following module declaration will fix any "cannot find module" errors:

modules.d.ts

declare module "*.gltf" {
  const content: string;
  export default content;
}

Note that if you supply the inline: true config option, you would want to change the above declaration to something like the following:

declare module "*.gltf" {
  const content: Record<string, unknown>; // Or a glTF interface if you have/need one
  export default content;
}

tsconfig.json

  {
    "compilerOptions": {
      // ...
    }.
    "include": [
+     "modules.d.ts",
      "foo.d.ts",
      "bar.d.ts
    ],
    "exclude": []
  }