Type Alias userSettings

userSettings: {
    ai?: {
        downloadReferences?: boolean;
        downloadReferencesDuringBuild?: boolean;
        install?: boolean;
        installDuringBuild?: boolean;
    };
    allowHotReload?: boolean;
    allowMetaPlugin?: boolean;
    buildPipeline?: {
        accessToken?: string;
        enabled?: boolean;
        maxWaitDuration?: number;
        projectName?: string;
        verbose?: boolean;
        version?: string;
    };
    copyIncludesFromEngine?: boolean;
    debug?: boolean;
    debugAlias?: boolean;
    debugImportChains?: boolean;
    debugLicense?: boolean;
    disableLogging?: boolean;
    dontInstallEditor?: boolean;
    dts?: { enabled?: boolean };
    facebookInstantGames?: {};
    license?: License;
    makeFilesLocal?:
        | boolean
        | "auto"
        | {
            enabled: boolean;
            exclude?: string[];
            excludeFeatures?: (
                | "draco"
                | "ktx2"
                | "materialx"
                | "xr"
                | "skybox"
                | "fonts"
                | "needle-fonts"
                | "needle-models"
                | "needle-avatars"
                | "polyhaven"
                | "cdn-scripts"
                | "github-content"
                | "threejs-models"
                | "needle-uploads"
            )[];
            features?: | "auto"
            | (
                | "draco"
                | "ktx2"
                | "materialx"
                | "xr"
                | "skybox"
                | "fonts"
                | "needle-fonts"
                | "needle-models"
                | "needle-avatars"
                | "polyhaven"
                | "cdn-scripts"
                | "github-content"
                | "threejs-models"
                | "needle-uploads"
            )[];
            platform?: "discord"
            | "facebook-instant"
            | null;
        };
    modules?: needleModules;
    noAlias?: boolean;
    noAsap?: boolean;
    noBuildInfo?: boolean;
    noBuildPipeline?: boolean;
    noCodegenTransform?: boolean;
    noCopy?: boolean;
    noCustomElementData?: boolean;
    noDependencyWatcher?: boolean;
    noFacebookInstantGames?: boolean;
    noPeer?: boolean;
    noPoster?: boolean;
    noReload?: boolean;
    openBrowser?: boolean;
    posterGenerationMode?: "default"
    | "once";
    pwa?: Record<string, unknown> | boolean;
    remote?: boolean | { qr?: boolean };
    useDrop?: boolean;
    usePostprocessing?: boolean;
    useRapier?: boolean;
    vite44Hack?: boolean;
}

Settings for the Needle plugin

Type declaration

Optionalai?: {
    downloadReferences?: boolean;
    downloadReferencesDuringBuild?: boolean;
    install?: boolean;
    installDuringBuild?: boolean;
}
Configure installation of local AI assistant skill files. The files install during dev server startup by default. Build-time installation is opt-in because builds should not normally mutate the project directory or fetch helper documentation.
- OptionaldownloadReferences?: boolean
  Set to false to skip downloading linked reference files during dev-server installation.
  Default
```
true
```
- OptionaldownloadReferencesDuringBuild?: boolean
  Set to true to download linked reference files during build-time installation.
  Default
```
false
```
- Optionalinstall?: boolean
  Set to false to disable AI helper file installation. Can also be disabled with NEEDLE_AI=false or NEEDLE_AI=0 (case-insensitive).
- OptionalinstallDuringBuild?: boolean
  Set to true to install AI helper files during Vite builds.
  Default
```
false
```
OptionalallowHotReload?: boolean
Set to false to disable hot reload for the needle plugin.
OptionalallowMetaPlugin?: boolean
set to false to prevent meta.html modifications (vite only)
OptionalbuildPipeline?: {
    accessToken?: string;
    enabled?: boolean;
    maxWaitDuration?: number;
    projectName?: string;
    verbose?: boolean;
    version?: string;
}
Use to configure optimized builds
- OptionalaccessToken?: string
  If defined the access token will be used to run compression on Needle Cloud.
  
  Expected to be a Needle Cloud access token (created in the Needle Cloud UI), NOT a JWT. Do not pass a licensing JWT here.
