> For the complete documentation index, see [llms.txt](https://wiki.thunderstore.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.thunderstore.io/mods/your-first-upload.md). # Your First Upload Publishing your first mod on Thunderstore, step by step. This page walks you through publishing your first mod on Thunderstore from start to finish. If you have uploaded before and just need the package requirements, see [Creating a Package](https://wiki.thunderstore.io/mods/creating-a-package) instead. ## Quick checklist * [ ] Thunderstore account and team created * [ ] Mod files in the correct folder structure for your game * [ ] `manifest.json` (validated) * [ ] **Mod installed from a zip and tested on a clean profile, in game** * [ ] Mod functions as intended * [ ] `icon.png` (256x256, PNG) * [ ] `README.md` (UTF-8 format), reviewed with Markdown Preview and ideally with screenshots * [ ] All of the above zipped at the **root** of the zip * [ ] [Global Rules](/moderation/global-rules.md) read * [ ] Uploaded to the right community with categories set {% stepper %} {% step %} ## Create an account Register at [thunderstore.io](https://thunderstore.io/) by signing in with Discord, GitHub or Overwolf. You need an account to upload, but not to download mods. {% endstep %} {% step %} ## Create a team Every package on Thunderstore is owned by a **team**, not by a user account. You cannot upload without one. Teams are not created automatically, so you need to create one yourself. If you are modding solo, you can simply create a team named after your own username. You can do that at [thunderstore.io/teams](https://thunderstore.io/teams/), or click the user icon in the top right and choose **Teams**. {% hint style="warning" %} Your team name becomes part of your package's identity and cannot be changed later. It appears on your package page and makes up part of the dependency string other modders use to depend on your mod, in the format `TeamName-PackageName-Version`. Pick something you are happy to keep. {% endhint %} Teams are also how you add collaborators later, so if you are working with other people, pick a team name that fits the whole group.\ Remember that those with Owner rights have the same access as you. Keeping contributors as Members gives them enough access to update and interact with your packages.
{% endstep %} {% step %} ## Build your package A Thunderstore package is a zip file containing `icon.png`, `README.md` and `manifest.json` at its root, plus your mod files. The file names have to match exactly, including the extension. [Creating a Package](https://wiki.thunderstore.io/mods/creating-a-package) has the exact requirements for each of those, and a minimal example package you can download and copy. Thunderstore only checks the required files, so an upload can go through and still not install correctly. Mod managers do their best to work out where files should go. If your mod is not installing correctly in a mod manager, refer to [Packaging Your Mods](https://wiki.thunderstore.io/mods/packaging-your-mods). You can test this before uploading by using the **Import local mod** functionality, located inside the mod manager's settings. ### Your manifest Your `manifest.json` tells Thunderstore and mod managers what your package is. A minimal example: ```json { "name": "MyFirstMod", "version_number": "1.0.0", "website_url": "https://github.com/yourname/MyFirstMod", "description": "A short summary of what your mod does.", "dependencies": [] } ``` * `name`: your package name. Letters, numbers and underscores only, no spaces. Changing it later creates a new package * `version_number`: in Major.Minor.Patch format, for example `1.0.0` * `website_url`: a link to your source code or mod page. Can be left as an empty string * `description`: a short summary shown in the mod listings, 250 characters at most * `dependencies`: other packages your mod needs, each in the `TeamName-PackageName-Version` format. Leave the list empty if there are none {% endstep %} {% step %} ## Test it in game Test the zip you are going to upload, not just your mod files. When you do the icon and README is up to you, plenty of authors work on those while the mod is still in progress. Zip your files the way [Step 6](https://wiki.thunderstore.io/mods/your-first-upload#create-the-zip) describes, then install the zip using the mod manager's **Import local mod** option and test the mod. Installing from a zip rather than copying files in by hand also catches a wrong folder structure from Step 3. Test that: * The mod manager installs or loads the package without errors * The game launches with the mod installed * The mod does what you intended it to do * Config options are generated and take effect, if your mod has any * No unexpected errors in the log are associated with your mod {% hint style="danger" %} Test on a clean profile. Your own profile with other mods may have dependencies, config files and leftovers that new users will not have. {% endhint %} If something is wrong, fix it, rebuild the zip and test again. {% endstep %} {% step %} ## Write your README and make your icon This is what people judge your mod on before they install it. They see it in this order: icon, short description, categories, and only then the README if they want more. ### Your icon `icon.png` has to be exactly 256x256 and a PNG. Beyond meeting that requirement, it is worth spending a little time on, because it sits next to every other mod in the listings and is the first thing people see. * Make it readable at small size * Give a hint of what the mod actually does or adds * Many users prefer icons that are not AI generated ### Make your README worth reading Your `README.md` is your mod's page. It is what people read before deciding to install, and it is the first thing they check when something does not work. New to Markdown, or not sure what Thunderstore supports? [Markdown Guide](https://wiki.thunderstore.io/mods/markdown-guide) covers what you need for a package README. Paste your README into [Markdown Preview](https://thunderstore.io/tools/markdown-preview/) as you write to see how it will render. Cover at least: * What the mod does, in the first two lines * What it changes or adds in game * Dependencies, if there are more than the obvious ones * A mod that only needs BepInEx or one well known library does not need a list * Configuration options, if there are any * Known issues or incompatibilities * Credits and contact, if you want feedback **Show it, do not just describe it.** Screenshots, GIFs or a short video clip do far more than a paragraph ever will, especially for anything visual such as models, textures, UI or effects. A single good screenshot near the top of the README is one of the cheapest things you can do to get people to install your mod. A pattern that works well: a showcase section near the top, split by feature, with a line of explanation and then the images or GIFs that demonstrate it. Detailed configuration and reference material goes further down, where the people who need it will still find it. {% hint style="info" %} Images have to be linked from somewhere they are publicly hosted, such as your GitHub repository or an image host. Files inside your package are not served as images on your package page, so a path pointing at a file in your zip will show as a broken image. Use a direct link to the image file: `![Description of the image](https://example.com/screenshot.png)` To show another package's icon, link it directly: `https://gcdn.thunderstore.io/live/repository/icons/Author-Package-1.0.0.png` {% endhint %} ### **Your changelog** `CHANGELOG.md` is optional, but it is where people look when a version breaks something. It follows a different convention from your README: newest version at the top, one heading per version, and a short list of what actually changed. ``` ## 1.1.0 - Added a config option for spawn rate - Fixed a crash when loading a save with no mods ## 1.0.0 - First release ``` "Various fixes and improvements" tells nobody anything. Name what changed. ### Final README check Open your README one more time and check that: * The README matches what the mod actually does * Dependencies and config options are listed * Your images load * There are no typos left {% endstep %} {% step %} ## Create the zip Two tools worth running before you zip: * [Manifest Validator](https://thunderstore.io/tools/manifest-v1-validator/) catches errors in your `manifest.json` * [Markdown Preview](https://thunderstore.io/tools/markdown-preview/) shows how your README will render, so you can spot problems before they are public {% hint style="info" %} The markdown preview tool cannot check file encoding. If your README contains special characters, confirm the file is saved as UTF-8 without BOM in your text editor. {% endhint %} Select the **files**, not the folder containing them, then compress the selection. {% hint style="danger" %} If you zip the folder instead of its contents, your files will not be at the root of the zip and the package cannot be uploaded. {% endhint %} Step by step instructions for Windows and other systems are in [Creating a Package](https://wiki.thunderstore.io/mods/creating-a-package). This is the zip you upload, so build it fresh from your final files. If you changed any mod files since you tested in Step 4, install this zip and test it once more before you upload. {% endstep %} {% step %} ## Upload Open the [upload page](https://thunderstore.io/package/create/) and fill in the form. You will be asked for: * **Upload file**: your zip, up to 10GB * **Team**: the team the package will be published under * **Communities**: which community or communities the package is listed in * **Categories**: how people filter and find your mod. The list only appears once you have picked a community. Pick what genuinely applies to your package, and check how similar mods in that community are tagged, since communities apply categories differently. This is also where you set the **AI generated** category. See **AI generated** content in the [Global Rules](https://wiki.thunderstore.io/moderation/global-rules#ai-generated-content) for what counts * **Contains NSFW content**: set this to Yes if the content is not suitable for children
{% hint style="warning" %} Check the **NSFW flag** before you submit. It cannot be changed afterwards. Categories can be edited later under **Manage Package**, but the files in a version cannot, so anything missing or wrong in your README stays on your page until you publish a new version. Run through the final README check before you submit. {% endhint %}
{% hint style="info" %} Modding a game that does not have a community on Thunderstore yet? See [Adding a new game](https://wiki.thunderstore.io/ecosystem/adding-a-new-game). {% endhint %} {% endstep %} {% step %} ## Check your package page Once the upload succeeds, open your package page and confirm: * The icon displays correctly * The README renders the way you expected * The description reads well in list views * The categories are correct * Any dependencies you declared are listed {% endstep %} {% step %} ## Publishing an update The files in a version cannot be changed after upload. To change your mod, you upload a new, higher version. See [Updating a Package](https://wiki.thunderstore.io/mods/updating-a-package) for how to do that without accidentally creating a second package. Categories and other package settings can be edited at any time under **Manage Package**, without uploading a new version. {% endstep %} {% endstepper %} ## Before you publish All packages are subject to the [Global Rules](https://wiki.thunderstore.io/moderation/global-rules), plus any rules specific to the community you upload to. Read them once before your first upload. Many takedowns come from uploading content you do not have permission to distribute, such as reuploading someone else's mod without their permission. ## If your upload is rejected | Message | Usual cause | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | Missing required files | The zip contains a folder rather than the files at its root | | Invalid icon | Icon is not exactly 256x256, or is not a PNG | | Invalid manifest | Malformed JSON, or a missing field | | Invalid name | Package name contains spaces or characters that are not allowed | | Invalid submission | Your package needs a manual review. Reach out to the moderators in the [Thunderstore Discord](https://discord.thunderstore.io/) | Requirements for each of these are in [Creating a Package](https://wiki.thunderstore.io/mods/creating-a-package). Uploaded successfully but something is wrong afterwards? * Package does not appear where you expect: [Mod not visible?](https://wiki.thunderstore.io/mods/mod-not-visible) * Mod does not work when installed with a mod manager: recheck [Packaging Your Mods](https://wiki.thunderstore.io/mods/packaging-your-mods) for your game * A new version created a second package instead of updating: [Updating a Package](https://wiki.thunderstore.io/mods/updating-a-package) Still stuck? Two good places to ask: * **The** [**Thunderstore Discord**](https://discord.thunderstore.io/) for anything about the site itself, uploading, or moderation * **Your game's own modding community** for anything specific to that game. This is usually the faster answer, since the people there know the quirks of the game