Forge是Atlassian的下一代框架，用于构建与Confluence集成的应用程序, Jira, or Jira Service Management. Forge provides Web UI elements, api和部署环境使开发人员能够通过使用JavaScript在Atlassian的云基础设施中创建功能齐全的应用程序, HTML, CSS and other Web technologies. Forge应用程序可以通过Atlassian Marketplace作为软件分发，任何Atlassian Cloud客户都可以订阅.

Atlassian为您需要的各种构建块提供了大量文档[1], as a developer, 可以用来编写Forge应用程序吗. 然而，并不是所有的文档都是完美的，通常会有漏洞. 本博客旨在弥补一些差距，并帮助您达到“Hello World”级别.

Let's Go

首先，按照Forge的入门页面[2]中描述的步骤进行操作，然后再回到这个博客. 此外，mg官方游戏中心将使用Visual Studio Code作为开发环境.

现在，在Visual Studio Code的终端中，让mg官方游戏中心使用 forge create command to scaffold our app:

你面临着两个选择:

The name of the app. Let’s call it getting-started.
The app template category. You have multiple options; consult the Forge documentation for more information. In our case, we’ll choose Custom UI.
The app template. mg官方游戏中心将创建一个Jira项目页面[3]——也就是说, 一个Jira页面，它将显示与给定Jira项目相关的信息-所以mg官方游戏中心将选择 jira-project-page.

过了一会儿，将创建一个包含基本Forge应用程序代码的目录. Let’s take a look:

代码结构类似于Node应用程序. 然而，如果你仔细观察，你会注意到有 two sets of code:

The static 目录及其子目录包含UI代码. 当用户通过Web浏览器访问应用程序时，将收到包含这些文件的捆绑包.
The src 目录包含将在Atlassian云中运行并可以执行后端功能的代码. 查看Forge运行时[4]了解更多信息.

的一个子目录 static is named hello-world. 该字符串还在代码中的几个地方使用. We’ll change that later.

A Note about Forge Environments

Out of the box, Forge提供了三种云环境，你的应用可以在其中运行——开发, staging, and production. 每个环境的名称都是不言自明的, 但要了解更多关于每个的目的和用法, 你可以访问环境和版本[5]. mg官方游戏中心将使用开发环境来实现mg官方游戏中心的目的.

Building the App

让mg官方游戏中心继续尝试构建应用程序. 首先，mg官方游戏中心需要运行来构建前端部分 npm run build in the …/static/hello-world directory:

Why didn’t that work? 那是因为mg官方游戏中心没有安装所需的 npm 包，其中包括React. Forge应用ui是基于React的，模板是使用Create React app构建的. [6]

让mg官方游戏中心安装这些软件包，然后再试一次. 您可能从代码结构中注意到，前端代码和后端代码都需要独立的 npm packages, so we’ll need to run npm install for both:

That’s better.

Deployment

现在，让mg官方游戏中心尝试将应用按原样部署到mg官方游戏中心的开发环境中:

The forge deploy 命令将实际部署到您指定的任何Atlassian Cloud环境. 它要经过几个步骤，其中一个是运行 forge lint 命令，验证代码是否可部署到Atlassian Forge的检查器. 如果愿意，可以直接运行该命令.

Why is it failing? 原来是Forge应用模板生成的代码有一个bug. mg官方游戏中心可以通过移动 …/static/hello-world/public directory to …/static/hello-world/build, then running npm run build again for the front-end code:

Why did it fail this time? We just uncovered another bug. Namely, the react-scripts build that npm run build 在引擎盖下运行期望一个 index.html 由Create React App提供，但不包含在模板生成的代码中. Download the file from http://github.com/facebook/create-react-app/blob/main/packages/cra-template/template/public/index.html, then create a …/static/hello-world/public 目录，并把它放在这里:

现在，让mg官方游戏中心再次尝试构建和部署:

Excellent!

To run the deployed code, 让mg官方游戏中心访问一下Atlassian Cloud开发者站点，该站点是您在前面的let 's Go小节中创建的Forge入门过程的一部分. 在该站点的Jira部分- e.g., http://your-site.atlassian.net/jira/ 创建一个Jira项目，如果你还没有，然后访问项目的页面- e.g., http://your-site.atlassian.net/jira/software/c/projects/KEY -看看左边的边栏. 你应该会在这里看到你的应用:

