Skip to main content

FAQ

General

Where did the name "proto" come from?

We wanted to keep with the space theme, and spent quite some time digging through Wikipedia and ultimately landed on the page for protostar (this is why our logo's a star). We really liked the definition of protostar, as it basically means "the beginning phase of a star". Even the the prefix proto means "first" or "earliest form of".

This was great as that's the impression we had in mind for our tool. proto is the first piece required for setting up your developer environment. The toolchain is the first layer in the foundation.

From an aesthetic standpoint, proto's typography works well with moon and moonbase, as most of the letters are circle shaped. Double points for proto having two o's like the other products!

Are you worried about confusion with other tools like protobufs?

Nah.

What is a tool?

A tool in the context of proto is either a language, dependency/package manager (typically for a language), or third-party CLI. The tool is something that can be downloaded and installed by version onto a machine.

Furthermore, a tool should have a primary executable file that can be executed with proto run or through proto's shims. Additionally, a tool can also provide secondary executable files. For example, npm (the primary) also provides npx and node-gyp (secondaries).

What is a plugin?

A plugin is a WASM (or TOML) file for a tool.

The terms tool and plugin are often used interchangeably, but plugin primarily refers to the WASM portion of a tool, while tool refers to the entire package: metadata, business logic, branding, so on an so forth.

Will you support more languages?

Yes! We'd love to support as many as possible, and if you'd like to help, join our Discord community! Feel free to create a plugin in the mean time.

Will you support other kinds of tools?

No, we will only support languages, dependency managers, and CLIs, which should be enough. However, you can create a plugin to support other kinds of tools.

Will you support "build from source"?

In the future we have plans to support building from source. For the time being, proto is built around pre-built archives for easier portability.

How can I install a global package for a language?

You can install a global with the proto install-global command. Most languages install a global to a shared location regardless of the language's version (Deno is ~/.deno/bin, Rust is ~/.cargo/bin, etc), so globals can also be installed outside of proto using language specific commands.

The exception to this is Node.js (and npm, pnpm, yarn). Each of these tools install global packages differently, and some are tied to the parent tools version. So if you install a new language version, you lose your global packages. We suggest using proto install-global for all Node.js packages, which installs everything to a shared location, ~/.proto/tools/node/globals/bin. You'll also need to manually add these global directories to your PATH.

However, if you'd prefer to use the native non-proto workflow, you can disable the globals intercept using the tools.node.intercept-globals setting.

How to run a canary release after installing it?

Once a tool has been installed with --canary, the canary version can be explicitly referenced using our version detection rules. The easiest approach is to prefix the shim with an environment variable:

$ PROTO_BUN_VERSION=canary bun ./index.ts

Or to explicitly configure the version in .prototools:

bun = "canary"

OS is unable to find an installed binary, how to resolve?

To start, ensure that proto's shim and binary directories are listed first on PATH, and takes precedence over other binaries of the same name that may collide.

Secondly, proto is powered through shims, which means on Windows, we do not provide .exe binaries (for shims), and instead use .cmd. If you're attempting to run a script that uses a hard-coded binary name like node.exe, you'll need to do one of the following:

  • Remove the trailing .exe and simply run node instead. Windows will use the PATHEXT environment variable to find the appropriate extension, which includes .cmd by default.
  • Ensure ~/.proto/bin is in your PATH. If a shim cannot be found, the original binary will be used instead.

Troubleshooting

Network requests keep failing, how can I bypass?

When a tool is executed, we validate the version to ensure it's correct. We achieve this by making network requests to a remote service to gather the list of valid versions. If you're having network issues, or the request is timing out, you can bypass these checks with the following:

  • Pass a fully-qualified version as an environment variable. The version must be installed for this to work.

    PROTO_NODE_VERSION=20.0.0 node --version

    If executing a Node.js package manager, you'll need to set versions for both Node.js and the manager. This is required since manager's execute node processes under the hood.

    PROTO_NODE_VERSION=20.0.0 PROTO_NPM_VERSION=10.0.0 npm --version
  • Pass the PROTO_BYPASS_VERSION_CHECK environment variable. This will bypass the network request to load versions, but does not bypass other requests. However, this is typically enough.

    PROTO_BYPASS_VERSION_CHECK=1 node --version