modpack-lock

by nickesc - GitHub | Modrinth

Creates a modpack lockfile for files hosted on Modrinth (mods, resource packs, shaders and datapacks).

Overview

Many mod and pack authors request that modpack creators link to Modrinth or CurseForge downloads rather than re-hosting files. This makes it difficult to track content files in version control when pushing to a remote server.

This script generates a modpack.lock file containing a plaintext representation of the modpack's contents. This object contains the metadata for the content available on Modrinth, including hashes, versions, names, download URLs and more. An optional modpack.json file can also be created to store your modpack's metadata (name, version, modloader, dependencies, etc.) alongside the lockfile. This setup allows for easy diffing and clear version history.

While an .mrpack file could be used to track changes to the modpack, it is a large, binary file that cannot be diffed and can contain large amounts of duplicate data from the rest of the repository.

Using the scripts field in modpack.json, you can also define reusable, tracked shell commands for common modpack tasks (like publishing, generating assets or CI/CD workflows).

Installation

To install the script globally with npm:

npm install -g modpack-lock

Alternatively, you can run it using npx:

npx modpack-lock

CLI

To generate a lockfile for your modpack, run:

modpack-lock

The script will:

• Scan target directory's mods, resourcepacks, datapacks, and shaderpacks directories for .jar and .zip files
• Calculate SHA1 hashes for each file
• Query the Modrinth API for matching versions
• Generate a modpack.lock file (and update modpack.json dependencies if present)

Use flags to generate README.md files for each category or update the .gitignore to ignore content hosted on Modrinth.

Usage: modpack-lock [options] [command]

Creates a modpack lockfile for files hosted on Modrinth (mods, resource packs, shaders and datapacks)

Options:
  -p, --path <path>       Path to the modpack directory
  -d, --dry-run           Dry-run mode - no files will be written

GENERATION
  -l, --licenseFile       Add the LICENSE file to the modpack
  -g, --gitignore         Update the .gitignore file to ignore content hosted on Modrinth
  -r, --readme            Generate README.md files for each category

LOGGING
  -q, --quiet             Quiet mode - only show errors and warnings
  -s, --silent            Silent mode - no output

INFORMATION
  -V                      output the version number
  -h, --help              display help for modpack-lock

Commands:
  init [options]          Initialize a modpack with a modpack.json file and a modpack.lock lockfile.
  run [options] <script>  Run a script defined in the modpack.json file's 'scripts' field

[!TIP]

Did you know?

You can generate summary files for each category by running modpack-lock -r. This will generate a README.md file in each of the content folders, detailing the scanned files and important attribution information for them.

Initialization

To initialize a new modpack, run:

modpack-lock init

This command will:

• Prompt the user for the modpack's metadata (name, version, author, etc.)
• Generate the lockfile
• Generate a modpack.json file that stores your modpack's metadata (name, version, author, etc.), including a list of dependencies

The interactive mode will prompt you for each field. Set their initial values using the available option flags. Use --noninteractive with the required options to skip the interactive-prompt and use the provided values.

Usage: modpack-lock init [options]

Initialize a modpack with a modpack.json file and a modpack.lock lockfile.

Options:
  -f, --folder <path>                                Path to the modpack directory
  -n, --noninteractive                               Non-interactive mode - must provide options for required fields
  --add-license                                      Add the LICENSE file to the modpack
  --add-gitignore                                    Update the .gitignore file to ignore content hosted on Modrinth
  --add-readme                                       Generate README.md files for each category

MODPACK INFORMATION
  --name <name>                                      The name of the modpack; defaults to the directory name
  --version <version>                                The modpack version; defaults to 1.0.0
  --id <id>                                          The modpack's slug/ID; defaults to the directory name slugified
  --description <description>                        A description of the modpack
  --author <author>                                  The author of the modpack; required
  --projectUrl <projectUrl>                          The project's homepage URL; defaults to a guessed Modrinth project URL
  --sourceUrl <sourceUrl>                            The project's source code URL; defaults to a guessed GitHub repository URL
  --license <license>                                The modpack's license; popular licenses are fetched from GitHub; defaults to mit in interactive mode
  --modloader <modloader>                            The modpack's modloader; a list of loaders is fetched from Modrinth; required
  --targetModloaderVersion <targetModloaderVersion>  The target modloader version
  --targetMinecraftVersion <targetMinecraftVersion>  The target Minecraft version; a list of versions is fetched from Modrinth; required

INFORMATION
  -h, --help                                         display help for modpack-lock init

Running Scripts

To run a script defined in modpack.json, run:

modpack-lock run <script>

This command takes the name of the script as its first argument:

• It searches for a scripts fiels in modpack.json in the current directory by default.
• Use the -f option to specify a different path to the modpack directory.
• For debug logging, use the -D option.

To pass additional arguments and options to the script, write them after a -- separator:

modpack-lock run <script> -- [options] <args>

The scripts field in modpack.json is a key-value pair of script names and their corresponding shell commands. The scripts field is optional and is omitted by default.

Usage: modpack-lock run [options] <script>

Run a script defined in the modpack.json file's 'scripts' field

Arguments:
  script               The name of the script to run

Options:
  -f, --folder <path>  Path to the modpack directory
  -D, --debug          Debug mode -- show more information about how the command is being parsed

INFORMATION
  -h, --help           display help for modpack-lock run

API

For programmatic usage, modpack-lock exports these functions:

• getModpackInfo()
• getLockfile()
• generateJson()
• normalizeDependencies()
• generateGitignoreRules()
• generateReadmeFiles()
• generateLicense()
• generateLockfile()
• generateModpackFiles()
• promptUserForInfo()

See the API documentation for full details.

File Formats

modpack.lock

The lockfile contains metadata about Modrinth-hosted files found in modpack directories:

{
  "version": "1.0.1",
  "generated": "2026-01-06T03:00:00.000Z",
  "total": 7,
  "counts": {
    "mods": 1,
    "resourcepacks": 3,
    "datapacks": 1,
    "shaderpacks": 2
  },
  "dependencies": {
    "mods": [
      {
        "path": "mods/example-mod.jar",
        "version": { ... }
      }
    ],
    "resourcepacks": [ ... ],
    "datapacks": [ ... ],
    "shaderpacks": [ ... ]
  }
}

modpack.json

The JSON file contains your modpack metadata and a dependency list:

{
  "name": "My Modpack",
  "version": "1.0.0",
  "id": "my-modpack",
  "description": "",
  "author": "name",
  "projectUrl": "",
  "sourceUrl": "",
  "license": "",
  "modloader": "modloader",
  "targetModloaderVersion": "",
  "targetMinecraftVersion": "x.y.z",
  "scripts": {
    "example": "echo 'example script'"
  },
  "dependencies": {
    "mods": {
      "fabric-api": "0.141.2+1.21.11",
      "example-mod": "1.2.3",
      "mods/local-mod.jar": "*"
    },
    "resourcepacks": { ... },
    "datapacks": { ... },
    "shaderpacks": { ... }
  }
}

[!IMPORTANT]

Don't commit binaries

Use modpack-lock -g to automatically update your .gitignore file with rules to ignore modpack contents, with exceptions for any files that are not hosted by Modrinth:

# .gitignore

# modpack-lock:start
mods/*.jar
resourcepacks/*.zip
datapacks/*.zip
shaderpacks/*.zip
*/**/*.disabled

## Exceptions
!mods/example.jar
# modpack-lock:end

This section is managed by modpack-lock and will be updated automatically when you run modpack-lock -g. Changes made inside this section will be overwritten, but any changes you make outside of this section will be preserved.

License

This project is licensed under the MIT License - see the LICENSE file for more details.