Modules & Crates Best Practices

How to Use This List

• Apply before splitting or merging crates in a workspace.
• Review public lib.rs exports each release.

A - Module Layout

• Keep main.rs thin; logic in lib.rs. Testable library core.
• Group by domain (auth, billing), not layer only. Find files by feature.
• Limit pub use reexports to curated prelude. Avoid export everything.
• Prefer crate:: paths in library code over deep super::. Refactor-safe.
• One module per file when file grows past ~300 lines. Split early.

B - Visibility

• Default private; escalate to pub deliberately. Smaller API surface.
• Use pub(crate) for internal cross-module API. Not world-visible.
• Constructors validate invariants; private fields. Encapsulation.
• Document #[non_exhaustive] on extensible public enums. Semver.
• Hide implementation modules; expose traits/types only. pub mod sparingly.

C - Workspaces & Crates

• Centralize dependency versions in [workspace.dependencies]. One lockfile truth.
• CI runs cargo test --workspace --all-features. Catch cfg gaps.
• Publish only intended crates; virtual workspace root not published. crates.io policy.
• Enforce dependency direction (domain has no axum/sqlx). Hexagonal boundaries.
• Feature flags documented in README and Cargo.toml comments.

D - Public API

• Semver and changelog for published crates. Breaking change discipline.
• missing_docs on public items. rustdoc completeness.
• Examples in examples/ compile on CI. cargo test --examples.
• MSRV in rust-version field. Consumer expectations.
• Avoid leaking pub paths to internal modules in docs. rustdoc #[doc(inline)] careful.

FAQs

Related

• Designing a Public API
• Workspaces
• Cargo Best Practices
• Unsafe Rust Best Practices

External Related Links

• The Cargo Book - Official guide and reference for Cargo.
• crates.io - Official crate registry.
• docs.rs - Automatic documentation hosting for every crate on crates.io.
• Rust for Rustaceans (Amazon) - Jon Gjengset.
• The Rust Programming Language, 2nd Edition (Amazon) - Steve Klabnik & Carol Nichols.

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.