Preserve default.project.json During Package Installation

[soyuta]

I'm currently testing a pre-release build of pesde 0.8.

In pesde 0.8, hook scripts such as roblox_sync_config_generator have been removed.
As a result, users can no longer generate their own default.project.json.

default.project.json is currently excluded and is also automatically omitted when dependencies are installed.

Originally, this was intended to prevent a dependency package's Roblox hierarchy from conflicting with pesde, for example, by accidentally defining a DataModel.
and to avoid requiring every user to write their own default.project.json

However, now that hook scripts are gone, I'm not sure whether default.project.json should still be excluded during dependency installation.

From a Git submodule and Wally perspective, a package's default.project.json describes how that package should appear in Roblox.
It also allows package authors to configure options such as emitLegacyScripts or exclude specific files, making it a useful part of the package itself.

This is especially relevant in pesde 0.8, where includes and build_files have been removed.
When a project containing an installed package is built with Rojo, every file in that package will now be included.
As a result, any files that are not explicitly excluded (such as documentation, .txt, .toml, or .json files) will be exposed as StringValue or ModuleScript, which does not fit well with the Roblox ecosystem.

For packages targeting both Luau and Roblox, there may also be modules that are intended for Luau only and should not be included in the Roblox build. In such cases, package authors may need to use Rojo options such as globIgnorePaths.

Additionally, Rojo has supported syncRules since version 7.5.0.
These rules control how files are transformed during synchronization, and the feature may become even more powerful as Rojo continues to evolve.
syncRules are particularly useful for handling custom file extensions that would otherwise require complex or repetitive Rojo configuration.

For example, if a package wants to distribute a default.project.json that uses syncRules, consumers currently have to duplicate the same configuration in their project's root default.project.json.

Rather than removing the possibility of creating a package that is incompatible with pesde because of an incorrectly written default.project.json, I think it would be better to respect the extensibility that default.project.json provides.

[daimond113]

Thank you for testing 0.8. As of now, it is in a really rough shape and far from being finalised. Since this is a fast-moving target, I currently recommend discussing design decisions or suggesting ideas on real-time platforms like Discord. The feat/registries-v2 branch is much closer to the expected final product in that it brings back registries and their associated settings (e.g. includes). Once registries v2 are implemented, we expect to shortly release the first betas. During this time, the design will still be fluid and adjustable freely, so there will be no backwards compatibility concerns.

For this reason, I cannot respond with any specifics or final decisions because there's not a fixed shape yet. However, we do agree that there needs to be a way of not syncing unnecessary things to Roblox.

The original roblox_sync_config_generator script was intended to generate a sync config that minimised the amount of files required to sync (e.g. excluding documentation); it was required that it didn't change the package's structure because pesde assumes a 1:1 match with the file system. This is why pesde packages, unlike Wally, still have a src folder/module script in Roblox. pesde also intended to be compatible with tools other than Rojo, such as ones that don't use a project.json file, which is why they were forbidden from being published; the inability to accidentally define a DataModel was mostly a positive side effect. build_files also supported only top-level entries because of compatibility as well as complexity concerns.

Wally didn't make such design guarantees, which is why we do not modify their configuration - it could carry Roblox-specific settings or define complex hierarchy manipulation. emitLegacyScripts doesn't affect ModuleScripts, which should be the only type of script a package has. Anything else is unsupported because it doesn't match expected semantics of having one entry-point per program. This also applies to using Rojo to create Roblox instances - this should all be done in code.

In 0.8, pesde will also stop assuming one runtime per project (this is an incredibly common practice, e.g. using Luau scripts to pre-process your Roblox game's source code). We don't have any plans to specify the packages directory layout, so something like a general-purpose script that runs over every package and gives you the path could be considered, but a better approach may pop up during development, so I recommend that this discussion be revisited once beta releases begin.

[soyuta]

Thank you for the detailed explanation. I also agree with pesde's philosophy.
No tool should be tied exclusively to Roblox, Rojo, or any other specific ecosystem.
Any platform or tool can change significantly or even become unmaintained over time, so I think keeping packages as independent as possible is the right direction.

At the same time, I think that philosophy may weaken the reason for unconditionally excluding default.project.json

Now that pesde is moving away from assuming a single runtime environment per project, packages are expected to detect whether they are running under Lune, Lute, Roblox, or another environment and adapt accordingly.
I think the same principle should apply to project configuration files as well, whether that means preserving project.json, default.project.json, someproject.toml, or any other tool-specific configuration.

This allows each tool to rely on its own configuration format. I also don't expect default.project.json to be widely adopted by other tools, since repurposing another tool's existing manifest would generally be considered poor design.

---

One case I'm a little unsure about is localization.

I'm currently working on translations, and in my case, translations need to be managed per package.

Roblox uses CSV for localization tables, but CSV isn't really a format well suited for translation.
Since it stores all of the data line by line, it's also not a particularly convenient format for contributing translations to an open-source project, especially when the same localization files also need to work in CLI or local environments outside Roblox.

So I've been looking into formats such as PO.

For a simple example, suppose I have:

locales/
messages.pot
ko.po
ja.po
en.po

This works fine in a local environment, but Rojo ignores extensions such as .po and .pot.
So I would need to use syncRules to have those PO files treated as text, which requires a default.project.json.

{
  "name": "my-cli",
  "syncRules": [
    {
      "pattern": "*.{po,pot}",
      "use": "text"
    }
  ],
  "tree": {
    "src": { "$path": "src" },
    "pesde": { "$path": "pesde" },
  }
}

I think the package itself should provide the PO -> text mapping, rather than having the consumer configure it.

I could work around this by switching to JSON (although even with JSON, I would still need syncRules if I wanted the JSON file itself to be synced as a StringValue), or by keeping everything as pure Luau code, but hmm...

If pesde is specifically intended for distributing packages consisting only of Luau code, I can understand that. In my case, I tend to build things by combining multiple packages.

For example, I might have one package containing a piece of the game's UI along with its corresponding localization.
I think splitting things into smaller packages like this makes them easier to maintain as open-source projects and easier for others to contribute to.

So preventing default.project.json in order to avoid depending on Rojo actually feels like it makes packages more dependent on the tooling in another way.
Wouldn't it make more sense to allow default.project.json, but reject it when it describes a structure that doesn't maintain the 1:1 mapping expected by pesde? (For example, it could be rejected if default.project.json has a name set or if the tree is invalid)
If even doing this kind of validation would ultimately mean depending on Rojo, then I think it might actually be better to just leave it up to the user.
These days, it also seems like more packages are being made with compatibility with environments like Lute in mind, so I feel like there are fewer packages than before that can only be installed through Wally or only used in Roblox.

[daimond113]

I do not want to maintain a parser, no matter how small, for sync tool configs inside pesde since it creates multiple problems: why is Rojo special; why doesn't tool X also have an integration like this? what happens if Rojo adds new options or even changes the configuration overall?

I've been considering how to mirror non-Luau files in Roblox, and the simplest solution will most likely be to require that they are synced as scripts that return strings of their contents. However, this is mostly something I've just thought about in my free time without any actual integration testing or anything.

Regardless, Luau itself doesn't allow you to natively read non-Luau files, so polyfilling readfile is slightly out of scope of pesde itself. My aforementioned idea may be the solution userspace pesde converges on, though. It'll probably be dictated by std packages (or even our official pesde/std itself).