DEV Community: Adrien Poly

Deploying a Rails App with Kamal on Hetzner: A Beginner's Guide

Adrien Poly — Fri, 09 Jun 2023 19:37:31 +0000

Hello there!

I was curious about Kamal and wanted to give it a try to host a simple application on a cheap VPS. With this guide, I'll walk you through the process step by step that I used to create and deploy your first Rails application with KAMAL on a Hetzner VPS.

For this tutorial, we'll keep things as simple as possible. We'll deploy an application that uses an SQLite database.

What you will need first:

a Docker account with an Api key
an Hetzner account

Assuming you have that ready you should be able to deploy you first app with Kamal in less than 10 minutes

Scaffold a Rails Application

First, let's scaffold an application. At the time of writing this guide, it's important to use the --main flag to use the Rails 7.1 alpha version.



new rails_kamal_hetzner -a propshaft --main -c tailwind -j esbuild
cd rails_kamal_hetzner
bundle add tailwindcss-rails
bin/rails tailwindcss:install
git add .
git commit -m "rails new"
rails g scaffold post title:string content:text
rails db:create db:migrate

Next, you'll need to update your routes.



# config/routes.rb
-  # root "articles#index"
+  root "posts#index"

Create a VPS on Hetzner

Now that we have a basic app set up, let's create a VPS on Hetzner. You'll need to navigate through the sign-up and confirmation process, after which you can create a new project from your account.

For this tutorial, we'll select the CAX11, one of the most affordable VPS options with 2vCPU and 4GB RAM.

Please note that at the time of writing, KAMAL does not support IPv6, so you need to retain IPv4.

You'll also need to add an SSH key to your server. Here's how to copy and paste the key:



pbcopy < ~/.ssh/id_rsa.pub

Then test your SSH access to the server with this command:



ssh root@your_server_ip

If you encounter the prompt, "Are you sure you want to continue connecting (yes/no/[fingerprint])?", answer 'yes'.

If you're unable to SSH into the server, you'll need to resolve this issue before proceeding further.

Deploying with KAMAL

With our application and server ready, it's time to put KAMAL into action. First, install it with the following command:



gem install kamal

Then run kamal init. This will create several files, including config/deploy.yml and .env.

In the .env file, update the RAILS_MASTER_KEY value and the KAMAL_REGISTRY_PASSWORD with a key created in your Docker account.

Next, update the config/deploy.yml file as follows:



service: rails_hetzner_kamal

image: adrienpoly/rails_hetzner_kamal

servers:
  - hetzner_ip_v4

registry:
  username: adrienpoly
  password:
    env: KAMAL_REGISTRY_PASSWORD
env

:
  secret:
    - RAILS_MASTER_KEY
ssh:
  user: root # important to change it here as by default Kamal use app and Hetzner root

You can omit the other files for now. Commit your changes and then run the command to bootstrap servers with curl and Docker.



kamal server bootstrap

Once this operation is successful, you can execute your first deploy with kamal deploy. The first deployment might take a few minutes and should conclude with a successful health check message.

At this point, you should be able to visit the IP address in a browser and see your Rails app! Et voilà!

Persisting the Data

Well well well, not really voilà yet. If you create a Post and make a new deployment, you'll notice that the data is lost. This happens because the SQLite database is running inside the Docker image by default. Each time a new container is built, it erases the data.

To solve this, you need to add a volume to the Docker container. In the config/deploy.yml file, add this line:



volumes:
  - "storage:/rails/storage"

Now, the data is written outside of the container and persists across deploys.

And that's it! You've deployed your first Rails application with KAMAL on a Hetzner VPS.

Happy deploying!

[15-11-2023] Updated to reflect the name change from MRSK to Kamal

PS : Here is my referral link if you want to test Hetzner https://hetzner.cloud/?ref=gyPLk7XJthjg it gives you a 20€ credit to test

StimulusJS 2.0 silencing depreciation message

Adrien Poly — Sun, 06 Dec 2020 21:54:05 +0000

Stimulus 2.0

🚀 The long expected Stimulus 2.0 is Out. The upgrade from 1.1.1 to 2.0 should be very smooth as they are very minimal breaking changes.

Mute the data-target depreciation message in production

