Packages
Use packages to share and reuse functions between apps.
A package is a collection of shared code that can be reused between apps. Packages help your organization prevent duplication and promote consistent behavior across apps. Packages are versioned and have their own permissions, allowing admins to govern access to code and resources.
Packages support sharing functions.
Use this guide to learn more about how to create and use packages.
Requirements
Before you begin, ensure the following requirements are met:
- Your organization is on an Enterprise plan.
- Your organization has been grated access to the Packages feature by Retool
- Retool AI Access is enabled in Settings > AI.
Assign permissions
Configure your organization so that the appropriate people have permissions to use, create, or own packages. By default, the Admin group has Own access to packages, and the Editor group has Use access. If you want to expand access to packages, you can grant permissions to a group.
Grant permissions
Manage package permissions by granting groups object permissions.
To set up permissions for packages, use the following steps:
- Navigate to Settings > Groups, and select or create a group.
- Go to the Object permissions tab and click Edit permissions.
- Click Universal access, and set the access level that you want to give the group for Packages.
- Optionally, set the access level for Resources. Use access on a resource is required to create functions that call the resource.
- Click Review changes, then click Confirm.
- Add users to the group.
Learn more in Manage object permissions.
Access levels
The following table outlines the capabilities of each access level.
| Access level | Capabilities |
|---|---|
| Use |
|
| Edit |
|
| Own |
|
Create package
To create a new package, click Packages in the main Retool navigation. Click Create package.
Use the prompt box to describe the reusable functions that you want to author. Click to change the AI model that your prompt uses.
The functions that the agent drafts appear in the Overview tab. Click each function to open the Function playground. There, review the code or run the function with sample parameters. You can make changes to each function using the prompt box, or by manually editing the code. If applicable, click Approve when you're happy with the function.
By default, you must approve each function that edits, adds, or deletes data before you publish the package. You can disable this setting by toggling Require approval to run functions that may modify data off.
Publish package
You must publish your package before it can be used in an app. When you're ready to publish your changes, click Publish. In the publishing modal that appears, choose whether to tag your changes as a patch, minor, or major update. This creates a new version of your package, which can be imported into your apps.
Package publishing differs from app publishing in that you must tag your changes as a release every time you publish a package.
Click Next to publish the package.
Update package
To update a package, select it from the Packages page. Use the Chat tab to prompt the agent to make updates to your package, or manually make changes to functions from the Code tab. When you're ready, publish the package. The publish modal shows you which apps, if any, use this package.
Import a shared function to an app
To add one or more shared functions to an app, prompt the agent to add the package or function that you want to add.
Update an imported package
When you import a package into an app, the app uses the newest version of the package available. Builders retain control of the package version that their app uses. If someone publishes a change to the package, apps that already imported it keep using their installed version and do not break.
When a package used in your app has a newer version, the app builder shows a notification during your next editing session. Open the notification to view every outdated package, including with the functions that were added, updated, and deleted in each.
For each package, choose whether to update to the latest version or keep your current version. You can select multiple packages to update together, or update them one at a time.
Edit an imported function
Imported functions may not necessarily perform the exact function that the app needs or expects. For users with Edit or Own access to the package, the agent prompts the user to update the app or edit the function. If you edit the function, the app forwards your request to the Packages interface, and you can finish making your changes there.
When you return to the app builder, the agent prompts you to update your app to use the latest package version.
Share function to a package
To make functions created in the app builder reusable, you can share the function to a package using the following steps:
- In the app builder, switch to the Data tab and select the function that you want to share.
- In the Function playground that appears, click Share to package.
- In the modal that appears, choose the package that you want to add the function to.
- Your change will create a new release of the package. Choose in the Releases dropdown whether you want to create a new patch, minor, or major release.
- Click Publish.
Use packages with the Retool CLI
If you build apps with the Retool CLI, you can find, use, create, and publish packages from the command line. This lets you, or a local development agent, reuse your organization's shared functions in code that you write on your own machine.
Packages are stored as independent directories, separate from any app.
Requirements
Before you begin, ensure the following requirements are met:
- Your organization meets the requirements for packages.
- Retool has enabled the CLI package commands for your organization. If a
retool packagescommand reports that packages are not enabled, contact Retool support to request access. - You have installed the Retool CLI and signed in.
The package access levels also apply in the CLI. For every package command and option, refer to the Retool CLI reference.
Create and publish a package
To create or change a package, use the following steps:
-
Create a package, or download one that you can edit:
retool packages init "Finance helpers"creates a package in Retool and a local package directory with one starter function.retool packages clone @retool.org.example/financedownloads an existing package on a local branch. Runretool packages listto find the package name.
-
Add or edit functions. Each function is one file in
backend/that default-exports an async function and takes aparamsobject, like a function in an app. A package can't have afrontend/directory, dependencies, or imports of other packages. Retool manages itspackage.json, including the version. -
Validate the package with
retool check. To also typecheck and build the package locally, first install the tools without changingpackage.json:npm install --no-save --no-package-lock esbuild typescript -
Optionally, test a function with
retool packages run, as you would in an app. The test run needs the tools from the previous step. -
Send your changes to Retool with
retool push -m "<what changed>".pushlists any functions that still need approval. -
Publish a version of the package. Choose
patch,minor, ormajor, and Retool sets the version number.retool publish --release patchWhen the publish finishes, the CLI prints the version and the
pnpm -F backend addcommand that installs it in an app.
By default, a function that adds, edits, or deletes data needs approval before you can publish the package. retool publish stops, lists each pending function, and says whether you can approve it based on your access to the given resource called by the function. If you can, review the function, then run retool publish again with --approve-function <path> for each function, or --approve-functions for all of them. If you can't, the CLI prints a link to approve the function in Retool. Send it to someone with edit access to the function's resources and workflows.
You can't publish a protected package from the CLI. retool publish stops and prints a link to the package in Retool, where you publish it.
Use a package in an app
To call a shared function from an app, install its package in the app. Then call the shared function from one of the app's own functions. Use the following steps:
-
From your local app directory, list the packages that your organization publishes and the functions that each one exports.
retool packages list --functionsThe CLI also saves this list in your local app directory under
.retool/packages/. The file for each package shows the import path of each function. -
Install the package in the app's
backenddirectory. Pin the exact version that the list shows.pnpm -F backend add @retool.org.example/finance@1.2.0 --save-exact -
Write a function in the app that imports the shared function and calls it. Import the shared function from its
.tspath, and pass it aparamsobject.backend/getInvoiceTotal.tsimport calculateTotal from '@retool.org.example/finance/backend/calculateTotal.ts'export default async function getInvoiceTotal({ params }: { params: { invoiceId: string } }) {return { total: await calculateTotal({ params: { invoiceId: params.invoiceId } }) }} -
Validate the app with
retool check. -
Send the app to Retool with
retool push.
When a newer version of the package is published, run the pnpm -F backend add command again with that version, then run retool check.
Source Control
Enterprise organizations that use Source Control can protect packages for more control over changes.
Protect a package
Protect a package with the following steps:
- On the Packages page, locate the package that you want to protect, and click ᐧᐧᐧ. Select Protect package.
- In the modal that appears, click Protect package.
- Click Open pull request.
- Retool opens a pull request in a new tab. Review and create the pull request with the initial commit for the package. Merge it when you are ready.
- Return to the Packages interface. A confirmation modal appears with the message Protection complete. Click Done.
Publish a protected package
For packages, making changes in your source control repository and publishing your package are decoupled. For each change you make, you must first open a pull request, and separately publish the package.
- Make your desired changes to the package.
- Click Open pull request. A modal appears, showing a checklist that ensures all functions have been approved and that there are no merge conflicts. Confirm by clicking Open pull request again.
- Retool opens a pull request in a new tab. Review and create the pull request with your changes. Merge it when you are ready.
- Return to the package interface. Open Change History and switch to the Publish History tab.
- Find the commit that you want to publish, and click Publish.
- Review the commit selection in the modal that appears, and choose whether to tag the changes as a major, minor, or patch release. Click Publish.
A Pending publish tag appears next to the commit that you tagged as a release. On the next Source Control deployment, Retool begins a build of the tagged commit, bundling each function and publishing it as a versioned release. This build makes the new version of your package available to your apps.