Skip to content

QUICK_START.md

Latest commit

 

History

History
380 lines (267 loc) · 6.79 KB

QUICK_START.md

File metadata and controls

380 lines (267 loc) · 6.79 KB

Quick Start Guide: Building & Publishing the PDFify Ruby Gem

Overview

This gem wraps your PDFify API to make it super easy for developers (like vroom) to integrate HTML-to-PDF conversion.

Development & Testing (Local)

Step 1: Install Dependencies

cd pdfify-ruby
bundle install

Step 2: Build the Gem

gem build pdfify.gemspec

Output:

Successfully built RubyGem
Name: pdfify
Version: 0.1.0
File: pdfify-0.1.0.gem

Step 3: Install Locally for Testing

gem install ./pdfify-0.1.0.gem

Step 4: Test with PDFify Server

Start your PDFify Rails server first:

cd ../pdfify
rails s

Get an API token:

cd ../pdfify
rails runner "puts ApiToken.first&.token || 'No tokens found. Create one in the dashboard.'"

Run the test script:

cd ../pdfify-ruby
ruby test_example.rb

Or test in IRB:

irb
require 'pdfify'

PDFify.configure do |config|
  config.api_key = "pfy_test_xxxxxxxx"  # Your actual token
  config.base_url = "http://localhost:3000"
end

pdf = PDFify.convert(html: "<h1>Hello World!</h1>", test: true)
File.binwrite("test.pdf", pdf)
exit

Check the generated test.pdf file!

Publishing to RubyGems.org

Prerequisites

  1. Create RubyGems account: https://rubygems.org/sign_up

  2. Set up credentials:

# Get your API key from https://rubygems.org/profile/edit
curl -u YOUR_USERNAME https://rubygems.org/api/v1/api_key.yaml > ~/.gem/credentials

# Secure it
chmod 0600 ~/.gem/credentials

Step 1: Prepare for Release

Update gemspec with your details:

Edit pdfify.gemspec:

spec.authors       = ["Your Actual Name"]
spec.email         = ["[email protected]"]
spec.homepage      = "https://github.com/yourusername/pdfify-ruby"
spec.summary       = "Ruby client for PDFify HTML-to-PDF API"

Check all files are ready:

ls -la

You should see:

  • ✓ lib/pdfify.rb
  • ✓ lib/pdfify/version.rb
  • ✓ lib/pdfify/configuration.rb
  • ✓ lib/pdfify/client.rb
  • ✓ pdfify.gemspec
  • ✓ README.md
  • ✓ LICENSE.txt
  • ✓ CHANGELOG.md
  • ✓ Gemfile

Step 2: Build the Gem

gem build pdfify.gemspec

This creates pdfify-0.1.0.gem.

Step 3: Push to RubyGems

gem push pdfify-0.1.0.gem

Expected output:

Pushing gem to https://rubygems.org...
Successfully registered gem: pdfify (0.1.0)

Step 4: Verify

Visit: https://rubygems.org/gems/pdfify

You should see your gem listed!

Step 5: Install from RubyGems

Now ANYONE can install it:

gem install pdfify

Or in a Gemfile:

gem 'pdfify', '~> 0.1.0'

Releasing Updates

When you add new features or fix bugs:

1. Update Version

Edit lib/pdfify/version.rb:

module PDFify
  VERSION = "0.2.0"  # Bump version
end

2. Update Changelog

Edit CHANGELOG.md:

## [0.2.0] - 2026-02-15

### Added
- New feature X
- New feature Y

### Fixed
- Bug fix Z

3. Build & Push

gem build pdfify.gemspec
gem push pdfify-0.2.0.gem

Version Numbering (Semantic Versioning)

Format: MAJOR.MINOR.PATCH

  • PATCH (0.1.0 → 0.1.1): Bug fixes, no new features
  • MINOR (0.1.0 → 0.2.0): New features, backward compatible
  • MAJOR (0.9.0 → 1.0.0): Breaking changes, not backward compatible

Examples:

  • Fixed a typo: 0.1.0 → 0.1.1
  • Added webhook support: 0.1.0 → 0.2.0
  • Changed API interface: 0.9.0 → 1.0.0

Emergency: Unpublish a Version

If you accidentally published a broken version:

gem yank pdfify -v 0.1.0

Warning: Only do this for critical bugs. Users who already installed will keep the old version.

Using in the Vroom App

Replace DocRaptor

Old (DocRaptor):

# Gemfile
gem 'docraptor'

# config/initializers/docraptor.rb
DocRaptor.configure do |config|
  config.username = Rails.application.secrets.DOCRAPTOR_API_KEY
end

# lib/core/pdf_output.rb
docraptor = DocRaptor::DocApi.new
pdf = docraptor.create_doc(
  document_content: html,
  document_type: "pdf",
  test: Rails.env.development?
)

New (PDFify):

# Gemfile
gem 'pdfify'

# config/initializers/pdfify.rb
PDFify.configure do |config|
  config.api_key = Rails.application.secrets.PDFIFY_API_KEY
  config.base_url = "https://api.pdfify.example.com"  # Your production URL
end

# lib/core/pdf_output.rb
pdf = PDFify.convert(
  html: html,
  test: Rails.env.development?
)

That's it! Drop-in replacement.

Gem File Structure

pdfify-ruby/
├── lib/
│   ├── pdfify.rb                    # Main entry point
│   └── pdfify/
│       ├── version.rb               # VERSION constant
│       ├── configuration.rb         # Config class
│       └── client.rb                # HTTP client
├── pdfify.gemspec                   # Gem metadata
├── Gemfile                          # Development dependencies
├── README.md                        # Full documentation
├── LICENSE.txt                      # MIT license
├── CHANGELOG.md                     # Version history
├── QUICK_START.md                   # This file
└── test_example.rb                  # Test script

Generated when you build:
├── pdfify-0.1.0.gem                 # The actual gem file

Checklist Before Publishing

  • Tested locally with ruby test_example.rb
  • Updated version in lib/pdfify/version.rb
  • Updated CHANGELOG.md
  • Updated author/email in pdfify.gemspec
  • Created RubyGems account
  • Set up ~/.gem/credentials
  • Built gem: gem build pdfify.gemspec
  • Ready to push: gem push pdfify-0.1.0.gem

Troubleshooting

"Cannot find gem pdfify"

Make sure you installed it:

gem install ./pdfify-0.1.0.gem

"Failed to connect to PDFify API"

Make sure your PDFify server is running:

cd pdfify
rails s

"Invalid API key"

Get a token from your Rails app:

cd pdfify
rails runner "puts ApiToken.first.token"

"Permission denied when pushing to RubyGems"

Check your credentials:

cat ~/.gem/credentials
chmod 0600 ~/.gem/credentials

"Gem name already taken"

Choose a different name in pdfify.gemspec:

spec.name = "pdfify-client"  # Or something unique

Next Steps

  1. ✓ Build the gem locally
  2. ✓ Test it with your PDFify server
  3. ✓ Publish to RubyGems.org
  4. ✓ Integrate into vroom to replace DocRaptor
  5. ✓ Save $600-3,400/year!
  6. Share with the community

Resources

You're all set! Happy gem building!