The data-target API has changed. While the 1.1 version is still supported. There is a warning message in the console every time an old syntax is seen for the first time.

The best way to fix this of course is to update all data targets but in a large code base this can take some time.

Another solution to gradually update your code is to silence the warning in production.

Here is a snippet to help

import { Application } from 'stimulus'
import { definitionsFromContext } from 'stimulus/webpack-helpers'

const application = Application.start()

// remove Stimulus depreciation warnings in production
if (process.env.NODE_ENV === 'production') {
  application.logger = { ...application.logger, warn: () => {} }
}

Introducing Stimulus-use composable behaviors for your controllers

Adrien Poly — Tue, 19 May 2020 16:51:38 +0000

TL;DR : it is not React hooks for Stimulus, just a simple way to add new behaviors and lifecycle methods to your controllers.

From the early days of Stimulus, I enjoyed the simplicity and elegance of this modest framework. Nice conventions, simple and flexible API and not the least very robust.

Motivations

In the past I explored several ways to create standard controllers either wrappers of libraries stimulus-flatpickr or stimulus-conductor. While the first got a bit of traction mostly due to the popularity of Flatpickr, very few standard Stimulus controllers really stand out from the crowd.

I spent some time recently doing quite a bit of React and got to discover the hooks and among them the react-use library.

While in no way I ambition to bring full-blown hooks to Stimulus, I think there is a sweet spot for having composable modules that can enhance with new behaviors your controllers.

Stimulus-use

So with this in mind, I imagined Stimulus-use. For now, it is a modest set of new behaviors (your can think of lifecycle events too) that you can add to your controller. For this initial release, it adds only a few behaviors but the objective was to get it out, show it, get it tested and get feedbacks on the overall API.

Extend or Compose

All new behavior are available either as a Controller that you can extend.

import { IntersectionController } from 'stimulus-use'

export default class extends IntersectionController {
  appear(entry) {
    // triggered when the element appears within the viewport
  }
}

Or as useFunction you can use when you want to enhance your controller with a new behavior or compose several new ones into a single Controller.

import { Controller } from 'stimulus'
import { useIntersection, useResize } from 'stimulus-use'

export default class extends Controller {
  connect() {
    useIntersection(this)
    useResize(this)
  }

  appear(entry) {
    // triggered when the element appears within the viewport
  }

  resized({ height, width }) {
    // trigered when the element is resized
  }
}

Future & vision

While I don't think all behaviors available in React-use would make sens in Stimulus, quite a few are interesting and can be ported in a Stimulus way to this project. Things like idle, visible, windowResize, clipboard, lazyImage, localStorage, animations, clipboard etc.

While things tends to move slowly within Stimulus core (and I don't think it is a real issue as long as the list of issues remains close to nil) and as more and more people are getting into Stimulus we see definitely a need for more examples and standard patterns.
Some great projects such as :

are really helping

I hope this project can bring together more contributors so that we can all create in a more agile way some enhancement to Stimulus that would be :

Standard, (stop reinventing the wheel)
Battle tested
Polyfilled
Documented
easy to use and compose with existing code

All contributions/contributors are welcome just ping me here or on the issues/PR Stimulus-use

stimulus-use / stimulus-use

A collection of composable behaviors for your Stimulus Controllers

A collection of composable behaviors for your Stimulus Controllers

New lifecycle behaviors: adds new standard behaviors to your Stimulus controllers.
Composable: compose at will different behaviors in a single controller with mixins.
Modular: built as ES6 modules, just import what you need and tree shaking will remove the rest.
Typescript: Types available, better autocompletion.
Tiny: 3k gzip + tree shaking 🌳🌳🌳

Getting Started

Stimulus 3

If you want to use stimulus-use with Stimulus 3 you can use the version 0.50.0+. This and all future versions are designed to work with the @hotwired/stimulus npm package.

Note: If other packages still depend on the stimulus npm package you can safely keep that in your package.json, this won't break the stimulus-use compability.

Using npm

npm i stimulus-use @hotwired/stimulus

Using yarn

yarn add stimulus-use @hotwired/stimulus

Stimulus 2 and below

If you want to use stimulus-use with Stimulus…

View on GitHub

Animations with Turbolinks and Stimulus

Adrien Poly — Wed, 13 May 2020 03:26:31 +0000

When using CSS animations with Turbolinks, you may experience page blink during page load. We will see how we can easily change that using the life cycle events of a Stimulus controller.

Turbolinks preview

When navigating back, Turbolinks will first display a preview of the page that was stored in the local cache and then replace this preview by the server response. This give the instant page load feeling effect of Turbolinks.

This preview comes from a snapshot taken locally by Turbolinks during the previous visit. Two things must be considered :

The preview has the state of the animations when you left the page.
If your animations are meant to start on page load then they will most probably start when the preview page is displayed

Those are typically two sources of blink effect when using animations with Turbolinks.

The first one because the page preview displays the page with the animations already played but then resets it when the preview is replaced by the real server response.

The second because if the animations start on the page preview then once the page preview is replaced, the animation will be reset. So either the animation is played twice or partially during first load.

Solution

Lets assume a typical controller where you play an animation on an element during after page load.

export default class extends Controller {
  connect() {
    this.element.classList.add("play-animation")
  }
}

1) Ignore preview

