problem

Yew applications lack a native solution for managing page metadata. Titles, descriptions, social cards and icons typically require manual DOM manipulation, leading to repetitive code and limited SEO support.

motivation

While building Yewi Kit, I realised the ecosystem lacked a first-class approach to document head management. Rather than treating SEO as an afterthought, I wanted metadata to become part of the page definition through a declarative, Rust-native API. The project also became an opportunity to explore Rust metaprogramming through procedural macros and compile-time code generation.

solution

Built Yewi SEO as a document head management framework combining typed runtime APIs with procedural macros. Pages declare metadata using the #[seo(...)] attribute, while helper macros generate and synchronise meta tags, Open Graph properties, Twitter Cards, icons and links automatically.

decisions

• Separated compile-time procedural macros from the runtime crate.
• Designed a declarative API centred around #[seo(...)] instead of imperative DOM updates.
• Provided helper macros such as apply_meta!, apply_open_graph!, apply_twitter_card!, apply_link! and apply_icon! for fine-grained control.
• Used strongly typed metadata structures to minimise invalid configurations at compile time.
• Designed the framework to remain extensible as new metadata standards emerge.

challenges

• Keeping metadata synchronised with Yew's client-side router.
• Handling error conditions and edge cases gracefully.
• Supporting multiple metadata standards while maintaining a consistent developer experience.

lessons

• Procedural macros can eliminate boilerplate while preserving readability and type safety.
• Separating compile-time generation from runtime behaviour leads to a cleaner architecture.
• Learning Rust metaprogramming deepened my understanding of token streams, AST transformations and compile-time code generation.
• Strongly typed metadata structures allow for more robust error handling and type-safe configuration.