Reforge ⚒️🔥

A project of:

Atlassian apps that get it done

What is Reforge?

Reforge is an opinionated bundler for forge projects that uses esbuild to easily generate your distribution files from a developer-friendly project structure.

How to use Reforge?

1. In your project add the reforge dependency: npm i @resolution/reforge, yarn add @resolution/reforge, pnpm add @resolution/reforge, etc.

2. Copy the following folder structure (in the future you'll be able to do forge create):

   .
   ├── src/                          -- Source files
   │   ├── modules/                  -- Module entries
   │   │   ├── jira$globalPage/      -- A jira:globalPage module
   │   │   │   └── application.tsx   -- A jira:globalPage entry
   │   │   └── function/             -- A function module
   │   │       └── backend.ts        -- A function entry
   │   └── app.ts                    -- Configuration file (optional)
   ├── assets/                       -- Asset files (optional)
   │   └── image.jpg                 -- An asset file to copy into the resource directory of resources that reference it (optional)
   ├── .env                          -- Declare your app id here (required)
   └── package.json

• Application file (app.ts) may export [^1]:

  • default: The base manifest. This is the place to define non-module options like permissions, or additional modules that can just be copied without being processed. Any resources you pass will be copied and rewritten into the dist directory.
  • reforgeConfig: Optional config for Reforge, see more here.

• Resource entrypoints (e.g jira$globalPage.tsx) may export:

  • default (required): A React component that will be passed to react-dom to be rendered when the entrypoint is accessed.
  • reforgeResourceAssets: A string[] containing the filenames of assets from the assets directory to copy into this resource's directory. These are typically images, JSON files, etc.

• Any module entrypoints (e.g backend.ts) may export [^1]:

  • reforgeModuleManifest: The section of the manifest to generate for this file. For resources, this will typically contain things like a title, icon etc.
  • May instead export as a function (optionally async) that takes a Record<string, string> with the environment based on the environment variables from the .env files, as well as NODE_ENV (build mode, either production or development).

[^1]: Non-resource entrypoints may instead be exported as a function (optionally async) that takes a Record<string, string> with the environment based on the environment variables from the .env files, as well as NODE_ENV (build mode, either production or development).

3. Call reforge build with: npx reforge build, yarn reforge build, pnpm reforge build, etc.

   • Optional: Add the previous command to your scripts section in the package.json.

4. A dist/ folder that is ready to be deployed will be generated.

   • Optional: cd into distand run forge deploy and forge install.
   • Optional: add the previous command to your scriptssection in the package.json.

Why should you use Reforge?

| Features | Reforge | Forge | | ------------------- |------------| ------ | | bundles code | yes | no | | language | typescript | any | | framework | react | any | | manifest | automatic | manual |

Roadmap

| Description | Version | Released | | ------------------------------------------ |---------|----------| | Initial release, reforge bundler | 1.0.0 | yes | | Improved dev mode, asset directory support | 1.1.0 | yes | | Rewrite to ESBuild, better configurability | 2.0.0 | yes | | DOMException polyfill | 2.0.1 | yes | | Downgrade peer react version | 2.1.0 | yes | | Add support for custom renderers | 2.2.0 | yes | | Create command for projects and modules | ?.?.? | no | | Proper ESM distribution files | ?.?.? | yes | | Backend-frontend type inference [^4] | ?.?.? | no | | Product API type inference | ?.?.? | no | | Write proper documentation | ?.?.? | no |

[^4]: Meanwhile, check forge-trpc