Constructing Ridgeline: Engineering a Actual-Time 3D Expertise in Webflow

Ridgeline is a climbing and images web site: a cinematic stroll via three actual alpine treks. It’s a private venture, and actually my method of understanding how I need to construct websites. It began from one query: Can a Webflow web site host genuinely actual 3D terrain, which means precise elevation information (DEMs) draped as a survey-contour mesh and rendered stay in Three.js, not a video loop and never a baked sprite sheet, with out giving up Webflow’s editability?

The one rule I set myself was a single sentence: “I don’t care if it’s a built-in part or exterior JS, I need to SEE it.” That rule quietly determined the entire structure. I checked out two methods to get real-time 3D into Webflow earlier than I dedicated to 1, and that call (trade-offs and all) is the place the actual story is.

The completed web site is three “situation” scenes, every an actual trek drawn by itself terrain: Daybreak (Tre Cime, a storm), Dawn (Mont Blanc, blue-hour into pink), and Snow (Annapurna, evening blue with falling snow). They’re tied along with scroll-driven images and ambient sound, plus an atlas homepage that flies via the terrain with three clickable scene previews. All of it’s actual geometry, and all of it’s constructed and maintained from code via the Webflow MCP whereas staying a standard, human-editable Webflow venture.

The Daybreak trek is mine. I recorded the hike above Cortina within the Tre Cime, exported the exercise from Strava as a GPS monitor (GPX), cleaned the same old GPS spikes, and draped the actual hint onto the true SRTM slope. Solely a normalized, coordinate-free model of the monitor ships, so the terrain is recognizable however the precise route isn’t uncovered. (Dawn and Snow use believable synthesized routes, since I didn’t have a recorded monitor for these.)

Another factor value saying up entrance, as a result of it formed how briskly I might transfer: the entire web site was coded with Claude (Opus 4.8 and Fable 5), driving the Webflow MCP, and it got here collectively in a couple of week.

I additionally saved a construct log from day one: the selections, the wins, and the fallacious turns. This write-up is drawn straight from it, so the errors are in right here too, not simply the tidy remaining outcome.

The stack

Three.js + React Three Fiber + drei for the 3D scenes.
GSAP (ScrollTrigger) + Lenis for scroll and animation.
Blender (pushed via the Blender MCP) for each mesh, modeled or baked, then exported to glTF (Draco-compressed).
Cloudflare R2 to host the JS bundle plus the GLB and texture property (a CDN, with a cache-busted loader).
Webflow for construction, styling, pages, and CMS: the human-editable floor.
Webflow MCP (1.3 on the time of writing) because the construct layer, pushed by Claude: pages, elements, courses, variables, {custom} code, publishing.
Strava as the information supply for the actual Daybreak trek, exported as a GPX monitor and draped on the SRTM terrain.

1. Two methods to place React into Webflow, and why I selected the embed

Webflow has a correct native route for this: a Code Part (deployed through DevLink or a shared library) that lives within the Designer as a first-class aspect. It’s an excellent match when your part is UI-shaped. Mine was a unique animal. A single heavy WebGL bundle with its personal construct step, Three.js, a Blender-baked asset pipeline, and R2-hosted GLBs is loads of equipment to route via any part system. So I weighed it towards a self-hosted JS embed, and for this venture the embed received. The trade-off is the attention-grabbing half:

Self-contained construct. Three.js, the bundler, and the property all stay in a single place I management finish to finish.
Iterates in seconds. Deploy the bundle, hard-refresh, finished. No republish for a habits change.
Moveable. The identical embed runs on any web site or CMS, which fits a bundle this specialised.

The one factor an embed isn’t is a drag-and-drop Designer aspect. I solved that with attribute-driven mounting. The embed seems for host parts the designer locations (like [data-terrain-scene] or [data-terrain-card]) and mounts into them. The designer stays in command of the place; the code controls what.

// The embed hunts for designer-placed hosts and mounts into them, so the
// Webflow person retains arranging format and the 3D fills the slots they outline.

doc.querySelectorAll("[data-terrain-card]").forEach((host) =>  "dawn" );

Takeaways

Match the mixing path to the part. Validate it matches your use case earlier than you commit.
A self-hosted embed trades one Designer comfort for a self-contained construct and prompt iteration.
Attribute-driven mounting retains the break up clear: Webflow owns format, code owns habits.

