DEV Community: Antonio Bonet

I Missed Engine Debug Views in Three.js, So I Built a WebGPU Helper

Antonio Bonet — Mon, 08 Jun 2026 16:52:32 +0000

I come from an environment art and tech art background.

For years, my main tools were Unreal Engine 5 and the usual real-time engine stack. When you work inside engines, you get used to seeing more than the final frame.

You check normals.
You check depth.
You isolate lighting.
You inspect albedo, roughness, wireframe, buffers, masks, and whatever else helps explain why the frame looks the way it does.

That workflow sticks.

Lately, while doing more rendering work in Three.js, especially around WebGPU and TSL, I started missing that layer.

Three.js gives you a lot of freedom, but once the scene grows, the final image is not enough.

A material looks wrong.

Is it the normal map?
Is roughness packed wrong?
Is depth doing something weird?
Is lighting hiding the issue?
Is the shader fine but the input wrong?

Without debug views, you start guessing.

So I built threejs-debug-view.

GitHub:
https://github.com/tonyblu331/threejs-debug-compose

Docs:
https://github.com/tonyblu331/threejs-debug-compose#readme

pnpm add threejs-debug-view

What it is

threejs-debug-view is a WebGPU-first helper for inspecting render debug views in Three.js + TSL.

It gives you a way to see what your render pipeline is producing while you build.

Not a full scene inspector.
Not an EffectComposer helper.
Not a WebGL fallback.

Just a dev component for render debugging.

What it shows

Built-in views include:

beauty
normals
depth
albedo
roughness
metallic
AO
opacity
emissive
material normals / normal maps
wireframe
lighting-only
reflection-only
estimated shader complexity

The goal is not to expose every possible render state.

The goal is to make the useful layers easy to reach.

Beauty tells you what the user sees.

Debug views tell you why it looks like that.

Layouts

You can display views as:

single
overlay
split
row
column
quad
grid

So you can compare the frame against the data behind it.

Beauty next to normals.
Depth next to roughness.
Lighting-only next to reflection-only.
Shader cost next to the final output.

That is the part I wanted from engine workflows.

Less guessing.
More looking.

import { DebugViews } from "threejs-debug-view/react"
import { DEFAULT_DEBUG_VIEWS } from "threejs-debug-view"

<DebugViews
  views={DEFAULT_DEBUG_VIEWS}
  layout="grid"
  columns={4}
  rows={1}
  showLabels
/>

R3F adapter

The package includes an R3F adapter and Leva controls.

import { DebugViews, useDebugViewsControls } from "threejs-debug-view/react"
import { DEFAULT_DEBUG_VIEWS, getDebugViewLabels } from "threejs-debug-view"

function DebugLayer() {
  const controls = useDebugViewsControls({
    viewLabels: getDebugViewLabels(DEFAULT_DEBUG_VIEWS),
  })

  return <DebugViews views={DEFAULT_DEBUG_VIEWS} {...controls} />
}

This makes it easier to switch views and layouts at runtime without rewriting the scene every time you want to inspect another layer.

Custom TSL layers

The built-in views are only the base.

You can also add your own TSL debug layers.

That matters once the useful view becomes project-specific.

A mask.
A falloff.
A weight.
A confidence value.
A reconstruction term.
A material signal.
Some temporary output that only makes sense for the shader you are building.

import { float, vec4 } from "three/tsl"
import { createCustomDebugView, DEFAULT_DEBUG_VIEWS } from "threejs-debug-view"
import { DebugViews } from "threejs-debug-view/react"

const customLayer = createCustomDebugView({
  id: "debug:custom-layer",
  label: "Custom Layer",
  node: vec4(float(1), float(0), float(0), float(1)),
})

<DebugViews views={[...DEFAULT_DEBUG_VIEWS, customLayer]} />

Use a stable id when the node can be recreated between React renders.

That helps the render graph dedupe equivalent views instead of treating them as new work every render.

WebGPU-first

This is WebGPU-first.

No WebGL fallback yet.

It is built around Three.js WebGPU, TSL, MRT passes, and a fullscreen render pipeline.

So the scope is clear:

WebGPU-first.
TSL-first.
R3F-friendly.

Why I made it

I did not want a full editor inside Three.js.

I just missed the speed of engine debug views.

The ability to stop looking only at the final image and quickly check the layers underneath.

That is how I am used to debugging render work.

So I packaged the helper I wanted while building.

GitHub:
https://github.com/tonyblu331/threejs-debug-compose

Docs:
https://github.com/tonyblu331/threejs-debug-compose#readme

pnpm add threejs-debug-view

Feedback welcome, especially from people working with Three.js WebGPU, TSL, R3F, custom materials, or engine-style rendering workflows on the web.