- Optionalenabled?: boolean
  Set to false to prevent the build pipeline from running
- OptionalmaxWaitDuration?: number
  The max duration the build pipeline will wait for the website bundling process to finish. After bundling has finished the pipeline will start processing the exported glTF files.
  Default is 60000 (60 seconds)
  Default
```
60000
```
- OptionalprojectName?: string
  Set a project name (cloud only)
- Optionalverbose?: boolean
  Enable for verbose log output
- Optionalversion?: string
  Set to a specific version of the Needle Build Pipeline.
  Default
```
"latest"
```
  Example
```
"2.2.0-alpha"
```
OptionalcopyIncludesFromEngine?: boolean
When enabled the needle-engine include directory will be copied
Optionaldebug?: boolean
Enable verbose debug output for needle plugins.
OptionaldebugAlias?: boolean
When set to true a plugin will log all alias resolutions to a file in the project node_modules directory
Default
```
false
```
OptionaldebugImportChains?: boolean
Set to true to create an imports.log file that shows all module imports. The file is generated when stopping the server.
OptionaldebugLicense?: boolean
Enable verbose logging
OptionaldisableLogging?: boolean
OptionaldontInstallEditor?: boolean
set to false to suppress editor-sync package installation and connection
Optionaldts?: { enabled?: boolean }
Generate Typescript declaration files for references 3D assets in your project.
These will be available via context.sceneData in your code.
Default
```
enabled
```
- Optionalenabled?: boolean
  When set to false, disables the generation of TypeScript declaration files.
  Default
```
true
```
OptionalfacebookInstantGames?: {}
Custom configuration for facebook instant games.
Optionallicense?: License
Use to activate a needle engine license
OptionalmakeFilesLocal?:
    | boolean
    | "auto"
    | {
        enabled: boolean;
        exclude?: string[];
        excludeFeatures?: (
            | "draco"
            | "ktx2"
            | "materialx"
            | "xr"
            | "skybox"
            | "fonts"
            | "needle-fonts"
            | "needle-models"
            | "needle-avatars"
            | "polyhaven"
            | "cdn-scripts"
            | "github-content"
            | "threejs-models"
            | "needle-uploads"
        )[];
        features?: | "auto"
        | (
            | "draco"
            | "ktx2"
            | "materialx"
            | "xr"
            | "skybox"
            | "fonts"
            | "needle-fonts"
            | "needle-models"
            | "needle-avatars"
            | "polyhaven"
            | "cdn-scripts"
            | "github-content"
            | "threejs-models"
            | "needle-uploads"
        )[];
        platform?: "discord"
        | "facebook-instant"
        | null;
    }
