Use Retool custom component library
Learn how to use the Retool custom component library with your custom component.
When developing custom components, Retool recommends you use the Retool custom component library (retool-ccl) utility's dev function (dev mode). Dev mode updates your component in Retool as you make edits, which means you don't have to constantly deploy new versions and update your app in Retool.
Each developer (identified by the access key supplied at npx retool-ccl login) has their own dev revision of the component library.
Dev mode
Run the following command to use dev mode. The first time you run this command for a library it creates your dev version in Retool.
npx retool-ccl dev
This command continues to run and watch for file changes. Whenever you save your component files, they're automatically reflected in your Retool app.
With your dev version created, you can now use it in your Retool app. In App settings > Custom Components, you can switch between your dev version dev: {your-email} or any other published version. When you're ready to publish, be sure to change your app to use a published version instead of the dev version.
Update your component
To update your component, run npx retool-ccl dev, and then navigate to your app's Custom Component settings to change the version back to dev. When you're finished, follow the same steps to deploy your component and pin the app to the latest version.
To delete a library, sign in to your Retool organization and navigate to Settings > Custom Component Libraries. Removing a custom component library deletes all components in the library from your app.
Debug your components
As you build a custom component, you may need to troubleshoot issues that arise. When using dev mode, Retool includes source maps for your components, so you can use your browser's step-by-step debugging tools to debug any issues that come up.
Expand your library
You can add multiple custom components to your library by exporting more React components from src/index.tsx (only components exported from this file are detected). You can also create multiple libraries by creating a separate TypeScript project and following the steps in the Create a custom component guide.
Use custom component libraries across multiple instances or Spaces
If you deploy applications to multiple instances or to Retool Spaces, additional steps are required to use custom component libraries across them. When deploying the same custom component library to multiple instances or Spaces, choose a primary instance or Space for your components. This is the only instance or Space that you should ever log in or deploy your components to.
To use your components on other instances or Spaces, sync them from your primary instance or Space with the following command:
npx retool-ccl sync
This command guides you through configuring a sync target, and then copies over the library and all available versions. When new versions are available in the primary instance or Space, re-run the sync command to copy them to any others. Any applications that reference these components automatically use the recently synced version.
Send custom HTTP headers or cookies
If you have a self-hosted Retool deployment, you can use npx retool-ccl to send additional custom headers or cookies with each HTTP request. This can be helpful if there is an application load balancer that:
- Is between where you develop your custom components and the deployment instance.
- Blocks HTTP requests that are missing certain authentication headers or cookies.
To send custom HTTP headers or cookies, use the --header 'header-name: header_value' option when using npx retool-ccl.
Every command supports this option. You can also include it multiple times for each header to include.
npx retool-ccl login --header 'header-name: header_value' --header 'header-name-2: header_value_2'
When using the sync command, include --target-header to specify headers for the target instance of Retool. --header sends headers to the origin instance of Retool.
npx retool-ccl sync --header 'origin-header-name: value_1' --target-header 'target-header-name: value_2'
You can also send multiple cookies using a header name of Cookie.
npx retool-ccl deploy --header 'Cookie: cookie_one=cookie_value_one; cookie_two=cookie_value_two'