blueprint-gem

name	blueprint-gem
description	Work with Blueprinter gem for JSON serialization in Ruby. Covers fields, views, associations, transformers, extractors, and configuration. Use when creating, modifying, or debugging blueprints.

<essential_principles>

Blueprints are JSON object presenters - they transform Ruby objects into simple hashes for JSON serialization. They are NOT models, NOT decorators. Keep them focused on presentation logic only. Use views to provide different serialization contexts for the same blueprint. Don't create separate blueprint classes when views suffice. Views can include other views and exclude fields. Use `fields` (plural) for multiple simple attributes. Use `field` (singular) only when you need a block, renaming, or options. This keeps blueprints concise.

# Good - concise
fields :id, :name, :email, :created_at

# Only use singular when needed
field :full_name do |user|
  "#{user.first_name} #{user.last_name}"
end

`identifier` fields always render in every view (they have their own implicit `:identifier` view). Use for primary keys and unique identifiers only.

</essential_principles>

<quick_reference>

```ruby class UserBlueprint < Blueprinter::Base identifier :id

fields :email, :name, :created_at end

Usage

UserBlueprint.render(user) # JSON string UserBlueprint.render_as_hash(user) # Ruby Hash

</pattern>

<pattern name="computed-field">
```ruby
field :full_name do |user|
  "#{user.first_name} #{user.last_name}"
end

# With options access
field :display_name do |user, options|
  options[:admin] ? user.admin_name : user.public_name
end

```ruby association :company, blueprint: CompanyBlueprint association :posts, blueprint: PostBlueprint, view: :summary ``` ```ruby view :extended do fields :phone, :address association :orders, blueprint: OrderBlueprint end

Usage

UserBlueprint.render(user, view: :extended)

</pattern>

<pattern name="conditional-field">
```ruby
field :salary, if: ->(field_name, user, options) { options[:show_salary] }
field :age, unless: ->(field_name, user, options) { user.hide_age? }

</quick_reference>

What do you need help with?

1. Create a new blueprint
2. Understand a specific concept (views, associations, transformers, etc.)
3. Debug a blueprint issue
4. Something else

For option 2, specify the concept and I'll load the relevant reference.

| Response | Action | |----------|--------| | 1, "create", "new" | Read `workflows/create-blueprint.md` | | 2, "fields", "identifier" | Read `references/fields-and-identifiers.md` | | 2, "views", "view" | Read `references/views.md` | | 2, "association", "nested" | Read `references/associations.md` | | 2, "config", "configure", "setup" | Read `references/configuration.md` | | 2, "transformer", "extractor" | Read `references/transformers-and-extractors.md` | | 2, "conditional", "default", "if", "unless" | Read `references/conditionals-and-defaults.md` | | 3, "debug", "issue", "problem" | Read `references/anti-patterns.md` first | | 4, other | Clarify need, then select appropriate reference |

After reading, apply the knowledge to the user's specific situation.

<reference_index>

Core Concepts:

• fields-and-identifiers.md - Fields, identifiers, computed fields, field options
• views.md - Views, include/exclude, view inheritance
• associations.md - Nested blueprints, polymorphic associations

Advanced:

• configuration.md - Global config, JSON generators, field sorting
• transformers-and-extractors.md - Custom transformers and extractors
• conditionals-and-defaults.md - Conditional fields, defaults, nil handling

Troubleshooting:

• anti-patterns.md - Common mistakes and how to fix them

</reference_index>

<workflows_index>

Workflow	Purpose
create-blueprint.md	Create a new blueprint with proper structure
</workflows_index>