The Ruby/Rack port of Better Auth
Learn more about upstream Better Auth

Website · Issues

Better Auth Ruby is a Ruby port of Better Auth, the framework-agnostic authentication and authorization library from the TypeScript ecosystem.

The goal is upstream-compatible HTTP behavior with idiomatic Ruby internals: Rack first, Rails friendly, and tested against the upstream Better Auth source and test suite as the source of truth. This repository keeps the upstream project as a submodule under upstream/ and tracks port status in .docs/features/ and .docs/plans/.

This port is active work. Many server-side flows are implemented, but not every upstream edge case, adapter dialect, or TypeScript-only API has full parity yet.

# Gemfile
gem "better_auth-rails"

bundle install
bin/rails generate better_auth:install

# config/routes.rb
Rails.application.routes.draw do
  better_auth
end

# Gemfile
gem "better_auth"

require "better_auth"

auth = BetterAuth.auth(
  secret: ENV.fetch("BETTER_AUTH_SECRET"),
  base_url: "http://localhost:3000",
  database: BetterAuth::Adapters::Memory.new
)

run auth

# Gemfile
gem "better_auth-sinatra"

require "sinatra/base"
require "better_auth/sinatra"

class App < Sinatra::Base
  register BetterAuth::Sinatra

  better_auth at: "/api/auth" do |config|
    config.secret = ENV.fetch("BETTER_AUTH_SECRET")
    config.base_url = ENV.fetch("BETTER_AUTH_URL")
    config.database = ->(options) {
      BetterAuth::Adapters::Postgres.new(options, url: ENV.fetch("DATABASE_URL"))
    }
  end
end

Legend:

• Supported: implemented in Ruby with local tests.
• Not supported: not implemented or intentionally outside the Ruby server scope.
• Partial: implemented for the main Ruby server path, with documented upstream parity gaps.

Plugin support is tracked against Ruby server parity: TypeScript inference, browser helper packages, and native mobile client behavior are treated as out of scope only when the row says so explicitly.

Upstream Better Auth exposes many provider factories. The Ruby port currently ships the most common factories and the generic OAuth plugin can cover custom providers.

git clone --recursive https://github.com/sebasxsala/better-auth.git
cd better-auth
make install
make ci

cd packages/better_auth
bundle install
bundle exec rake test

cd packages/better_auth-sso
rbenv exec bundle exec rake

cd ../better_auth-api-key
rbenv exec bundle exec rake

cd ../better_auth-scim
rbenv exec bundle exec rake

cd ../better_auth-stripe
rbenv exec bundle exec rake

cd ../better_auth-oauth-provider
rbenv exec bundle exec rake

The upstream docs app has been copied into docs/ and is being adapted for Ruby/Rack/Rails. Pages that still contain upstream TypeScript examples include a warning callout at the top.

Ruby-first starter pages are available under docs/content/docs/introduction.mdx, docs/content/docs/installation.mdx, docs/content/docs/basic-usage.mdx, docs/content/docs/concepts/database.mdx, docs/content/docs/integrations/rack.mdx, docs/content/docs/integrations/rails.mdx, and docs/content/docs/integrations/sinatra.mdx.

better-auth/
├── upstream/                   # Submodule: upstream TypeScript Better Auth
├── docs/                       # Adapted upstream docs app
├── packages/
│   ├── better_auth/            # Core gem, Minitest
│   ├── better_auth-api-key/    # External API key plugin gem
│   ├── better_auth-rails/      # Rails adapter, RSpec
│   ├── better_auth-sinatra/    # Sinatra adapter, RSpec
│   ├── better_auth-sso/        # External SSO plugin gem
│   ├── better_auth-scim/       # External SCIM plugin gem
│   ├── better_auth-stripe/     # External Stripe plugin gem
│   └── better_auth-oauth-provider/ # External OAuth provider plugin gem
├── .docs/
│   ├── features/               # Feature parity notes
│   └── plans/                  # Port implementation plans
├── Gemfile
├── Rakefile
└── Makefile

• canary: day-to-day development; open PRs here.
• main: stable line; releases and CI publish run from here when versions bump.
• upstream/: git submodule and reference only.

git checkout canary
git pull origin canary
git checkout -b feat/my-change
# ... commit ...
git push -u origin feat/my-change
# Open PR to canary

Releases are automated with GitHub Actions on push to main when version.rb changes. The Rails adapter is published as both better_auth-rails and better_auth_rails as a compatibility alias; the Sinatra adapter publishes as better_auth-sinatra.

Details: RELEASING.md.

Dry-run locally:

make release-check

1. Fork the repo.
2. Branch from canary.
3. Read AGENTS.md and the relevant package instructions.
4. Run make ci before pushing.
5. Open a PR to canary.

Report vulnerabilities to security@openparcel.dev. See SECURITY.md.

MIT License