Adding simple helper can tell you if you are on a preview page on not

get isPreview() {
  return document.documentElement.hasAttribute("data-turbolinks-preview");
}

So now during connect we can easily know if we are in a preview or not. If we are in a preview we shouldn't play the animation as it would most likely be interrupted/play twice

export default class extends Controller {
  connect() {
    if (!this.isPreview) {
      this.element.classList.add('play-animation')
    }
  }

  get isPreview() {
    return document.documentElement.hasAttribute('data-turbolinks-preview')
  }
}

2) Tear down before snapshot

The goal is to bring back the page to its initial state before snapshot. For this we will use the disconnect() function that occurs right before the Turbolinks snapshot and simply remove animations that we may have played.

disconnect() {
  this.element.classList.remove('play-animation')
}

So a typical complete solution would look like this

export default class extends Controller {
  connect() {
    if (!this.isPreview) {
      this.element.classList.add('play-animation')
    }
  }

  disconnect() {
    this.element.classList.remove('play-animation')
  }

  get isPreview() {
    return document.documentElement.hasAttribute('data-turbolinks-preview')
  }
}

Happy Stimulus 🦄

Dynamic module import with Stimulus JS

Adrien Poly — Mon, 11 May 2020 21:12:32 +0000

Scoped behavior by default

Being built on top of the mutation observer, Stimulus Controllers are only loaded once a data-controller="my-controller" is visible within the DOM.

This is a great way to scope JS behavior to an element within a page.

With the typical Webpack loader, all the Controllers are bundled within the pack.

// src/application.js
import { Application } from "stimulus"
import { definitionsFromContext } from "stimulus/webpack-helpers"

const application = Application.start()
const context = require.context("./controllers", true, /\.js$/)
application.load(definitionsFromContext(context))

Importing large ES modules

When importing very large JS library you might want to only load them only on pages where the controller is used to avoid loading too much JS on other pages.

One nice feature of Webpack is the ability to dynamically load modules.

Using the lifecycle of Stimulus Controllers you can stick you dynamic import right into the initialize() or connect() function.

Here is and example to dynamically load moment

import { Controller } from "stimulus";

export default class extends Controller {

  connect() {
    import("moment").then(moment => {
      this.moment = moment.default;
    });
  }

  doSomething() {
    const formatedTime = this.moment().format("dddd, MMMM Do YYYY, h:mm:ss a");
  }
}

and a working demo

A praise to Microbundle

Adrien Poly — Sun, 10 May 2020 13:02:43 +0000

Microbundle is a zero-configuration bundler for tiny modules, powered by Rollup and created by Jason Miller the inventor of Preact.

I tested it in the past on a few projects and was always impressed by the ease of use and the performances. Out of all bundlers I tested, Microbundle has always been the one delivering the smallest builds.

Microbunlde v0.12 was released few days ago this was a good opportunity to test it again and I have to say that I am SOLD !!!

I am working on a typescript library project. My bundler was a mix of Typscript transpiller, Babel and Rollup. Lots of settings I had no clue about and lots of time spent trying to tune it.

I switch to Microbundle and it:

