Crate Boundaries and Workspace Layouts

How to decide what becomes a crate, how to arrange crates on disk, how to name them, and how to keep the dependency graph layered. Everything here is about structure; manifest keys are in manifest-and-inheritance.md, build speed in build-performance.md.

#Contents

• The unit of compilation
• Split or keep together
• Layout patterns
• Virtual manifest vs root package
• Naming
• Layering and the dependency graph
• Proc-macro crates
• -sys crates, build.rs and links
• The xtask pattern
• Tests, benches and examples
• Refactoring a monolith into a workspace
• Anti-patterns

#The unit of compilation

A crate is what rustc compiles in one invocation. That has consequences you cannot get around:

So a crate boundary is a performance tool and an API. Splitting along a line that the code crosses all the time gives you neither speed nor clarity.

#Split or keep together

Split when at least one of these is true:

1. Proc-macros. A proc-macro = true crate can export only procedural macros. Derives, attribute macros and function-like proc macros always need their own crate.
2. A crate is on the critical path of the build and cargo build --timings shows it compiling alone while cores sit idle. Splitting it into two halves that do not depend on each other lets them build in parallel.
3. A heavy dependency is only needed by part of the code (sqlx, tonic, wgpu, polars, candle). Put that part in its own crate so editing the rest does not drag the heavy part along, and so binaries that do not need it do not compile it.
4. An architectural rule must be enforced. The domain must not depend on HTTP or SQL: make domain a crate without those dependencies and the compiler enforces the rule forever.
5. Something is published separately (a client SDK, a macro crate, a -sys crate) or has a different release cadence or semver promise than the rest.
6. Several binaries share code. apps/server and apps/worker both depend on crates/core.
7. Different targets. A no_std or wasm-compatible core, platform-specific backends.
8. A build script or FFI. build.rs reruns only rebuild the crate that owns it; native linking (links) belongs in a -sys crate.

Keep together when:

• the pieces call each other in both directions (you would need a cycle or a trait for every call);
• the "crate" would be 200 lines with one consumer: a module is cheaper;
• splitting forces you into orphan-rule workarounds everywhere (newtypes around every foreign type);
• hot inner loops would cross the boundary and you do not want to sprinkle #[inline] or require LTO;
• you only want to "organise" code: modules and pub(crate) do that without manifests.

A rough shape that works for most services: 3-10 crates. Workspaces with 50+ crates exist (rust-analyzer, Bevy, Deno), but each crate there has a clear reason, and they invest in tooling to manage them.

#Layout patterns

#Flat crates/* (default)

myproj/
├── Cargo.toml          # [workspace] members = ["crates/*"]
├── Cargo.lock
└── crates/
    ├── myproj/         # facade / main library or binary
    ├── myproj-core/
    ├── myproj-macros/
    └── myproj-cli/

One glob covers every crate, the tree stays flat (no crates/a/crates/b), and finding a crate by name is trivial. rust-analyzer popularised this layout and argues for it in "Large Rust Workspaces": a flat list scales better than a hierarchy, because the hierarchy you choose today will be wrong tomorrow.

#apps/ + crates/ (or libs/)

platform/
├── Cargo.toml          # members = ["apps/*", "crates/*", "xtask"]
├── apps/
│   ├── api-server/     # bin, publish = false
│   ├── worker/         # bin, publish = false
│   └── admin-cli/      # bin, publish = false
├── crates/
│   ├── domain/
│   ├── storage/
│   ├── http-client/
│   └── test-support/   # publish = false, only in [dev-dependencies]
└── xtask/

Deployables are visible at a glance; libraries are reusable. Use default-members = ["apps/api-server"] if cargo run at the root should run the main app.

#Root package + helper members

serde-like/
├── Cargo.toml          # [package] name = "serde-like" + [workspace] members = ["derive"]
├── src/lib.rs          # pub use serde_like_derive::*;  (behind a "derive" feature)
└── derive/
    ├── Cargo.toml      # name = "serde-like-derive", proc-macro = true
    └── src/lib.rs

Good for one library with a companion macro crate: the main crate is at the repository root, cargo publish at the root publishes it, and the README sits next to its manifest.

#Separate workspaces under one repository

Use exclude (or simply a different directory outside members) plus a second Cargo.toml with its own [workspace] when the part:

• needs a different toolchain (nightly-only fuzz/ targets for cargo-fuzz, embedded firmware with build-std);
• needs incompatible dependency versions or features that would pollute unification;
• is an example meant to be copied by users as a standalone project.

