Docs menu

Rust on Primcloud

How Primcloud detects a Rust app, builds its binaries and frontend, and works out its process types.

On this page

Detection#

Primcloud builds your app as Rust when the root of your repo has a Cargo.toml. A crate with no binary, like a library, fails with "no binary target".

One language per app. Rust takes precedence over Bun and Node.js, so a repo with a Cargo.toml and a package.json is a Rust app with a frontend; see Frontend assets. That includes a JavaScript project that keeps a native addon's Cargo.toml at its root: move the crate into a subdirectory to keep it a JavaScript app. Every other language takes precedence over Rust: a repo that also has a go.mod, a composer.json, a requirements.txt, or another language's manifest at the root builds as that language.

The build#

The build installs the Rust toolchain named by rust-toolchain or rust-toolchain.toml, or the latest stable release; see Runtime versions. It then runs:

Terminal
cargo build --release --workspace --bins

--locked is added when your repo has a Cargo.lock, so the build fails rather than resolve different dependency versions from the ones you committed. Cargo downloads your dependencies as part of this step.

--workspace --bins compiles every binary target of every workspace member. A single package is its own workspace, so the same command covers both shapes, and a virtual workspace needs no root package.

Each compiled binary is installed on PATH under its target name. A binary whose required-features aren't enabled isn't built by Cargo; the build log lists it as skipped and it gets no process. If no binary is built at all, the build fails.

Your Cargo configuration is honored: [profile.release] settings in Cargo.toml, a .cargo/config.toml in the repo, and build.rs scripts all behave as they do locally. Your secrets are visible to Cargo during the build.

The toolchain, your downloaded dependencies, and compiled crates are reused from the previous build. Only what changed is recompiled: a crate in your repo with a changed file, and everything that depends on it.

Frontend assets#

A Rust app with a package.json at the root gets its frontend built before cargo build runs. The lockfile you commit picks the tool:

Lockfile Frontend build
package-lock.json, yarn.lock, or pnpm-lock.yaml Node.js is installed, dependencies are installed with npm, Yarn, or pnpm, and your package.json build scripts run. See Node.js package managers.
bun.lock or bun.lockb Bun is installed, dependencies are installed with bun install --frozen-lockfile, and your package.json build scripts run with Bun. See Bun package managers.

The build scripts are heroku-prebuild, then heroku-build or else build, then heroku-postbuild, whichever of them package.json defines.

Files the frontend build writes into your repo tree (a dist/ directory, say) ship with the app beside your source. Your binary starts in the app root, so it can serve them by relative path. Because the frontend is built first, it's also on disk when Cargo runs, for crates that embed assets at compile time.

Without a Procfile, the Rust binary is the web process. A start script in package.json doesn't take over.

Commit the lockfile for the tool you use. A package.json with no npm, Yarn, or pnpm lockfile, and nothing that marks it as a Bun project, gets no dependencies installed and no build scripts run.

Process types#

A Procfile decides your processes; see Formations. Without one, every binary becomes a process type that runs it, named after the binary. A binary named web is your web process; otherwise the first binary also runs as web, so your app always has one.

Port. Your web process must listen on $PORT (5000) on 0.0.0.0. Nothing passes the port to your binary, so read it in your code:

let port = std::env::var("PORT").expect("$PORT must be set");
let listener = std::net::TcpListener::bind(format!("0.0.0.0:{port}")).expect("bind to $PORT");

Other process types don't get a PORT.

Environment. No Rust-specific variables are set; your processes get PORT on web and your secrets. Your running app has your binaries and your repo's files, not the Rust toolchain.