First Class Citizen

[#1]

When growing up, many of us heard the phrase “first-class citizen.” In society, it has a social or political meaning. In programming, however, it has a precise technical definition.

A first-class object (or first-class citizen) is an entity that can:

• Be assigned to a variable

• Be passed as an argument to a function

• Be returned from a function

In short, it can be treated like any other value in the language.

But what does “first-class citizen” mean inside the context of Atlassian Forge?

Forge Today: The Actual State of Things

Forge is Atlassian’s cloud-native development platform for building apps that run inside Atlassian Cloud products like:

• Jira

• Confluence

• Bitbucket

Forge was introduced as the long-term strategic direction for Atlassian Cloud extensibility.

Meanwhile, Atlassian Connect is not “dead,” but Atlassian has clearly positioned Forge as the future platform. Connect apps continue to work, but new capabilities increasingly launch on Forge first, and Atlassian encourages vendors to migrate over time.

So when we talk about “first-class citizen” in Forge, we are no longer talking about programming language semantics. We’re talking about platform priority, capability parity, and long-term viability.

UI in Forge: The Two Official Paths

Forge supports two UI approaches:

1. UI Kit

2. Custom UI

Let’s examine both - based on actual current capabilities.

UI Kit

What UI Kit actually is:

UI Kit is a declarative component framework provided by Forge. You write React-like syntax, but it runs in a controlled Forge runtime environment.

What it does well

• Tight integration with Forge backend functions

• Automatic security sandboxing

• No need to host static assets

• Simplified development for standard workflows

• Works seamlessly with Forge’s permission model

Real limitations (based on current platform behavior)

• Limited component set

• No direct DOM access

• No arbitrary third-party frontend libraries

• Limited styling flexibility

• No full control over browser APIs

UI Kit is intentionally constrained. It is designed for simplicity, security, and platform consistency - not for deep UI customization.

It is not an abstraction layer in the classical software architecture sense. It is a managed UI runtime with guardrails.

Custom UI

Custom UI is fundamentally different.

Here you:

• Build your frontend however you like (React, Vue, Svelte, vanilla JS)

• Bundle static assets

• Host them via Forge

• Communicate with backend functions via @Forge/bridge

What Custom UI enables

• Full control of layout and styling

• Third-party libraries

• Advanced state management

• Complex visualizations

• Rich UX interactions

• Near-parity with modern SPA development

The trade-off:

• More setup complexity

• You manage bundling

• You handle frontend architecture decisions

So… Is UI Kit a First-Class Citizen in Forge?

If we use the programming definition - the answer is irrelevant. UI approaches are not values in a language.

Instead, let’s redefine first-class citizen in the context of Forge:

A first-class citizen in a platform is a capability that:

• Receives long-term investment

• Achieves feature parity with platform evolution

• Is not structurally limited compared to alternatives

• Is viable for building production-grade commercial apps

Under that definition:

• Custom UI clearly qualifies.

• UI Kit qualifies - but with intentional constraints.

UI Kit is not a “second-class” feature. It is officially supported and actively maintained. However, it is opinionated by design. It optimizes for:

• Security

• Simplicity

• Compliance

• Fast internal tooling

Custom UI optimizes for:

• Flexibility

• Power

• Complex UX

• Marketplace-grade apps

The Real Strategic Direction

Based on Atlassian’s current documentation and ecosystem guidance:

• Forge is the strategic platform.

• Custom UI is the path for advanced UI.

• UI Kit is ideal for simple extensions and structured UI use cases.

• Atlassian continues to invest in both, but Custom UI offers fewer architectural ceilings.

The Practical Conclusion

If you're building:

• Internal tools

• Simple workflow extensions

• Lightweight panels

UI Kit is perfectly valid.

If you're building:

• Commercial Marketplace apps

• Advanced dashboards

• Rich analytics

• Complex frontend experiences

Custom UI is the safer long-term architectural choice.

Final Thought

In programming, a first-class citizen is about capability equality.

In Forge, being a first-class citizen is about platform priority, extensibility, and long-term viability.

UI Kit is supported.

Custom UI is unconstrained.

Forge itself is the future.

And in that ecosystem, the real first-class citizen is the approach that removes architectural ceilings before they remove your growth.

[Caterina Curti]

Just stopped by to add the fact that it is possible to combine the two approaches. Within a UI Kit app, you can add a frame component (https://developer.atlassian.com/platform/forge/ui-kit/components/frame/) and have Custom UI elements in it.

From the description at the top of the page:

Frame component acts as a container for rendering static frontend applications, such as HTML, CSS, and JavaScript, ensuring seamless integration with the UI Kit. It provides flexibility in implementing desired user interfaces and supports communication with the main app through the Events API, allowing bidirectional and broadcast communication.

[Prince Nyeche]

@Caterina Curti - Thanks for stopping by.

That may absolutely be possible, but the underlying limitations still exist.

The point of this article isn’t to dismiss one approach over the other. It’s to highlight both options clearly so developers can make informed architectural decisions early.

Good developers don’t just ask, “Can this work?”
They ask, “Will this still work 18–24 months from now?”

It’s far better to evaluate long-term fit upfront than to discover structural constraints after significant time, effort, and product investment have already been made.