[workspace]
members = ["crates/*"]
exclude = ["fuzz", "examples/standalone-app"]

exclude takes paths (prefixes), not globs.

#Virtual manifest vs root package

A virtual manifest cannot have [dependencies], [features], [lib], [[bin]] or [lints] (use [workspace.lints]): those belong to a package. manifest_lint flags them as CW019.

#Naming

• Prefix every crate with the project (shop-domain, shop-infra). crates.io is a single global namespace; a name like core-utils will clash or confuse. Internal-only crates benefit too: use shop_domain:: reads unambiguously in code reviews.
• Folder name = crate name. crates/shop-domain/Cargo.toml contains name = "shop-domain". It keeps the glob, cargo -p shop-domain, and the file tree in sync.
• Hyphens in Cargo, underscores in Rust. shop-domain is imported as shop_domain. Pick one style for crate names and stick to it (hyphens are the common convention).
• Suffix conventions readers recognise: -macros / -derive (proc-macro), -sys (raw FFI bindings and native linking), -core (no-IO core), -cli (binary), -test-support or -testing (fixtures), xtask (build automation).
• Library and binary names can be overridden ([lib] name = "...", [[bin]] name = "shop"), which helps when the package name is long but the binary should be short.

#Layering and the dependency graph

A layered workspace has edges in one direction only. A common service shape (ports and adapters):

 layer 3  apps/shop-server  ── depends on ──► shop-infra, shop-app
 layer 2  shop-infra        ── depends on ──► shop-app, shop-domain    (sqlx, reqwest, tokio)
 layer 1  shop-app          ── depends on ──► shop-domain               (use cases, port traits)
 layer 0  shop-domain                                                   (types, rules; no IO)

Rules that keep it that way:

