Gems banner

Create Ruby Gem by Example

There's no doubt the critical role ruby gems play in rails app development. Think of devise, active admin and the rest. Yet with all these, few developers get to create their own gems. Perhaps because of lack clear docs on practical approach. But at some point, an RoR developer maybe tasked with modifying a gem or creating one; at least once. Today, I walk you through creating a Ruby gem by example. We'll be creating an API wrapper around The TVDB. You can check out the gem thetvdb-ruby here

Getting Started

We'll use Bundler, a popular tool for managing project dependencies. Let's get it installed.

$ gem install bundler

With bundler set up, we'll create our gem. I'll name it thetvdb

$ bundle gem thetvdb

Then change directory into the gem

$ cd thetvdb

If you list the items in the gem folder, you should see the following: gem structure


Of interest for now is the gemspec file, in my case thetvdb.gemspec. It defines the configuration of your gem. I'll go ahead and add meta data about thetvdb gem


Versioning for a gem is kept in the lib directory, under the gem name file in a script called version.rb (in our case lib/thetvdb/version.rb). The 3 digit string is divided by dots with the format 'X.X.X'


Now we're getting to the gem functionality. First off, I'll go ahead and add two dependencies that we'll use i.e rest-client and nokogiri to our Gemfile
Then go ahead run bundler

$ bundle install

Call those two dependencies in lib/thetvdb.rb file. Note, I've also required the gem version
I'll then go ahead and create a file client.rb inside /lib/thetvdb folder. The file will handle our API wrapper query. In the end, it's content will have the following

get_show method returns the show details together with its episodes.

Note ruby constant API_KEY, I'm parsing it as the token. At this point we haven't declared the constant. We need users to generate an initizlier file on installing the gem and then add their TVDB api key. To do that, we'll create a generator Inside /lib folder create a directory generators. Inside /generators, create thetvdb_genrator.rb file. Add the following contents
The second line source_root points to where our generator templates will be placed. Go ahead and create a folder templates inside generators DIR as well. Create a file thetvdb.rb inside the templates folder with the following contents
Finally, require client.rb in our main file /lib/thetvdb.rb. We'll eventually have the following


To get build the gem, we'll use the command

$ gem build thetvdb.gemspec

Once built we can push to ruby gems gem push
Or if you want to test it locally first, you can install it

$ gem install thetvdb-ruby-0.1.0.gem


To test if our gem is working fine, create a rails app then add this to your Gemfile
Then run bundler

$ bundle install

Generate initializer file for TVDb API

$ rails generate thetvdb

Place your API key on the generated thetvdb.rb file in initializers. You can use my API key if you don't have one.
In some controller action, I called the Thetvdb get_show method searching for my favorite TV show “The Amazing Race”
On loading localhost, I get a json response with the show details and its episodes. gem push

By Victor Areba

Blog pic
I am a passionate Rubyist. This is a platform where I share what I have learned over the years in matters Ruby, Rails, JavaScript and other related technologies. I also write non technical stuff particulary creative writing here Inkulumo. I enjoy swimming and watching movies.


27 September 2015
Wow nice gem.Keep up the Good work!.
01 October 2015
Very nice post! One tiny question about the initializer: require 'thetvdb' API_KEY = "9EF1D1E7D28FDA0B" I can't wrap my why this works! Intuitively I would have thought that you should first define API_KEY and only after you should require the file. To me API_KEY is just 'floating' in the initializer file and isn't even supposed to be defined in Client. Obviously this works but I would love to hear more about what's going on here... Thanks!.
Victor Areba
07 October 2015
@Anonymous after running the command $rails generate thetvdb, what will be generated will is a filed named thetvdb.rb in initializers with the contents require 'thetvdb' API_KEY = "Your API Key". So basically you'll replace "Your API Key" with actual TVDb key, I did explain there that I provided my API key so users can easily test this..

Login to post your comment