Visibility and the `pub` Keyword

21 min read

In JavaScript and TypeScript modules, nothing leaves a file unless you export it — and once exported, it is fully public to anyone who imports it. Rust takes the same “private by default” stance but gives you a far richer dial: pub, pub(crate), pub(super), and pub(in path) let you say exactly how far an item is allowed to travel. This page is about that dial.

Quick Overview

Every item in Rust — functions, structs, enums, modules, constants, and even individual struct fields — is private by default, visible only within the module that defines it (and that module’s children). You opt items into wider visibility with the pub keyword and its restricted variants. For a TypeScript/JavaScript developer the mental model is: Rust’s pub is like export, but Rust adds a graduated scale between “totally private” and “totally public” that JavaScript modules simply do not have.

Note: This page focuses on visibility — who is allowed to see an item. How items are organized into modules is covered in modules.md, how you name paths to reach them in module-tree.md, and how you bring them into scope with use (including re-exporting with pub use) in use-keyword.md.

TypeScript/JavaScript Example

In an ES module, a declaration is private to its file until you export it. There is no in-between: an exported symbol is reachable by any file that imports it, whether that file lives in the same folder, the same package, or a completely different npm package that depends on yours.

1
// Private to this file — no `export`, so nobody outside can see it.
2
function internalTaxRate(): number {
3
  return 0.08;
4
}
5

6
// Exported — now PUBLIC to every importer, in this package or another.
7
export function totalWithTax(amount: number): number {
8
  return amount + amount * internalTaxRate();
9
}
10

11
// A class whose fields are public unless marked `private`/`#`.
12
export class User {
13
  id: number;
14
  name: string;
15
  #email: string; // truly private (ES `#` field)
16

17
  constructor(id: number, name: string, email: string) {
18
    this.id = id;
19
    this.name = name;
20
    this.#email = email;
21
  }
22

23
  get email(): string {
24
    return this.#email;
25
  }
26
}

1
import { totalWithTax, User } from "./billing";
2

3
console.log(totalWithTax(100)); // 108
4
// internalTaxRate();           // not exported, not importable
5

6
const user = new User(1, "Ada", "ada@example.com");
7
user.name = "Ada Lovelace"; // public field, freely writable
8
// user.#email;             // SyntaxError: private field outside class

TypeScript’s private/protected keywords add compile-time field access control, but they are erased at runtime — nothing stops a (user as any).email cast. The ES # prefix is the only runtime-enforced privacy. The key point for the comparison: at the module level, JavaScript offers a binary switch — exported or not.

Rust Equivalent

1
mod billing {
2
    // Private by default — visible only inside `billing`.
3
    fn internal_tax_rate() -> f64 {
4
        0.08
5
    }
6

7
    // `pub` exposes this to the parent module (the crate root, here).
8
    pub fn total_with_tax(amount: f64) -> f64 {
9
        amount + amount * internal_tax_rate()
10
    }
11
}
12

13
mod model {
14
    #[derive(Debug)]
15
    pub struct User {
16
        pub id: u64,      // public field
17
        pub name: String, // public field
18
        email: String,    // private field — protected by the type's methods
19
    }
20

21
    impl User {
22
        pub fn new(id: u64, name: &str, email: &str) -> Self {
23
            User {
24
                id,
25
                name: name.to_string(),
26
                email: email.to_string(),
27
            }
28
        }
29

30
        pub fn email(&self) -> &str {
31
            &self.email
32
        }
33
    }
34
}
35

36
fn main() {
37
    let total = billing::total_with_tax(100.0);
38
    println!("Total: {total}");
39

40
    let mut user = model::User::new(1, "Ada", "ada@example.com");
41
    user.name = "Ada Lovelace".to_string(); // public field, writable
42
    println!("id={}, name={}", user.id, user.name);
43
    println!("email={}", user.email()); // private field, via getter
44
}

Real output:

1
Total: 108
2
id=1, name=Ada Lovelace
3
email=ada@example.com