When enabled, external CDN URLs are downloaded at build time and bundled locally. This creates fully self-contained deployments that work without internet access.
- true — enable with all features (download everything)
- "auto" — automatically detect which features the project uses and only include those
- { enabled: true } — same as true
- { enabled: true, features: "auto" } — same as "auto"
- { enabled: true, features: ["draco", "ktx2"] } — only include specific features
- { enabled: true, excludeFeatures: ["xr"] } — include all except specific features
- { enabled: true, features: "auto", excludeFeatures: ["skybox"] } — auto-detect but exclude specific features
Available features:
- "draco" — Draco mesh decoders
- "ktx2" — KTX2/Basis texture transcoders
- "materialx" — MaterialX WASM shader compiler
- "xr" — WebXR input profiles (controllers/hands)
- "skybox" — Skybox/environment textures
- "fonts" — Google Fonts CSS + font files
- "needle-fonts" — Needle font assets (MSDF, etc.)
- "needle-models" — Needle models
- "needle-avatars" — Needle avatars
- "polyhaven" — Polyhaven HDRIs/models
- "cdn-scripts" — Third-party scripts (QRCode.js, vConsole, HLS.js)
- "github-content" — GitHub raw content files
- "threejs-models" — three.js example models
- "needle-uploads" — Needle uploads assets
Optionalmodules?: needleModules
used by nextjs config to forward the webpack module
OptionalnoAlias?: boolean
disable vite.alias modification
OptionalnoAsap?: boolean
disable needle asap plugin and glTF / GLB preload links
OptionalnoBuildInfo?: boolean
Set to true to disable generating the buildinfo.json file in your output directory
OptionalnoBuildPipeline?: boolean
Set to true to disable the needle build pipeline (running compression and optimization as a postprocessing step on the exported glTF files)
OptionalnoCodegenTransform?: boolean
OptionalnoCopy?: boolean
disable automatic copying of files to include and output directory (dist)
OptionalnoCustomElementData?: boolean
Set to true to disable the plugin that ensures VSCode workspace settings for custom-elements.json data
OptionalnoDependencyWatcher?: boolean
OptionalnoFacebookInstantGames?: boolean
OptionalnoPeer?: boolean
set to true to prevent injecting peerjs parcelRequire global variable declaration
OptionalnoPoster?: boolean
set to true to disable poster generation
OptionalnoReload?: boolean
set to true to disable reload plugin
OptionalopenBrowser?: boolean
When set to true a plugin will automatically attempt to open the browser using a network ip address when the local server has started
Default
```
undefined
```
OptionalposterGenerationMode?: "default" | "once"
Use "default" to always generate the poster after 'src' has changed Use "once" to generate the poster only once, when no poster already exists
Optionalpwa?: Record<string, unknown> | boolean
Pass in PWA options, true to enable with defaults, or false to disable. Options are forwarded to vite-plugin-pwa.
Optionalremote?: boolean | { qr?: boolean }
Enable remote debugging: bind the dev server to your local network (host) and serve over HTTPS (via @vitejs/plugin-basic-ssl) so you can open the page on a phone, Quest or Apple Vision Pro on the same Wi‑Fi. The Needle logger already streams the device's console, errors and device info back over Vite's websocket (see node_modules/.needle/logs/latest.client.needle.log), so this makes "debug a scene on a real device from your laptop" work out of the box. HTTPS is required for WebXR / secure‑context features on the device; the self‑signed certificate shows a one‑time warning you accept on the device.

Requires @vitejs/plugin-basic-ssl (for HTTPS) and, optionally, qrcode-terminal (to print a scannable QR code). Can also be toggled with the NEEDLE_REMOTE env var (NEEDLE_REMOTE=1 / =false).
- true — enable with a terminal QR code
- { qr: false } — enable but don't print the QR code
Default
```
false
```
OptionaluseDrop?: boolean
When enabled the Vite drop plugin will be enabled.
Default
```
false
```
OptionalusePostprocessing?: boolean
Set to false to prevent postprocessing effects from loading.
NOTE: by default Needle Engine uses dynamic loading of postprocessing modules. This means that the postprocessing code is only loaded when a postprocessing effect is used in the scene.
OptionaluseRapier?: boolean
Set to false to prevent the Rapier physics engine from loading.
NOTE: by default Needle Engine uses dynamic loading of the Rapier physics engine. This means that the Rapier code is only loaded when a physics component is used in the scene.
Optionalvite44Hack?: boolean
required for

Serializable
https://github.com/vitejs/vite/issues/13736

Type Alias userSettings

Type declaration

Optionalai?: { downloadReferences?: boolean; downloadReferencesDuringBuild?: boolean; install?: boolean; installDuringBuild?: boolean;}

OptionaldownloadReferences?: boolean

Default

OptionaldownloadReferencesDuringBuild?: boolean

Default

Optionalinstall?: boolean

OptionalinstallDuringBuild?: boolean

Default

OptionalallowHotReload?: boolean

OptionalallowMetaPlugin?: boolean