2. Constructing the entire web site from code: the Webflow MCP workflow

That is the half that stunned me most. The complete web site (pages, elements, courses, CSS, variables, {custom} code, search engine marketing, publishing) is constructed and maintained by an agent via the Webflow MCP (Mannequin Context Protocol) server. The agent right here is Claude. And the output remains to be a very regular Webflow venture a human can open and edit.

The governing rule I settled on:

Markup and CSS stay within the Webflow Designer as named elements and courses. Habits, 3D, and animation stay in versioned JS on R2. The Designer holds construction; the CDN holds habits.

One factor value understanding early: Webflow provides you two locations for {custom} code, and so they’re for various jobs. There are registered scripts (the Scripts API, injected JS), and there’s head/footer {custom} code (uncooked HTML/CSS). Something that has to exist at first paint belongs in the second, and I’ll get to precisely why within the flash part.

Takeaways

An agent can drive an actual Webflow construct through MCP and depart a totally human-editable venture behind.
Preserve a tough line: construction in Webflow, habits in code. That’s what retains each halves maintainable.

3. Making the 3D actual: Blender to glTF to Three.js

The non-negotiable was that the geometry is actual, not a intelligent shader on a primitive. Each terrain is an actual DEM (an SRTM elevation dataset) for an precise massif, modeled in Blender, exported to glTF, and loaded in Three.js. If it’s “a crystal monolith,” the reply begins in Blender, not in JSX.

The pipeline:

Mannequin or bake in Blender. I exploit a parametric construct.py for math-defined shapes and interactive modeling for art-directed ones. Both method an actual .mix exists so the geometry will be iterated later.
Export to glTF with the flags that matter:

bpy.ops.export_scene.gltf(
    export_yup=True,        # Blender Z-up to a few.js Y-up
    export_apply=True,      # bake modifiers
    export_extras=True,     # object {custom} props to glTF extras to a few.js userData
    # ALWAYS Draco-compress. Static meshes shrink 5-13x (11 MB to ~1 MB)
    export_draco_mesh_compression_enable=True,
    export_draco_mesh_compression_level=6,
    export_draco_position_quantization=14,
)

Load with useGLTF, traverse to seek out named objects, apply supplies, and seize per-instance state at load. Don’t recompute geometry at runtime.

Blender ran via its personal MCP too, the identical agentic setup as Webflow, so mannequin tweaks might occur immediately in Blender when a scene wanted one, with no handbook round-trip via the UI.

The three terrain GLBs land at roughly 540-580 KB every after Draco, sufficiently small that the obtain was by no means the bottleneck. The bottlenecks had been all on the GPU and the primary thread, which is the remainder of this text.

The survey-map look is one shader, no textures

The contour-map aesthetic isn’t a texture. It’s a fraction shader that reads the mesh’s world-space top. The trick that retains the traces crisp at any digital camera distance is fwidth(): it derives the anti-alias width in display screen house from the speed of change of the band index, so traces are one pixel extensive whether or not you’re zoomed in or out.

// Survey-contour terrain (fragment): banding by elevation, hillshade, snow line.
float scaled = vWorldPos.y * uContourFreq;            // top to band index
float dMinor = abs(fract(scaled) - 0.5) * 2.0;
float aa     = fwidth(scaled) * 2.0;                  // screen-space AA width, crisp at any zoom
float minor  = 1.0 - smoothstep(uContourWidth - aa, uContourWidth + aa, dMinor);

// each Nth line is a bolder "index" contour, the basic survey-map learn
float dMajor = abs(fract(scaled / uMajorEvery) - 0.5) * 2.0;
float main  = 1.0 - smoothstep(uContourWidth * uMajorBoost - aa, uContourWidth * uMajorBoost + aa, dMajor);
float line   = max(minor * uMinorDim, main);

// hillshade from the floor regular, elevation tint, snow above the road
float shade  = clamp(dot(normalize(vWorldNormal), normalize(uLightDir)), 0.0, 1.0);
float elev   = clamp((vWorldPos.y - uElevLo) / (uElevHi - uElevLo), 0.0, 1.0);
vec3  floor = combine(uGround, uGroundHi, elev);
floor = combine(floor, combine(uGround * 0.5, floor * 0.92, shade), uHillshade);
floor = combine(floor, uSnowColor, smoothstep(uSnowLineY, uSnowLineY + uSnowSoftness, vWorldPos.y) * uSnowStrength);