Hmm… it isn’t. Why not? 当一个Forge应用被部署到一个给定的环境时, 它可以安装在Atlassian Cloud站点上. 但是，要为给定的站点进行实际安装，还需要进一步的步骤 forge install command.

当您运行该命令时，它将询问安装应用程序的Atlassian站点. Of course, 您将进入您按照Atlassian的入门页面上的步骤创建的网站:

让mg官方游戏中心刷新之前打开的Jira页面:

Now you see the app’s name, a default icon, 并表明该应用程序是开发环境版本. 您可以安装开发、暂存 and 同一Atlassian实例上给定应用程序的生产版本.

Click on the app’s name. 它会要求您授予您的Forge应用程序的某些权限，称为范围. 您可以在OAuth 2的作用域中阅读更多关于作用域的信息.0 (3LO) and Forge Apps [7]. 当您执行某些操作(如调用Atlassian api)时，这将变得特别重要. You’ll see the following:

When you click Allow Access, another page will open, 列出请求的权限并要求您接受它们. 一旦你这样做，你的应用程序将运行:

You briefly see a Loading… message, then Hello, world! appears. Success! 你有一个在Atlassian云上运行的Forge应用!

Let’s Make a Back-End Change

Let’s change the message from Hello, world! to Hi, world! and then deploy the change. 消息是由后端的代码生成的 index.js:

在浏览器中重新加载应用程序，然后……

Success! Our new message displays.

Let’s Make a Front-End Change

你会发现你为Forge应用编写的大部分代码都在前端, no matter how simple the app. 首先，让mg官方游戏中心做一个小小的改变，运行 forge deploy and see what happens:

现在，重新加载Forge应用程序，然后…

Why didn’t the change show up? 这是因为前端更改需要在部署前进行构建. Let’s run npm run build in the front-end directory, and then deploy:

Refresh the app, and…

Success! 显示的是Loading it…，而不是Loading…

Running Locally via forge tunnel

当然，您可以在每次进行代码更改时通过构建和部署来运行代码. 然而，它导致了大量的部署等待，从而导致了缓慢的开发和测试周期. Instead, you can tunnel，它使您能够在连接到Forge开发环境时在本地运行代码. 你可以通过跑步来挖掘隧道 forge tunnel in your app’s root directory:

现在，在浏览器中重新加载你的应用，看看会发生什么:

mg官方游戏中心看到一些消息在Visual Studio Code终端中滚动过去. 这意味着隧道正在运行本地版本的应用程序代码, 而不是Atlassian云的版本. 让mg官方游戏中心看看在修改本地后端代码时会发生什么, 然后在浏览器中重新加载应用程序:

Not bad! 它重新加载了后端更改.

但是，这并不能帮助mg官方游戏中心进行前端更改. 那样的话，mg官方游戏中心得让隧道停止，对吧 npm run build 在前端代码上，然后再次启动隧道. That’s not very efficient.

But wait, you can use Vite [8]! Vite是一个Web开发框架，它支持有效的即时本地编译, 热模块替换和其他缩短开发周期的功能几乎为零. To use Vite in your app, 参考Robin Wieruch的《mg官方游戏中心》教程[9], 以及Oliver Siebenmarck与Forge Tunnel和Vite video的开发[10].

Making Atlassian API Calls from the Front End

使用Forge自定义UI桥[11], mg官方游戏中心有能力Making Atlassian API Calls from the Front End. 让mg官方游戏中心通过修改mg官方游戏中心的应用程序来显示一个版本列表来尝试一下. 首先，添加一些版本(也称为 versions 在Jira的说法)到你的Jira项目:

然后，更改前端代码的App.js to look like so:

因为Atlassian库调用是异步的, and to keep the example simple, 我在一个 useEffect() hook. 我强烈推荐使用TanStack Query[12](以前称为React Query), 不仅仅是因为它支持异步函数, 还因为它以模块化的方式构建数据访问和突变代码的一般能力.

Now, do npm run build and forge deploy, as we’ve done before. 当mg官方游戏中心在浏览器中重新加载应用程序时会发生什么呢?

The word Releases appears, then disappears. What happened? 因为mg官方游戏中心的最新更改涉及到添加一个API调用, 让mg官方游戏中心打开浏览器的开发人员控制台, then refresh the app. 注意这里的一条消息: