Semantic Release Minecraft

Automate your Minecraft project release process with deep integration into Semantic Release!

✨Features

• Comprehensive configuration options put everything under your control.
• Use Semantic Release to automatically generate release notes for your project and avoid manual effort.
• Dual-platform support for CurseForge and Modrinth.
• Use strategy configurations for convenient multiple deployments. (e.g., Architectury and other multi-loader projects)

🚀Getting Started

You can install the package via npm:

npm install --save-dev semantic-release-minecraft

⚙️Configuration

The plugin configuration is passed via semantic-release's config (e.g., .releaserc.json). Below is a detailed explanation of the configuration options, grouped by scope.

If you don't want to read through the lengthy configuration introduction below, you can jump to the Configuration Reference to check out some practical configurations.

---

🛠️ CI Secret Configuration

For Modrinth and CurseForge API token configuration, you can set them via environment variables in tools like GitHub Actions:

CURSEFORGE_TOKEN: ${{ secrets.CURSEFORGE_TOKEN }}
MODRINTH_TOKEN: ${{ secrets.MODRINTH_TOKEN }}

Remember to configure the repository secrets in the repository settings.

Below are the links to obtain API tokens for CurseForge and Modrinth:

CurseForge

Once obtained, your Modrinth API token can only be viewed once. Please ensure you save your API token securely.

Modrinth

🌍 Global Configuration

Field	Type	Description	Default	Example
release_type	'alpha' | 'beta' | 'release'	Release type	'release'	'beta'
game_versions	string | string[]	Minecraft game versions	[]	['1.20.1', '1.21.1']
mod_loaders	string | string[]	Mod loaders	[]	['fabric', 'forge']
display_name	string	Mod display name	nextRelease.name	'[NeoForge 1.21.1] 1.0.0'
strategies	Record<any, any>[]	Store an array of strategy configurations for each release. See explanation below.	[{}]	[{ 'loader': 'fabric' }, { 'loader': 'neoforge' }]
glob	string | string[]	Glob patterns that matches all files requiring upload	['build/libs/!(*-@(dev|sources|javadoc)).jar','build/libs/*-@(dev|sources|javadoc).jar',]	-
primary_file_glob	string | string[]	Glob pattern matching the primary file	-	-
dependencies	Array of Objects	Global Dependency relations. See sub-table below.	[]	~~~

🕸️ Global Dependencies Sub-Configuration

Field	Type	Description	Default	Example
slug	string	Project Slug of dependency (required).	-	'yacl'
curseforge_project_id	string	CurseForge Project ID of dependency.	-	~~~
modrinth_project_id	string	Modrinth Project ID of dependency.	-	~~~
type	'required' | 'optional' | 'incompatible' | 'embedded'	Dependency type (required).	-	'embedded'

⚙️ Strategy (Template) Configuration

When using a strategy list, each strategy will be executed once. Values within the strategy will be embedded into most strings using Lodash's template function. For example, if you use a strategy like this:

{
    "loader": "fabric",
    "name": "Fabric"
}

You can use it in display_name like this: ‘[${ name } 1.21.1] ${ nextRelease.version }’.

Here, name is defined as specified in your strategy.

Similarly, you can embed content from semantic release context into strings. The most practical one is nextRelease.version, which is the version number calculated by Semantic Release for the upcoming release.

Therefore, the above string will be replaced at runtime with something like: [Fabric 1.21.1] 1.0.0

🔨 CurseForge Configuration

Configure under the curseforge object. Requires project_id to enable.

