installation.md

Installation Guide

Requirements

• Ruby >= 3.2
• Rails >= 7.1

---

Add to Gemfile

gem "active_data_source"

Then choose your adapters (all are optional):

# Pagination (choose one)
gem "pagy"           # recommended
# gem "kaminari"
# gem "will_paginate"

# Filtering + Search (choose one)
gem "ransack"        # recommended (handles both filtering and search)
# gem "pg_search"    # PostgreSQL full-text search
# gem "searchkick"   # Elasticsearch/OpenSearch

# Authorization (optional)
gem "pundit"
# gem "cancancan"

# Multi-tenancy (optional)
gem "acts_as_tenant"
# gem "apartment"

# Serialization (choose one)
gem "blueprinter"          # recommended
# gem "jsonapi-serializer"
# gem "active_model_serializers"

bundle install

---

Generate Initializer

# Coming in a future version — for now create manually:
touch config/initializers/active_data_source.rb

# config/initializers/active_data_source.rb
ActiveDataSource.configure do |config|
  config.pagination    = :pagy
  config.search        = :ransack
  config.authorization = :pundit        # or :none to disable
  config.serializer    = :blueprinter   # or :none for plain JSON
  config.multi_tenancy = :none
  config.response_format = :json        # or :json_api or :graphql

  config.default_page_size = 25
  config.maximum_page_size = 200
end

---

Autoloading Resources

Add app/resources to your autoload paths so Rails loads your Resource classes:

# config/application.rb
config.autoload_paths += [Rails.root.join("app/resources")]

Or if using Zeitwerk (Rails 7+), put resources in app/resources/ and they'll be autoloaded automatically.

---

Testing

Install test gems:

group :test do
  gem "rspec-rails"
  gem "factory_bot_rails"
  gem "shoulda-matchers"
  gem "simplecov"
end

Include ADS matchers in your spec/rails_helper.rb:

RSpec.configure do |config|
  config.include ActiveDataSource::Testing::Matchers, type: :resource
end