OptionalbuildPipeline?: { accessToken?: string; enabled?: boolean; maxWaitDuration?: number; projectName?: string; verbose?: boolean; version?: string;}

OptionalaccessToken?: string

Optionalenabled?: boolean

OptionalmaxWaitDuration?: number

Default

OptionalprojectName?: string

Optionalverbose?: boolean

Optionalversion?: string

Default

Example

OptionalcopyIncludesFromEngine?: boolean

Optionaldebug?: boolean

OptionaldebugAlias?: boolean

Default

OptionaldebugImportChains?: boolean

OptionaldebugLicense?: boolean

OptionaldisableLogging?: boolean

OptionaldontInstallEditor?: boolean

Optionaldts?: { enabled?: boolean }

Default

Optionalenabled?: boolean

Default

OptionalfacebookInstantGames?: {}

Optionallicense?: License

Optionalmodules?: needleModules

OptionalnoAlias?: boolean

OptionalnoAsap?: boolean

OptionalnoBuildInfo?: boolean

OptionalnoBuildPipeline?: boolean

OptionalnoCodegenTransform?: boolean

OptionalnoCopy?: boolean

OptionalnoCustomElementData?: boolean

OptionalnoDependencyWatcher?: boolean

OptionalnoFacebookInstantGames?: boolean

OptionalnoPeer?: boolean

OptionalnoPoster?: boolean

OptionalnoReload?: boolean

OptionalopenBrowser?: boolean

Default

OptionalposterGenerationMode?: "default" | "once"

Optionalpwa?: Record<string, unknown> | boolean

Optionalremote?: boolean | { qr?: boolean }

Default

OptionaluseDrop?: boolean

Default

OptionalusePostprocessing?: boolean

OptionaluseRapier?: boolean

Optionalvite44Hack?: boolean

Serializable

Settings

`Optional`ai?: {
downloadReferences?: boolean;
downloadReferencesDuringBuild?: boolean;
install?: boolean;
installDuringBuild?: boolean;
}

`Optional`downloadReferences?: boolean

`Optional`downloadReferencesDuringBuild?: boolean

`Optional`install?: boolean

`Optional`installDuringBuild?: boolean

`Optional`allowHotReload?: boolean

`Optional`allowMetaPlugin?: boolean

`Optional`buildPipeline?: {
accessToken?: string;
enabled?: boolean;
maxWaitDuration?: number;
projectName?: string;
verbose?: boolean;
version?: string;
}

`Optional`accessToken?: string

`Optional`enabled?: boolean

`Optional`maxWaitDuration?: number

`Optional`projectName?: string

`Optional`verbose?: boolean

`Optional`version?: string

`Optional`copyIncludesFromEngine?: boolean

`Optional`debug?: boolean

`Optional`debugAlias?: boolean

`Optional`debugImportChains?: boolean

`Optional`debugLicense?: boolean

`Optional`disableLogging?: boolean

`Optional`dontInstallEditor?: boolean

`Optional`dts?: { enabled?: boolean }

`Optional`enabled?: boolean

`Optional`facebookInstantGames?: {}

`Optional`license?: License

`Optional`modules?: needleModules

`Optional`noAlias?: boolean

`Optional`noAsap?: boolean

`Optional`noBuildInfo?: boolean

`Optional`noBuildPipeline?: boolean

`Optional`noCodegenTransform?: boolean

`Optional`noCopy?: boolean

`Optional`noCustomElementData?: boolean

`Optional`noDependencyWatcher?: boolean

`Optional`noFacebookInstantGames?: boolean

`Optional`noPeer?: boolean

`Optional`noPoster?: boolean

`Optional`noReload?: boolean

`Optional`openBrowser?: boolean

`Optional`posterGenerationMode?: "default" | "once"

`Optional`pwa?: Record<string, unknown> | boolean

`Optional`remote?: boolean | { qr?: boolean }

`Optional`useDrop?: boolean

`Optional`usePostprocessing?: boolean

`Optional`useRapier?: boolean

`Optional`vite44Hack?: boolean