Field	Type	Description	Default	Example
project_id	string	CurseForge project ID (required). Get from project website.	-	'1250626'
game_versions	string | string[]	CurseForge-specific game versions.	Global	['1.21.9', '1.21.10']
java_versions	number | number[]	Supported Java versions.	[]	21
environments	string | string[]	Release environments (e.g., client, server).	[]	'client'
game_versions_for_plugins	string | string[]	Game versions primarily used for Bukkit plugins.	[]	'1.20'
game_versions_for_addon	string | string[]	Game versions for add-ons.	[]	'1.21'
mod_loaders	string | string[]	CurseForge-specific loaders.	Global	'fabric'
changelog	string	Custom changelog text.	nextRelease.notes	'Custom changes for v1.0.0'
changelog_type	'text' | 'html' | 'markdown'	Changelog format.	'markdown'	'html'
display_name	string	CurseForge-specific display name.	Global	'Iris 1.9.6 for Fabric 1.21.10'
is_marked_for_manual_release	boolean	Mark release as manual so you can choose when to release.	false	true
relations	Array of Objects	Dependency relations. See sub-table below.	Global	-
glob	string | string[]	CurseForge-specific file glob.	Global	~~~
primary_file_glob	string | string[]	CurseForge-specific primary file.	Global	~~~

🧩 CurseForge Dependencies Sub-Configuration

Field	Type	Description	Default	Example
slug	string	Slug of dependency (required).	-	'architectury-api'
project_id	string	Project ID of dependency.	-	'419699'
dependency_type	'embeddedLibrary' | 'incompatible' | 'optionalDependency' | 'requiredDependency' | 'tool'	Dependency type (required).	-	'requiredDependency'

⚡ Modrinth Configuration

Configure under the modrinth object. Requires project_id to enable.

Field	Type	Description	Default	Example
project_id	string	Modrinth project ID (required). Copy from project website.	-	'uWsLN21d'
version_number	string	Custom version number.	nextRelease.version	'1.0.0+fabric'
display_name	string	Modrinth-specific display name.	Global	'3.14.1_Fabric_1.21.1'
game_versions	string[]	Modrinth-specific game versions.	Global	'1.12.2'
mod_loaders	string[]	Modrinth-specific loaders.	Global	'quilt'
changelog	string	Custom changelog.	nextRelease.notes	'See full changelog'
dependencies	Array of Objects	Dependency relations. See sub-table below.	Global	-
featured	boolean	Mark as featured version.	false	true
status	'listed' | 'archived' | 'draft' | 'unlisted' | 'scheduled' | 'unknown'	Version visibility status.	'listed'	'draft'
requested_status	'listed' | 'archived' | 'draft' | 'unlisted'	Requested status (for moderation).	'listed'	'unlisted'
glob	string | string[]	Modrinth-specific file glob.	Global	~~~
primary_file_glob	string | string[]	Modrinth-specific primary file.	Global	~~~

🔗 Modrinth Dependencies Sub-Configuration

Field	Type	Description	Default	Example
version_id	string	Specific version ID of dependency.	-	'e0mxOOIE'
project_id	string	Project ID of dependency.	-	'mOgUt4GM'
file_name	string	File name of the dependency, mainly for displaying external dependencies in modpacks.	-	~~~
dependency_type	'required' | 'optional' | 'incompatible' | 'embedded'	Dependency type (required).	-	'optional'

🗂️Configuration Reference

The following is an example configuration for an Architectury project, demonstrating how to use different options.

If you'd like a more detailed, comprehensive reference, you can find it in my project Better Client.

Some quick tips to help you grasp things faster:

• Each strategy runs once.
• Values within strategies and context can be embedded in strings.

[
  "semantic-release-minecraft",
  {
    "game_versions": "1.21.1",
    "mod_loaders": "${ loader }",
    "display_name": "[${ name } 1.21.1] ${ nextRelease.version }",
    "glob": "${ loader }/build/libs/better_client-${ loader }-${ nextRelease.version }.jar",
    "dependencies": [
      {
        "slug": "architectury-api",
        "type": "required"
      },
      {
        "slug": "yacl",
        "type": "required"
      }
    ],
    "strategies": [
      {
        "loader": "fabric",
        "name": "Fabric"
      },
      {
        "loader": "neoforge",
        "name": "NeoForge"
      }
    ],
    "curseforge": {
      "project_id": "1250626",
      "java_versions": 21,
      "environments": "client"
    },
    "modrinth": {
      "project_id": "uWsLN21d",
      "version_number": "${ nextRelease.version }+${ loader }"
    }
  }
]