vec3 contourCol = combine(uContourLo, uContourHi, elev);
gl_FragColor = vec4(combine(floor, contourCol, line), 1.0);

Each scene is similar shader with a unique set of uniforms (floor and contour colours, snow power, gentle path), which is what lets Daybreak, Dawn, and Snow really feel like three locations whereas sharing one program. One small contact that punches above its weight: a tiny per-pixel dither ((hash(gl_FragCoord.xy) – 0.5) * 0.0045) kills the 8-bit banding that in any other case exhibits up as grainy blotches within the near-black daybreak gradients.

Takeaways

Actual geometry reads in a different way than a faked primitive. It’s well worth the pipeline.
export_yup, export_apply, export_extras, and Draco are the 4 flags you at all times need.
fwidth() provides you resolution-independent line width, the important thing to crisp procedural contours at any zoom.
One shader plus per-scene uniforms beats three shaders, and an inexpensive dither beats seen 8-bit banding.

4. Animation: scroll with out re-rendering React

All movement is scroll-driven, and the cardinal rule is that React by no means re-renders on scroll. Scroll progress goes right into a ref and is learn contained in the render loop.

Lenis drives clean scroll and feeds ScrollTrigger.
GSAP ScrollTrigger owns pinning and scrub.
Progress goes right into a ref, learn each body in useFrame. No React state on the scroll path.

// Lenis + GSAP, wired as soon as. Lenis drives the ticker; ScrollTrigger reads it.

lenis.on("scroll", ScrollTrigger.replace);
gsap.ticker.add((t) => lenis.raf(t * 1000));
gsap.ticker.lagSmoothing(0);

Two patterns did the heavy lifting.

First, the frame-collapse part. A full-screen picture collapses right into a small 4:5 plate whereas surrounding picture columns stream in. The lure: animating width and top from full-screen to the plate modifications the facet ratio each body, which forces object-fit to re-crop every body, and that re-crop is a visual leap. The repair was to make the aspect a hard and fast 4:5 field, sized as soon as to cowl the viewport, animated purely by remodel: scale. Fixed field plus fixed facet means the browser computes the crop as soon as and by no means re-crops, with zero per-frame format.

// Uniform scale solely. No width/top tween, so no re-crop, no format thrash.

const coverW = Math.max(W, H * 0.8);
const scale = ip(ip(1.14, 1, parallax), plateW / coverW, collapse);
gsap.set(hero, { xPercent: -50, yPercent: -50, scale });

Then the lure after that, which price me far too lengthy. A CSS drift animation whose keyframes began from an offset state (scale(1.04) translate(...)). The moment it engaged, the aspect snapped to that offset. A second “leap” that survived each repair to the collapse math, as a result of it wasn’t the collapse. The lesson: any animation that toggles on mid-scroll has to begin from the aspect’s resting state (id), or it pops.

Takeaways

By no means re-render React on scroll. Progress in a ref, learn within the body loop.
Animating width and top re-crops object-fit each body. Favor remodel: it’s compositable, no format.
A keyframe that doesn’t begin at id will snap when it engages, and it hides from the code you assume is accountable.

5. The seams: preloader, first-paint flash, audio gate

The 3D was by no means the onerous half. The seams, the moments between states, ate more often than not. Each one is a teachable gotcha.

Begin with the first-paint flash. On a tough reload you’d catch a split-second of a plain background earlier than the darkish preloader confirmed up. It’s a timing drawback: the location’s JS is injected by a loader, so it runs after the browser has already painted the uncooked HTML, which implies JS can’t stop its personal pre-load flash. The duvet has to exist within the head {custom} code, synchronously, earlier than the rest:

The JS removes #topo-fp-guard in init() and raises the actual preloader in the identical tick, so there’s no flash on the best way out both. That physique>*{visibility:hidden} is aggressive, so the failsafe timeout is what retains a JS failure from leaving the web page clean.

Then the audio gate. Browsers block autoplay till a person gesture, so the preloader ends on an express Enter or Enter-muted selection, which doubles because the gesture that unlocks the ambient audio bus. Attempting to autoplay earlier than that could be a assured console error.

