🔍 Behind the Code: Crafting a Thoughtful .gemspec for Your Ruby Gem

April 16, 2025

Over the past few weeks, I’ve been working on a gem that integrates AI-powered buttons into the Trix editor using Stimulus: Trix-Genius. Along the way, I found myself reflecting on something that often gets overlooked: the humble .gemspec file.

Today, I want to share a breakdown of how I approached my .gemspec — and why it’s more than just boilerplate. Think of it as your gem’s elevator pitch to the Ruby ecosystem.

📦 What Is a .gemspec File?

A .gemspec file is the Ruby gem’s manifest. It defines metadata, dependencies, development tools, licensing, and file packaging. Without it, your gem is just code — unshippable and unknown to the world.

For trix-genius, here’s how I crafted the spec:

🧬 Anatomy of the Trix-Genius .gemspec

Gem::Specification.new do |s|
  s.name        = "trix-genius"
  s.version     = "0.1.4"
  s.summary     = "Integrates AI-powered buttons with Trix using Stimulus"
  s.description = "Trix-Genius adds AI-powered buttons and other custom controls to Trix editor using Stimulus."

💡 Tip: The summary is your quick pitch. The description dives deeper into value and purpose. Writing these well helps your gem stand out on RubyGems and GitHub.

👤 Author Metadata

 s.authors     = ["Giménez Silva Germán Alberto"]
  s.email       = "ggerman@gmail.com"

This builds trust and gives the community a point of contact for feedback or collaboration.

📁 Files and Structure

 s.files       = Dir["lib/**/*", "generators/**/*", "templates/**/*", "spec/**/*"]
  s.require_paths = ["lib"]

This section determines which files are packaged in the final gem. Using Dir[…] keeps things clean and avoids hardcoding each file path.

🌐 Project Links and Metadata

 s.homepage = "https://rubystacknews.com/..."
  s.metadata = {
    "source_code_uri" => "...",
    "changelog_uri" => "...",
    "documentation_uri" => "...",
    "bug_tracker_uri" => "...",
    "homepage_uri" => "...",
    "wiki_uri" => "..."
  }

These links turn your gem into a hub. They help others explore, understand, and contribute to your work.

🧱 Dependencies

 s.required_ruby_version = "~> 3.0"
  s.add_dependency "rails", ">= 6.0", "< 9.0"
  s.add_dependency "stimulus-rails", "~> 1.3"
  s.add_dependency "actiontext", "~> 8.0"
  s.add_dependency "faraday", "~> 2.12"
  s.add_dependency "yaml"

These declare what your gem needs to function properly. Setting Ruby and gem versions helps prevent compatibility issues and ensures your gem works as intended.

🧪 Development Dependencies

 s.add_development_dependency "rspec"
  s.add_development_dependency "generator_spec", "~> 3.0"

These are for building and testing the gem. They’re only used during development, so they don’t affect anyone installing your gem.

📜 License Declaration

s.license = "MIT"

Declaring a license like MIT signals that your gem is open to use, modification, and contribution — an important part of fostering community trust and adoption.