Rust Module Organization & Public API Design

Guide Rust library module organization and public API design with cargo-public-api.

115|8|Updated Mar 30, 2025
One-click install
npx skills add https://github.com/Goldziher/spikard --skill rust-module-organization-public-api-design
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: Rust Module Organization & Public API Design
Source: https://github.com/Goldziher/spikard/tree/main/.ai-rulez/skills/rust-module-organization-public-api-design
Command: npx skills add https://github.com/Goldziher/spikard --skill rust-module-organization-public-api-design

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill addresses the challenge of organizing Rust code effectively, ensuring a clear separation between internal implementation details and the public API, which is crucial for maintainability and preventing breaking changes.

Core Features & Use Cases

  • Module Structure: Guides on organizing code into logical modules based on features and domain.
  • Public API Definition: Best practices for defining a stable and user-friendly public API through re-exports in lib.rs.
  • Visibility Control: Explains the use of pub, pub(crate), and pub(super) for precise control over item visibility.
  • Feature Gates: Demonstrates how to use Cargo features to conditionally expose API elements.
  • API Validation: Introduces cargo-public-api for tracking and preventing breaking changes.
  • Use Case: A Rust library maintainer needs to refactor their codebase to ensure a clean public API and prevent accidental exposure of internal implementation details, while also preparing for future feature additions.

Quick Start

Apply the principles of Rust module organization and public API design to structure your library's codebase for clarity and stability.

Frequently Asked Questions about Rust Module Organization & Public API Design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I structure Rust modules for a library?

Structure Rust modules by grouping code into logical directories based on domain and features, then control visibility using `pub`, `pub(crate)`, and `pub(super)` keywords to separate internal details from the public API.

What's the best way to define a public API in Rust?

The best way to define a public API in Rust is by using re-export patterns in your `lib.rs` file, which aggregates exposed items from internal modules into a single stable interface for library consumers.

How do I conditionally expose API elements in Cargo?

You can conditionally expose API elements in Cargo by using feature gates, which allow you to compile specific code paths and modules only when certain Cargo features are explicitly enabled by the user.

How does cargo-public-api prevent breaking changes?

The `cargo-public-api` tool prevents breaking changes by tracking your library's exposed API surface and validating it against previous versions to ensure no unintended modifications or removals occur during refactoring.

When should I use pub(crate) instead of pub in Rust?

Use `pub(crate)` instead of `pub` in Rust when an item needs to be accessible across multiple modules within the same crate but must remain hidden from external users, preventing accidental API exposure.

How do I document a Rust public API effectively?

Document a Rust public API effectively by applying best practices alongside module organization principles, ensuring re-exported items in `lib.rs` have clear documentation that explains their intended usage and stability.