Templatus is an opinionated template to build web applications with Ruby on Rails and Hotwire. It simplifies the process of setting up a new application while following best practices.
Live demo available at https://templatus-hotwire.ledermann.dev
There are two sister repositories:
- For using Vue.js instead of Hotwire: https://github.com/templatus/templatus-vue/
- For using Inertia and Svelte.js instead of Hotwire: https://github.com/templatus/templatus-inertia/
- Ruby 4.0
- Ruby on Rails 8.1
- ActionCable for WebSocket communication
- PostgreSQL for using as SQL database
- Sidekiq for background processing
- Pagy with keyset (cursor) pagination for endless scrolling with constant query time
- Redis for Caching, ActionCable, and Sidekiq, each on its own database
- Hotwire for building the frontend without using much JavaScript by sending HTML instead of JSON over the wire
- TypeScript for static type checking in Stimulus controllers and other script code
- ViewComponent for building reusable, testable & encapsulated view components
- Tailwind CSS 4 to not have to write CSS at all
- daisyUI 5 for semantic component classes and a themeable color system (custom light and dark theme, switchable between light/dark/system)
- Lucide icons via Iconify for Tailwind, rendered as CSS masks (no runtime JS, CSS is emitted only for the icons actually used)
- Vite for bundling JavaScript and CSS with Hot Module Replacement (HMR) in development
- Bun as package manager for JavaScript dependencies
- Caddy for automatic HTTPS on
.localhostdomains in development - Overmind for starting up the application locally (Procfile handling like Foreman)
- dotenv to load environment variables from .env into ENV
- Prettier for auto-formatting JavaScript, TypeScript and CSS in Visual Studio Code
- Herb for linting and formatting ERB templates, including Tailwind class sorting
- Ruby LSP with RuboCop for auto-formatting Ruby code in Visual Studio Code
- Lookbook as development UI for ViewComponent
- annotaterb for annotating models and routes
- Live reloading
- RuboCop for Ruby static code analysis
- ESLint for JavaScript static code analysis
- ShellCheck for linting shell scripts
- Brakeman for static security analysis of Rails code
- bundler-audit and
bun auditfor checking dependencies against known vulnerabilities - size-limit to keep the compiled JavaScript below a fixed budget
- RSpec for Ruby testing
- Factory Bot for setting up Ruby objects as test data
- Capybara with Playwright for system tests
- Docker for production deployment, NOT for development
- DockerRailsBase for fast building an optimized Docker image based on Alpine Linux
- GitHub Actions for testing, linting, and building Docker image
- Dependabot configuration for updating dependencies (with auto-merge), grouped per toolchain and with a cooldown that matches Bun's
minimumReleaseAge, so freshly published (and possibly malicious) versions are never installed right away - Ready for serving assets via CDN like CloudFront
- Honeybadger for error tracking in Ruby and JavaScript
- RorVsWild for performance monitoring
- Plausible for privacy friendly analytics
- Lockup to place a staging server behind a basic codeword
- Lograge for single-line logging
- Gzip and Brotli compression of dynamic responses (HTML, JSON) using Rack::Deflater, Rack::Brotli
- Fine-tuned Content Security Policy (CSP)
- Ready for PWA (manifest, service-worker)
This template is developed with optimized performance and security in mind. The following benchmarks are performed against the demo installation on production. It uses an inexpensive virtual server on the Hetzner Cloud behind a Traefik setup.
100% in all categories.
215 KB of compiled JavaScript (minified, uncompressed). The largest parts are:
- Turbo with ActionCable (72 KB)
- Stimulus (32 KB)
- Honeybadger (25 KB)
There is no JavaScript for icons at all: they are CSS masks generated at build time, and only for the icons actually used.
$ SECRET_KEY_BASE_DUMMY=1 RAILS_ENV=production bin/rails assets:precompile
bun install v1.3.14 (0d9b296a)
Checked 222 installs across 266 packages (no changes) [14.00ms]
vite v8.1.5 building client environment for production...
/*! 🌼 daisyUI 5.6.18 */
✓ 47 modules transformed.
computing gzip size...
public/vite/manifest.json.br 0.26 kB
public/vite/assets/logo-DdqaqAN0.svg.br 0.26 kB
public/vite/manifest.json.gz 0.30 kB
public/vite/assets/logo-DdqaqAN0.svg.gz 0.30 kB
public/vite/assets/rolldown-runtime-QTnfLwEv.js.br 0.37 kB
public/vite/assets/rolldown-runtime-QTnfLwEv.js.gz 0.42 kB
public/vite/assets/logo-DdqaqAN0.svg 0.49 kB │ gzip: 0.30 kB
public/vite/manifest.json 1.00 kB │ gzip: 0.30 kB
public/vite/assets/application-_WYGBmFW.js.br 1.61 kB
public/vite/assets/application-_WYGBmFW.js.gz 1.89 kB
public/vite/assets/application-RQtmhSlY.css.br 12.77 kB
public/vite/assets/application-RQtmhSlY.css.gz 14.85 kB
public/vite/assets/vendor-njP3BUuM.js.br 49.30 kB
public/vite/assets/vendor-njP3BUuM.js.gz 56.31 kB
public/vite/assets/application-RQtmhSlY.css 91.05 kB │ gzip: 14.98 kB
public/vite/assets/rolldown-runtime-QTnfLwEv.js 0.69 kB │ gzip: 0.42 kB
public/vite/assets/application-_WYGBmFW.js 4.80 kB │ gzip: 1.89 kB
public/vite/assets/vendor-njP3BUuM.js 209.83 kB │ gzip: 57.41 kB
Small footprint: The demo application transfers only 62 KB of (compressed) data on the first visit.
With multi-stage building and using DockerRailsBase the build of the Docker image takes very little time. Currently, the build job requires about 1,5 minutes on GitHub Actions (see https://github.com/templatus/templatus-hotwire/actions)
The Docker image is based on Alpine Linux and is optimized for minimal size (currently 117 MB uncompressed disk size). It includes just the bare minimum - no build tools like Node.js, no JS sources (just the compiled assets), no tests.
$ container-diff analyze ghcr.io/templatus/templatus-hotwire -n
-----Size-----
Analysis for ghcr.io/templatus/templatus-hotwire:
IMAGE DIGEST SIZE
ghcr.io/templatus/templatus-hotwire sha256:... 116.7M
- Clone the repo locally:
git clone git@github.com:templatus/templatus-hotwire.git
cd templatus-hotwire- Install PostgreSQL, Redis, Caddy, Overmind and ShellCheck (if not already present). On a Mac with HomeBrew, run this to install from the
Brewfile:
brew bundle- Let Caddy install its local certificate authority, so HTTPS works without browser warnings:
caddy trust- Setup the application to install gems and JavaScript packages and create the database:
bin/setup- Start the application locally:
bin/devThen open https://templatus.localhost in your browser.
bin/devThen open https://templatus.localhost/lookbook/ in your browser.
RuboCop:
bin/rubocop
ESLint:
bun run lint
TypeScript:
bun run tsc
ERB (linting, formatting and validation with Herb):
bin/herb lint
bun run erb:check # or `bun run erb:format` to fix
bin/herb analyze .
Shell scripts:
shellcheck $(git ls-files '*.sh')
All of the above (plus security scans, the JavaScript size budget and the test suite), exactly as CI runs it:
bin/ci
Ruby tests:
bin/rspec
open coverage/index.html
System tests with Capybara and Playwright:
bin/rspec spec/system
docker network create public
docker compose up