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 →

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 →

Supported 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

Progressive Web Apps (PWA)

Turn your Needle Engine project into a Progressive Web App with offline support, automatic updates, and installability.

PWA Benefits:

• 📱 Install on home screen (mobile & desktop)
• ⚡ Works offline
• 🔄 Auto-update when you publish new versions
• 🚀 Faster loading with smart caching

Setup

1. Install the Vite PWA plugin:

npm install vite-plugin-pwa --save-dev

2. Configure vite.config.js:

Pass the same pwaOptions object to both needlePlugins and VitePWA.

import { VitePWA } from 'vite-plugin-pwa';

export default defineConfig(async ({ command }) => {

    // Create the pwaOptions object. 
    // You can edit or enter PWA settings here (e.g. change the PWA name or add icons).
    /** @type {import("vite-plugin-pwa").VitePWAOptions} */
    const pwaOptions = {};
  
    const { needlePlugins } = await import("@needle-tools/engine/plugins/vite/index.js");

    return {
        plugins: [
            // pass the pwaOptions object to the needlePlugins and the VitePWA function
            needlePlugins(command, needleConfig, { pwa: pwaOptions }),
            VitePWA(pwaOptions),
        ],
        // the rest of your Vite config...

Testing PWAs

To test your PWA, deploy the page, for example using the DeployToFTP component.
Then, open the deployed page in a browser and check if the PWA features work as expected:

• the app shows up as installable
• the app works offline
• the app is detected as offline-capable PWA by pwabuilder.com

PWAs use Service Workers to cache resources and provide offline support. Service Workers are somewhat harder to use during development, and typically are only enabled for builds (e.g. when you use a DeployTo... component).

You can enable PWA support for development by adding the following to the options object in your vite.config.js.

const pwaOptions = {
  // Note: PWAs behave different in dev mode. 
  // Make sure to verify the behaviour in production builds!
  devOptions: {
    enabled: true,
  }
};

Please note that PWAs in development mode do not support offline usage – trying it may result in unexpected behavior.

Automatically update running apps

Websites typically show new or updated content on page refresh.

In some situations, you may want the page to refresh and reload automatically when a new version has been published – such as in a museum, trade show, public display, or other long-running scenarios.

To enable automatic updates, set the updateInterval property in the pwaOptions object to a duration (in milliseconds) in which the app should check for updates. If an update is detected, the page will reload automatically.

const pwaOptions = {
  updateInterval: 15 * 60 * 1000, // 15 minutes, in milliseconds
};

More PWA options

Since Needle uses the Vite PWA plugin under the hood, you can use all options and hooks provided by that.
For example, you can provide a partial manifest with a custom app title or theme color:

const pwaOptions = {
  // manifest options provided here will override the defaults 
  manifest: {
    name: "My App",
    short_name: "My App",
    theme_color: "#B2D464",
  }
};

For complex requirements like partial caching, custom service workers or different update strategies, you can remove the { pwa: pwaOptions } option from needlePlugins and add PWA functionality directly through the Vite PWA plugin.

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

Customizing how loading looks

See the Loading Display section in needle engine component reference

Builtin styles

The needle-engine loading appearance can use a light or dark skin.
To change the appearance use the loading-style attribute on the <needle-engine> web component.
Options are light and dark (default):

<needle-engine loading-style="light"></needle-engine>

Custom Loading Style — PRO feature

Please see the Loading Display section in needle engine component reference