@needle-tools/engine/plugins/types/userconfig.d.ts

Needle Engine is a web-based runtime for 3D apps. It runs on your machine for development with great integrations into editors like Unity or Blender - and can be deployed onto any device! It is flexible, extensible and networking and XR are built-in.

import { License } from "./license.js";

export type needleModules = {
    webpack: object | undefined
}

/**
 * Settings for the Needle plugin
 */
export type userSettings = {

    /** disable needle asap plugin and glTF / GLB preload links */
    noAsap?: boolean;

    /** disable vite.alias modification */
    noAlias?: boolean;
    /** Enable verbose debug output for needle plugins. */
    debug?: boolean;
    /**
     * When set to `true` a plugin will log all alias resolutions to a file in the project node_modules directory
     * @default false
     */
    debugAlias?: boolean;

    /** disable automatic copying of files to include and output directory (dist) */
    noCopy?: boolean;
    /** When enabled the needle-engine include directory will be copied */
    copyIncludesFromEngine?: boolean;
    /** set to false to tree-shake rapier physics engine to the reduce bundle size */
    useRapier?: boolean;
    /** experimental */
    usePostprocessing?: boolean;
    noDependencyWatcher?: boolean;
    /** set to false to suppress editor-sync package installation and connection */
    dontInstallEditor?: boolean;
    /** set to false to prevent meta.html modifications (vite only) */
    allowMetaPlugin?: boolean;
    /** set to true to prevent injecting peerjs `parcelRequire` global variable declaration */
    noPeer?: boolean;
    /** set to true to disable reload plugin */
    noReload?: boolean;
    /** Set to false to disable hot reload for the needle plugin. */
    allowHotReload?: boolean;

    /** When enabled the Vite drop plugin will be enabled. @default false */
    useDrop?: boolean;

    noCodegenTransform?: boolean;
    noFacebookInstantGames?: boolean;
    /** Custom configuration for facebook instant games. */
    facebookInstantGames?: {}
    /** Set to true to create an imports.log file that shows all module imports. The file is generated when stopping the server. */
    debugImportChains?: boolean;

    /** Set to true to disable generating the buildinfo.json file in your output directory */
    noBuildInfo?: boolean;

    /** Set to true to disable the needle build pipeline (running compression and optimization as a postprocessing step on the exported glTF files) */
    noBuildPipeline?: boolean;

    /**
     * Use to configure optimized builds
     */
    buildPipeline?: {
        /** Set to false to prevent the build pipeline from running */
        enabled?: boolean,
        /** Set a project name (cloud only) */
        projectName?: string,
        /** Enable for verbose log output */
        verbose?: boolean,

        /** Set to a specific version of the Needle Build Pipeline.
         * @default "latest"
         * @example "2.2.0-alpha"
        */
        version?: string;

        /** If defined the access token will be used to run compression on Needle Cloud */
        accessToken?: string | undefined;

        /**
         * 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
         */
        maxWaitDuration?: number; // in ms, default 60000 (60 seconds)
    }

    /** required for @serializable https://github.com/vitejs/vite/issues/13736 */
    vite44Hack?: boolean;

    /** set to true to disable poster generation */
    noPoster?: boolean;
    // posterFormat?: "image/webp";// | "image/png";
    /** 
     * Use "default" to always generate the poster after 'src' has changed
     * Use "once" to generate the poster only once, when no poster already exists
    */
    posterGenerationMode?: "default" | "once";

    /** Pass in PWA options, `true` to enable with defaults, or `false` to disable.
     * Options are forwarded to `vite-plugin-pwa`.
     */
    pwa?: Record<string, unknown> | boolean;

    /** used by nextjs config to forward the webpack module */
    modules?: needleModules;

    /**
     * Use to activate a needle engine license
     */
    license?: License;

    /** Enable verbose logging */
    debugLicense?: boolean;

    /**
     * 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
     */
    makeFilesLocal?: boolean | "auto" | {
        enabled: boolean;
        /** URL patterns to exclude from making local */
        exclude?: string[];
        /** Target platform preset */
        platform?: "discord" | "facebook-instant" | null;
        /** 
         * Feature categories to include.
         * - `"auto"` — Automatically detect which features the project uses.
         * - `FeatureName[]` — Explicit list. When set, ONLY these features are processed.
         * - When omitted, ALL features are included.
         */
        features?: "auto" | Array<"draco" | "ktx2" | "materialx" | "xr" | "skybox" | "fonts" | "needle-fonts" | "needle-models" | "needle-avatars" | "polyhaven" | "cdn-scripts" | "github-content" | "threejs-models" | "needle-uploads">;
        /** Feature categories to exclude. Applied after `features` (including after auto-detection). */
        excludeFeatures?: Array<"draco" | "ktx2" | "materialx" | "xr" | "skybox" | "fonts" | "needle-fonts" | "needle-models" | "needle-avatars" | "polyhaven" | "cdn-scripts" | "github-content" | "threejs-models" | "needle-uploads">;
    }

    /**
     * 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
     */
    openBrowser?: boolean;

    disableLogging?: boolean;

    /** Set to true to disable the plugin that ensures VSCode workspace settings for custom-elements.json data */
    noCustomElementData?: boolean;
}