⚡️ Introducing Custom UI: Static HTML/CSS/JS frontends on Forge

[huw]

When we launched Forge for in-house developers, we heard a lot of meaningful feedback from you, our developer community. In particular, you told us that Forge’s frontend needs:

• More flexibility & components
• A clear migration path for existing apps
• A smoother learning curve for developers unfamiliar with React

We heard you, and we listened. To respond to your feedback meaningfully, however, we had to look further than the UI kit (f.k.a. Forge UI). We’ve been hard at work since June on a complementary frontend offering: Custom UI .

You can dive in and play around with it right now, or read on to learn more about how it works, and how it fits with our existing frontend offerings.

What Custom UI does

When you use Custom UI, you statically define HTML, CSS, JS, and image files that are hosted and displayed inside existing Forge modules on our secure infrastructure. You get complete control over what framework (or lack of framework) you use, provided you give us a static bundle with an index.html file.

We’re excited to announce that Custom UI is live in all currently eligible Forge Jira modules, starting today, and we’ll be rolling out to Confluence and Editor in the coming days and weeks.

We’ve designed Custom UI to avoid three key classes of security vulnerabilities that we see in Connect:

1. Like UI kit, we don’t send your app’s tokens or secrets to the frontend, so there’s less chance of token leakage leading to malicious control.
2. We ensure a high level of trust for scripts running in your app, in an effort to make cross-site scripting—one of the largest categories of bugs we’ve seen in our bug bounty program—much more difficult.
3. By default, apps can only egress data through the secure Forge FaaS platform. Custom UI apps can achieve this via our newly imagined Custom UI bridge.

(2) and (3) are implemented using a strict Content Security Policy, which means Custom UI apps will only display onbrowsers that Atlassian officially supports. This means that your apps will not be able to support cross-site scripts such as Google Analytics right now. We’re looking into how to best support these kinds of requirements, and to understand that we’d love to hear what functionality you need in the comments below or by direct message. For more details on how we keep Custom UI secure, check out our documentation.

How to choose between Custom UI, UI kit, and Connect

Custom UI is launching in GA preview at Developer Day on November 10 with full GA to follow very soon. This means that it’s ready for anyone—from in-house customizer to experienced Marketplace Partner—to start building on today, to get your apps ready in time for the Forge Marketplace launch in early 2021. You’ll also soon be able to start integrating Connect apps with Forge, meaning that you can start playing with Custom UI and hosted functions in your existing apps. Tune into Developer Day to learn more about adopting Forge with Connect apps.

If you’re starting a new app from scratch

You should start on Forge, which allows you to pick what UI extensibility option to use on a module-by-module basis across your app. If your module is relatively straightforward, start with UI kit, and work with Custom UI on more complex modules when you require extra functionality or customization. For more information on the differences between Custom UI and UI kit, check out our documentation.

If you have an existing static frontend on Connect (Cloud) or P2 (Server & Data Center)

To make your apps as secure as possible by taking advantage of the features listed above, we recommend you move your app’s frontend onto Forge. The Forge team has opened up many migration paths to make this as easy as possible—you can rebuild your app from scratch to be fully Forge-native, or adopt Forge with your Connect app module-by-module (currently in alpha; watch Developer Day for more).

You can migrate your static frontend directly onto Custom UI, or rebuild it in either Custom UI or UI kit, depending on your needs. If you choose to migrate your frontend, we recommend working on it incrementally, since parts of your app might have to change to work with the new security enhancements.

If your app needs to use a cross-site script (ex. Google Analytics)

We don’t currently support cross-site scripts in Custom UI, in order to start from a position of keeping our users secure. However, we do intend to have a solution for this, so try to build your app in Custom UI without cross-site scripts for now and tell us what scripts you still need to use. We’re keen to work with you to ship a great solution for these features.

If your app needs a dynamic frontend (ex. Server Side Rendering, PHP, ASP)

You should continue to build your app on Connect—but tell us about your needs! We’re really interested in learning about what kinds of apps require dynamic frontends, so if your app falls into this bucket, comment below or shoot us a direct message with your use case and we’ll look into how we can cover it on Forge.

Get started today

Tune into Developer Day on Nov 10 to learn more about all the stuff we’re announcing for Forge and the Ecosystem Platform, including Custom UI. Once you’re done, dive into Custom UI, and let us know what you think of it—the future of Custom UI will be shaped by our developers, for our developers, and your feedback will help us prioritize our roadmap to deliver you value sooner.

Forge on with your apps!

[danielwester]

This is awesome!

Any plans on supporting AP.* (or a compatibility version of it)? Looking at the integration pieces with rest of Jira (such as AP.Dialog).

[huw]

Atlassian Connect JS isn’t currently supported—but stay tuned, since we’re looking at ways we can reimagine its functionality to better fulfil the community’s requirements over the coming weeks and months (for example, APIs like Dialog may not be product-specific, so it’s the same API across all supported products).

Let us know if there’s anything else from AP you’re keen to get in your app

[pch]

Hi.
Can you create a jira or trello board where we could post our API requests to avoid duplicates?

Cheers
Przemyslaw

[naiara]

I’m also interested in learning about integration with AP or any equivalent. Besides calling methods like AP.Dialog, other common use for AP is retrieving context information from AP.context (i.e. in confluence the contentId and the spaceKey)

