Skip to main content

Working with Mod

Mods are distributed as NuGet and NPM packages that can be installed into a host application. However, when a mod is under active development, publishing a new package version and installing it back into the host application for every change is inconvenient. This slows down both development and debugging.

To solve this, we use @webinex/cli. It allows a host application to consume a mod directly from the local source tree without publishing it as a package first.

The workflow is:

  1. unbox the mod;
  2. run the host application against the local mod source code;
  3. make and verify changes;
  4. box the mod back into package references when the work is finished.

0. Install @webinex/cli globally​

npm install -g @webinex/cli

The current known version is 0.0.20, but it is recommended to check npmjs.com for a newer version.

Run the commands from the repository root unless a specific working directory is required.

1. Unbox Mod​

Before working on a mod locally, it must be "unboxed". During unboxing, @webinex/cli does two things:

  1. It adds all mod .NET projects to the solution and replaces <PackageReference /> entries with <ProjectReference /> entries in projects that depend on the mod. This allows the host API to use the local mod source code directly.
  2. It adds an external configuration to the host application's package.json. This configuration points to the local folder of the mod NPM package. Vite then reads the mod frontend code directly from that folder, following package.json exports.

Run:

wex mod unbox --app main --mod <mod-name>

For example:

wex mod unbox --app main --mod billing

After that, restart the host API and Vite. Both will use the local mod version instead of the published package version.

To work on the mod frontend, open the mod in the IDE and run pnpm watch in the mod frontend package folder. This starts the mod frontend build in watch mode. Changes are rebuilt automatically and become visible in the host application because Vite reads the mod code directly from the local mod folder.

For backend changes, rebuild or restart the host API as needed. Since the host solution references the mod projects directly after unboxing, the API uses the local .NET source code instead of the NuGet package.

2. Box Mod​

After finishing local development, the mod can be "boxed" back:

wex mod box --app main --mod <mod-name>

This command first publishes the NuGet and NPM packages to local storage. Then it removes the mod .NET projects from the solution, replaces <ProjectReference /> entries back with <PackageReference /> entries pointing to the latest published version, and removes the external configuration from the host application's package.json. After that, Vite reads the mod frontend code from the installed NPM package again.

tip

After running box, it may be necessary to delete the node_modules/.vite folder manually so Vite stops using cached code from the local mod folder.

It may also be necessary to run dotnet restore --force in the host API folder to restore the latest published NuGet package version of the mod.

After that, restart the host API and Vite. They will use the published mod version again.

Troubleshooting​

If the host frontend still appears to use the local mod source after boxing, clear Vite cache:

pnpm vite:cache:clear

If the host API still appears to use old assemblies or package versions, force NuGet restore in the host API workspace:

dotnet restore --force

If the frontend mod changes are not reflected while unboxed, make sure pnpm watch is running in the mod frontend package and that the host application's package.json still contains the external entry created by wex mod unbox.