Worked out of the box
Removed at least 10 packages from my package.json
Reduced the build size by 2
Delivers out of the box umd, CommonJS/Node, types and module builds

🙏 🙏 Thanks Jason & team 👏👏

Jason Miller 🦊⚛Follow

Composable Stimulus Controllers?

Adrien Poly — Sat, 09 May 2020 22:16:33 +0000

Quite some time ago I wrote a simple Stimulus wrapper for Flatpickr. I learned a lot while doing this project. One of my initial goal was to explore the possibility of having standard controllers with in the Stimulus world. Controllers anyone could use to avoid reinventing the wheel every time.

Stimulus by default is a modest (yet powerful) framework. The list of available standard controllers is also rather modest.

Beside a few exceptions I don't have the feeling they are widely used. While many factors can explain it, for me the missing ability to compose multiple simple behavior within a controller has been a major obstacle of adoption.

I have been recently looking into this and made a few prototypes. Would love to have feedbacks if anyone already tackled this problem

Have you made in your projects some reusable, shareable and composable Controllers ?

Hey.com / New front end paradigm / What is DHH cooking?

Adrien Poly — Mon, 10 Feb 2020 16:23:00 +0000

DHH announced last week a very promising new email service from Basecamp

// Detect dark theme var iframe = document.getElementById('tweet-1225487645268160512-857'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1225487645268160512&theme=dark" }

Earlier DHH mentioned some new technics for optimizing front end (simpler code/faster)

// Detect dark theme var iframe = document.getElementById('tweet-1212930897357479937-971'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1212930897357479937&theme=dark" }

Hey.com is built using this new approach and DHH will present it at Rails conf.

// Detect dark theme var iframe = document.getElementById('tweet-1225504208465670147-604'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1225504208465670147&theme=dark" }

What are your guesses?

Critical CSS with Rails and Webpacker - SprocketsLess Part 1

Adrien Poly — Mon, 02 Sep 2019 20:09:26 +0000

This is the first of hopefully a series of articles on new advanced usage available when moving all assets to Webpacker. In the first part, we will look into optimizing your CSS size.

We all want fast & reliable web pages. When doing a Page Speed Audit what often comes up as a recommendation is critical CSS. Critical CSS and especially above the fold critical CSS is the ability to inline (in the HTML) the minimal CSS required to render the top of your page (above the fold). I have for some time looked into an easy solution to achieve this in a Rails app but I was never really successful at it.

One of the great thing with Webpack (ie Webpacker in Rails) is all of the echo systems around it. While the JS side in Rails is largely documented they are also lots of tools available for CSS & images.

A few months ago I discovered a great video from GoRails for using PurgeCss in a Rails application.

Understanding PurgeCSS

The global concept of PurgeCSS is that on one side you feed PurgeCSS with all of your files where you would have some CSS class used (usually .html, html.erb, .js). PurgesCSS create a list of all token that could be CSS selectors.

On the other side Webpacker create a CSS bundle using the mini-css-extract-plugin. PurgeCSS extract a list of tokens

The result is the intersection of those two lists of tokens.

Multiple Pack with Multiple Rules

With Webpacker it is easy to have multiple packs. You just need to create a new some-pack.js file in app/javascript/packs directory.

The global idea of what we are going to do is:

Define a second pack critical.js with only some CSS import in it.
Split our PurgesCss process in PostCss to apply much stricter rules for critical.css.
Inline our Critical CSS in the HTML as Dev.to is doing by the way.
Lazy load our main application.css.

Our critical.js entrypoint

Given an application.js that would look something like this:

// app/javascript/packs/application.js

require("@rails/ujs").start();
require("local-time").start();
require("turbolinks").start();

window.Rails = Rails;

// import CSS
import "stylesheets/application.scss";

// import Stimulus controllers
import "controllers/index";

// import vendor JS
import "bootstrap";

Our main entry point, import our main application.scss that usually look something like that:

// app/javascript/stylesheets/application.scss

// Fonts
@import "config/fonts";

// Graphical variables
@import "config/colors";

// Vendor
@import "~bootstrap/scss/functions";
@import "config/bootstrap_variables";
@import "~bootstrap/scss/bootstrap";