Notice the new dimension compared to JavaScript: pub is applied per field, not just per type. A pub struct can still hide some of its data, which is the foundation of encapsulation in Rust.

Detailed Explanation

Private by default, like an un-`export`ed declaration

When you write a plain fn, struct, enum, const, static, trait, or mod with no visibility keyword, it is private. “Private” in Rust means: visible inside the defining module and any of that module’s descendant modules, but invisible to the parent module and to siblings.

1
mod billing {
2
    fn internal_tax_rate() -> f64 { 0.08 } // private to `billing`
3
}
4

5
fn main() {
6
    let r = billing::internal_tax_rate(); // does not compile (error[E0603]: private function)
7
    println!("{r}");
8
}

The real compiler error:

1
error[E0603]: function `internal_tax_rate` is private
2
 --> src/main.rs:8:22
3
  |
4
8 |     let r = billing::internal_tax_rate();
5
  |                      ^^^^^^^^^^^^^^^^^ private function
6
  |
7
note: the function `internal_tax_rate` is defined here
8
 --> src/main.rs:2:5
9
  |
10
2 |     fn internal_tax_rate() -> f64 {
11
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Note: A subtle but important asymmetry — child modules can always see into their parents’ private items, but parents cannot see into their children’s private items. Privacy in Rust flows outward: you publish to ancestors, you never hide from descendants. This is the opposite of how many object systems think about “private.”

`pub` — export to the parent (and beyond)

Adding pub makes an item visible to the module that contains it. That is the literal meaning of pub — and it is why a pub item in a module that is itself private is still not reachable from far away: visibility composes along the whole path. The general rule:

An item is reachable from some location only if every segment of the path to it — each enclosing module and the item itself — is visible from that location.

So to expose billing::total_with_tax to code outside your crate, both total_with_tax and the billing module would need to be pub (pub mod billing).

Field visibility: the part JavaScript modules don’t have

In TypeScript, marking a class public exports the class; field-level privacy is a separate, class-scoped feature (private, #). In Rust, fields have their own visibility, independent of the struct’s:

1
pub struct User {
2
    pub id: u64,   // anyone who can see `User` can read/write this
3
    email: String, // only code in this module can touch it
4
}

A field with no pub is private even when the struct is pub. Reading it from outside is an error[E0616]:

1
error[E0616]: field `email` of struct `User` is private
2
  --> src/main.rs:16:25
3
   |
4
16 |     println!("{}", user.email);
5
   |                         ^^^^^ private field

And — a detail that surprises newcomers — if a struct has any private field, you cannot build it with a struct literal from outside the module at all, even if you only set the public fields:

1
mod model {
2
    pub struct User {
3
        pub id: u64,
4
        email: String, // private
5
    }
6
}
7

8
fn main() {
9
    let user = model::User {
10
        id: 1,
11
        email: "ada@example.com".to_string(), // does not compile (error[E0451])
12
    };
13
    println!("{}", user.id);
14
}

1
error[E0451]: field `email` of struct `User` is private
2
  --> src/main.rs:12:9
3
   |
4
10 |     let user = model::User {
5
   |                ----------- in this type
6
11 |         id: 1,
7
12 |         email: "ada@example.com".to_string(),
8
   |         ^^^^^ private field

This is intentional and powerful: by hiding even one field, the type forces outside callers through a constructor (User::new), which is how Rust guarantees invariants — the equivalent of a TypeScript class that hides its backing fields behind a constructor and getters, but enforced at compile time across the whole crate boundary.

The graduated scale: `pub(crate)`, `pub(super)`, `pub(in path)`

This is where Rust goes beyond export. Between “private” and “fully public” sit three restricted forms:

Form	Reachable from…
`pub`	Everywhere the path is visible — including other crates
`pub(crate)`	Anywhere in this crate, but never from a crate that depends on yours
`pub(super)`	The parent module and everything nested under that parent
`pub(in some::path)`	Only within the named ancestor module (and its descendants)

1
mod network {
2
    // Visible anywhere in THIS crate, but NOT to external crates.
3
    pub(crate) fn connection_id() -> u64 {
4
        42
5
    }
6

7
    pub mod tcp {
8
        // Visible only to the parent module `network` (and its descendants).
9
        pub(super) fn raw_handshake() -> &'static str {
10
            "SYN/ACK"
11
        }
12

13
        // Visible only within the `network` module subtree.
14
        pub(in crate::network) fn buffer_size() -> usize {
15
            8192
16
        }
17

18
        pub fn open() -> &'static str {
19
            let _ = buffer_size(); // same module: always fine
20
            "tcp-open"
21
        }
22
    }
23

24
    pub fn diagnostics() -> String {
25
        let hs = tcp::raw_handshake();    // `network` can see `pub(super)` of its child
26
        let bs = tcp::buffer_size();      // and `pub(in crate::network)` items too
27
        format!("handshake={hs}, buffer={bs}")
28
    }
29
}
30

31
fn main() {
32
    println!("conn id = {}", network::connection_id()); // pub(crate): visible at crate root
33
    println!("{}", network::tcp::open());               // pub: visible everywhere
34
    println!("{}", network::diagnostics());
35
}

Real output:

1
conn id = 42
2
tcp-open
3
handshake=SYN/ACK, buffer=8192

Tip: pub(crate) is the workhorse. Most “this is public to my own code but I never want to commit to it as part of my library’s API” items should be pub(crate). It is the closest thing Rust has to “internal” in C# or “package-private” in Java — a level JavaScript modules cannot express at all.

The mental model for pub(super) deserves care. It means “visible to my parent module.” Because privacy flows outward and descendants always inherit access, anything nested under that parent can also reach the item. So pub(super) is not “visible only to the immediate parent and nothing else” — it is “visible to the parent subtree.” We will see exactly where this trips people up in Common Pitfalls.

Enums: variants inherit the enum’s visibility

Unlike struct fields, enum variants and their fields are automatically as public as the enum itself. You do not (and cannot) write pub on a variant:

1
mod payments {
2
    pub enum Status {
3
        Pending,
4
        Settled { amount: u64 }, // variant fields are public automatically
5
        Failed,
6
    }
7

8
    pub fn describe(s: &Status) -> String {
9
        match s {
10
            Status::Pending => "pending".to_string(),
11
            Status::Settled { amount } => format!("settled: {amount}"),
12
            Status::Failed => "failed".to_string(),
13
        }
14
    }
15
}
16

17
fn main() {
18
    let s = payments::Status::Settled { amount: 500 };
19
    if let payments::Status::Settled { amount } = &s {
20
        println!("amount = {amount}");
21
    }
22
    println!("{}", payments::describe(&s));
23
}

Real output:

1
amount = 500
2
settled: 500

This makes sense: an enum’s whole purpose is for callers to match on its variants, so hiding individual variants would defeat the point. If you need a “closed” enum that callers can’t exhaustively match or construct, you reach for other patterns (a private struct wrapper, or the #[non_exhaustive] attribute), not field visibility.

Key Differences

Concept	TypeScript/JavaScript	Rust
Default for a top-level item	Private to the file until `export`ed	Private to the module (visible to descendants)
Granularity	Binary: exported or not	Graduated: `pub`, `pub(crate)`, `pub(super)`, `pub(in path)`
”Internal to my package” level	None (an `export` is reachable cross-package)	`pub(crate)`
Field visibility	`private`/`#` on class members (class-scoped)	Per-field `pub` (independent of the struct)
Enforcement	`private`/`protected` erased at runtime; `#` enforced	Always enforced at compile time, across crate boundaries
Constructing a type with hidden state	Allowed via `as any` casts	Impossible from outside if any field is private (`E0451`)
Direction of privacy	Members hidden from outside the class	Items hidden from ancestors; descendants always have access

Why the extra knobs? Rust libraries publish a stable public API to other crates via crates.io (see publishing.md). Everything that is merely pub becomes part of that semver contract; changing or removing it is a breaking change. pub(crate) lets you write code that is shared freely inside your crate without ever leaking into your public API. JavaScript packages have no language-level equivalent — the convention is fragile (underscore prefixes, internal/ folders, an exports map in package.json), and none of it is checked by the compiler.

Note: The visibility of an item also interacts with use-based re-exports. You can keep an item defined deep inside a private module and surface it at the crate root with pub use, decoupling your file layout from your public API. That technique lives in use-keyword.md.

Common Pitfalls

Pitfall 1: Assuming a `pub struct` makes its fields public

Coming from JavaScript, where exporting a class exposes its public fields, it is easy to expect pub struct to do the same. It does not — fields are private unless individually marked pub.

1
mod model {
2
    pub struct User {
3
        pub id: u64,
4
        email: String, // forgot `pub`
5
    }
6
    impl User {
7
        pub fn new(id: u64, email: &str) -> Self {
8
            User { id, email: email.to_string() }
9
        }
10
    }
11
}
12

13
fn main() {
14
    let user = model::User::new(1, "ada@example.com");
15
    println!("{}", user.email); // does not compile (error[E0616]: private field)
16
}

1
error[E0616]: field `email` of struct `User` is private
2
  --> src/main.rs:16:25
3
   |
4
16 |     println!("{}", user.email);
5
   |                         ^^^^^ private field

Fix: add pub to the field, or expose a getter method (pub fn email(&self) -> &str). Prefer the getter when the field has invariants to protect.

Pitfall 2: Leaking a private type through a public function

If a pub (or pub(crate)) function returns or accepts a type that is less visible than the function itself, the function’s signature would expose a name callers cannot otherwise reach. Rust warns about this (lint private_interfaces) and the type is unusable at the call site:

1
mod config {
2
    struct Secret {           // private type
3
        token: String,
4
    }
5
    pub fn load() -> Secret { // public fn returning a private type
6
        Secret { token: "abc".to_string() }
7
    }
8
}
9

10
fn main() {
11
    let _s = config::load(); // does not compile (the returned type is private)
12
}

1
warning: type `Secret` is more private than the item `load`
2
 --> src/main.rs:8:5
3
  |
4
8 |     pub fn load() -> Secret {
5
  |     ^^^^^^^^^^^^^^^^^^^^^^^ function `load` is reachable at visibility `pub(crate)`
6
  |
7
note: but type `Secret` is only usable at visibility `pub(self)`
8
...
9
error: type `Secret` is private
10
  --> src/main.rs:14:14
11
   |
12
14 |     let _s = config::load();
13
   |              ^^^^^^^^^^^^^^ private type

Fix: make Secret at least as visible as load (pub(crate) struct Secret), or lower load’s visibility to match the type. The rule is: an item’s public surface may not be more visible than the types it mentions.

Pitfall 3: Misreading `pub(super)` as “only the immediate parent”

pub(super) means “visible to my parent module,” and because descendants inherit ancestor access, that includes everything nested under the parent — not just the parent’s own body. Reaching the item from a cousin under the same parent succeeds, which surprises people who expected a tighter restriction:

1
mod app {
2
    pub mod inner {
3
        pub(super) fn helper() -> u32 { 1 } // visible to `app` and all of `app`'s descendants
4
    }
5
    pub mod other {
6
        pub fn call_it() -> u32 {
7
            super::inner::helper() // compiles — `other` is inside `app`
8
        }
9
    }
10
}

But step outside the parent subtree (here, the crate root is not inside app) and it is private again:

1
mod app {
2
    pub mod inner {
3
        pub(super) fn helper() -> u32 { 1 }
4
    }
5
}
6

7
fn main() {
8
    println!("{}", app::inner::helper()); // does not compile (error[E0603]: private function)
9
}

1
error[E0603]: function `helper` is private
2
  --> src/main.rs:10:32
3
   |
4
10 |     println!("{}", app::inner::helper());
5
   |                                ^^^^^^ private function

Fix: if you truly want only one specific ancestor module to have access (and nothing else), name it explicitly with pub(in crate::app). If you want crate-wide access, use pub(crate).

Pitfall 4: Reaching for `pub` when `pub(crate)` is what you mean

Marking helpers pub “so my other modules can use them” silently enlarges your crate’s public API. Once published, those items are part of your semver contract and you cannot remove them without a major version bump. There is no compiler error here — that is exactly why it is dangerous.

Fix: default to pub(crate) for anything that is shared internally but not meant for external consumers. Reserve plain pub for the genuine public surface of a library. (See publishing.md for why this matters at release time.)

Best Practices

Start private, widen only when forced. Write items with no visibility keyword first; add pub/pub(crate) when a real consumer appears. The compiler error tells you precisely when.
Use pub(crate) as your default for shared internals. It is the idiomatic “internal but not public API” level and keeps your published surface small and stable.
Hide struct fields and expose behavior. Make fields private and offer constructors plus getter/setter methods when there are invariants to protect; expose fields with pub only for plain data holders (configuration structs, DTOs) that have no invariants.
Keep public APIs free of private types. Heed the private_interfaces lint; if a function is pub, every type in its signature must be at least as visible.
Prefer explicit pub(in path) over loose pub(super) when you want a single, named module to be the only privileged caller — it documents intent and survives refactors that move modules around.
Decouple file layout from public API with pub use. Organize code into private submodules for your own sanity, then re-export the curated public items at a stable path. (Details in use-keyword.md.)
Run cargo doc --no-deps --open to see exactly what your crate exposes — only pub items reachable from the crate root show up, which is the truest picture of your public API.

Real-World Example

A production-flavored event store that uses field visibility to enforce an invariant: every stored event gets a store-assigned sequence number, and the internal index is kept in sync with the event list. Callers can never corrupt either because the fields are private — the only way in is through push.

1
mod store {
2
    use std::collections::HashMap;
3

4
    /// An append-only event log. The internal storage is hidden so the
5
    /// `events` vec and the `index` map can never drift out of sync.
6
    pub struct EventStore {
7
        events: Vec<Event>,            // private: callers must use `push`
8
        index: HashMap<String, usize>, // private: maintained internally
9
    }
10

11
    #[derive(Clone, Debug)]
12
    pub struct Event {
13
        pub id: String,      // public: callers read this freely
14
        pub payload: String, // public
15
        seq: u64,            // private: assigned by the store, never the caller
16
    }
17

18
    impl Event {
19
        /// Read-only access to the store-assigned sequence number.
20
        pub fn seq(&self) -> u64 {
21
            self.seq
22
        }
23
    }
24

25
    impl EventStore {
26
        pub fn new() -> Self {
27
            EventStore {
28
                events: Vec::new(),
29
                index: HashMap::new(),
30
            }
31
        }
32

33
        /// The single, invariant-preserving way to add an event.
34
        pub fn push(&mut self, id: &str, payload: &str) {
35
            let seq = self.events.len() as u64;
36
            self.index.insert(id.to_string(), self.events.len());
37
            self.events.push(Event {
38
                id: id.to_string(),
39
                payload: payload.to_string(),
40
                seq,
41
            });
42
        }
43

44
        pub fn get(&self, id: &str) -> Option<&Event> {
45
            let pos = *self.index.get(id)?;
46
            self.events.get(pos)
47
        }
48

49
        /// Crate-internal metric: other modules in this crate may read the
50
        /// count, but external crates cannot rely on it.
51
        pub(crate) fn len(&self) -> usize {
52
            self.events.len()
53
        }
54
    }
55
}
56

57
// Surface the public types at the crate root, independent of file layout.
58
pub use store::{Event, EventStore};
59

60
fn main() {
61
    let mut es = EventStore::new();
62
    es.push("user.created", "{\"id\":1}");
63
    es.push("user.renamed", "{\"id\":1,\"name\":\"Ada\"}");
64

65
    if let Some(ev) = es.get("user.renamed") {
66
        println!("id={}, seq={}, payload={}", ev.id, ev.seq(), ev.payload);
67
    }
68

69
    println!("total events (crate-internal): {}", es.len());
70
}

Real output:

1
id=user.renamed, seq=1, payload={"id":1,"name":"Ada"}
2
total events (crate-internal): 2

Note the layered design: id and payload are pub because they are plain data the caller supplied; seq is private with a read-only getter because the store owns it; the EventStore internals are fully private; and len is pub(crate) because internal tooling may want it but it is not part of the library’s public promise. This is the kind of fine-grained control that JavaScript’s binary export cannot express.

Exercises

Exercise 1: Expose the right function

Difficulty: Easy

Objective: Practice the difference between a private helper and a public entry point.

Instructions: Make area callable from main, while keeping scale_factor private to the module. Fill in the visibility keywords so the program compiles and prints 6.

1
mod geometry {
2
    fn area(width: f64, height: f64) -> f64 {
3
        scale_factor() * width * height
4
    }
5

6
    fn scale_factor() -> f64 {
7
        1.0
8
    }
9
}
10

11
fn main() {
12
    println!("{}", geometry::area(2.0, 3.0)); // should print 6
13
}

Solution

Only area needs to be public; scale_factor stays private and remains reachable from inside the module.

1
mod geometry {
2
    pub fn area(width: f64, height: f64) -> f64 {
3
        scale_factor() * width * height
4
    }
5

6
    fn scale_factor() -> f64 {
7
        1.0
8
    }
9
}
10

11
fn main() {
12
    println!("{}", geometry::area(2.0, 3.0));
13
}

Output:

1
6

Exercise 2: Encapsulate an invariant with field visibility

Difficulty: Medium

Objective: Use a private field to force callers through methods that protect a balance from going negative.

Instructions: Complete the Account type so that owner is a public field, balance is private, and the balance can only change through deposit and withdraw. A withdrawal larger than the balance must return an Err.

1
mod bank {
2
    pub struct Account {
3
        // owner should be a public field
4
        // balance should be private
5
    }
6

7
    impl Account {
8
        pub fn open(owner: &str) -> Self {
9
            /* ??? */
10
        }
11

12
        pub fn deposit(&mut self, amount: u64) {
13
            /* ??? */
14
        }
15

16
        pub fn withdraw(&mut self, amount: u64) -> Result<(), String> {
17
            /* ??? */
18
        }
19

20
        pub fn balance(&self) -> u64 {
21
            /* ??? */
22
        }
23
    }
24
}
25

26
fn main() {
27
    let mut acct = bank::Account::open("Ada");
28
    acct.deposit(100);
29
    acct.withdraw(30).unwrap();
30
    println!("{} has {}", acct.owner, acct.balance());
31
    println!("{:?}", acct.withdraw(1000));
32
}

Solution

1
mod bank {
2
    pub struct Account {
3
        pub owner: String, // public: freely readable/writable
4
        balance: u64,      // private: protected by deposit/withdraw
5
    }
6

7
    impl Account {
8
        pub fn open(owner: &str) -> Self {
9
            Account { owner: owner.to_string(), balance: 0 }
10
        }
11

12
        pub fn deposit(&mut self, amount: u64) {
13
            self.balance += amount;
14
        }
15

16
        pub fn withdraw(&mut self, amount: u64) -> Result<(), String> {
17
            if amount > self.balance {
18
                return Err("insufficient funds".to_string());
19
            }
20
            self.balance -= amount;
21
            Ok(())
22
        }
23

24
        pub fn balance(&self) -> u64 {
25
            self.balance
26
        }
27
    }
28
}
29

30
fn main() {
31
    let mut acct = bank::Account::open("Ada");
32
    acct.deposit(100);
33
    acct.withdraw(30).unwrap();
34
    println!("{} has {}", acct.owner, acct.balance());
35
    println!("{:?}", acct.withdraw(1000));
36
}

Output:

1
Ada has 70
2
Err("insufficient funds")

Because balance is private and the struct has a private field, no caller outside bank can build an Account literal or set the balance directly — they must go through the methods.

Exercise 3: Pick the tightest restricted visibility

Difficulty: Hard

Objective: Wire up pub(crate), pub(super), and pub(in path) so the program compiles with the narrowest visibility that still works.

Instructions: engine::run must be callable from main (it is internal to this crate, never an external API). scheduler::tick should be reachable only from within engine. scheduler::next_id should be reachable only from within the engine subtree. Choose the most restrictive keyword for each.

1
mod engine {
2
    pub mod scheduler {
3
        fn tick() -> u64 {
4
            next_id()
5
        }
6

7
        fn next_id() -> u64 {
8
            7
9
        }
10
    }
11

12
    fn run() -> u64 {
13
        scheduler::tick()
14
    }
15
}
16

17
fn main() {
18
    println!("{}", engine::run()); // should print 7
19
}

Solution

run is internal-to-the-crate API called from main (which is outside engine), so pub(crate) is the tightest fit.
tick must be visible to engine (its grandparent module), so pub(super) exposes it to engine and everything nested under it.
next_id should be confined to the engine subtree, which pub(in crate::engine) states explicitly.

1
mod engine {
2
    pub mod scheduler {
3
        // Visible to the parent (`engine`) and its descendants.
4
        pub(super) fn tick() -> u64 {
5
            next_id()
6
        }
7

8
        // Visible only within the `engine` module subtree.
9
        pub(in crate::engine) fn next_id() -> u64 {
10
            7
11
        }
12
    }
13

14
    // Visible across the whole crate, but not to external crates.
15
    pub(crate) fn run() -> u64 {
16
        scheduler::tick()
17
    }
18
}
19

20
fn main() {
21
    println!("{}", engine::run());
22
}

Output:

1
7

Tip: engine::run could have been plain pub and the program would still compile — but for a binary crate there is no “external crate” to expose it to, and using pub on a genuinely internal item is the habit Pitfall 4 warns against. pub(crate) documents the intent precisely.

Visibility and the `pub` Keyword

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

Private by default, like an un-`export`ed declaration

`pub` — export to the parent (and beyond)

Field visibility: the part JavaScript modules don’t have

The graduated scale: `pub(crate)`, `pub(super)`, `pub(in path)`

Enums: variants inherit the enum’s visibility

Key Differences

Common Pitfalls

Pitfall 1: Assuming a `pub struct` makes its fields public

Pitfall 2: Leaking a private type through a public function

Pitfall 3: Misreading `pub(super)` as “only the immediate parent”

Pitfall 4: Reaching for `pub` when `pub(crate)` is what you mean

Best Practices

Real-World Example

Further Reading

Official Documentation

Exercises

Exercise 1: Expose the right function

Exercise 2: Encapsulate an invariant with field visibility

Exercise 3: Pick the tightest restricted visibility

Visibility and the pub Keyword

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

Private by default, like an un-exported declaration

pub — export to the parent (and beyond)

Field visibility: the part JavaScript modules don’t have

The graduated scale: pub(crate), pub(super), pub(in path)

Enums: variants inherit the enum’s visibility

Key Differences

Common Pitfalls

Pitfall 1: Assuming a pub struct makes its fields public

Pitfall 2: Leaking a private type through a public function

Pitfall 3: Misreading pub(super) as “only the immediate parent”

Pitfall 4: Reaching for pub when pub(crate) is what you mean

Best Practices

Real-World Example

Further Reading

Official Documentation

Related Sections in This Guide

Exercises

Exercise 1: Expose the right function

Exercise 2: Encapsulate an invariant with field visibility

Exercise 3: Pick the tightest restricted visibility

Visibility and the `pub` Keyword

Private by default, like an un-`export`ed declaration

`pub` — export to the parent (and beyond)

The graduated scale: `pub(crate)`, `pub(super)`, `pub(in path)`

Pitfall 1: Assuming a `pub struct` makes its fields public

Pitfall 3: Misreading `pub(super)` as “only the immediate parent”

Pitfall 4: Reaching for `pub` when `pub(crate)` is what you mean