Vite Plugin Configuration

The Needle Engine Vite plugin (needlePlugins) provides build-time features for optimizing, transforming, and bundling your project. Configure it via the options object passed to needlePlugins() in your vite.config.js.

import { defineConfig } from 'vite';

export default defineConfig(async ({ command }) => {
    const { needlePlugins } = await import("@needle-tools/engine/vite");
    return {
        plugins: [
            needlePlugins(command, { /* options go here */ }),
        ],
    };
});

Options Overview

Aliases

Needle Engine sets up Vite aliases to ensure consistent module resolution across your project and its dependencies.

Key alias: three/addons

Needle resolves three/addons to three/examples/jsm. This means you can write:

import { OrbitControls } from "three/addons/controls/OrbitControls.js";

and it will resolve correctly regardless of which three.js version your dependencies expect.

Needle also ensures that all packages in your project resolve to the same three.js installation, preventing duplicate copies that can cause subtle bugs (e.g. instanceof checks failing across different three.js instances).

Debugging alias resolution

If you're running into unexpected module resolution issues, enable alias debug logging:

needlePlugins(command, {
    debugAlias: true,
});

This writes a detailed log of every import resolution to node_modules/.needle/needle.alias.log. The log shows which files are being imported and how they get resolved — useful for diagnosing cases where the wrong version of a package is picked up.

Build Pipeline

The build pipeline compresses and optimizes your glTF/GLB assets during production builds. It runs automatically when you build with the --production flag:

npx vite build -- --production

Without --production, the pipeline is skipped (useful for quick test builds).

Cloud vs local compression

The pipeline supports two modes:

• Cloud compression (default when a token is provided) — sends assets to Needle Cloud for optimized processing. Set your access token via process.env.NEEDLE_CLOUD_TOKEN or in the config.
• Local compression — runs the build pipeline locally on your machine.

Configuration

needlePlugins(command, {
    buildPipeline: {
        enabled: true,
        accessToken: process.env.NEEDLE_CLOUD_TOKEN, // optional, auto-read from env
        projectName: "my-project",                   // cloud project name
        version: "stable",                           // optional, default: "stable"
        maxWaitDuration: 60000,                      // ms to wait for bundling to finish (default: 60s)
        verbose: false,                              // enable detailed log output
    },
});

To skip the pipeline entirely, use noBuildPipeline: true.

Copy Files

During builds, Needle automatically copies files to the output directory (dist/ by default):

1. Assets — your project's assets/ directory is copied to dist/assets/
2. Include — your project's include/ directory is copied to dist/include/

Custom copy paths

You can copy additional files or directories by configuring build.copy in your needle.config.json:

{
    "build": {
        "copy": ["myFolder", "myFile.txt"]
    }
}

Each entry is resolved relative to your project root and copied into the output directory.

To disable all automatic copying, set noCopy: true in the plugin options.

makeFilesLocal

Available since Needle Engine 4.16.0

Downloads external CDN assets at build time and bundles them into your output, producing fully self-contained deployments that work without internet access.

The plugin scans your project's compiled code for known external URLs (Google Fonts, Draco/KTX2 decoders, skyboxes, WebXR controller profiles, and more) and replaces them with local copies.

When to use: playable ads, app store submissions (Facebook Instant Games, Discord Activities), offline PWAs, restricted hosting environments (kiosks, museums).

Quick start

// Download everything
needlePlugins(command, { makeFilesLocal: true });

// Auto-detect which features your project uses
needlePlugins(command, { makeFilesLocal: "auto" });

Configuration

Available features

Examples

Auto-detect with exclusions:

needlePlugins(command, {
    makeFilesLocal: {
        enabled: true,
        features: "auto",
        excludeFeatures: ["xr", "polyhaven"],
    },
});

Only specific features:

needlePlugins(command, {
    makeFilesLocal: {
        enabled: true,
        features: ["draco", "ktx2", "fonts"],
    },
});

For Facebook Instant Games:

needlePlugins(command, {
    makeFilesLocal: {
        enabled: true,
        features: "auto",
        platform: "facebook-instant",
    },
});

Build output

When enabled, downloaded assets are placed in an ext/ directory inside your build output, organized by feature type. The plugin logs a summary at the end of each build.

Defines

The plugin injects Vite defines — compile-time constants that enable tree-shaking of optional features.

useRapier — When set to false, the Rapier physics engine WASM module is tree-shaken from the bundle. Note that Rapier is already lazily loaded by Needle Engine at runtime (it's only fetched when a physics component is actually used), so this option only affects the size of the build output — not runtime performance.

needlePlugins(command, {
    useRapier: false,
});

The plugin also injects build metadata (NEEDLE_ENGINE_VERSION, NEEDLE_ENGINE_GENERATOR, NEEDLE_PROJECT_BUILD_TIME) automatically.

See Also

• Progressive Web Apps (PWA) — Offline support and installability
• Optimization & Compression — Build pipeline, KTX2, Draco
• Deployment Platforms — Hosting and deployment options
• needle.config.json — Project configuration file