$fa-font-path: "~@fortawesome/fontawesome-free/webfonts";
@import "~@fortawesome/fontawesome-free/scss/fontawesome";
@import "~@fortawesome/fontawesome-free/scss/brands";

// Components
@import "components/index";

// layouts
@import "layouts/sticky-footer";

We can create a very basic critical.js, the only thing it will do is to import a new critical.scss stylesheet.

// app/javascript/packs/critical.js
import "stylesheets/critical.scss";

In our critical.scss file we can start to be a little more selective as what we put inside to help PurgeCSS make a better job. (it does make a small difference)

// colors
@import "config/colors";

// vendor
@import "~bootstrap/scss/functions";
@import "config/bootstrap_variables";
@import "config/bootstrap_critical"; // pick only the Bootstrap module you need

// Components
@import "components/banner"; //just pick the components you need for the homepage

PostCSS / PurgeCSS configuration

Then this is the important part. We need to tell PurgeCSS to apply different rules per files. Luckily we have a context full of information in PostCSS.

So we can pass our information context to the environment:

module.exports = ctx => environment(ctx);

Add a context variable to our envrionment

const environment = ctx => ({
  plugins: [
    require("postcss-import"),
    require("postcss-flexbugs-fixes"),
    require("postcss-preset-env")({
      autoprefixer: {
        flexbox: "no-2009"
      },
      stage: 3
    }),
    purgeCss(ctx)
  ]
});

Call our PurgeCss plugin with this context

const purgeCss = ({ file }) => {
  return require("@fullhuman/postcss-purgecss")({
    content: htmlFilePatterns(file.basename),
    defaultExtractor: content => content.match(/[A-Za-z0-9-_:/]+/g) || []
  });
};

And now that we have the filename in PurgeCss, we can specify different rules for each file. For my critical CSS, I specify only pages related to the home page and the usual set of patterns for all other files.

const htmlFilePatterns = filename => {
  switch (filename) {
    case "critical.scss":
      return [
        "./app/views/pages/index.html.erb",
        "./app/views/shared/_navbar.html.erb",
        "./app/views/layouts/application.html.erb"
      ];
    default:
      return [
        "./app/**/*.html.erb",
        "./config/initializers/simple_form_bootstrap.rb",
        "./app/helpers/**/*.rb",
        "./app/javascript/**/*.js"
      ];
  }
};

So in full, it looks like that

// postcss.config.js

const environment = ctx => ({
  plugins: [
    require("postcss-import"),
    require("postcss-flexbugs-fixes"),
    require("postcss-preset-env")({
      autoprefixer: {
        flexbox: "no-2009"
      },
      stage: 3
    }),
    purgeCss(ctx)
  ]
});

const purgeCss = ({ file }) => {
  return require("@fullhuman/postcss-purgecss")({
    content: htmlFilePatterns(file.basename),
    defaultExtractor: content => content.match(/[A-Za-z0-9-_:/]+/g) || [],
  });
};

const htmlFilePatterns = filename => {
  switch (filename) {
    case "critical.scss":
      return [
        "./app/views/pages/index.html.erb",
        "./app/views/shared/_navbar.html.erb",
        "./app/views/layouts/application.html.erb"
      ];
    default:
      return [
        "./app/**/*.html.erb",
        "./config/initializers/simple_form_bootstrap.rb",
        "./app/helpers/**/*.rb",
        "./app/javascript/**/*.js"
      ];
  }
};

module.exports = ctx => environment(ctx);

Results

In a small test I did I had those results

Initial bundle size of 32kb
With purge CSS this dropped to 9kb
My critical.css only 3kb!

BAMMMMM 🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉🎉

Inline CSS from Webpacker

I did scratch my head a bit to inline my CSS file in the HTML. Thanks to Stackoverflow I could get some help here

<% if current_page?(root_path) %>
  <!-- Inline the critical CSS -->
  <style>
    <%= File.read(File.join(Rails.root, 'public', Webpacker.manifest.lookup('critical.css'))).html_safe %>
  </style>

  <!-- Lazy load the rest with loadCSS -->
  <link rel="preload" href="<%= Webpacker.manifest.lookup('application.css') %>" as="style" onload="this.rel='stylesheet'">
  <noscript><link rel="stylesheet" href="<%= Webpacker.manifest.lookup('application.css') %>"></noscript>
