@resolution/reforge

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 ¹:

  • 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 ¹:

  • 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).

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 2	?.?.?	no
Product API type inference	?.?.?	no
Write proper documentation	?.?.?	no

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). ↩ ↩²

2. Meanwhile, check forge-trpc ↩