How to Use Custom Components Across Spaces & Multiple Retool Instances

🧑‍💻 Retool Tips & Tricks
1

This guide outlines how to set up your environment, make changes, and sync custom components across instances connected through source control.

Multiple instances, Spaces and source control are available on the Enterprise Plan.

Step 1: Choose a Primary Instance For Your Component

When deploying a custom component library to multiple Retool instances or Spaces, you should choose one instance to be your primary development environment. This is the only instance you should login to, and the only place where you'll develop or deploy new versions of your custom components.

Step 2: Configure Your Sync Target With npx retool-ccl sync

This command will guide you through setting up a sync target, where you'll specify the instance you want to sync to.

CleanShot 2025-04-15 at 14.41.12@2x
CleanShot 2025-04-15 at 14.41.12@2x2272×198 200 KB

Before running it, make sure you've created an access token for the target instance. The token must have the Custom Component Libraries read and write scopes enabled to allow proper access through the Retool API.

Once these steps are complete, any time you run npx retool-ccl sync, that instance will be available to select for easy synchronization.

Step 3: Implement the Following Workflow

Now that you have your primary instance and ability to sync, it’s time to develop. Here's the workflow I use to ensure consistent custom component deployment across instances.

For the following example, I have two Retool instances. My Staging instance (localhost:3000) is where I do all of my app development. My Production instance (becs.retool.dev) is only used for production. No app changes are made directly to that instance; instead, changes made in staging are pulled into production via source control.

Watch the video here: How to Use Custom Components Across Multiple Retool Instances | Loom

  1. In your custom component repo, login to your primary custom component instance using npx retool-ccl login.

  2. Create a new branch in your app within your Retool Staging instance.

  3. Enter the dev environment in your custom component repo using npx retool-ccl dev.

  4. Make the necessary changes to the custom component and save.

  5. Deploy the updated version of your component using npx retool-ccl deploy.

  6. Sync the new version of your custom component library to your secondary instance by running npx retool-ccl sync and selecting the instance.

  7. In the Staging instance, exit the custom component dev mode and update version to the latest deploy.

  8. Commit and open a PR for your app changes from the Staging instance.

Once merged, you’ll see your Production instance updated with the newest version of the custom component.

9 Likes
2

Hi @becca ! Thanks for this helpful guide.

We started our component library before we got spaces. Now that we have spaces and are following the gitflow branching model, we have a uat space where do our development, and that gets merged into main.

How do we repoint our custom component library to our new uat space/instance?

1 Like
3

Hey @sgodoshian! Right now, are you using separate Custom Component Libraries for each space? Am I understanding that correctly? Or does the Custom Component only exist in the UAT space?

4

Hi @becca! We want to use the same Custom Component Library in both spaces. We added it to our uat space using npx retool-ccl sync. But when we run npx retool-ccl dev, there are no development branches to select in our uat space, only our main space.

5

Hmm. Where was the Custom Component original deployed (npx retool-ccl deploy)? Where you logged into UAT or Prod? Feel free to send screenshots too, that always helps. :slight_smile:

2 Likes
6

The custom component was originally deployed to Prod. Does it need to be redeployed to UAT?

Here's what I'm trying

retool-uat-space-component-library-dev-changes-not-showing
retool-uat-space-component-library-dev-changes-not-showing1914×1026 222 KB

2 Likes
7

My understanding is that the dev version of your CCL will only ever be associated with the primary instance. You essentially want to make UAT the new primary instance, right? :thinking: I think redeploying is probably what you want, but I'm not sure if you'll need to run an init command first. The fact that you were able to run dev suggests that it's not necessary.

2 Likes
8

Hey @sgodoshian,

Like @becca mentioned, it’s pretty simple to set up custom components across multiple Retool spaces. We actually talked about this before with @Darren in this thread: Cicd for custom component using retool-ccl without user interaction .

The nice part is that you can sync custom components across different spaces automatically, without any manual user interaction. Makes life a lot easier when you want to keep everything consistent and up to date.

On top of that, if you want to take it a step further, you can even plug this into a CI/CD pipeline so updates roll out smoothly across all your spaces.

2 Likes
9

Let us know if you have any follow up questions about this, @sgodoshian!

2 Likes
10

Cicd for custom component using retool-ccl without user interaction - #6 by Darren - this is great, thank you for sharing!

We ended up creating a new custom component library deployed first to UAT.

3 Likes