> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lightdash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom dependencies

> Add packages to data apps and check dependency requirements and limits

[Experimental](https://docs.lightdash.com/support/feature-badges.md#experimental)

> [!NOTE]
>
> 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](https://docs.lightdash.com/self-host/customize-deployment/environment-variables.md#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](https://docs.lightdash.com/workflow/local-data-app-development.md) to download or create the app first:

```bash theme={null}
cd lightdash/apps/revenue-explorer
pnpm add deck.gl          # updates package.json AND pnpm-lock.yaml
lightdash upload --apps revenue-explorer
```

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:

```text theme={null}
"revenue-explorer" declares custom dependencies that will be installed in the build sandbox:
  + deck.gl@^9.3.5 (not in default template)
Upload "revenue-explorer" with custom dependencies?
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.