Skip to main content

Add third-party packages to an app

Add third-party packages to extend the functionality of your app.

Retool supports adding npm packages so that additional functionality can be used in your apps.

Configure support for public npm packages​

Third-party npm packages are enabled by default. To disable this setting, navigate to Settings > Advanced settings and toggle off Allow third-party npm packages in apps.

Configure support for private registries​

Enterprise organization admins can specify private registries from which users can install packages. This enables you to distribute custom packages from a server that you control to users in your organization. Follow the instructions in this section to add private registries to your organization.

Requirements​

Private registries are subject to the following requirements:

  • Registries must be npm-compatible (support the npm registry API). Packages installed from a Git repository, a direct URL, or a local file path aren’t supported.
  • Registry URLs must begin with https://. URLs beginning with http:// are not permitted.

Add a private registry​

Complete the following steps to add a private registry:

  1. Navigate to Settings > App Security.
  2. In the Private npm registries section, click Add registry.
  3. For Registry URL, enter the address of your registry. For example: https://npm.example.com.
  4. Under Authentication, choose one of the following options. Retool stores credentials encrypted. After you save, the credential is never shown again, and the registry’s row shows only the authentication type.
    1. None if the registry doesn’t require sign-in.
    2. Bearer Token, then enter the token.
    3. Basic Auth, then enter the username and password.
  5. (Optional) In Scopes, enter the npm scopes to download from this registry, for example @acme, and press Enter after each one. Add a scope to a registry to allow users to install every package in that scope from that registry. Refer to Choose how packages are routed for more information.
  6. (Optional) Turn on Use as default registry. Refer to Set a default registry for more information.
  7. Click Add registry.
note

Retool strongly recommends providing read-only credentials for your registry.

Set a default registry​

You can optionally set one registry as the default.

If you set a default registry, all packages without a listed scope are downloaded from there, including the common ones that apps include automatically, such as React. When you turn on a default registry, make sure the registry has every package your builders use, including those required by Retool.

note

Retool doesn't fall back to npmjs.org when a package is routed to a configured registry that's unreachable. In that case, the package download fails.

Stop using private registries​

To stop using private registries, remove each entry from the Private npm registries section in Settings > App Security. Retool then loses access to packages that exist only in your private registries and downloads packages from npmjs.org instead. Apps that depend on a missing package fail to build and cannot be published.

Choose how packages are routed​

When the user prompts the agent to install a package, the package is downloaded from the first of the following locations that applies:

  1. If the package name includes a scope that is listed in the Private npm registries settings, such as @acme/design-system, it is downloaded from the registry that includes that scope.
  2. If the package name has no listed scope, and a default registry is set, it is downloaded from the default registry.
  3. If the package name has no listed scope, and no default is set, it is downloaded from npmjs.org.

Install packages in apps​

Ask the agent to add your desired npm package from the prompting box.

Use the `lightweight-charts` npm package for my charts.
Install `mui/material` and use that for my component design.

The agent always asks for permission before installing a third-party package. When prompted, carefully review the request, and apply any security guidance provided to you by your organization administrators or security team. If you trust the package, approve it, and the agent will configure your app accordingly.

You can also prompt the agent to update or remove any dependencies.

Security restrictions​

Retool imposes certain restrictions on the types of packages that can be installed. Retool blocks a package if it does not meet the following requirements:

  • When installing public npm packages, the version of the package must be at least 5 days old. Compromised packages are often discovered quickly. By waiting 5 days to install a package, you reduce the risk of installing a package before it's been fully vetted. This restriction doesn't apply to packages from private registries.
  • Packages must use one of the following open source licenses, which allow for use and distribution with minimal restrictions. While Retool enforces a list of allowable licenses, it is your responsibility to confirm the license requirements for any third-party packages in your apps.

The agent always asks for permission before installing a third-party package.

While Retool does not strictly enforce package compatibility, the agent uses React 19 to build your apps. Ensure your package supports this version in order to avoid any adverse effects.

Best practices​

The agent verifies that your package meets the security requirements but it cannot verify any third-party packages you add to your app. You must independently verify each package that you install in your app. These best practices apply to packages from both public npm and private registries. Use them to safely add packages to your app. Refer to Risks and security considerations for more information.

Verify the package name before installing​

Double-check the exact spelling of any package name before installing it. Attackers sometimes publish packages with names that closely resemble popular packages to trick users into installing malicious code. Confirm the package name on npmjs.com or your registry URL and verify it matches the one you intend to install.

Check package reputation and maintenance​

Before installing a package, review its activity on npmjs.com or your registry URL and its source repository. For a package from a private registry, also confirm who owns and maintains it. Look for indicators of an actively maintained and widely trusted package:

  • High weekly download counts.
  • Recent publish dates.
  • Active issue tracking and pull request history.
  • Multiple contributors or a reputable publisher.

Avoid packages with very few downloads, no recent updates, or a single anonymous maintainer.

Review the package's dependencies​

A package's dependencies are also included when you install them. A trusted package can still introduce risk through a compromised or vulnerable dependency. Check the package's dependency tree on npm and avoid packages with an unusually large number of transitive dependencies.

Check for known vulnerabilities​

Search for the package in a vulnerability database such as the npm advisory database or Socket before installing. These sources list known security issues and can help you assess whether a package is safe to use. Packages hosted only in a private registry won't appear in public databases, so scan them with your organization's own security tooling.

Risks and security considerations​

The following sections outline the risks of installing third-party packages in your app, whether they come from public npm or a private registry.

Third-party packages, even those that are well-known and widely vetted, could have compromised code. For example, the following scenarios are possible:

  • A package has its supply chain compromised. For example, attackers could retrieve the package maintainers' git tokens.
  • A package uses another package as its dependency, which is compromised in some way.
  • A package is subject to typosquatting, or the user accidentally installs a package that’s maliciously owned instead of the one that is trusted.
  • A package could contain a vulnerability that could be exploited at runtime.
  • A private registry, or the credentials used to publish to it, is compromised, so attackers can publish malicious versions of internal packages.
  • A package that was previously safe could include a vulnerability in an update.

If you add an untrusted or compromised package to your app, malicious payloads could be executed at install time or at runtime. If this occurs, the following risks are possible:

  • Attackers could have access to any action the user takes, such as resetting their password or multi-factor authentication (MFA), inviting or promoting an outside account to admin, etc.
  • Attackers could make arbitrary resource queries in the organization.
  • Attackers could install malware in the code execution environment to monitor resource queries and forward them to an attacker-controlled log.