Every developer, no matter your experience level, is familiar with the practice of finding and fixing problems in code, also known as debugging. It's a core developer skill, and there is no way to build software or apps without it. We've all had that moment where you've spent hours hunting for the source of an error, only to spot one measly typo!
No matter how much experience you have with debugging, techniques can vary depending on the software or development platform. Thankfully, there are a few handy tricks you can use to speed up the process or give you better insight into what's wrong. The more you know about what's causing an issue, the faster you can jump in and fix it.
Just as Chrome DevTools offers a ton of debugging options beyond the ever-popular console.log(), Forge also provides specific tools to help you spot problems in your code. Familiarity with these tools will help you build your apps quicker and more efficiently than ever before.
We spoke to Dmitrii Sorin, an Atlassian engineer who works on the team building Forge, to round up 5 useful Forge debugging practices, skills, and tools.
One: Run your app locally using tunneling
When it comes to debugging on Forge, tunneling is the primary tool you'll use to debug your app in development. The tunnel watches for code changes and rebuilds your app, so you don't have to re-deploy after every change. Some developers debug their apps by changing the code and running forge deploy; however, this isn't ideal, as it's much slower than using forge tunnel, and there's a daily deploy limit per Forge environment.
Tunneling runs your app code locally on your machine via the Forge CLI. You can start a tunnel for any app that has been deployed and installed to a site. Tunneling gives you real time logging for your app; you can use console.log() statements to see the output in your terminal as the code executes. Be aware that it's limited to the default development environment, and you can only tunnel one app at a time.
The forge tunnel command accepts a –debug flag that allows you to perform remote, interactive debugging. When you add debugger; breakpoints into your code, and run forge tunnel –debug, you’ll be prompted with a message like the following:
Once you open the provided inspector URL, you'll see that Chrome DevTools pauses execution on the debugger; breakpoints you added in your code (if you're not tunneling in debug mode, the debugger; statements are ignored). This means you can effectively stop time when the Forge tunnel hits the breakpoint – allowing you to poke around and debug in the context you need!
Two: Check logs in the Developer Console to see errors more clearly
Logging messages to the console is a common practice for debugging code. While Forge does support logging via the forge logs CLI command, the best way to view your logs is in the Developer Console. It has an easy-to-use interface which lets you choose and view different time periods, and even download your logs as an archive (there's nothing worse than losing a useful log or error message in the terminal!).
Three: Utilize triggers to test specific functions
If you want to debug a specific function, add a trigger. There are three types of triggers: web, product, and scheduled. We recommend using web triggers for debugging.
Web triggers are URLs that point to a function. You'll create a temporary URL for your function, and when you send a request to this URL, it invokes the function, meaning you can test it on demand. While many applications will also require some context from the UI to simulate real-world conditions, that’s the basic idea.
Product triggers are functions that can be invoked when a certain product event occurs. For instance, you can define a function that will be invoked when a Jira issue is created.
Scheduled triggers are functions that can be invoked on a scheduled interval. These aren't generally used for debugging purposes.
Four: Monitor production using Developer Console's app alert email
Errors in the production environment are particularly crucial because they impact your users. An easy way to act fast when production errors arise is to keep an eye out for emails sent by the Developer Console. Whenever your app invocation success rate drops below 99%, you'll get an email that looks like this:
When the success rate gets back to 99%, you'll get another email. This one will include a link to the Developer Console. Clicking this link takes you straight to the Metrics page, where you can see a breakdown of your recent drop in success rate. From there, you can also switch to the Logs page and see a readout of which errors occurred in your app during this time period.
Five: Access production logs
Once your app is in production, there are still ways to manage debugging. App log sharing is now enabled automatically during installation. Now, any time a user installs your app on their site, you'll automatically get access to the app logs for that site. Logs can help you drill down into error messages and identify what's going wrong with your app. And when you know the root cause, you can solve it.
Debugging on Forge vs Connect
If you're already experienced with using Connect, some of these concepts will be familiar, like using a tunnel to debug. When you develop a Connect app, you need to run a tunnel with ngrok or a similar tool to see requests being received by your local machine. When you develop a Forge app, the concept is the same. You run forge tunnel, and Forge starts a tunnel automatically, and the same thing happens: the app on your local machine will start receiving requests.
It's also worth noting that Forge provides two ways to build your frontend: UI Kit and Custom UI. Custom UI is fundamentally similar to Connect; it's a classic frontend app that talks to the backend (in the case of Forge, the backend is Forge runtime). Thus, all standard frontend debugging techniques will apply for Custom UI apps.
Now go fix some bugs!
When it comes to building and debugging Forge apps, the Forge docs are a great place to start. Reading documentation is always a worthwhile investment: just a few minutes of reading the docs might save you hours of frustrating debugging in the future.
Additionally, you can always harness the power of the Atlassian Developer Community to crowdsource answers or experiences (or share your own breakthroughs!) If you've found a new and helpful debugging insight, share it with the community or find out how you can supercharge your process. We're all ears!
If you're ready to try out these debugging tips, build something exciting on Forge now.