Roblox Library Template

📦 A template for Roblox developers to integrate advanced CLI tools like Argon or Rojo 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 (alternative to Rojo) and 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

📦 Use as a Template

This is the recommended way to start your own project with this template.

1. Simply click here, create your repository on GitHub and then clone it locally.

2. Make sure that you have Rokit installed! Finally, download all of the required tools:

rokit install

3. You are now ready to start cooking some code! Remember to use:

• rokit for your toolchain (CLI tools, utilities)
• pesde for your packages, libraries, scripts and dependencies
• argon or rojo for code syncing between your favorite editor and Roblox Studio
• luau-lsp for auto-completion, linting and typechecking
• stylua for code formatting and styling

4. Optionally you should check out other popular tools like:

• Moonwave - tool for generating documentation from comments in Lua source code
• Blink - an IDL compiler written in Luau for Roblox buffer networking
• Lune - standalone Luau runtime similar to runtimes for other languages such as Node, Deno, Bun, or Luvit for vanilla Lua
• darklua - CLI tool that transforms Lua 5.1 and Roblox Luau code using configurable rules

⚠️ 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.

🧪 For Development and Contribution

Please read CONTRIBUTING.md guide if you want to contribute improvements to the template itself or forking it for personal use without starting a fresh project.

📦 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

4. 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.

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

pesde add frostproject/roblox_library_template

⚠️ 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

By using this template, you're also copying over several Markdown files and GitHub specific files (e.g., LICENSE.md, SUPPORT.md, SECURITY.md, CODEOWNERS etc.) that contain project-specific text and references. You are responsible for reviewing and updating these files to reflect your own project's name, license, contacts, and details.

While not always enforced, it is recommended to follow the code style guide provided. As this is only a template repository, we can only suggest you what to use. The boilerplate code we have follows the official Roblox Lua style guide and the Lua Rocks style guide. We use 3 tab spaces for indentation and a few other cool settings by default. All of that is up to your own preference and has no real meaning. You can configure them in the stylua.toml

💡 You can also use the safe-settings tool to automatically apply labels and settings to your repositories—just like we do.

⬆️ Back to the top