CSS ellipsis is great. Until the string itself matters.

Antonio Bonet — Tue, 02 Jun 2026 19:50:37 +0000

CSS ellipsis is great.

Until the string itself matters.

It works when you only need to visually hide overflow.

A long label.

A table cell.

A title inside a card.

Done.

But sometimes your app needs more than a clipped box.

Sometimes it needs the actual truncated string.

Sometimes it needs to preserve a match.

Sometimes it needs to cut from the middle.

Sometimes it needs to prepare the text before the UI renders.

That is why I built Truncate.

A small Pretext powered library for all those cases where CSS ellipsis is not enough.

Even the weird ones.

Try it here:

Playground:
https://tonyblu331.github.io/truncate/

Repo:
https://github.com/tonyblu331/truncate

The problem

Most truncation starts here:

.label {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

And honestly, that is still the right answer for a lot of UI.

CSS ellipsis does not fail.

It does exactly what it is meant to do.

It clips text visually.

But it does not give you the final string.

It does not know which part of the text matters.

It does not know that a file extension should stay visible.

It does not know that a search result should keep the match in view.

It does not help when you need the output before rendering.

It just clips.

That is the gap Truncate is trying to cover.

What Truncate does

Truncate gives you small utilities for text truncation before it reaches the UI.

It supports:

width based truncation
multiline truncation
middle cuts
start cuts
search aware truncation
range aware truncation
custom markers
height aware truncation
grapheme safe text
DOM free usage

The point is not to replace CSS.

CSS is still the right tool when the browser only needs to hide overflow.

Truncate is for the cases where your app needs to know what the final text should be.

Basic usage

import { truncate } from "@tonybonet/truncate";

truncate("A very long string", {
  font: "16px Inter",
  maxWidth: 100,
});

Simple.

But the useful part is when the case gets more specific.

Middle truncation

Some strings should not only be cut from the end.

Filenames.

URLs.

Emails.

Hashes.

IDs.

Anything where the start and end both matter.

import { truncateMiddle } from "@tonybonet/truncate";

truncateMiddle("really-long-file-name-final-final-v12.pdf", {
  font: "14px Inter",
  maxWidth: 220,
});

Because this:

really-long-file-name...

is not always as useful as this:

really-long...v12.pdf

Small detail.

Big difference.

Search aware truncation

Search results should not blindly cut text and hope the useful part survives.

If someone is searching inside logs, errors, docs, or long records, the preview should try to keep the match visible.

import { truncateAround } from "@tonybonet/truncate";

const result = truncateAround(logLine, {
  font: "14px Geist Mono",
  maxWidth: 320,
  target: "Cannot read properties of undefined",
  context: 18,
});

Because this:

[2026-06-03 14:22:10] production-api-worker...

is not as useful as this:

...TypeError: Cannot read properties of undefined...

That small difference makes search results, command palettes, logs, support tools, and debugging UIs feel much more intentional.

Range aware truncation

Sometimes you already know the exact part of the text that matters.

Maybe it came from search.

Maybe it came from a parser.

Maybe it came from your own indexing layer.

So you can preserve that range directly.

import { truncateRange } from "@tonybonet/truncate";

truncateRange(article, {
  font: "16px Inter",
  maxWidth: 320,
  start: match.start,
  end: match.end,
  before: 12,
  after: 12,
});

The API does not only return the text.

It also gives you metrics.

So if the range was preserved, you know.

If it could not fit, you know.

No fake confidence.

No silent weirdness.

Custom markers

You are not locked into ....

Sometimes you want something more explicit.

truncateByWidth(articleIntro, {
  font: "16px Inter",
  maxWidth: 260,
  ellipsis: " READ MORE",
});

Sometimes you want something smaller.

truncateByWidth(mediaTitle, {
  font: "16px Inter",
  maxWidth: 220,
  ellipsis: ".",
});

Again, tiny detail.

But UI is full of tiny details.

DOM free by default

Truncate does not depend on reading layout from the page.

At the core, it measures through Canvas2D.

That makes it useful for:

browser apps
OffscreenCanvas
Node canvas polyfills
tests
server side utilities
pre rendered snippets

Sometimes you do not want to wait for the DOM to decide what the text should be.

You want the string ready before it gets there.

Yes, it even supports GIFs

Because every tiny UI utility eventually meets the weird case.

Install

pnpm add @tonybonet/truncate

Or:

npm install @tonybonet/truncate

Links

Playground:
https://tonyblu331.github.io/truncate/

Docs:
https://github.com/tonyblu331/truncate?tab=readme-ov-file#api

Repo:
https://github.com/tonyblu331/truncate

If you have a weird truncation case, send it my way.

That is probably the best test for this.