Publishing a Package

This page covers the shared flow for creating and updating your own packages: forest init, forest publish, versioning, and dependencies. These steps are the same on every platform. How you actually lay out and write the code inside a package differs by platform, so each step links to the matching platform guide.

Prerequisites

Before you can create and upload packages, you’ll need the following:

A Forest account
The Forest CLI installed

The flow

Create a directory for your package

A package is just a folder of code with a forest.json manifest at its root. Start with an empty directory named after your package.

Initialize with the Forest CLI


forest init

forest init asks which platform the package targets, then scaffolds the package:

Roblox: prompts for a package name and the path to your root module (default src/init.luau, created as a starter module if it doesn’t exist), then writes a forest.json with the name, version 0.1.0, platform, and root. Pass --packages-dir <name> to rename the dependency folder from the default Packages; the name is written as packagesDir.
UEFN: scaffolds a package or project manifest based on where you run it. See Authoring & Publishing.

Pass -p/--platform to skip the platform picker:


forest init --platform roblox   # or: --platform uefn

You rarely edit forest.json by hand. See the complete field reference for every field, its type, and an example manifest.

forest init is for authoring a package. If you’re setting up a game or project that only consumes packages, use forest init --project (or just run forest install, which offers the same bare manifest).

Write your code

Every package exposes a public API through an entry point. What that entry point looks like depends on the platform you target:

Roblox: one root module whose return value is the entire public API; init created a starter for you. See Package Anatomy.
UEFN: a folder of Verse modules that consumers import with using. See Authoring & Publishing.

Publish to Forest


forest publish

This uploads your package to the registry, making it available for others to install. If it’s your first time publishing, you’ll be prompted to log in.

The CLI asks a few questions: visibility (public or private), name, description, version, and license. Visibility is permanent. Every later version inherits what you choose here. Every account includes 10 private packages for free; Pro removes the limit (see Private Packages).

License safety ratings

Every published package needs a license: an SPDX identifier or a LICENSE file the CLI can detect (see the license field). The registry then runs an automated license review on every version and assigns it a safety rating, shown on the package page and returned by the API:

Rating	Meaning
`safe`	Permissive license; use freely, minor obligations at most (e.g. MIT, Apache-2.0).
`caution`	Usable, but carries obligations that bite in specific cases; read the version’s license caveats.
`unsafe`	Plausibly obligates open-sourcing the game that consumes it (e.g. strong copyleft).
`pending`	Custom or unrecognized license text, awaiting review.
`unknown`	The license could not be determined.

Ratings are an automated review, not legal advice. On caution or unsafe, read the actual license (and the caveats listed on the version) before shipping the package in a commercial project. forest audit reports the ratings across your whole dependency tree.

Publishing a package with dependencies

If your package relies on other packages, install those dependencies locally before publishing. For example, if your package relies on forest/utils:


forest i forest/utils

Installing writes the dependency into your forest.json (as a ^ version range), and forest publish uploads that dependency list as-is. The CLI does not scan your source for imports, so a dependency exists exactly when it’s listed in forest.json. See Dependencies & Versioning for range syntax and resolution rules.

When someone installs your package, Forest automatically installs its dependencies alongside it. The exact on-disk arrangement is platform-specific (Roblox, UEFN), but in every case a package finds its own dependencies without any configuration from the consumer.

Updating a package

To publish an update, change your code and run forest publish again.

The CLI asks what kind of change you made (bugfix, new feature, or breaking change) and increments the patch, minor, or major version accordingly, then uploads the new version.

While you’re iterating, you don’t need to publish on every change to test inside a real project: on Roblox, forest link points a project’s dependency at your local package folder so edits show up live, and forest unlink restores the registry version when you’re done.

For how Forest handles version numbers, including the range syntax consumers use to depend on your package, see Dependencies & Versioning and the SemVer guidelines.