{"id":15016380,"url":"https://github.com/finesoftware/forge-dev-kit","last_synced_at":"2025-08-20T16:31:20.690Z","repository":{"id":37035687,"uuid":"478352454","full_name":"finesoftware/forge-dev-kit","owner":"finesoftware","description":"A zero-config toolkit for creating fine Forge apps","archived":false,"fork":false,"pushed_at":"2024-10-30T01:02:17.000Z","size":813,"stargazers_count":25,"open_issues_count":35,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-30T03:51:10.648Z","etag":null,"topics":["atlassian","confluence","forge","jira","react"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/finesoftware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-04-06T00:59:06.000Z","updated_at":"2024-08-30T21:05:11.000Z","dependencies_parsed_at":"2024-03-25T10:56:14.700Z","dependency_job_id":"b9d8a160-36dd-4a49-9796-09abccd66cc1","html_url":"https://github.com/finesoftware/forge-dev-kit","commit_stats":{"total_commits":50,"total_committers":3,"mean_commits":"16.666666666666668","dds":0.26,"last_synced_commit":"5e445267f0300d1a227475ccc8d1b692ab602c8f"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/finesoftware%2Fforge-dev-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/finesoftware%2Fforge-dev-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/finesoftware%2Fforge-dev-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/finesoftware%2Fforge-dev-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/finesoftware","download_url":"https://codeload.github.com/finesoftware/forge-dev-kit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230438185,"owners_count":18225870,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["atlassian","confluence","forge","jira","react"],"created_at":"2024-09-24T19:48:46.200Z","updated_at":"2024-12-19T13:07:14.150Z","avatar_url":"https://github.com/finesoftware.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![image](documentation/assets/jxl-banner-small.png)](https://jxl.app)\n\n\u003cbr\u003e\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"documentation/assets/fdk-logo.svg\" width=400 /\u003e\n\u003c/p\u003e\n\n\u003cbr\u003e\n\nA zero-config toolkit for creating fine Forge apps.\n\n# Background\n\nThe Forge Dev Kit (FDK) is a preconfigured set of libraries and frameworks for developing apps for Atlassian Jira - and soon, Confluence - with ease. The FDK builds on Atlassian Forge, TypeScript, React, Emotion, Next.js, and the Atlassian Design System, plus a number of libraries to glue it all together.\n\nFDK doesn't replace the standard Forge tooling; it instead simplifies the creation of [Custom UI](https://developer.atlassian.com/platform/forge/custom-ui/)-based modules, which can then be used within any (new or existing) Forge app.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"documentation/assets/fdk-diagram.png\" width=800 /\u003e\n\u003c/p\u003e\n\n\n# Getting started\n\n## Requirements\n\nBefore getting started, make sure that [Forge is set up for development](https://developer.atlassian.com/platform/forge/getting-started/).\n\n## Creating your FDK module\n\nCreate a new FDK module by running\n\n``` console\nnpx @finesoftware/forge-dev-kit create\n```\n\nIn the wizard that follows, chose the `Hello world` template, and read through any instructions carefully.\n\n## Updating your Forge app\n\nIf you don't have a Forge app yet, [create one using the Forge CLI](https://developer.atlassian.com/platform/forge/build-a-hello-world-app-in-jira/#create-your-app).\n\nIn your Forge app's `manifest.yml`, find or create a new `module`, of a type that supports Forge's Custom UI (such as `jira:projectPage`). In the module's `resources`, point to the FDK module's `out` directory, like so:\n\n``` diff\nmodules:\n+  jira:projectPage:\n+    - key: hello-world\n+      title: Hello world\n+      resource: hello-world-resource\n\nresources:\n+  - key: hello-world-resource\n+    path: ../hello-world/out\n```\n\nAlso make sure that your `manifest.yml` includes the following `permissions`:\n\n``` diff\npermissions:\n+   content:\n+       styles:\n+         - 'unsafe-inline'\n+       scripts:\n+         - 'unsafe-eval'\n```\n\n## Starting your Forge app\n\nIn your Forge app's base directory, run\n\n``` console\nforge deploy\nforge install --upgrade\n```\n\nVoilà! You should now see your FDK-based _Hello world_ app in action - in this case, using a module of type `jira:projectPage`:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"documentation/assets/fdk-hero.png\" width=600 /\u003e\n\u003c/p\u003e\n\n## Making your first change\n\nTo make a change to the _Hello world_ module, open the module directory in an IDE of your choice (Visual Studio Code will work great), and navigate to the `src/index.tsx` file. This file is the entry point to your module. In `src/index.tsx`, you will see the React code behind _Hello world_. Make a small change to it - for example, change the `h3` text, like so ...\n\n``` diff\n- \u003ch3\u003eFine Software Forge Dev Kit\u003c/h3\u003e\n+ \u003ch3\u003eG'day!\u003c/h3\u003e\n```\n\n... or write any other valid React code. Just keep exporting a React component as the file's `default export` - that's expected and required by FDK.\n\nNext, in the root directory of your module, run\n\n``` console\nyarn run generate\n```\n\nThis will compile your code, and generate the static resources into the `out` directory.\n\nNext, navigate to your Forge app's root folder, and run\n\n``` console\nforge deploy\n```\n\nWhen you reload Jira in your browser, you should now see your changes live.\n\n## Setting up your inner dev loop\n\nYou already deployed a change to your Forge app - well done! However, as you start making more comprehensive changes, you don't want to go through the hassle of `generate` + `deploy` all the time. Luckily, FDK plays well with Forge's [tunneling](https://developer.atlassian.com/platform/forge/tunneling/) capabilities.\n\nFirst, in your module's root directory, run\n\n``` console\nyarn run dev\n```\n\nto start your module's `next.js` development server. By default, it is running on port `3000`.\n\nNext, navigate in your Forge app's `manifest.yml`, and modify your module resource definition, like so:\n\n\n``` diff\nresources:\n  - key: hello-world-resource\n    path: ../hello-world/out\n+   tunnel:\n+     port: 3000\n```\n\n... where `3000` is the port that your dev server is running on.\n\nNext, start your app in tunneling mode, using\n\n``` console\nforge tunnel\n```\n\nYou can now go on to make further changes to your module, and simply reload Jira to view them live.\n\n# Guides\n\n- [Understanding your FDK module](./documentation/guides/01-understanding-your-fdk-module.md)\n- [Recommended project structure](./documentation/guides/02-recommended-project-structure.md)\n- [Accessing your module's _context_](./documentation/guides/03-accessing-your-modules-context.md)\n- [Fetching data from Jira](./documentation/guides/04-fetching-data-from-jira.md)\n- [Updating data in Jira](./documentation/guides/05-updating-data-in-jira.md)\n- [Navigating in Jira](./documentation/guides/06-navigating-in-jira.md)\n\n\u003cbr\u003e\u003cbr\u003e\n\n[![image](documentation/assets/jxl-banner-large.png)](https://jxl.app)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffinesoftware%2Fforge-dev-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffinesoftware%2Fforge-dev-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffinesoftware%2Fforge-dev-kit/lists"}