Building Atlassian Plugins That Scale: Lessons from the Marketplace
After shipping multiple plugins to the Atlassian Marketplace, here are the architectural patterns and hard-won lessons we wish we had known from day one.
Building for the Atlassian ecosystem is a uniquely interesting engineering challenge. You are working within a well-defined platform that has its own conventions, performance expectations, and security model — but you also have customers with wildly varying configurations, data volumes, and usage patterns.
After shipping plugins to the Marketplace and supporting them across hundreds of customer instances, we have accumulated a set of hard-won lessons.
Understand the Data Model First
The single most expensive mistake you can make in an Atlassian plugin is building against your assumptions about how customers will use Jira or Confluence — rather than against the actual data model.
A feature that works beautifully in a project with 500 issues will fail silently in an enterprise instance with 500,000. Build for the 99th percentile from day one.
Practical guidance:
- Always paginate API calls. Never assume you can fetch all items in a single request.
- Test with large datasets early. Spin up a test instance and seed it with realistic data volumes.
- Use Atlassian's batch APIs where available. They exist for a reason.
Embrace the Forge Runtime
If you are starting a new plugin today, build it on Forge. The Connect model (external hosted apps) is still supported, but Forge's runtime-managed model dramatically reduces operational overhead and simplifies the security story.
Yes, Forge has constraints. The function execution timeout, the storage API, the remote calls model — they all require adjustment if you are coming from a conventional web app mindset. But the tradeoffs are overwhelmingly favorable for most plugin use cases.
Design for Configuration Diversity
Enterprise Atlassian instances are deeply customized. Custom fields, workflow configurations, permission schemes, project types — your plugin will encounter combinations you never anticipated.
What this means in practice:
- Never hardcode field IDs or workflow transition names. Resolve them dynamically.
- Build graceful degradation for missing fields or permissions.
- Test against both a clean project and a heavily customized one.
- Expose sensible defaults that work for 80% of users out of the box, with configuration options for the rest.
Performance Is a Feature
Atlassian's Marketplace review process has become increasingly rigorous about performance. More importantly, users will abandon a plugin that makes their Jira feel sluggish.
Instrument your plugin from day one:
- Log execution times for all API calls and data operations
- Use Forge product triggers efficiently — avoid running heavy operations in synchronous issue update webhooks
- Cache aggressively where data freshness requirements allow
The Support Burden Is Real
Building a plugin is one thing. Supporting it across versions of Jira Cloud (which updates automatically), across customer configurations, and across the long tail of edge cases is a different challenge entirely.
Invest in:
- Comprehensive error logging that includes enough context to reproduce issues without access to the customer's instance
- A compatibility matrix so you know which versions of your plugin support which Jira/Confluence features
- In-app documentation that reduces the surface area of support questions
Versioning and Backwards Compatibility
Your customers have automated workflows that depend on your plugin's behavior. Breaking changes — even well-intentioned ones — cause real business disruption.
Treat your plugin's configuration schema and any exposed APIs as a public contract. Maintain backwards compatibility, provide migration paths, and communicate changes clearly in your changelog.
Building an Atlassian plugin and want expert guidance? Reach out — we offer Atlassian development consultancy and can help at any stage of the process.