Skip to main content
Custom dependencies are off by default. On Lightdash Cloud, contact Lightdash support to enable them for your organization. On self-hosted instances, add enable-data-app-custom-dependencies to LIGHTDASH_ENABLE_FEATURE_FLAGS (see feature flags). Uploading an app that declares custom dependencies also requires the manage:DataAppDependency permission, granted only to admins by default.
By default, apps build against a fixed, pre-installed library set that Lightdash vets and ships — edits to package.json are ignored. Turning custom dependencies on lets an app pull additional packages from the public npm registry into the build sandbox, which is why it’s opt-in:
  • A third-party library becomes part of your app. It can shape how the app behaves and touch any data the app is allowed to query, so the main consideration is trust in the libraries you choose. That’s also why the upload permission (manage:DataAppDependency) is restricted to admins by default.
  • Lightdash adds several layers of protection to reduce that risk: every uploaded version is screened against the OSV malicious-package feed, installs use --frozen-lockfile --ignore-scripts so lifecycle scripts can’t run, the sandbox has no access to Lightdash credentials, and network egress is limited to the npm registry.
With custom dependencies enabled, you can extend the pre-installed set from the app folder. Follow Local data app development to download or create the app first:
Both files matter: the dependency set is package.json plus a matching pnpm-lock.yaml (the server installs with pnpm, so an npm lockfile won’t do). On upload, the CLI shows what you’re adding and asks for confirmation:
If the upload fails with Custom app dependencies are not enabled for your organization, you have the manage:DataAppDependency permission, but custom dependencies aren’t turned on for your organization. Rules the CLI and server enforce:
  • Registry semver specs only (^9.3.5, ~1.2.0, ranges). No git:/file:/URL specs and no dist-tags like latest.
  • At most 60 direct dependencies; lockfile ≤ 2 MB and consistent with package.json.
  • Every version is screened against the OSV malicious-package feed at upload; known-bad versions are rejected outright.
Additional hardening: install scripts also never run on your machine — the scaffolded .npmrc sets ignore-scripts=true; keep it. Self-hosted instances can further tighten the policy by requiring a minimum package release age (LIGHTDASH_APP_DEPENDENCY_MIN_RELEASE_AGE_DAYS) or pointing installs at an internal mirror (LIGHTDASH_APP_DEPENDENCY_REGISTRY_HOSTS). Uploads are the only way to change dependencies. When someone iterates on the app in the UI, the AI builder can edit src/ but the stored dependency set is restored as-is — its package.json edits are ignored. Dependency changes on a version are visible in the version history.