Web Integration & Frameworks

Needle Engine is a web component that works with any modern web framework or vanilla JavaScript. Install it via npm and use it anywhere.

Learn more about Needle Engine →

Already have a website?

This page is about building a web project with Needle (frameworks, bundlers, the web component). If you already have a site — your own HTML, Webflow, WordPress, AEM… — and just want to drop a scene in, see Embedding Needle Engine.

Quick Start

Install:

npm i @needle-tools/engine

Use in HTML:

<script type="module">
  import '@needle-tools/engine';
</script>
<needle-engine src="path/to/your.glb"></needle-engine>

That's it! Needle Engine automatically bundles with your project for optimized production builds.

📖 See web component reference →

Bundling and tree shaking

Bundling means that all the css, js and other files making up your project are combined into less, and smaller, files at build time. This ensures that instead of downloading numerous small scripts and components, only one or a few are downloaded that contain the minimal code needed. The Vite docs contain a great explanation for why web apps should be bundled: Why Bundle for Production

Tree shaking is a common practice in web development where unused code is removed from the final bundle to reduce file size. This is similar to "code stripping" in Unity. The MSDN docs have a good explanation of tree shaking.

Examples

A few common ways to use the <needle-engine> web component.

Show a model with lighting, shadows and camera controls

<needle-engine
  src="path/to/your.glb"
  camera-controls="1"
  background-color="transparent"
  environment-image="studio"
  contact-shadows>
</needle-engine>

Run your own code once the scene is ready

<script type="module">
  import { onStart } from '@needle-tools/engine';

  onStart(context => {
    console.log('Scene loaded', context.scene);
    // add three.js objects, query components, drive animations…
  });
</script>

Use straight from a CDN — no install, no bundler

<script type="module" src="https://cdn.jsdelivr.net/npm/@needle-tools/engine/dist/needle-engine.min.js"></script>
<needle-engine src="https://your-host.com/assets/MyScene.glb"></needle-engine>

ViteSupported Frameworks & Bundlers

Needle Engine is framework-agnostic—use it with any modern web stack. Our default template uses Vite, but you can integrate with any framework or bundler.

Production-Ready Stacks

FrameworkStatusNotes
Vite + HTML✅ Default templateMinimal setup, great for getting started
Vite + Vue✅ Production usePowers needle.tools • Sample
Vite + React⚡ Experimental templateAvailable in Unity integration
Vite + Svelte✅ Supported
Vite + SvelteKit✅ Supported
Next.js✅ SupportedExample project
react-three-fiber⚡ Experimental templateAvailable in Unity integration
Vanilla JS (CDN)✅ SupportedNo bundler needed • Guide

Have a Different Stack?

Let us know what you're building with! We're always looking to improve the experience and provide more examples.

Tips

Some frameworks require custom settings in needle.config.json. Learn more here. Typically, the baseUrl needs to be set.

How do I create a custom project template in Unity?

You can create and share your own web project templates to use other bundlers, build systems, or none at all.

Create a new Template

  1. Select Create/Needle Engine/Project Template to add a ProjectTemplate into the folder you want to use as a template
  2. Done! It's that simple.

The dependencies come from unity when there is a NpmDef in the project (so when your project uses local references).
You could also publish your packages to npm and reference them via version number.

PWAProgressive Web Apps (PWA)

Turn your Needle Engine project into an installable, offline-capable Progressive Web App with automatic updates and smart caching.

Learn how to set up PWA support →

Accessing Needle Engine and Components from external javascript

Code that you expose can be accessed from JavaScript after bundling. This allows to build viewers and other applications where there's a split between data known at edit time and data only known at runtime (e.g. dynamically loaded files, user generated content).
For accessing components from regular javascript outside of the engine please refer to the interop with regular javascript section

Next Steps