<% else %>
  <%= stylesheet_pack_tag 'application', 'data-turbolinks-track': 'reload' %>
<% end %>

Et voila!!!!

Demo: https://sprockets-less-rails6.herokuapp.com
Source code: https://github.com/adrienpoly/sprockets-less-rails6

Rails 6.0.0 beta1 released

Adrien Poly — Sat, 19 Jan 2019 10:21:04 +0000

Hey

Rails 6.0.0 beta1 has just been released 🎉 🚀.

TL;DR

Webpacker

Webpack is now the official JS bundler, Sprockets remains the recommended asset pipeline for static assets (images) and CSS.

New Frameworks

It includes 2 new frameworks:

Action Text : to easily add rich content support to your app
Action MailBox : to easily route incoming emails

Even more scalable

2 major features for scaling:

Parallel testing: speeds up your testing suite in multicores environment
Multiple database: Simple API to support multiple database with Active Records

and lots of other improvements

The complete release note

https://weblog.rubyonrails.org/2019/1/18/Rails-6-0-Action-Mailbox-Action-Text-Multiple-DBs-Parallel-Testing/

Step by Step guide to test Rails ActiveText

Adrien Poly — Thu, 04 Oct 2018 13:34:13 +0000

🚧❌ EDITED ActionText is now fully released in Rails 6 don't follow this guide that was written for the preview version

You might have seen the video of DHH about ActionText upcoming feature in Rails 6. This is a step by step guide for creating the exact same example as in the video.

⚠️ If like me you never ran an edge version of Rails before and wonder how to do it then this is for you

Create a new app from the Edge version of Rails

Clone the Rails repo

git clone https://github.com/rails/rails.git
cd rails
bundle install

Create a new app with Rails Edge, YABE (YABE: Yet Another Blog Example)

We will want to create a new app within the same directory and using the locally installed Rails generator

#move out of rails folder first
cd ..

#create the app with the local rails generator and the edge flag to use GH master branch
rails/railties/exe/rails new yabe --edge

cd yabe

Start the app

⚠️ remember to always use the local rails command: bin/rails

bin/rails s

Visit http://localhost:3000

You should now have the rails startup screen showing

Rails version: 6.0.0.alpha 🎉🎉

Installing ActionText

Add the ActionText gem (and image variants for active Storage):

# Gemfile
gem "actiontext", github: "rails/actiontext", require: "action_text"
gem "image_processing", "~> 1.2" # for Active Storage variants

Install gem, assets, npm dependency, and migrations

bundle install
bin/rails action_text:install
bin/rails db:migrate

Scaffold Post

bin/rails g scaffold post title:string
bin/rails db:migrate

Add a rich text field to Post

# app/models/post.rb
class Post < ApplicationRecord
  has_rich_text :content
end

Active Text brings a polymorphic model under the hood for managing RichText

Add a field to your form

<%= form.rich_text_area :content %> : rich_text_area is the new content type to display Trix

<%#app/views/posts/_form.html.erb %>
<%= form_with(model: post) do |form| %>
  …
  <div class="field">
    <%= form.label :content %>
    <%= form.rich_text_area :content %>
  </div>
  …
<% end %>

finally, display the rich text on a page:

<%= @post.content %>

Update the strong params in PostsController

def post_params
  params.require(:post).permit(:title, :content)
end

Start blogging

http://localhost:3000/posts

My 2 cents

My first take out was to use an edge version of Rails.
With regards to ActiveText I am impressed with how simple it is to now add rich text editing in a Rails app.
I love Trix don't get me wrong but I would like to have a layer of abstraction to potentially have other front-end solution for the Editor.

Introducing Stimulus-Flatpickr wrapper 📅

Adrien Poly — Wed, 12 Sep 2018 12:30:46 +0000

I really enjoyed using Stimulus JS since it has been released early this year. For once I can now easily organize my JS code without pulling a full-blown frontend framework.

Stimulus-flatpickr wrapper started as an experiment, I needed to use Flatpickr in a project and built a Stimulus Controller for it. I quickly realized that it could make sense to have a generic Stimulus controller for this library.