1. Lower layers define traits, upper layers implement them. shop-app defines trait OrderRepo; shop-infra implements it for Postgres; the binary wires them together. The domain never imports the database crate.
2. Shared types sink. When two crates both need OrderId, it moves down into the lowest crate that both depend on, not sideways into one of them.
3. No cycles, not even through dev-dependencies if you can avoid it. Cargo allows a dev-dependency cycle (a tests use b, b depends on a), but it compiles a twice (once as the library, once for the test) and types from the two copies do not match, which yields baffling "expected a::Foo, found a::Foo" errors. Put shared test fixtures in a test-support crate at the bottom instead.
4. Binaries are leaves. Nothing depends on an apps/* crate. If code in a binary is needed elsewhere, move it into a library crate.
5. Fan-in at the bottom is fine; fan-out at the bottom is a smell. A low-layer crate that depends on many crates will rebuild often and rebuild everything above it.

Print the graph with /tmp/crate_graph .; layer numbers are the longest path to a crate with no internal dependencies. Crates in or above a cycle get no layer and the cycle is listed (CW011). cargo tree --workspace -e normal --depth 1 and cargo depgraph (third-party) show the same from Cargo's point of view when a toolchain is available.

#Breaking a cycle

// Before: shop-core needs storage::save(), shop-storage needs core::Order -> cycle.

// After: core defines the port...
// crates/shop-core/src/lib.rs
pub struct Order { pub id: u64 }
pub trait OrderStore {
    fn save(&self, order: &Order) -> Result<(), StoreError>;
}
#[derive(Debug)]
pub struct StoreError;

// ...storage implements it (storage -> core, never core -> storage)
// crates/shop-storage/src/lib.rs
pub struct PgStore;
impl shop_core::OrderStore for PgStore {
    fn save(&self, _order: &shop_core::Order) -> Result<(), shop_core::StoreError> { Ok(()) }
}

#Proc-macro crates

• A proc-macro crate ([lib] proc-macro = true) runs inside the compiler and can only export procedural macros, so any runtime types, traits or helper functions the generated code refers to live in the "main" crate.
• Standard pairing: foo (runtime) re-exports foo-macros; generated code refers to ::foo::... paths so users only depend on foo.

# crates/foo/Cargo.toml
[features]
derive = ["dep:foo-macros"]
[dependencies]
foo-macros = { workspace = true, optional = true }

// crates/foo/src/lib.rs
#[cfg(feature = "derive")]
pub use foo_macros::Builder;

• Proc-macros are compiled for the host. With resolver 2+, features enabled on their dependencies (syn, quote, proc-macro2) do not leak into the target build, and vice versa.
• syn with features = ["full"] is one of the slowest dependencies in many trees. Keep macro crates small, enable only the syn features needed (derive, parsing, printing, clone-impls, proc-macro are the defaults; full only if you parse arbitrary items or expressions), and avoid having many macro crates each pulling a different syn major.
• A proc-macro crate cannot be used by the crate that defines it; integration-test macros from a separate crate or from tests/ of the macro crate (with trybuild for compile-fail tests).

#-sys crates, build.rs and links

• A foo-sys crate contains raw FFI declarations plus the build.rs that finds or builds the native library, and sets links = "foo" in [package]. Only one package in the whole dependency graph may declare a given links value, which is why two semver-incompatible versions of the same -sys crate cannot coexist.
• A safe wrapper foo depends on foo-sys. Users depend on foo.
• Keep build scripts in the smallest possible crate: any change that triggers a build script rerun rebuilds that crate and its dependents. Emit precise cargo::rerun-if-changed=PATH lines (the cargo:: form needs Cargo 1.77; cargo:rerun-if-changed works everywhere). Without any rerun-if line the script reruns when any file in the package changes.
• Build-script dependencies go in [build-dependencies]. With resolver 2+ their features are resolved separately from normal dependencies.
• Code generation (protobuf, bindgen, sqlx offline data) can run either in build.rs (always fresh, slower builds, needs the generator on every machine) or in cargo xtask codegen with the generated files committed (fast builds, reviewable diffs, CI checks freshness). The second scales better in big workspaces.

#The xtask pattern

Build automation written in Rust, run with cargo xtask <task>, no make/just/npm required:

xtask/
├── Cargo.toml   # name = "xtask", publish = false
└── src/main.rs

# .cargo/config.toml
[alias]
xtask = "run --package xtask --"

// xtask/src/main.rs
use std::process::{Command, ExitCode};

fn main() -> ExitCode {
    let task = std::env::args().nth(1);
    let ok = match task.as_deref() {
        Some("ci") => run("cargo", &["clippy", "--workspace", "--all-targets", "--locked", "--", "-D", "warnings"])
            && run("cargo", &["test", "--workspace", "--locked"]),
        Some("codegen") => run("cargo", &["run", "-p", "shop-codegen"]),
        _ => {
            eprintln!("usage: cargo xtask <ci|codegen>");
            false
        }
    };
    if ok { ExitCode::SUCCESS } else { ExitCode::FAILURE }
}

fn run(cmd: &str, args: &[&str]) -> bool {
    Command::new(cmd).args(args).status().is_ok_and(|s| s.success())
}

Guidelines: keep xtask dependencies light (it is compiled on first use), make it a member so it shares the lock file and target directory, publish = false, and exclude it from default-members so cargo build does not build it. Typical tasks: codegen, dist (build release artefacts), ci (the same steps CI runs), bench, install-hooks, release.

#Tests, benches and examples

Each tests/*.rs file links its own binary; 40 files in a crate that links tokio and sqlx can spend more time linking than testing. Consolidating into one tests/it/ binary is one of the cheapest build-time wins.

#Refactoring a monolith into a workspace

1. Turn the existing crate into a member: move it to crates/<name>/ (or keep it as the root package first).
2. Add the virtual root manifest with resolver, [workspace.package], [workspace.dependencies]; move profiles and [patch] to the root; keep the single Cargo.lock at the root.
3. Extract leaf modules first (types with no internal dependencies): they become -core/domain. Fix visibility (pub(crate) items used across the new boundary become pub, ideally behind a narrower API).
4. Re-export from the original crate (pub use shop_domain::*;) so downstream code keeps compiling while you migrate imports.
5. Move heavy-dependency modules into adapter crates; replace direct calls from lower layers with traits.
6. Run /tmp/manifest_lint . --strict, /tmp/dep_audit . --strict and /tmp/crate_graph . after each step; run cargo build --timings before and after to confirm the split helped.

#Anti-patterns

• One crate per module ("crate soup"). 80 tiny crates that all depend on each other: no parallelism, more metadata, more manifests, endless version bumps.
• utils / common dumping ground. Everything depends on it and it depends on everything heavy, so every change rebuilds the world. Split by concern (shop-ids, shop-time) or push items to their users.
• Binaries with logic. main.rs of 3,000 lines that tests cannot reach. Keep main thin; move logic to a library crate.
• Domain depends on infra (domain uses sqlx::FromRow or axum types). The boundary exists on paper only.
• Mixed editions and copy-pasted metadata in every member instead of [workspace.package].
• Nested workspaces by accident (a member with its own [workspace] table): Cargo errors about multiple workspace roots; remove the inner [workspace] or exclude the directory.