How Iguana Components Are Structured
In a previous post, we looked at the idea behind Components and why Iguana is built around them. Now we can take a closer look at how a Component is actually put together. Even though each Component has its own purpose, they all follow the same structure. This consistency is what makes them reliable, reusable, and easy to understand.
This post explains the two main sides of every Component, how configuration works, and how Iguana keeps everything organized inside the system.
Two Parts of Every Component
Every Component has two connected parts that work together during development and when the interface is running.
1. Configuration: The frontend card
The card is the part users see in the Iguana dashboard. It contains fields, switches, buttons, and other information about the Component. This is where someone can set values, enter environment specific details, and control basic behavior like starting and stopping the Component.
The purpose of the card is to expose only what needs to be configurable. It keeps the settings simple and avoids forcing users to understand the underlying code.
2. Code: The backend Translator project
Behind the card is the Translator project. This is where all the scripting logic lives. The Translator contains the functions, helpers, transformations, and operations that make the Component do its job. This is the part developers edit when they build or customize a Component.
Because the code lives in a Translator project, it is version controlled with Git. This gives teams a clear history of changes and a safe way to manage updates.
How the Card and Translator Work Together
These two parts are connected through configuration fields. A field defined inside the Component project appears on the card in Iguana. When a user enters a value in the card, that value becomes available to the code in the Translator.
This design allows a Component to be reused in many contexts without changing its code. For example, you might use the same Component to send data to two different systems. Each instance of that Component can have its own settings on the card, while the underlying logic stays the same.
The Role of config.json
Inside every Component project is a file named config.json. This file defines the fields that appear on the card. It describes:
- The name of each field
- The type of data the field accepts
- The default value
- Whether it should be visible or hidden
- How Iguana should store and secure it
When Iguana reads config.json, it builds the card for the Component. If a developer updates the file, the card updates automatically the next time the Component loads.
This provides a clean separation between how a Component looks in the UI and how it behaves in code.
How Iguana Manages Component Code
All Component code lives inside a Git repository. Iguana handles:
- Creating the repository
- Saving commits when you make changes in the Translator
- Allowing you to view revision history
- Letting you roll back if needed
This means the entire logic of a Component is tracked and backed up. Teams can collaborate safely, and upgrades become predictable.
Each Component also has a run directory that Iguana uses when the Component is active. The system keeps the development code and runtime code separate, which helps with safety and debugging.
Why This Structure Matters
Predictability
Every Component uses the same pattern. A card for configuration. A Translator project for code. A config.json file to connect the two.
Clear roles
Non developers adjust settings on the card. Developers write and maintain the code. Each group works in the right place without stepping on each other.
Secure and flexible configuration
Custom fields can be encrypted, validated, or hidden. This lets Components handle sensitive information like API keys in a safe way.
Reuse at scale
One Component can be deployed many times with different configurations. A single codebase can serve multiple interfaces.
A Component in Action
When Iguana starts a Component, it loads the configured fields, runs the Translator code, and provides whatever behaviour the Component is built for. The card remains available for users to update settings, and the Translator remains version controlled for developers.
This creates a workflow where configuration, logic, and runtime behaviour work together in a clean and reliable way.
