managing-cargo-dependencies

Cargo.toml dependency management patterns for HASH workspace. Use when adding dependencies, managing workspace dependencies, organizing Cargo.toml sections, setting version pinning, configuring default features, or working with public dependencies.

⭐1.4kstars🔀107forks📁View on GitHub🕐Updated Nov 26, 2025⬇️2downloads

When & Why to Use This Skill

This Claude skill provides a standardized framework for managing Cargo.toml dependencies within a Rust workspace. It enforces strict organizational patterns, version pinning strategies, and feature flag configurations to ensure codebase consistency, maintainability, and build efficiency.

Use Cases

  • 1. Workspace Dependency Integration: Streamlining the addition of external crates to the workspace root using standardized caret versioning and optimized feature settings.
  • 2. Cargo.toml Structural Organization: Automatically organizing package-level dependencies into the mandatory four-section pattern (Public/Private and Workspace/Third-party) for maximum readability.
  • 3. Public API Visibility Management: Ensuring that dependencies exposed in a library's public API are correctly configured with the 'public = true' attribute to prevent compilation errors.
  • 4. Dependency Auditing and Maintenance: Providing a consistent workflow for updating or removing crates across a complex multi-package workspace while adhering to project-specific best practices.
namemanaging-cargo-dependencies
descriptionCargo.toml dependency management patterns for HASH workspace. Use when adding, updating, or removing dependencies, organizing Cargo.toml sections, configuring version pinning and default features, or managing public dependencies.
licenseAGPL-3.0
typedomain
enforcementsuggest
priorityhigh

Cargo Dependencies Management

Guidance for adding and managing dependencies in Cargo.toml files within the HASH repository's workspace structure.

Core Principles

HASH uses a strict workspace dependency pattern:

✅ DO:

  • Add external dependencies to workspace root [workspace.dependencies]
  • Use caret version specifiers (e.g., version = "1.0.0" = ^1.0.0)
  • Set default-features = false for all dependencies unless specifically needed
  • Use workspace = true in package Cargo.toml
  • Organize dependencies into 4 sections with comment headers
  • Use public = true for dependencies exposed in public API
  • Align dependency names using spaces for readability

❌ DON'T:

  • Add version numbers directly in package Cargo.toml
  • Use exact versions with = prefix (e.g., =1.0.0) in workspace root
  • Enable default-features without considering impact
  • Mix different dependency types without section comments
  • Forget public = true for dependencies exposed in public API

Quick Reference

The 4-Section Pattern

Every package Cargo.toml must organize dependencies into these sections:

[dependencies]
# Public workspace dependencies
hash-graph-types = { workspace = true, public = true }
hashql-core      = { workspace = true, public = true }

# Public third-party dependencies
serde     = { workspace = true, public = true, features = ["derive"] }
tokio     = { workspace = true, public = true }

# Private workspace dependencies
error-stack = { workspace = true }
hash-codec  = { workspace = true }

# Private third-party dependencies
tracing     = { workspace = true }
regex       = { workspace = true }

Keep all 4 section comments even if a section is empty.

Quick Add Process

  1. Check workspace root - Is dependency already there?
  2. Add to workspace if needed - With caret version 1.2.3
  3. Determine section - Public workspace/third-party or private?
  4. Add to package - Use workspace = true (+ public = true if needed)

Detailed Guides

Choose the guide that matches the task:

workspace-setup.md

Use when: Adding new dependencies to workspace root

  • How to add external crates to workspace
  • Version pinning with exact versions
  • Default features configuration
  • Workspace member paths

package-dependencies.md

Use when: Adding dependencies to a package Cargo.toml

  • The 4-section organizational structure
  • Public vs private dependencies
  • When to use public = true
  • Alignment and formatting rules
  • Feature configuration

examples-reference.md

Use when: Looking for real examples from HASH codebase

  • Complete examples from @local/codec
  • Complete examples from @local/hashql/core
  • Optional dependencies pattern
  • dev-dependencies structure

Common Patterns

Adding a New External Dependency

# 1. Add to workspace root Cargo.toml
[workspace.dependencies]
my-crate = { version = "1.2.3", default-features = false }

# 2. Add to package Cargo.toml (appropriate section)
[dependencies]
# Private third-party dependencies
my-crate = { workspace = true }

Making a Dependency Public

# Use when the dependency appears in your public API
serde = { workspace = true, public = true, features = ["derive"] }
tokio = { workspace = true, public = true }

Optional Dependencies

[dependencies]
serde = { workspace = true, optional = true, features = ["derive"] }

[features]
serde = ["dep:serde", "other-dep/serde"]

References