Nexus mods

This package allows you to manage the download and update Minecraft mods and external files.

Included APIs :

• CurseForge
• Modrinth
• Github Release

Install :

To include Nexus Mods in your project, you can install it using npm:

npm i @arffornia/nexus_mods

Usage :

First, you need to instantiate an instance of NexusMods :

const nexusMods = new NexusMods(
    "Your Minecraft directory path ("./.minecraft")",
    callback?
    modDirName, // default: mods
);

• You can also specify an optional callback function using the Callback interface.

Load from Json file :

NexusMods lets you easily manage all your mods in a json file. Who can look like that :

{
    "mods": {
        "curseforge": [
            {
                "displayName": "Mekanism",
                "projectId": "268560",
                "fileId": "4776410"
            },
            {
                "displayName": "Ender IO",
                "projectId": "64578",
                "fileId": "5460093"
            }
        ],
        "modrinth": [
            {
                "displayName": "Applied Energistics 2",
                "versionId": "kF3whRqC"
            }
        ],
        "github": [
            {
                "displayName": "Arffornia Mod",
                "owner": "Arffornia",
                "repoName": "Arffornia_Mods",
                "groupId": "fr.thegostsniperfr.arffornia",
                "artifactId": "arffornia",
                "version": "1.0.0"
            }
        ]
    },
    "externalFilesIndexUrl": "https://raw.githubusercontent.com/Arffornia/Nexus_Mods/refs/heads/main/externalFiles/index.json"
}

then just call loadModsFromJson to load the mods in NexusMods :

await nexusMods.loadModsFromJson(jsonModList);

You can also load the json file using an url :

await nexusMods.loadModsFromJsonUrl(jsonUrlModList);

Loading External Files

Nexus Mods can also manage external files using an index system, similar to how it handles mod files.
This is useful, for example, when you want to update configuration files or other resources alongside your mods.

External files are listed inside an index.json, which contains metadata for each file (such as path, hash, etc.).

There are two ways to load an external file index:

• From your mod list file:
  Add the URL of the external index by using the externalFilesIndexUrl field.

• Programmatically:
  You can load the external files manually in your code using one of these methods:

await nexusMods.loadExternalFiles(jsonIndexFile);

(where jsonIndexFile is a parsed JSON object)

or

await nexusMods.loadExternalFilesFromJsonUrl(jsonIndexFileUrl);

(where jsonIndexFileUrl is a URL pointing to a remote index.json)

Generating an External File Index

Nexus Mods provides a small utility to easily generate your index.json file.

Use the following method:

await generateIndex(storageDir, outputFile);

• storageDir: Absolute path to the storage directory.
• outputFile: the path where the generated index.json will be saved.

This will scan all files under storageDir, calculate their metadata (such as paths and hashes), and output a ready-to-use index file.

See an example

Load from Curseforge API file :

You can load a mod directly into the code using the Curseforge api:

// Example to get Ender IO mod.
const curseforgeAPI = new CurseforgeAPI();
const projectId = '64578';
const fileId = '5460093';

const modFile = await curseforgeAPI.getModFile(projectId, fileId);
nexusMods.addModFile(modFile);

Load from Modrinth API file :

You can load a mod directly into the code using the Modrinth api:

// Example to get Arffornia mod.
const githubAPI = new GithubAPI();

const owner = 'Arffornia';
const repoName = 'Arffornia_Mods';
const groupId = 'fr.thegostsniperfr.arffornia';
const artifactId = 'arffornia';
const version = '1.0.0';

const modFile = await githubAPI.getModFile(owner, repoName, groupId, artifactId, version);
nexusMods.addModFile(modFile);

Load from Github Release Registry file :

You can update file from Github Registry:

// Example to get Arffornia mod.
 const githubAPI = new GithubReleasesAPI();

const owner = 'Arffornia';
const repoName = 'Arffornia_Mods';
const tag = 'v1.0.0';
const assetName = "arffornia-1.0.0.jar";

const modFile = await githubAPI.getModFile(owner, repoName, tag, assetName);
nexusMods.addModFile(modFile);

Download / Update mods :

Once you have loaded the mods into a NexusMods instance, you can download/update them simply with :

const checkHash = true; // Compare files by hash. On false, it's like a forced download.
const deleteUnregisteredMods = true; // Delete unregistered mods from the mod folder.

await nexusMods.updateMods(checkHash, deleteUnregisteredMods);

Advanced: Dynamic File Renaming with Environment Variables

Nexus Mods supports dynamic file renaming using environment variables. This is useful for cases where file names need to be configured externally, for instance, in a CI/CD environment or for different deployment targets.

This feature is controlled by the following environment variables:

• NM_REPLACE_ENV_VARIABLES: A boolean (true or false) that enables or disables the feature. Default: false.
• NM_REPLACE_ENV_VARIABLE_PREFIX: A string that defines the prefix for the environment variables to be replaced. Default: "NM_".

When enabled, any file path provided to a ModFile constructor will be scanned for placeholders in the format ${PREFIX_...}. If a matching environment variable is found, the placeholder is replaced with its value.

Note: This renaming process is applied at the core ModFile level, meaning it works seamlessly for all mods and files, whether they are loaded from a JSON mod list or fetched directly from APIs (CurseForge, Modrinth, GitHub Releases).

Example

Suppose you have a configuration file that you want to rename based on the environment.

1. Set your environment variables:

export NM_REPLACE_ENV_VARIABLES=true
export NM_CONFIG_FILE_NAME="production_settings"

2. Define the file path with a placeholder:

In your mod list JSON or when creating a ModFile programmatically, use a placeholder for the part of the filename you want to replace.

For an external file, your index.json might look like this:

{
  "path": "config/${NM_CONFIG_FILE_NAME}.properties",
  "hash": "...",
  "override": true
}

3. Result:

When Nexus Mods processes this file, it will resolve the path to config/production_settings.properties before downloading or updating it. If the NM_CONFIG_FILE_NAME environment variable was not set, the path would remain config/${NM_CONFIG_FILE_NAME}.properties.

Callbacks (Progress & Steps)

Nexus Mods supports an optional callback system to track download and update progress.

You can provide a Callback object when initializing NexusMods.
The callback allows you to monitor different steps and track download progress.

You can take a look of the step enum & Callback interface here.

Tests

Tests are managed by Jest

You can run the tests using :

npm test

License

This project is licensed under the MIT licence. You can consult the complete text of the licence in the file LICENSE.