I am opening this as an issue as this is wanted and planned functionality, and there is actionable development work to start here. Once we are happy with parts of this I will create sub-issues for those specific parts which can then be worked on.

---

The status quo

Currently there are two way in which a Gleam package can be compiled:

1. As the root of a project
2. As a dependency of one of these root packages

The root package gets a build directory, and the dependencies are downloaded/copied/cloned into this directory. Gleam tooling such as the CLI (gleam build, etc) and the language server are run from and in the context of the root package.

If any of the dependency packages are worked with directly (running CLI commands from within them, opening their files in the LS) then they are treated as the root of their own project, distinct from the project they are in the build directory of.

Problems

The current design has some drawbacks:

1. If a developer is working with multiple packages that are conceptually one (e.g. a web application with a frontend, backend, and shared packages that depend on each other as path dependencies) then there is no guarantee that each of the 3 projects will resolve to the same versions for "shared" dependencies. This could result in unexpected behaviour in production.
2. As each package has its own copy of all of its dependencies any that are "shared" get compiled multiple times, wasting compute and the developer's time.
3. Each package performs dependency resolution independently, making it easy to hit Hex's rate limits. @crowdhailer hit this recently with his company's monorepo.
4. If a dependency is navigated to in the developers LS-using editor (such as through go-to-definition) then the language server will treat it as a new root project and perform dependency resolution for it. As well as wasting compute and Hex API requests, this likely will result in different dependency versions being selected again, which can result a very confusing situation where the code you have navigated to is not the code that is actually in the final application.

The proposed solution

Upgrade the Gleam toolchain to understand when a package is part of a larger Gleam project, and use the build directory of that project.

Stage 1: Context detection for dependencies

Make it so when a package is interacted with it checks its file-system ancestors and determines whether it is in the build directory of another package. If it is then use the build directory and manifest for that package.

This will resolve the language server issues for Hex and git dependencies.

Stage 2: Workspaces

Permit the developer to specify that their packages are part of a workspace, which is a collection of packages that share one build directory + manifest. These packages can depend on each other, but they don't have to.

Workspaces have a root directory, and all the packages within the workspace have to be located within the directory. The build directory and the manifest.toml are located at the root of the directory.

This will resolve the wasted computation and Hex requests issues, and the issue of differing versions between dependencies.

Some commands could be run within a workspace directory, even if not in any of the directories of the contained packages:

• gleam build builds all packages.
• gleam check checks all packages.
• gleam clean
• gleam deps list
• gleam deps download
• gleam deps outdated
• gleam deps update
• gleam tree
• gleam new would create a new package but it would be preconfigured to be part of the workspace.
• gleam shell
• gleam update

Questions

1. Do we like the name "workspace"? Now is the time to bikeshed.
2. Can one specify dependencies at the workspace level? Or would it only be the contained packages that can have dependencies?
3. How would the developer configure their packages to create a workspace? Presumably something in the gleam.toml files of each package. Would the workspace itself have a gleam.toml? Let's look at other languages with a feature like this to see what they do. (Rust's cargo, what else?)

Future additions

Support for gleam run, gleam test, gleam docs build. The exact behaviour of these commands has yet to be designed or researched.

Prior discussions

• https://github.com/gleam-lang/gleam/discussions/3859