Sound: an ambient layer that tracks the scene

As soon as the gate unlocks the bus, every scene runs its personal quiet audio, so it reads as ambiance somewhat than a soundtrack.

A per-scene ambient mattress. Dawn will get a tender forest loop, Snow a skinny snow-wind, and Daybreak stays “silent” as a result of its storm carries the sound. Beds cross-fade with the scene swap, so there’s no onerous minimize on navigation.
Occasions, not a loop. Reaching a summit on the trek line performs a brief arrival chime. The Daybreak storm is the showpiece: every lightning strike schedules its thunder by distance, setTimeout(() => audio.thunder(d), 350 + d * 3200), so an in depth bolt cracks nearly instantly and a far one rumbles seconds later, precisely like the actual factor. Low background rumbles roll in each 7-19s to maintain the storm alive between strikes.
One swap controls all of it. The gate’s Enter or Enter-muted selection units a single window.__topoSound.enabled flag, broadcast on a topo:sound occasion, and each scene’s audio reads from it. Muting is prompt and survives web page transitions.

The rule I adopted: sound needs to be the factor you’d miss if it had been gone, not the factor you discover when it’s there.

Takeaways

A loader-injected script can’t stop its personal first-paint flash. The guard belongs in synchronous head code.
Any full-page guard wants a failsafe timeout, or a load failure means a completely clean web page.
Fold the audio-unlock gesture right into a UI second you have already got (the Enter button). Don’t bolt on a separate immediate.
Tie sound to the scene. Per-scene beds plus occasions like distance-timed thunder promote the place, and one international mute flag retains it prompt and nav-safe.

6. Web page transitions with out the body drop

Navigating between scenes is a PJAX swap beneath a WebGL “flood” cowl, a topographic-contour reveal that sweeps in, holds, then drains. The important thing architectural name: the terrain canvas is a single persistent WebGL context. Navigation swaps the scene information (setScene), it doesn’t tear down and re-create the canvas. Spinning up a contemporary context per navigation is the way you get evicted contexts and black flashes.

The residual drawback was subtler. The flood already drained on a scene-ready occasion, however that occasion fired when the brand new mesh was parsed, earlier than its materials’s shader had compiled. So the compile stalled the primary thread in the course of the seen reveal. The repair is compileAsync:

// Compile the swapped-in scene's shader + add its GLB OFF the primary thread,
// and solely hearth scene-ready (which drains the flood) as soon as it is truly GPU-ready.

if (gl.compileAsync) {
  const finished = () => onMesh(mesh, bbox);          // dispatches "topo:scene-ready"
  const fallback = setTimeout(finished, 1200);        // by no means dangle the transition
  gl.compileAsync(root, digital camera).then(() => { clearTimeout(fallback); finished(); });
}

compileAsync makes use of the parallel-shader-compile extension, so the heavy work occurs off-thread and the reveal attracts a scene that’s already heat. The identical trick pre-warms the summit-cairn scene earlier than it scrolls into view, and it killed a roughly one-second freeze on first reveal.

One sincere observe that matches the “no free lunch” theme: there’s nonetheless about 110ms of synchronous work (the innerHTML swap plus re-wiring the brand new web page’s JS), however it runs whereas the flood is totally opaque and holding, so it’s invisible. I left it there somewhat than restructure a fragile PJAX operate for a acquire no person can see. Good the place it’s seen, pragmatic the place it isn’t.

Takeaways

Persist one WebGL context throughout navigation. Swap information, not the canvas.
Gate your reveal on GPU-ready, not parsed. compileAsync strikes the compile off the primary thread.
Know which stalls are seen. Conceal the unavoidable ones beneath an opaque cowl as an alternative of combating them.

7. Efficiency is usually not animating issues

That is the part the title guarantees. Attending to a locked 60fps was a run of “cease doing work that doesn’t change a pixel” edits. I constructed a tiny in-page FPS profiler first. You toggle it with a keypress, and it buckets body fee by scroll depth and labels the part, so a drop reads as min 34 @ 46% (Frames) as an alternative of a obscure “it feels janky.” Each repair under was geared toward an actual quantity and an actual location:

the place	earlier than	after
Homepage intro (terrain canvases)	46fps, min 33	60, min 56
Snow scene (falling snow)	37fps	60
Summit reveal (first scroll-in)	~1000ms freeze	gone
Footer entrance	min 7	min 57

The wins, so as of impression. None of them price visible high quality:

Freeze the shadow map. The important thing gentle and terrain are static; solely the digital camera flies. But a 2048 PCF shadow map re-rendered your entire scene into itself each body. Bake it as soon as, then set gl.shadowMap.autoUpdate = false. Shadows are camera-independent, so nothing modifications.
Drop wasted MSAA. The background canvas renders via a post-processing composer, so its personal antialias:true buffer solely ever receives a full-screen blit, an MSAA allocation and resolve each body for nothing. And the blur cross ran multisampling:4, which is MSAA on a blur. Each off.
Animate particles on the GPU. The falling snow ran a per-frame CPU loop over roughly 2,000 factors and re-uploaded the entire place buffer, 3 times, one per layer. These CPU-to-GPU sync stalls had been the one scene that dropped frames on a quick GPU (which feels stalls extra, not much less). Static positions plus a vertex shader that computes the autumn from uTime provides an similar have a look at near-zero per-frame price.

// GPU snowfall. Positions add as soon as; the shader does the falling and wrapping.

remodeled.y = mod((place.y + 1.2) - aSpeed * uTime, uRange) - 1.2;

remodeled.x = place.x + sin(uTime * 0.6 + aSway) * 0.1;

Cease per-frame tree walks. A few scene.traverse() loops rewrote materials opacity each body even when the worth hadn’t modified. Cache the fabric record as soon as, and skip fully when the worth is regular.
Substitute costly “ambiance” with low cost fades. A four-layer animated-gradient “mist” cowl that lifted with a full-screen blur(9px) was repainting repeatedly for what reads as a fade. A darkish opacity fade seems the identical and prices nothing.

The through-line, borrowed from each good efficiency put up: the quickest body is the one which doesn’t do work. Nearly each win right here was elimination, not cleverness.

Takeaways

Construct a profiler earlier than you optimize. Bucket by location so fixes are aimed.
Static gentle plus a shifting digital camera means you may freeze the shadow map. Free.
Buffer re-uploads stall quick GPUs probably the most. Push per-particle animation into the vertex shader.
Audit antialias and MSAA when a composer is concerned. It’s usually paid for and by no means used.

8. Content material: editable, and constructed to be discovered

The scene pages are static, however the web site carries a CMS Assortment (the gallery) so editorial content material stays editable in Webflow, not locked in code. The sample that retains a CMS and a code embed cooperating:

The Assortment holds the content material: titles, coordinates, copy, imagery.
The embed reads the attributes and DOM the CMS template renders (like a [data-terrain-card="{slug}"]) somewhat than fetching the CMS API itself, so the 3D binds to regardless of the editor publishes and not using a second information supply.
Design tokens (colours, sort scale, spacing) keep as Webflow variables, so per-scene accents are editable within the Designer, not hardcoded within the shader.

Holding content material actual and editable pays off in discoverability too. Clear semantic markup, per-page titles and meta descriptions, and the quick Core Net Vitals that fell out of the efficiency work are precisely what search crawlers and AI reply engines (AEO) parse greatest. Actual content material in actual HTML, loading quick, reads properly to each folks and machines.

Takeaways

Let the CMS personal content material, and let the embed learn the rendered DOM, not a parallel API.
Preserve accents and tokens as Webflow variables so the look stays editable.
search engine marketing and AEO come largely at no cost from the identical self-discipline: semantic markup, per-page metadata, and a genuinely quick web page.

Reflections

If I did this once more:

I’d attain for the self-hosted embed on day one for a bundle this specialised, although weighing each integration paths was time properly spent.
I’d deal with the body price range as a design constraint from the beginning, not a cleanup cross. The largest wins right here had been architectural (one WebGL context, a frozen shadow map, off-thread shader compiles), and people are far cheaper to design in than to retrofit.
I’d observe the 2 custom-code channels up entrance. A small factor that may’ve saved me a beat.

The recurring lesson, and the one value leaving you with: “it compiles” will not be “it’s finished.” Nearly each repair on this construct got here from watching the precise rendered web page in a targeted tab. The jumps, the flashes, the body drops had been invisible within the code and apparent on display screen.