Attribute Macros

18 min read

If you have ever written @Component, @Injectable, or a custom method decorator in TypeScript, you already know the shape of an attribute macro: a name you attach above a declaration that transforms or augments it. Rust’s #[attribute] syntax looks almost identical, but it runs at compile time and rewrites your code into entirely new source before the compiler ever type-checks it.

Quick Overview

An attribute macro is a kind of procedural macro that you place in front of an item — usually a function, but also a struct, module, or impl block — to inspect and rewrite that item. The annotated item is handed to your macro as a stream of tokens, and whatever tokens you return replace it. Frameworks use this for things like #[tokio::main], web routes (#[get("/users")]), and test harnesses (#[test]). This page covers the concept and a minimal, hand-written example; the mechanics of the proc-macro crate, syn, and quote are covered in depth in Procedural Macros.

TypeScript/JavaScript Example

The closest TypeScript analogue is a decorator. Here is a standard (TC39 stage-3) method decorator that wraps a method so it logs when it is entered and how long it took — a pattern you have probably seen in logging or tracing libraries. It works in TypeScript 5.x and runs on Node v22 after compilation.

1
// Standard (TC39 stage-3) decorators, supported in TypeScript 5.x and Node v22.
2
function logCalls<This, Args extends unknown[], Return>(
3
  target: (this: This, ...args: Args) => Return,
4
  context: ClassMethodDecoratorContext,
5
) {
6
  const name = String(context.name);
7
  // The decorator REPLACES the method with this wrapper at runtime.
8
  return function (this: This, ...args: Args): Return {
9
    console.log(`-> entering ${name}`);
10
    const start = performance.now();
11
    const result = target.call(this, ...args);
12
    console.log(`<- leaving ${name} after ${(performance.now() - start).toFixed(3)}ms`);
13
    return result;
14
  };
15
}
16

17
class OrderService {
18
  @logCalls
19
  orderTotal(itemCents: number, qty: number): number {
20
    return itemCents * qty + 500; // items plus a flat $5.00 shipping fee
21
  }
22
}
23

24
const svc = new OrderService();
25
console.log("total =", svc.orderTotal(1299, 3));

Compiling with tsc --target ES2022 deco.ts and running node deco.js prints:

1
-> entering orderTotal
2
<- leaving orderTotal after 0.007ms
3
total = 4397

The decorator runs at runtime: every time orderTotal is invoked, the wrapper function executes. The original method is still a real value being passed around and called through target.call(...). There is per-call indirection, and the wrapping happens while your program is running.

Note: A TypeScript decorator is a runtime function that receives the thing it decorates as a value. A Rust attribute macro is a compile-time function that receives the thing it annotates as source code (tokens) and emits new source code. This difference drives almost everything else on this page.

Rust Equivalent

In Rust, the same “log on entry and exit” behavior is an attribute macro named log_calls. Attribute macros must live in their own crate of type proc-macro, so this is a two-crate setup: a macro crate that defines the attribute, and an application crate that uses it. The current stable toolchain is Rust 1.96.0 on the 2024 edition; cargo new selects it automatically.

The macro crate (log_attr/Cargo.toml) must opt in to being a proc-macro crate and depends on syn and quote:

1
[package]
2
name = "log_attr"
3
version = "0.1.0"
4
edition = "2024"
5

6
[lib]
7
proc-macro = true   # REQUIRED — this is what makes #[proc_macro_attribute] legal
8

9
[dependencies]
10
syn = { version = "2", features = ["full"] }
11
quote = "1"
12
proc-macro2 = "1"

The macro itself (log_attr/src/lib.rs) parses the annotated function, then re-emits it with a wrapped body:

1
use proc_macro::TokenStream;
2
use quote::quote;
3
use syn::{parse_macro_input, ItemFn};
4

