Roblox Library Template

📦 A template for Roblox developers to integrate advanced CLI tools like Rojo or Argon into GitHub workflows, streamlining build, test, and deploy processes for libraries and packages.

This repository serves as a starting point for creating reusable, modular libraries for Roblox or Luau projects. It is designed to work seamlessly with tools like Argon (Rojo), Pesde.

🚨 Disclaimer

This repository is intended for educational and template purposes only.
Any code included here is purely for demonstration and showcase. It is not production-ready and should not be used directly in live experiences. This template is still a "work in progress".

🚀 Usage

📦 As a Dependency

To use your library in your own project, simply add it as a dependency using pesde:

pesde add frostproject/roblox_library_template

🧪 For Development

To work directly with this template (e.g., for customization or contribution):

Clone the repository:

git clone https://github.com/frostproject/roblox-library-template.git
cd roblox-library-template

Install the required tools:

rokit install
pesde install

This will set up everything you need to begin development.

⚠️ Note: You are expected to have a basic understanding of Luau development, Roblox tooling, and dependency management. Using this template without that knowledge is discouraged and considered bad practice.

📦 Publishing & Maintenance

This template includes GitHub Actions workflows for automated publishing to the pesde package registry. You can also use Wally by modifying the workflow—it's a matter of preference. We consider pesde a better alternative, which is why we aim to make it more discoverable.

📝 Steps to Publish a New Version

1. Make your changes, implement and commit them as usual.
2. Update the CHANGELOG.md Follow the Keep a Changelog format. It’s simple and helps consumers understand what changed.
3. Commit your changes

git add .
git commit -m "feat: Add amazing new feature"
git push

Now it's time to create and push a version tag. This will automatically trigger the workflow to:

• Update pesde.toml
• Build and package the release
• Publish it to the registry

git tag -a 1.2.3 -m "chore: release v1.2.3"
git push origin 1.2.3

🔥 You’re done! A new release will be created and published automatically.

⚠️ Important Notes

Never manually edit pesde.toml’s version field. This is handled by the workflow. Manually changing it can break the automated publishing process. The only exception is if you're completely opting out of the workflow and managing releases manually. Please, don't put a "v" in the tag name, for example - v1.2.3. This might break the workflow as it doesn't follow semantic versioning. It is fine to put it in the commit message, though.

It’s safe and advised to regularly update pesde.lock. You may bump dependencies and commit those changes. It is discouraged to modify the file manually. Please use pesde update for that regard.

To enable the GitHub workflow for automated publishing to the pesde registry, you must add PESDE_TOKEN as a repository secret or organization secret. To obtain it, please use pesde auth login and then pesde auth token. More information here.

📘 Maintainer's Guide

If you’re new to package or repository maintenance, we've prepared a simple guide just for you:

👉 Maintainer's Cook Book (WORK IN PROGRESS)
Covers the basics of semver, commits, triaging, dependency bumps, tagging, and more. While we're still cooking it up for you, feel free to reach out via Discord DMs if you need help: iceeburr