Troubleshoot and debug your Forge app
5 min
By the end of this lesson, you’ll be able to:
- Describe the benefits of Forge tunnel for local development and debugging
- Compare Forge tunnel to the standard deploy cycle for faster iteration
- Use logs to identify and resolve common errors
- Use Forge lint to identify and fix errors in your Forge app configuration
Accelerate iteration
Building a Forge app is an iterative process. You build, test, adjust, deploy, and repeat, often many times. Whether you're changing a layout, updating backend logic, or fixing bugs, you need immediate feedback to move forward.
Forge supports iteration by providing powerful tools to help you test changes in real-time, catch issues early, and accelerate your development workflow.
👇Click each box to take a quick look at what each one does.
Iterate faster with Forge tunnel
When you're developing Forge apps, speed matters. Every time you make a change to your app, you usually have to run forge deploy before you can test it, slowing down your development loop.
Instead of repeatedly deploying your app every time you make a change, you can use Forge tunnel to see your updates in real-time without requiring a full redeploy.
The tunnel acts as a live connection between your local development environment and your app running in the Atlassian cloud. It streams output, so you can see exactly what your app is doing as it runs.
The benefits of using Forge tunnel include:
- Faster iteration: See updates in real-time as you change your code, without redeploying.
- Immediate feedback: View app behavior and outputs as users interact with it.
- Live connection: Monitor what’s happening behind the scenes, using logs.
How to use Forge tunnel
To start the tunnel, run this command in your terminal:
forge tunnel
After the tunnel starts, open your plug-in app in the Atlassian app (like Jira or Confluence), and interact with it as you usually would. Your changes will appear immediately. If you modify your code while the tunnel is active, Forge will automatically reload it and reflect the updates.
As you make changes, you’ll see real-time output in your terminal, including error messages, function calls, and logs. We’ll cover how to use these logs to troubleshoot later.
👇Watch this animation to see how the forge tunnel lets you test your code in real-time.
Debug your Forge apps
Use logs to understand what’s happening in your app
When you're building Forge apps, understanding what's happening behind the scenes is key, especially when something doesn't work as expected. Logging allows you to track your app’s behavior, displaying the flow of execution, and catching errors during development and after deployment.
In Forge, you can use the logs to confirm:
- Whether a function was triggered
- What values were received or returned
- If and where an error occurred
How Forge log and console.log() work together
Logging is a key part of understanding what your app is doing and diagnosing problems during development and after deployment. In Forge apps, you use console.log() statements in your code to output messages at runtime. Where those messages appear depends on how and where the app is running:
- During local development with Forge tunnel: If you're running your app locally using forge tunnel, console.log() messages appear live in your terminal. This helps you test and iterate quickly without needing to redeploy your app.
- After deploying your app (for backend code): When your app is deployed and running in the Atlassian cloud, logs from backend code (such as resolvers) are captured and can be viewed using the forge log command in your console. This is helpful when debugging apps running in staging or production environments.
- For apps with a frontend: Logs and errors from the frontend are not captured by Forge and won't appear in the cloud logs. Instead, they appear in the browser’s developer console. To view them, open your browser’s developer console while running the app.
👇Troubleshoot Forge apps using logs.
In short, to use logs in Forge:
- Use console.log() statements in your app code.
- Use forge tunnel or forge log to retrieve those logs, depending on where the app is running.
- Use the browser’s developer console to view frontend logs.
Because Forge apps may handle sensitive information, it’s important to follow Atlassian’s logging guidelines. Avoid logging personal data, authentication tokens, or any information that could pose a security or privacy risk.
Catch errors early with Forge lint
Before you run your app, it’s important to catch common errors in your manifest and code. Forge lint is a command that checks your app's structure and configuration to make sure everything is set up correctly. It reviews your app’s manifest file and code and flags problems that could break your app at runtime.
This saves time by catching problems like:
- Syntax errors
- Incorrect function names or types
- Misconfigured permissions or modules
Running Forge lint
Forge automatically runs the forge lint command as part of the forge deploy process. If errors are found, the deployment will stop, and you’ll be prompted to fix the problems first. If only warnings are detected, the deploy will continue, but you’ll still see messages so you can address them.
Even though linting runs automatically during deployment, it's a good idea to lint manually during development to catch problems early, especially before committing code or sharing your app with teammates.
You can run this command at any time in your app’s root directory: Forge lint.
👇Here's an error thrown by forge lint.