5
/// An attribute macro that wraps a function so it logs when it is entered
6
/// and when it returns, including how long the body took.
7
#[proc_macro_attribute]
8
pub fn log_calls(_attr: TokenStream, item: TokenStream) -> TokenStream {
9
    // Parse the annotated item as a complete function definition.
10
    let input = parse_macro_input!(item as ItemFn);
11

12
    // Pull apart the pieces of the original function.
13
    let vis = &input.vis;     // pub / pub(crate) / (nothing)
14
    let sig = &input.sig;     // fn name(args) -> Ret
15
    let block = &input.block; // the original { ... } body
16
    let name = &sig.ident;    // just the function name, e.g. `order_total`
17

18
    // Re-emit the function with the same signature, but a new body that
19
    // wraps the original block with logging on either side.
20
    let expanded = quote! {
21
        #vis #sig {
22
            println!("-> entering `{}`", stringify!(#name));
23
            let __started = std::time::Instant::now();
24
            let __result = (|| #block)();
25
            println!("<- leaving  `{}` after {:?}", stringify!(#name), __started.elapsed());
26
            __result
27
        }
28
    };
29

30
    expanded.into()
31
}

The application crate (app/Cargo.toml) depends on the macro crate by path:

1
[package]
2
name = "app"
3
version = "0.1.0"
4
edition = "2024"
5

6
[dependencies]
7
log_attr = { path = "../log_attr" }

And uses the attribute exactly like a decorator — you place it above the function:

1
use log_attr::log_calls;
2

3
/// Compute the total price in cents, including a flat $5.00 shipping fee.
4
#[log_calls]
5
fn order_total(item_cents: u32, qty: u32) -> u32 {
6
    let shipping = 500;
7
    item_cents * qty + shipping
8
}
9

10
#[log_calls]
11
fn greet(name: &str) {
12
    println!("Hello, {name}!");
13
}
14

15
fn main() {
16
    let total = order_total(1299, 3);
17
    println!("total = {total} cents");
18
    greet("Ada");
19
}

Running cargo run -p app prints:

1
-> entering `order_total`
2
<- leaving  `order_total` after 42ns
3
total = 4397 cents
4
-> entering `greet`
5
Hello, Ada!
6
<- leaving  `greet` after 500ns

Note: Notice log_calls works on both order_total (returns a u32) and greet (returns ()), with no generics or trait bounds. That is because the macro never sees types — it manipulates tokens. The wrapped body just forwards whatever the original returned.

Detailed Explanation

The attribute macro signature

Every attribute macro has the exact same signature:

1
// Signature shape — both parameters are token streams, the return is tokens.
2
#[proc_macro_attribute]
3
pub fn log_calls(_attr: TokenStream, item: TokenStream) -> TokenStream { /* ... */ }

attr is the tokens inside the parentheses of the attribute itself. For #[log_calls] it is empty; for #[get("/users")] it would be the tokens "/users".
item is the tokens of the thing the attribute is attached to — here, the entire fn order_total(...) { ... }.
The returned TokenStream completely replaces the original item. If you return item unchanged, the function is untouched. If you return nothing, the function disappears.

This is fundamentally different from a TypeScript decorator, which receives the method as a callable value and returns a replacement value at runtime.

Parsing with `syn`

parse_macro_input!(item as ItemFn) turns the raw token stream into a structured syntax tree. ItemFn is syn’s representation of a free function, exposing fields like .vis (visibility), .sig (the signature: name, generics, parameters, return type), and .block (the body). Working with this tree is far safer than string manipulation — you get the real Rust grammar, not a regex.

Generating with `quote`

The quote! { ... } macro is the inverse of parsing: it builds a new token stream from a template. Inside it, #vis, #sig, #block, and #name interpolate the pieces we extracted (the # is quote’s splice operator, unrelated to a comment). So we reconstruct the original function header, then write a brand-new body.

A few details in the generated body matter:

stringify!(#name) turns the identifier into a string literal at compile time, so the log shows the function’s actual name.
let __result = (|| #block)(); wraps the original body in an immediately-invoked closure. This lets the body return early without skipping the “leaving” log, and gives us a single value to log around. (For functions that themselves return early, this preserves correct control flow.)
The underscore-prefixed names (__started, __result) are an intentional, low-collision choice. Rust’s macro hygiene handles most identifier clashes, but #[proc_macro_attribute] macros are less hygienic than macro_rules! for identifiers that appear in the user’s body, so distinctive names are a sensible habit. Hygiene is covered in Macro Basics.

Seeing the expansion

You never have to imagine what an attribute macro produces. The cargo expand tool (install with cargo install cargo-expand) prints your code after macro expansion. For the order_total example above, cargo expand --bin app shows the rewritten function:

1
// Output of `cargo expand` (lightly trimmed): the macro replaced the function body.
2
fn order_total(item_cents: u32, qty: u32) -> u32 {
3
    {
4
        ::std::io::_print(format_args!("-> entering `{0}`\n", "order_total"));
5
    };
6
    let __started = std::time::Instant::now();
7
    let __result = (|| { item_cents * qty + 500 })();
8
    {
9
        ::std::io::_print(
10
            format_args!(
11
                "<- leaving  `{0}` after {1:?}\n",
12
                "order_total",
13
                __started.elapsed(),
14
            ),
15
        );
16
    };
17
    __result
18
}

This is the key insight: by the time the program runs, there is no macro — only ordinary, fully-monomorphized Rust. There is no decorator object, no per-call lookup, no wrapper allocation. The cost is paid once, during compilation.

Key Differences

Aspect	TypeScript decorator	Rust attribute macro
When it runs	At runtime (and once at class-definition time)	At compile time, before type-checking the result
What it receives	The decorated value (a function/class) and a context object	The annotated item as tokens (source code)
What it returns	A replacement value, or `void`	A `TokenStream` that replaces the item’s source
Runtime cost	Wrapper indirection on every call	Zero — the generated code is the code
Where it can live	Any module	A dedicated `proc-macro = true` crate
Can read types?	Yes, via reflection/metadata at runtime	No — it sees syntax only, never resolved types
Failure mode	Throws at runtime	Emits a compiler error; program never builds

The mental-model shift for a TypeScript developer: a decorator is a function that wraps a value; an attribute macro is a program that writes a program. Because the macro emits plain source code that the compiler then checks normally, a mistake in your generated code surfaces as an ordinary type error pointing into the expanded code — not a runtime exception.

Tip: The three flavors of procedural macro are attribute macros (#[name], this page), derive macros (#[derive(Name)]), and function-like macros (name!(...)). They share the same proc-macro crate plumbing but differ in how they are triggered.

Common Pitfalls

Pitfall 1: Forgetting `proc-macro = true`

Attribute macros are only legal in a crate that declares itself a proc-macro crate. Leave out the [lib] proc-macro = true line and the compiler rejects the attribute:

1
// log_attr/src/lib.rs — in a crate WITHOUT `proc-macro = true` in Cargo.toml
2
use proc_macro::TokenStream;
3

4
#[proc_macro_attribute] // does not compile
5
pub fn noop(_attr: TokenStream, item: TokenStream) -> TokenStream {
6
    item
7
}

The real error from cargo build:

1
error: the `#[proc_macro_attribute]` attribute is only usable with crates of the `proc-macro` crate type
2
 --> src/lib.rs:3:1
3
  |
4
3 | #[proc_macro_attribute]
5
  | ^^^^^^^^^^^^^^^^^^^^^^^

The fix is the [lib] proc-macro = true stanza shown in the Rust Equivalent section.

Pitfall 2: Applying the attribute to the wrong kind of item

Our macro parses its input as ItemFn. If you put #[log_calls] on a struct instead of a function, parse_macro_input! cannot match the fn grammar and produces a precise error:

1
use log_attr::log_calls;
2

3
#[log_calls] // does not compile — log_calls expects a function, not a struct
4
struct Order {
5
    total: u32,
6
}

The real error from cargo build:

1
error: expected `fn`
2
 --> app2/src/main.rs:4:1
3
  |
4
4 | struct Order {
5
  | ^^^^^^

Warning: Coming from TypeScript, it is tempting to assume an attribute “just adds metadata” and is harmless anywhere. It is not — an attribute macro replaces the item, so it must understand what it was given. A well-written macro either accepts multiple item kinds or fails with a clear message.

Pitfall 3: Expecting the macro to inspect types

A decorator in TypeScript can read parameter types via reflect-metadata at runtime. An attribute macro cannot. Inside log_calls, input.sig knows the parameter is written as u32, but it has no idea whether u32 is an alias, what trait it implements, or whether it equals some other type — that information does not exist yet at macro-expansion time. If your design needs resolved type information, an attribute macro is the wrong tool; consider generics and traits (see Generics & Traits) instead.

Pitfall 4: Generating code that does not compile

Because the macro emits source, a bug in your template becomes a compiler error in the expanded code. If you forget to handle the function’s return value and drop __result, the wrapped function silently changes its return type to () and every caller fails to type-check. Run cargo expand whenever the error message is confusing — it shows you the exact code the compiler is complaining about.

Best Practices

Reach for an attribute macro only when simpler tools fall short. A higher-order function, a generic wrapper, or a macro_rules! (Declarative Macros) is far less machinery. Attribute macros shine when you must rewrite a declaration’s shape — adding fields, generating sibling functions, registering routes — which ordinary code cannot do.
Parse into the most specific syn type you support. ItemFn for functions, ItemStruct for structs, or syn::Item if you genuinely accept several kinds and want to branch. Specific types give better error messages.
Preserve everything you do not intend to change. Re-emit the original visibility, generics, where-clauses, and attributes. The simplest faithful pattern is to interpolate the whole parsed item (#input) and only add around it, rather than reconstructing it field by field.
Emit real compile_error! diagnostics for misuse. Returning syn::Error::new_spanned(item, "message").to_compile_error() points the error at the user’s code with a message you control — much friendlier than a parse failure. This is detailed in Procedural Macros.
Keep the generated code minimal and predictable. Smaller expansions compile faster and are easier to debug with cargo expand.
Pin syn with the full feature when you parse function bodies or full items; the default feature set does not include the full grammar.

Real-World Example

Web frameworks like Actix and Rocket let you annotate a handler with its HTTP route. Here is a minimal version of that idea: a #[get("/path")] attribute that keeps your handler intact and generates a sibling function describing where it is mounted. This demonstrates an attribute macro that reads its own arguments (the path literal) — the attr parameter we ignored earlier.

The macro (added to log_attr/src/lib.rs):

1
use proc_macro::TokenStream;
2
use quote::quote;
3
use syn::{parse_macro_input, ItemFn, LitStr};
4

5
/// A route-style attribute that takes a path literal, e.g. `#[get("/users")]`.
6
/// It keeps the original handler unchanged and generates a sibling function
7
/// `<name>_route()` returning the (method, path) the handler is mounted at.
8
#[proc_macro_attribute]
9
pub fn get(attr: TokenStream, item: TokenStream) -> TokenStream {
10
    // The attribute's OWN tokens: parse them as a string literal.
11
    let path = parse_macro_input!(attr as LitStr);
12
    let input = parse_macro_input!(item as ItemFn);
13

14
    let name = &input.sig.ident;
15
    // Build a new identifier `<name>_route` for the generated helper.
16
    let route_fn = quote::format_ident!("{}_route", name);
17

18
    let expanded = quote! {
19
        // Emit the original handler unchanged...
20
        #input
21

22
        // ...plus a generated helper describing its mount point.
23
        pub fn #route_fn() -> (&'static str, &'static str) {
24
            ("GET", #path)
25
        }
26
    };
27

28
    expanded.into()
29
}

The handler in the application crate:

1
use log_attr::get;
2

3
#[get("/users")]
4
fn list_users() -> String {
5
    "[\"ada\", \"linus\"]".to_string()
6
}
7

8
fn main() {
9
    // `list_users` still exists and behaves normally...
10
    // ...and `list_users_route` was generated for us by the macro.
11
    let (method, path) = list_users_route();
12
    println!("mounted {method} {path} -> {}", list_users());
13
}

Running cargo run -p app prints:

1
mounted GET /users -> ["ada", "linus"]

This is exactly the trick real frameworks use: the attribute does not change your handler, but it generates extra registration code beside it that the framework later collects. The attr parameter — empty for #[log_calls] — carries the "/users" literal here, parsed as a syn::LitStr. For the full machinery behind proc-macro2, custom parsing, and richer argument syntax, see Procedural Macros.

Exercises

Exercise 1: A `#[timed]` attribute

Difficulty: Easy

Objective: Write an attribute macro that prints only how long a function took, leaving its return value and behavior unchanged.

Instructions:

In your proc-macro crate, add a #[proc_macro_attribute] pub fn timed(...).
Parse the item as an ItemFn, wrap the original body so you measure elapsed time around it, and print the elapsed Duration to standard error using the function’s name.
Apply #[timed] to a function such as fn sum_to(n: u64) -> u64 { (1..=n).sum() } and confirm the return value is unchanged.

Solution

1
use proc_macro::TokenStream;
2
use quote::quote;
3
use syn::{parse_macro_input, ItemFn};
4

5
/// `#[timed]` prints how long a function took, to standard error.
6
#[proc_macro_attribute]
7
pub fn timed(_attr: TokenStream, item: TokenStream) -> TokenStream {
8
    let input = parse_macro_input!(item as ItemFn);
9
    let vis = &input.vis;
10
    let sig = &input.sig;
11
    let block = &input.block;
12
    let name = &sig.ident;
13

14
    quote! {
15
        #vis #sig {
16
            let __start = std::time::Instant::now();
17
            let __out = (|| #block)();
18
            eprintln!("[timed] {} took {:?}", stringify!(#name), __start.elapsed());
19
            __out
20
        }
21
    }
22
    .into()
23
}

1
use log_attr::timed;
2

3
#[timed]
4
fn sum_to(n: u64) -> u64 {
5
    (1..=n).sum()
6
}
7

8
fn main() {
9
    println!("sum = {}", sum_to(1_000));
10
}

Running cargo run -p app prints (the exact duration varies):

1
[timed] sum_to took 6.917µs
2
sum = 500500

Exercise 2: An attribute that reads an argument

Difficulty: Medium

Objective: Write #[warn_deprecated("message")] that prints a warning before the function body runs. This exercises the attr parameter.

Instructions:

Add #[proc_macro_attribute] pub fn warn_deprecated(...).
Parse attr as a syn::LitStr to capture the message, and parse item as an ItemFn.
Re-emit the function with a body that first prints WARNING: <name> is deprecated: <message> to standard error, then runs the original block.

Solution

1
use proc_macro::TokenStream;
2
use quote::quote;
3
use syn::{parse_macro_input, ItemFn, LitStr};
4

5
/// `#[warn_deprecated("use X instead")]` warns before running the body.
6
#[proc_macro_attribute]
7
pub fn warn_deprecated(attr: TokenStream, item: TokenStream) -> TokenStream {
8
    let message = parse_macro_input!(attr as LitStr);
9
    let input = parse_macro_input!(item as ItemFn);
10
    let vis = &input.vis;
11
    let sig = &input.sig;
12
    let block = &input.block;
13
    let name = &sig.ident;
14

15
    quote! {
16
        #vis #sig {
17
            eprintln!("WARNING: `{}` is deprecated: {}", stringify!(#name), #message);
18
            #block
19
        }
20
    }
21
    .into()
22
}

1
use log_attr::warn_deprecated;
2

3
#[warn_deprecated("call `checkout_v2` instead")]
4
fn checkout() -> &'static str {
5
    "ok"
6
}
7

8
fn main() {
9
    println!("checkout = {}", checkout());
10
}

Running cargo run -p app prints:

1
WARNING: `checkout` is deprecated: call `checkout_v2` instead
2
checkout = ok

Exercise 3: A route attribute that generates a sibling function

Difficulty: Hard

Objective: Recreate the #[get("/path")] attribute from the Real-World Example: keep the handler intact and generate a <name>_route() helper returning ("GET", path).

Instructions:

Parse attr as a LitStr (the path) and item as an ItemFn (the handler).
Build a new identifier <name>_route with quote::format_ident!.
Emit the original function unchanged (interpolate the whole #input) plus the generated helper.
Call both the handler and its generated _route function from main.

Solution

1
use proc_macro::TokenStream;
2
use quote::quote;
3
use syn::{parse_macro_input, ItemFn, LitStr};
4

5
/// `#[get("/path")]` keeps the handler and generates `<name>_route()`.
6
#[proc_macro_attribute]
7
pub fn get(attr: TokenStream, item: TokenStream) -> TokenStream {
8
    let path = parse_macro_input!(attr as LitStr);
9
    let input = parse_macro_input!(item as ItemFn);
10

11
    let name = &input.sig.ident;
12
    let route_fn = quote::format_ident!("{}_route", name);
13

14
    quote! {
15
        #input
16

17
        pub fn #route_fn() -> (&'static str, &'static str) {
18
            ("GET", #path)
19
        }
20
    }
21
    .into()
22
}

1
use log_attr::get;
2

3
#[get("/users")]
4
fn list_users() -> String {
5
    "[\"ada\", \"linus\"]".to_string()
6
}
7

8
fn main() {
9
    let (method, path) = list_users_route();
10
    println!("mounted {method} {path} -> {}", list_users());
11
}

Running cargo run -p app prints:

1
mounted GET /users -> ["ada", "linus"]

Attribute Macros

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

The attribute macro signature

Parsing with syn

Generating with quote

Seeing the expansion

Key Differences

Common Pitfalls

Pitfall 1: Forgetting proc-macro = true

Pitfall 2: Applying the attribute to the wrong kind of item

Pitfall 3: Expecting the macro to inspect types

Pitfall 4: Generating code that does not compile

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1: A #[timed] attribute

Exercise 2: An attribute that reads an argument

Exercise 3: A route attribute that generates a sibling function

Parsing with `syn`

Generating with `quote`

Pitfall 1: Forgetting `proc-macro = true`

Exercise 1: A `#[timed]` attribute