use-facet-crates
Guidelines for using facet crates (facet-json, facet-toml, facet-args) instead of serde-based alternatives for consistent dogfooding
When & Why to Use This Skill
This Claude skill serves as a specialized technical guide and automation assistant for Rust developers transitioning from the Serde ecosystem to Facet-based crates. It facilitates 'dogfooding' by providing precise mapping for JSON, TOML, and CLI argument parsing, ensuring architectural consistency and promoting the use of internal libraries over external dependencies within a workspace.
Use Cases
- 1. Library Migration: Streamlining the replacement of legacy crates like , , and with their counterparts in existing Rust projects.
- 2. Code Review & Standardization: Enforcing workspace-specific coding standards by identifying where Serde is used and suggesting the correct implementation.
- 3. Dependency Auditing: Scanning files to detect Serde-based dependencies and providing a roadmap for migrating to internal 'facet' alternatives to ensure self-sufficiency.
- 4. Developer Onboarding: Providing clear examples and documentation for new contributors on how to implement serialization and CLI parsing using the project's custom framework.
| name | use-facet-crates |
|---|---|
| description | Guidelines for using facet crates (facet-json, facet-toml, facet-args) instead of serde-based alternatives for consistent dogfooding |
Use Facet Crates Instead of Serde Ecosystem
When writing code in this workspace, prefer facet-based crates over serde-based ones. This project is building facet as a replacement for serde, so we should dogfood our own libraries.
Crate Replacements
| Instead of | Use | Notes |
|---|---|---|
serde |
facet |
Core derive and traits |
serde_json |
facet-json |
JSON serialization/deserialization |
toml |
facet-toml |
TOML parsing |
serde_yaml |
facet-yaml |
YAML support |
clap |
facet-args |
CLI argument parsing |
serde_derive |
facet (derive) |
#[derive(Facet)] replaces Serialize/Deserialize |
When to Use Which
Use facet-json for:
- New code in this workspace
- Internal tools (like benchmark-analyzer)
- Anything that doesn't need serde compatibility
serde_json is acceptable for:
- Interop with external crates that require serde
- Benchmarks comparing facet vs serde performance
- Code that specifically tests serde compatibility
Quick Example
// OLD (serde)
use serde::{Serialize, Deserialize};
use serde_json;
#[derive(Serialize, Deserialize)]
struct Config {
name: String,
}
let config: Config = serde_json::from_str(json)?;
// NEW (facet)
use facet::Facet;
use facet_json as json;
#[derive(Facet)]
struct Config {
name: String,
}
let config: Config = json::from_str(json)?;
Checking Dependencies
When adding new dependencies or reviewing code, check Cargo.toml for serde ecosystem crates and consider if facet alternatives exist.
TODO for This Workspace
The benchmark-analyzer currently uses serde_json for JSON serialization in chart data. This should be migrated to facet-json for consistency (eating our own dogfood).
Location: tools/benchmark-analyzer/src/report.rs - uses serde_json::to_string() for chart labels/data.