[huw]

Absolutely, you can find the Forge-wide feedback/request board at FRGE on ecosystem.atlassian.net. I read every request.

[jmort]

I’ve just run through the hello world Jira issue panel tutorial it worked great.

Immediate observations:

• After i used forge tunnel the whole thing broke, unless I was using forge tunnel (no helpful log messages, just a graphql error about a missing environment) [FRGE-163] - Ecosystem Jira
• Dev flow was a bit frustrating in the example because npm run build had to be run frequently, and then forge deploy which really slows down the experience
• AP.request style API calls would be nice so that it isn’t necessary to proxy application api calls through a function
• Other AP APIs might be useful, but i’ve not done anything particularly interesting with it yet. At the very least it would be good to trigger dialogs.

[danielwinterw]

Hey @naiara,

Context information is available in the custom UI resolvers. If you do need this information in the UI itself, you can return it from the function. See the following example:

In your FaaS function:

resolver.define("example-key", ({ payload, context }) => {
  console.log(context);

  return { example: `Hello, ${payload.foo}!` };
});

In your custom UI:

import { invoke } from '@forge/bridge';

const getData = async () => {
  const result = await invoke('example-key', { foo: 'bar' });

  console.log(result);
}

If you have a use case that this doesn’t cover, don’t hesitate to reach out

[danielwinterw]

Hey @jmort,

• Regarding forge tunnel breaking, can I confirm you are on CLI version @forge/cli@0.24.0 or greater? You can check this by running forge --version and upgrade via npm i -g @forge/cli@latest.
• We are aware of the current dev flow and will be improving it in future iterations of custom UI, any specific feedback on this is welcome!
• With the AP.request calls, do you think this would still be an important thing for you if the dev loop did not require a build and deploy (i.e. faster)?

Thank you for taking the time to provide feedback!

[jmort]

hi @danielwinterw,
I’m using 0.24.0, after some time (I tried it the next day) everything worked fine again. (I haven’t tried to reproduce).

For me, dev flow should be similar to using webpack dev server, I should save and then changes should be live as fast as possible.

With AP.request, yes it would improve dev speed if we don’t have to keep deploying proxy functions, but also it adds unnecessary complexity and overhead to have to push everything through a proxy function. Something akin to AP.request (doesn’t have to be REST could be GraphQL) means that all the logic can stay in the same place and would improve the user experience as there are no unnecessary resolver functions being called.

[danielwinterw]

@jmort again, thank you for that feedback! I’ll take it back to the team

[jmort]

What is the limit of bundle size? I just tried to embed a video which was blocked by the CSP, so if i want to use large assets they will have to be part of the bundle.

[AnnaHbner]

Unfortunately I cannot see the repository of the todo app, the new example with custom ui. Should that not be public or is it a mistake?

[danielwinterw]

Hi Anna, the link should work now. Thanks for letting us know

https://bitbucket.org/atlassian/todo-app-custom-ui

[danielwinterw]

Hey @jmort

See this page for the Forge platform limits. We have recently updated it with custom UI. https://developer.atlassian.com/platform/forge/platform-limits/

10MB is the max bundle size per resource currently, although if you have a use case that needs something higher then please let us know

[danielwester]

Since 10MB seems kinda like arbitrary - what’s the reasoning for it? (Because like @jmort - it’s quite easy to have large assets like videos because of other forge limitations). I’m also kinda concerned about the limitation of 1000 files (guess we can go back to css sprites).

Will we be able to point to our own cdn’s for our own assets once Forge leaves alpha?

[danielwinterw]

@daniel thanks for providing that feedback

You’re right, the limits imposed are currently arbitrary. To protect our platform, we need to impose upper bounds which is why this exists. We want to set the limits for GA based on the requirements from our developer community, so this kind of information is really valuable to us.

To help me understand a little more, do you think there is a reasonable limit that can be imposed, or do you think it varies significantly? We’d be happy to consider changing things based on feedback.

In terms of serving your own assets, we are currently considering this possibility. It may, however, mean that users need to consent to it as it can provide a means of data egress.

[danielwester]

Well it really depends on the app and what libraries it’s using. One of my react based apps is around 350 files - and it’s not that advanced on the client side (it’s got some bells and whistles - but not that huge).

My suggestion would be to start with a “target” with the huge blinking sign with “we will change this depending on what we see” and then start measuring what people are doing… 'cause you give me a limit - I’ll come up with a way to work around it…

That said - I would poll the vendor community with the more interesting apps on the client side and ask them about their apps. It would be good though for an explanation of what a bundle really is from you and how you see them being used…

(Oh - can you lower the App title to be 40 chars instead of 50? That way it matches the marketplace… https://developer.atlassian.com/platform/marketplace/building-your-presence-on-marketplace/ )

[jmort]

I don’t have any forge specific cases right now that would exceed the limits, but a number of our more complex apps would exceed both the 10mb and 1000 file limits. It is the kind of thing that would indicate that Forge isn’t ready for real apps, and we would hesitate to bet too much on it from a technical strategy perspective.

[danielwinterw]

Hi @jmort,

As mentioned, we are more than happy to look into increasing the limits. It definitely shouldn’t be an indication that Forge isn’t ready for real apps.

I’d love to hear what kind of bundle sizes you are working with in your more complex apps so that it can act as a data point for us.