Rust Modules, Packages, Crates and Workspaces: Complete Project Structure Guide

Rust Learning Path — Chapter 16. Once a Rust program grows beyond a few files, good project structure becomes essential. Rust gives you several related building blocks—modules, crates, packages, and workspaces—that help you organize code without sacrificing compile-time safety.

This chapter explains how those pieces fit together, how visibility works with pub, how use paths simplify imports, how to split code across files, and when a Cargo workspace is the right choice.

1. The terminology first#

2. Binary and library crates#

A project created with cargo new my_app normally starts as a binary crate because Cargo creates src/main.rs.

A library project can be created with:

That creates src/lib.rs. A package may contain both library and binary targets, which is common for real applications: shared business logic stays in the library while the executable only handles startup and wiring.

3. Create modules with mod#

Suppose an application has configuration and API logic:

Then create src/config.rs:

And src/api.rs:

4. Visibility and pub#

Rust items are private to their parent module by default. Use pub only where another module really needs access.

Here User and id are public, while email remains private. This lets a module protect its own invariants instead of exposing every field.

5. Absolute and relative module paths#

You can refer to an item using a path from the crate root:

Or with a relative path such as super:: when moving to a parent module:

For application code, clear absolute paths from crate:: are often easier to understand as the codebase grows.

6. Nested modules and directories#

A larger API module might look like:

src/api.rs declares the submodules:

This is a good pattern when one logical module needs several source files.

7. Re-export a clean public API#

Re-exporting lets callers use a shorter, more stable path:

Consumers can now write:

instead of depending on the internal module layout.

8. Multiple binaries#

A package can expose several executables under src/bin:

Run them with:

This is useful when an application has an HTTP server and a background worker sharing the same library.

9. Cargo workspaces#

When several related packages should be developed together, use a workspace:

Workspace root:

Now Cargo can build or test all members together:

10. Workspace dependencies#

Shared dependency versions can be declared centrally:

Then a member package can inherit them:

11. Suggested backend layout#

The exact folder names matter less than keeping responsibilities clear and dependencies flowing in sensible directions.

12. Common mistakes#

• Making everything pub just to silence visibility errors.
• Creating dozens of tiny modules before the code actually needs them.
• Putting all logic in main.rs .
• Using a workspace for a project that only needs one package.
• Exposing internal modules instead of re-exporting a small public API.

13. Mini lab: split an application#

Create a project and refactor it into three modules:

Create config, service, and output modules. Keep fields private where possible, expose only necessary functions, and verify with:

Key takeaways#

• Modules organize names inside a crate.
• Crates are compilation units.
• A Cargo package contains crate targets.
• Workspaces group related packages and share build artifacts.
• Keep APIs intentionally small with privacy and re-exports.