Sonata Logo Big

Sonata

Luau package manager, module loader and compiler

Why use Sonata?

One command, sn, creates projects, manages dependencies, runs your code and compiles it into executables that run without Sonata installed.

extension Modular

Build your own modules and organize multi-file structured projects with ease. require("./util") loads files relative to the script, keeping your code reusable, clear, and simple to maintain.

package_2 Package Manager

Manage your dependencies with the git-powered package manager. Any Git repository is a package, and a lock file pins exact commits so builds stay reproducible.

inventory_2 Batteries included

15 built-in libraries for files, processes, TLS networking, JSON, YAML, TOML, cryptography, time zones, compression, regex and more. No dependencies needed.

account_tree Tasks

Programs run on a scheduler. While one task waits on a socket, child process, timer or channel, the others keep running.

rocket_launch Standalone executables

sn build bundles your project and its dependencies into one file that runs anywhere, optionally with a smaller runtime holding only the libraries you use.

sentiment_very_satisfied Easy to use

With Luau's simple syntax, powerful type system, and excellent performance, combined with Sonata's builtin modules and loaders, you can build anything you can imagine with ease.

From idea to executable

Scaffold a project, pull in a package straight from Git, run it, and ship a single binary. It's all the same tool.

  • create_new_folder
    sn init scaffolds a project and its manifest
  • add_box
    sn pkg add installs any Git repository
  • play_arrow
    sn run runs the entry script
  • rocket_launch
    sn build compiles a standalone executable
descriptionmain.luau terminalTerminal settingsproject.luau 
local fs = require("@sonata/fs")
local term = require("@sonata/term")
local task = require("@sonata/task")

-- Print every entry in the current directory,
-- each one from its own task
for _, name in fs.listDir(".") do
    task.spawn(function()
        term.stdout:writeLine(term.style(name, "bold", "cyan"))
    end)
end
$ sn init hello
$ cd hello
$ sn pkg add github.com/acme/json5
$ sn run
Hello World!
$ sn build
# standalone executable written to dist/
-- .sonata/project.luau
return {
    name = "myProject",
    version = "0.1.0",
    description = "A new Sonata project",
    entrypoint = "main.luau",
    authors = {},
    dependencies = {},
}

Batteries included

Every library ships with Sonata. Import any of them with require("@sonata/<name>").

folder
fs

Files, directories, globbing, watching and locking.

lan
net

TCP, UDP, Unix sockets, TLS, DNS, URLs, HTTP/1.1 and WebSocket.

terminal
process

The running program, child processes and signals.

account_tree
task

Tasks and the tools to coordinate them.

keyboard
term

Standard streams, colors, cursor control and keyboard input.

data_object
json

Parse, serialize and edit JSON.

swap_horiz
serde

YAML, TOML, INI, CSV and TSV, plus a toolkit for custom formats.

lock
crypto

Hashes, HMAC, key derivation, ciphers, signatures and UUIDs.

folder_zip
compress

gzip, zlib, deflate and zstd compression, streaming, checksums.

schedule
datetime

Dates, times and time zones, precise to the nanosecond.

manage_search
regex

ECMAScript regular expressions.

route
path

Lexical path manipulation for POSIX and Windows.

inventory_2
pocket

Read-only asset files packed with the program.

memory
sys

Facts about the machine, clocks and sleeping.

music_note
sonata

Build info, projects and the package manager.

Install Sonata

Runs on Linux, macOS and Windows.

terminalLinux / macOS desktop_windowsWindows downloadManual buildFrom source
1
Run the install script

The script downloads the latest release for your system into ~/.sonata and adds ~/.sonata/bin to your PATH through your shell's rc file. It needs curl or wget, and tar.

curl -fsSL https://sonata.5418.org/install.sh | bash

No curl? Use wget -qO- https://sonata.5418.org/install.sh | bash instead.

2
Restart your shell and check that it works
sn --version
Options

Pass options after bash -s --, or set the environment variable instead:

curl -fsSL https://sonata.5418.org/install.sh | bash -s -- --version 0.1.92 --dir /opt/sonata
OptionVariableDescription
--version <tag>SONATA_VERSIONRelease to install, e.g. 0.1.92. Defaults to the newest release, pre-releases included.
--dir <path>SONATA_INSTALLInstall location. Defaults to ~/.sonata; sn goes in <dir>/bin.
--no-modify-pathSONATA_NO_MODIFY_PATH=1Don't add <dir>/bin to your PATH.

The script also works from Git Bash on Windows. Want to read it first? View install.sh

1
Run the install script in PowerShell

The script downloads the latest release into %USERPROFILE%\.sonata and adds its bin folder to your user PATH.

irm https://sonata.5418.org/install.ps1 | iex
2
Open a new terminal and check that it works
sn --version
Options

Set environment variables before running the script:

$env:SONATA_VERSION = "0.1.92"
$env:SONATA_INSTALL = "C:\sonata"
irm https://sonata.5418.org/install.ps1 | iex

Or download the script and pass them as parameters:

irm https://sonata.5418.org/install.ps1 -OutFile install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Version 0.1.92 -Dir C:\sonata
ParameterVariableDescription
-VersionSONATA_VERSIONRelease to install, e.g. 0.1.92. Defaults to the newest release.
-DirSONATA_INSTALLInstall location. Defaults to ~\.sonata.
-NoModifyPathSONATA_NO_MODIFY_PATH=1Don't add <dir>\bin to your user PATH.

Want to read it first? View install.ps1

1
Download the archive for your platform

Archives are named sonata-<version>-<system>-<arch>.tar.gz (.zip on Windows).

downloadLatest release
2
Extract it and add bin to your PATH

Extract anywhere you like, but keep the folders together: sn looks for its runtime in ../libexec/sonata/ relative to itself.

3
Check that it works
sn --version
Linux / macOS

You need CMake 3.21+, a C++20 compiler, Git, zlib and OpenSSL.

git clone --recursive https://github.com/runsonata/sonata.git
cd sonata
./b.sh release
./b.sh install    # installs to $PREFIX, default ~/.local

Make sure ~/.local/bin (or $PREFIX/bin) is on your PATH.

Windows

Build in a Developer PowerShell. You need CMake 3.21+, MSVC, Git, zlib and OpenSSL.

git clone --recursive https://github.com/runsonata/sonata.git
cd sonata
cmake --preset release
cmake --build --preset release --config Release
cmake --install build/release --prefix "$env:LOCALAPPDATA\sonata"

Then add %LOCALAPPDATA%\sonata\bin to your PATH.

Discord logo

Discord Server

Join the Discord server to:
  • support
    Get support
  • bug_report
    Report bugs
  • lightbulb
    Suggest features
  • forum
    Chat with other users
  • campaign
    Get updates on new features
group_add Join the Discord
check Copied to clipboard