Rust Modules & Crates Practice: mod, use, pub, Crate Structure

People confuse these constantly. Here is the hierarchy:

A package is what you cargo new. A crate is what the compiler builds. A module is how you organize code inside a crate.

The most common module mistake is trying to use a module you never declared:

// WRONG: using without declaring
// use crate::utils::helper; // error[E0432]: unresolved import

// RIGHT: declare the module first
mod utils;  // tells Rust to look for src/utils.rs
use crate::utils::helper;

Without mod utils;, the compiler has no idea utils exists. The mod declaration is what makes Rust load the file.

Making the module pub does not make its contents public. Visibility is per-item:

// In lib.rs
pub mod utils;  // module is public

// In utils.rs
fn helper() { }  // WRONG: function is private — error[E0603]

pub fn helper() { }  // RIGHT: function is also public

A public module can contain entirely private items. You must mark each item that should be accessible. Struct field visibility follows the same rules -- see structs and enums for the pub field pattern.

Rust cannot find the file matching your mod declaration:

// src/lib.rs
mod utils;  // error[E0583] if neither src/utils.rs nor src/utils/mod.rs exists

Check: file name must exactly match the module name, and it must be in the right directory relative to the parent module's location.

When you write mod utils;, Rust looks for:

• src/utils.rs (modern style, preferred)
• src/utils/mod.rs (older style, still works)

If utils has submodules, use the directory approach:

// src/lib.rs
mod network;

// src/network.rs (or src/network/mod.rs)
pub mod client;
pub mod server;

// src/network/client.rs
pub fn connect() { }

The modern style is network.rs with a network/ directory for submodules. Since Rust 2018, foo.rs and a foo/ directory can coexist, so mod.rs is no longer required.

If your package has both src/main.rs and src/lib.rs, Cargo builds two separate crates — a binary and a library — each with its own module tree:

// src/lib.rs
pub mod config;  // only visible to the library crate's tree

// src/main.rs
// WRONG: main.rs can't see lib.rs modules directly
// use config::Settings;  // error[E0432]

// RIGHT: main.rs must use the library crate by its package name
use my_package::config::Settings;

This is why "I declared it in lib.rs but main.rs can't see it" happens. The binary crate depends on the library crate like any external dependency.

// From src/network/client.rs
use crate::config::Settings;     // absolute: starts at crate root
use super::server::listen;       // relative: goes up to network, then into server
use self::helpers::parse_url;    // explicit current module (rarely needed)

Since Rust 2018, extern crate is no longer needed in most cases — the compiler resolves crate names automatically from Cargo.toml dependencies. The Facade design pattern applies naturally here: re-export a simplified API from your crate root while hiding complex internal module structure.

pub fn public_api() { }                          // visible to everyone
pub(crate) fn internal_only() { }                // crate-wide, hidden from dependents
pub(super) fn parent_only() { }                  // parent module only
pub(in crate::network) fn network_only() { }     // visible within crate::network subtree
fn private_helper() { }                          // current module only

The Privacy Rule Beginners Miss

Items are private by default. Child modules can access private items of their ancestor modules, but parents cannot access private items of children. The testing guide shows how #[cfg(test)] mod tests uses this rule to test private functions from a child module:

mod parent {
    fn secret() { }

    mod child {
        fn peek() {
            super::secret();  // OK: child can see parent's private items
        }
    }

    fn try_peek() {
        // child::peek();  // ERROR: parent can't see child's private items
    }
}

Keep internal modules private and re-export the public API from lib.rs:

// src/lib.rs — clean public API
mod internal;
mod config;
pub use internal::Config;     // users write my_crate::Config
pub use config::Settings;     // users write my_crate::Settings

The Prelude Pattern

For crates with many public types, create a prelude module:

// src/prelude.rs
pub use crate::Config;
pub use crate::Error;
pub use crate::Result;

// Users can do:
// use my_crate::prelude::*;

• The Rust Book: Modules — packages, crates, modules, paths
• Rust By Example: Modules — practical module examples
• Rust Reference: Visibility — pub, pub(crate), pub(in path) rules
• Rust Reference: Items and Modules — module file lookup, inline modules