Today we will demonstrate this package through a simple, yet interesting example. I have worked quite a bit recently with date pickers and realized that it is always very simple to convert a field to a date pickers but they are many small details required to make it a real easy to use solution.

The goal is to create a basic booking system where the user:

can only select available dates (the ones already booked must be disabled)
gets a datepicker in his language
see a date in the input field in the locale format
see a list of all bookings
all of this playing nicely in a Single Page Application

the stack is rather simple: Rails, Stimulus, Turbolinks, and Flatpickr for the date picking solution.

At the end we won't have any Ajax at all and less than 10 lines of Javascript to do this 🎉🎉🎉

Lets get started: New app and stimulus setup

They are several tutorials out there, I won't get into all the details but settings up Stimulus in your Rails app if you already have webpack installed is as simple as that:

rails webpacker:install:stimulus

This will add Stimulus package to your package.json, adds the initialization code in your main application.js file and a new controllers directory under javascript for all of your new Stimulus controllers

You can read this article for more details about setting up Stimulus in your rails

For today's demo, we are going to create a brand new app

  rails new --webpack=stimulus stimulus-flatpickr

...and don't forget to add the packs

  #app/views/layouts/application.html.erb
  ...
  <%= stylesheet_pack_tag    'application', media: 'all', 'data-turbolinks-track': 'reload' %>
  <%= javascript_pack_tag 'application', 'data-turbolinks-track': 'reload' %>
  ...

Appointment Model and Controller

We are doing a booking engine. We need an Appointment model with a single column a start_at date and a scope method to get the up_comings appointments for the next n days (we can only book for the next 60 days).

#models/appointment.rb
class Appointment < ApplicationRecord
  validates :start_at, uniqueness: true

  scope :up_comings, ->(nb_days) {
                       where('start_at >= ? AND start_at < ?',
                             Time.zone.now,
                             Time.zone.now + nb_days.days).order(start_at: :asc)
                     }
end

Our controller is pretty standard (for simplicity we only handle the success path here 👶, no error managment)

class AppointmentsController < ApplicationController
  before_action :set_appointment, only: %i[update destroy]

  def index
    @appointments = Appointment.up_comings(60)
    @appointments_dates = @appointments.pluck(:start_at)
    @appointment = Appointment.new
  end

  def create
    redirect_to appointments_path if Appointment.create(appointment_params)
  end

  def update
    redirect_to appointments_path if @appointment.update(appointment_params)
  end

  def destroy
    @appointment.destroy
    redirect_to appointments_path
  end

  private

  def set_appointment
    @appointment = Appointment.find(params[:id])
  end

  def appointment_params
    params.require(:appointment).permit(:start_at)
  end
end

stimulus-flatpickr controller

As per the documentation we are going to create a Stimulus controller that will extend the generic stimulus-flatpickr controller.

First, let's add the packages that we will need

  yarn add stimulus-flatpickr

and add the new controller

// ./controllers/flatpickr_controller.js
import Flatpickr from "stimulus-flatpickr";
import "flatpickr/dist/themes/dark.css";

// creates a new Stimulus controller by extending stimulus-flatpickr wrapper controller
export default class extends Flatpickr {}

The views

Lets put a small structure to have the booking form on the left and the up comings appointments list on the right.

#app/views/appointments/index.html.erb
<div class="main">
  <h2><%= t ".title" %></h2>
  <div class="row">
    <div class="col">
      <h3><%= t ".new" %></h3>
      <%= render "form", appointment: @appointment %>
    </div>
    <div class="col">
      <h3><%= t ".appointments" %></h3>
      <%= render @appointments %>
    </div>
  </div>
</div>

#app/views/appointments/_appointment.html.erb
<div class="appointments">
  <%= render "form", appointment: appointment %>
  <%= link_to "x", appointment_path(appointment), method: :delete%>
</div>

and our form where all the magic will happen 🎉

#app/views/appointments/_form.html.erb
<%= form_with model: appointment do |f| %>
  <%= f.text_field :start_at,
      data: {
        controller: "flatpickr",
        flatpickr_min_date: Time.zone.now,
        flatpickr_max_date: Time.zone.now + 60.days,
        flatpickr_disable: Appointment.up_comings(60).pluck(:start_at),
      } %>
<% end %>

