https://github.com/nickesc/modpack-lock

Creates a modpack lockfile for files hosted on Modrinth (mods, resource packs, shaders and datapacks)
https://github.com/nickesc/modpack-lock

lockfile minecraft modpack modrinth

Last synced: 3 months ago
JSON representation

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

Host: GitHub
URL: https://github.com/nickesc/modpack-lock
Owner: nickesc
License: mit
Created: 2026-01-06T03:08:19.000Z (5 months ago)
Default Branch: main
Last Pushed: 2026-02-28T20:19:49.000Z (3 months ago)
Last Synced: 2026-02-28T23:37:37.354Z (3 months ago)
Topics: lockfile, minecraft, modpack, modrinth
Language: JavaScript
Homepage: https://www.npmjs.com/package/modpack-lock
Size: 2.05 MB
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 5
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# modpack-lock

###### by nickesc - [GitHub](https://github.com/nickesc) | [Modrinth](https://modrinth.com/user/nickesc)

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

```bash
npm install -g modpack-lock
```

Alternatively, you can run it using `npx`:

```bash
npx modpack-lock
```

## CLI

To generate a lockfile for your modpack, run:

```bash
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.

```text
Usage: modpack-lock [options] [command]

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

Options:
-p, --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] 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:

```bash
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.

```text
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:

```bash
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:
>
> ```bash
> 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.

```text
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()`
- `generateGitignoreRules()`
- `generateReadmeFiles()`
- `generateLicense()`
- `generateLockfile()`
- `generateModpackFiles()`
- `promptUserForInfo()`

See the [API documentation](https://nickesc.github.io/modpack-lock) for full details.

## File Formats

### `modpack.lock`

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

```json
{
"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:

```json
{
"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": [ ... ],
"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:
>
> ```txt
> # .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](LICENSE) file for more details.

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/nickesc/modpack-lock

Awesome Lists containing this project

README