proc-macro2

In production, proc-macro2 is invisible in the best way possible. It's a compile-time dependency that adds zero runtime overhead - no connection pools, no resource management, no logging hooks because there's nothing to manage at runtime. The API mirrors std's proc_macro nearly 1:1, making it trivial to write testable macro code that can run outside the compiler context.

The ability to write unit tests for procedural macros is the killer feature. Without proc-macro2, testing token manipulation logic requires integration tests that compile test crates. With it, you can write normal #[test] functions that exercise your token parsing and generation logic directly. Error messages from span tracking are precise and helpful during both development and when users encounter macro errors.

The main gotcha is understanding when to use proc-macro2 vs proc-macro types at API boundaries. The .into() conversions are zero-cost but require mental overhead. Version stability has been excellent - the 1.0 line has maintained compatibility while tracking compiler changes seamlessly.

proc-macro2 is an essential tool when building procedural macros or working with token streams. It provides a stable API that mirrors the compiler's proc_macro but works outside of macro contexts, enabling unit testing and library composition. The API design is intuitive once you understand token streams - Span, TokenStream, and TokenTree are well-documented and behave predictably.

The real value shines when testing. You can write tests for your macro logic without needing integration tests that compile entire crates. The conversions between proc_macro and proc_macro2 types are seamless with the .into() trait. Error messages are clear, especially around span manipulation, which helps tremendously when debugging macro hygiene issues.

Documentation is thorough with good examples of common patterns like creating identifiers, literals, and groups. The type system prevents many footguns - you can't accidentally mix spans from different contexts. It integrates perfectly with syn and quote, forming the standard toolkit for macro development.

Using proc-macro2 day-to-day is mostly frictionless once you understand its purpose: it wraps the compiler's proc_macro types so you can test and develop macro code outside of actual proc macro contexts. The API mirrors std::proc_macro almost exactly, which means if you know one, you know the other. The `TokenStream`, `Span`, and `Ident` types work as expected, and converting between proc-macro2 and proc_macro is trivial with `.into()`.

The main learning curve comes from the sparse documentation. The crate docs explain *what* it is, but not *why* you'd use it or how to structure your macro crates effectively. I had to piece together patterns from existing macro libraries like syn and quote. Error messages are generally clear when you mess up token operations, but debugging macro expansion issues still requires println-style debugging with `to_string()` on TokenStreams.

Once you've seen the pattern (proc-macro2 in your lib, thin wrapper in proc-macro crate), it becomes second nature. The ability to write unit tests for macro logic is invaluable and makes this crate essential for serious macro development.