Getting Started

Installation

Add Panko to your Gemfile:

gem "panko_serializer"

Then install it:

bundle install

Panko needs Ruby 3.4 or newer and ActiveSupport 7.2 or newer. It is pure Ruby, so there is no native extension to build.

Creating your first serializer

A serializer is a subclass of Panko::Serializer that declares which attributes and associations to emit:

class PostSerializer < Panko::Serializer
  attributes :title
end

class UserSerializer < Panko::Serializer
  attributes :id, :name, :age

  has_many :posts, serializer: PostSerializer
end

Serializing an object

Create the serializer, then pass the object to serialize:

# => a JSON String
PostSerializer.new.serialize_to_json(Post.first)

# => a Ruby Hash with string keys
PostSerializer.new.serialize(Post.first)

Use serialize_to_json when you want JSON, and serialize when you want a Hash (for example, to nest inside a larger structure).

Serializing a collection

For arrays and ActiveRecord relations, use Panko::ArraySerializer with each_serializer::

users = User.all

Panko::ArraySerializer.new(users, each_serializer: UserSerializer).to_json

Using serializers in a controller

Putting it together in a Rails controller:

class UsersController < ApplicationController
  def index
    users = User.includes(:posts).all
    render json: Panko::ArraySerializer.new(users, each_serializer: UserSerializer).to_json
  end
end

And that’s a Panko-serialized endpoint.

Preload associations you serialize (User.includes(:posts) above) so serialization doesn’t trigger N+1 queries.

Next steps

  • Serializers: the full Panko::Serializer / Panko::ArraySerializer API, including context and scope.
  • Attributes and Associations: the serializer DSL in depth.
  • Filters: serialize a subset of attributes.
  • Response: compose serialized output into a larger JSON response.
  • Compiling at boot: for servers that fork workers (Puma or Unicorn with preload_app).


Copyright © 2026 Panko Serializer. Distributed under the MIT License.

This site uses Just the Docs, a documentation theme for Jekyll.