Type Alias userSettings

userSettings: {
    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;
    useDrop?: boolean;
    usePostprocessing?: boolean;
    useRapier?: boolean;
    vite44Hack?: boolean;
}

Settings for the Needle plugin

Type declaration

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
- 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.
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

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

OptionaluseDrop?: boolean

Default

OptionalusePostprocessing?: boolean

OptionaluseRapier?: boolean

Optionalvite44Hack?: boolean

Serializable

Settings

`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`useDrop?: boolean

`Optional`usePostprocessing?: boolean

`Optional`useRapier?: boolean

`Optional`vite44Hack?: boolean