This is the important part to understand :

We defined a flatpickr_controller.js so whenever an HTML element has a data-controller="flatpickr" attribute, then the stimulus controller will enter into action.

So here in the view, data: { controller: "flatpickr" } will be converted to data-controller="flatpickr" and therefore convert the field into a datepicker.

We can also pass options to the datepicker using the same data attributes(data-flatpickr-the-kebab-case-option-name). Here we set a min and max date to disable everything before today and everything after today + 60 days.

Also, we prepare for the next step where we will disable the dates that are already booked by passing an array of the current bookings.

Submit on select

Lets automatically submit whenever a user selects a date (not perfect UX! I know, it is mostly for simple demo purpose).
The flatpickr controller has all the official flatpickr hooks available (open, close, change etc). Here we need to submit the form when the value has changed. So let's override the change() function.

export default class extends Flatpickr {
  // automatically submit form when a date is selected
  change(selectedDates, dateStr, instance) {
    const form = this.element.closest("form");
    Rails.fire(form, "submit");
  }
}

Going Live

At this point we have the following result:

We start to have something interactive.... The cool thing is that Turbolinks being installed by default kicks in automatically and Ajaxify all links. All Stimulus controllers are by designed working with Turbolinks. So there is nothing else to do here, it just works!. No custom Ajax call or SRJ to have this SPA look and feel. 💪 🚀 ❤️

Localizing the date picker and the date format

We have a SPA look & feel and the availabilities for our booking engine. The next step is to localize it correctly. Currently, it is only in English and the date format if rather ugly 2018-09-12 👎.

date formats

The stimulus-flatpickr wrapper offers a nice bonus feature over the standard library, it will convert strftime date formats to flatpickr custom date formats.

So to customize the date format we can pass the local format directly to the date picker like this:

data: {
  controller: "flatpickr",
  flatpickr_alt_input: true,
  flatpickr_alt_format: t("date.formats.long"),
  flatpickr_default_date: appointment.start_at,
  flatpickr_disable: @appointments_dates - [appointment.start_at],
  flatpickr_min_date: Time.zone.now,
  flatpickr_max_date: Time.zone.now + 60.days,
}

flatpickr_alt_format: t("date.formats.long") -> will output "%B %d, %Y" when the locale is :en and "%e %B %Y" when the locale is :fr and this gets converted automatically to the nearest flatpickr format. As DRY as it can be 🎉!

Translations

We now have almost everything. The last point is to correctly translate the datepicker for every locale.

We are going to import the different locales in our stimulus controller. Every time time Turbolinks silently replace the content of the page, the initialize() function is of the stimulus controller is called. This is where we are going to set our local and pass it to flatpickr.

Our final controller looks like this

import Flatpickr from "stimulus-flatpickr";

// import a theme (could be in your main CSS entry too...)
import "flatpickr/dist/themes/dark.css";

// import the translation files and create a translation mapping
import { French } from "flatpickr/dist/l10n/fr.js";
import { english } from "flatpickr/dist/l10n/default.js";

// create a new Stimulus controller by extending stimulus-flatpickr wrapper controller
export default class extends Flatpickr {
  locales = {
    fr: French,
    en: english
  };

  initialize() {
    //set the locale and also sets the global flatpickr settings  
    this.config = {
      locale: this.locale,
      altInput: true,
      showMonths: 2,
      animate: false
    };
  }

  // automatically submit form when a date is selected
  change(selectedDates, dateStr, instance) {
    const form = this.element.closest("form");
    Rails.fire(form, "submit");
  }

  get locale() {
    if (this.data.has("locale")) {
      return this.locales[this.data.get("locale")];
    }
  }
}

That's all folks!

You can find the entire demo project here 👉 https://github.com/adrienpoly/rails_stimulus_flatpickr

and more important the stimulus-flatpickr wrapper 👉 https://github.com/adrienpoly/stimulus-flatpickr

I hope you enjoyed this introduction. I personally think we will see more and more standard Stimulus controllers and the Rails community will more and more drop Gems used for front end packages only.

I am not senior dev with tons of experience so feel free to Comments, issues, PR. They are all welcome and if you feel this package is useful for you, leave it a star ⭐

Happy Coding 🎉