DEV Community: thomasvanholder

Create a modal with the HTML dialog element, Tailwind and Stimulus

thomasvanholder — Fri, 29 Jul 2022 08:24:00 +0000

Support for the dialog element is now widespread, with safari being the last of the main browsers to provide native support.

The dialog HTML element is an appealing choice for creating a modal as it comes with built-in functionality for opening and closing modals.

This tutorial uses Stimulus as a light-weight JavaScript framework. To learn more about Stimulus, visit the docs. When you use vanilla JS, you can mimic the data-action and data-target behavior in by utilizing the appropriate document.querySelectors and eventListeners instead.

The form and button styling are extrapolated to improve readability. See here for a full gist of the CSS, HTML and JS.

1. Add button and dialog
2. Close modal by esc key
3. Close modal by backdrop click
4. Reset form after modal close
5. Change default backdrop style
6. Add animation

1. Add button and dialog

To start, let's create a button and dialog element wrapped in a stimulus controller.



<div data-controller="modal">
  <button data-action="modal#open" class="btn-outline">Open modal</button>

  <dialog data-modal-target="modal">
    <button type="button" data-action="modal#close" class="absolute top-4 right-4">X</button>

    <h1>Reset your password</h1>

    <hr class="mb-4">

    <form class="space-y-4">
      <label>Email</label>
      <input type="text">

      <button type="button" data-action="modal#close" class="btn-outline">Close</button>
      <button type="button" class="btn-blue">Reset Password</button>
    </form>
  </dialog>
</div>

The corresponding stimulus controller is pretty barebones.



//app/javascript/controllers/modal_controller.js

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["modal"]

  open(event) {
    event.preventDefault();

    this.modalTarget.showModal();
  }

  close(event) {
    event.preventDefault();

    this.modalTarget.close();
  }
}

The showModal() method displays the modal on the top layer and adds a default background. Any interaction outside the dialog is inaccessible.
The close() method simply closes the dialog.

2. Close modal by esc key

This is an easy one. Closing the modal by escape key is included by default when utilising the dialog element. Nice!

3. Close modal by backdrop click

Remove all default padding on the dialog element to ensure only a background click triggers the closing of the modal.
Add padding on the h1 and form element instead.



<dialog data-modal-target="modal" class="p-0">
 ...
 <h1 class="p-4">Reset your password</h1>

 <form class="p-4 space-y-4">
   ...
 </form>
</dialog>

Add an eventListener that initiates after opening the modal to listen for the backdrop click.



export default class extends Controller {
  // ....
  open(event) {
    event.preventDefault();

    this.modalTarget.showModal();

    this.modalTarget.addEventListener('click', (e) =>  this.backdropClick(e));
  }

  backdropClick(event) {
    event.target === this.modalTarget && this.close(event)
  }
}

The backdropClick() method verifies if the clicked element is the dialog and, if so, closes the modal.

4. Reset form after modal close

The form still populates previously filled input after closing and re-opening the modal. To start the modal with empty inputs, add a form target and reset the form.



<form class="p-4 space-y-4" data-modal-target="form">
  ...
</form>



import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = ["modal", "form"]

  close(event) {
    event.preventDefault();

    this.modalTarget.close();

    this.formTarget.reset() // or find by id selector
  }
}

5. Change default backdrop style

Add the backdrop selector to the dialog html element.



<dialog class="p-0 backdrop:bg-gray-400 backdrop:bg-opacity-50">
 ...
</dialog>

6. Add animation

The default animation is quite abrupt and appears instantaneous on the screen. To make the transition smoother, let's add a fade-in custom animation with a duration of 0.5 seconds.

In the tailwind.config.js file, add a fade-in keyframe and animation. The effect can be applied using the animate-fade-in class.



module.exports = {
  // ... 
  theme: {
    extend: {
      keyframes: {
        "fade-in": {
          '0%': { opacity: '0%' },
          '100%': { opacity: '100%' },
        }
      },
      animation: {
        "fade-in": 'fade-in 0.5s ease-in-out',
      } 
    }
  }
}

Next, add the newly created animation to the dialog element using the open modifier: open:animate-fade-in.



<dialog data-modal-target="modal" class="p-0 backdrop:bg-gray-400 backdrop:bg-opacity-50 open:animate-fade-in">
 ...
</dialog>

You can easily add this animation to the backdrop as well: open:backdrop:animate-fade-in.



<dialog data-modal-target="modal" class="p-0 backdrop:bg-gray-400 backdrop:bg-opacity-50 open:animate-fade-in open:backdrop:animate-fade-in">
 ...
</dialog>

That's it! Using the dialog element simplifies creating modals by leveraging its build-in API features.

How to migrate rails sprockets to propshaft

thomasvanholder — Wed, 16 Mar 2022 16:08:21 +0000

Propshaft has a smaller scope than sprockets and requires you to rely on the js-bundling and css-bundling gems to handle the building of CSS and JS assets. Read the docs for an extensive upgrade guide.

To migrate from webpacker to js-bundling, you can read this article.

Depreciate Sprockets
Install Propshaft
Migrate Asset Helpers
Display inline SVG

1. Depreciate Sprockets

Remove the gem "sprockets" from Gemfile
Delete the config/assets.rb file
Delete the assets/config/manifest.js file

2. Install Propshaft

Add to Gemfile

gem "propshaft"

3. Migrate asset helpers

Replace asset helpers like image_url and font_url in css files with standard URLs because Sprockets uses absolute paths while Propshaft uses relative paths. Make sure to prepend the asset path with / to link to the asset.

/* old */
image_url("home.png")

/* new */
url("/home.png")

4. Display inline svg

Before Propshaft loading inline SVG requires to dump a long SVG content inline or to leverage a gem like inline_svg. Propshaft offers the ability to render inline svg's.

Rails.application.assets.load_path.find('logo.svg').content

How to turn on Rails 7 framework defaults (part 1)

thomasvanholder — Fri, 21 Jan 2022 09:39:06 +0000

This tutorial inspects turning on each setting of new_framework_defaults_7.0.rb file. The intended goal is to fully migrate to Rails 7's default set-up.

button_to_generates_button_tag
apply_stylesheet_media_default
verify_foreign_keys_for_fixtures

1. button_to_generates_button_tag

Rails.application.config.action_view.button_to_generates_button_tag = true

What

The button_to helper had inconsistent behaviour. Rails PR.

string argument: <input type="submit">
block argument: <button type="submit">

# 'new' is the string argument
<%= button_to "New", new_task_path %>

Before

<input type="submit" value="New">

After

<button type="submit">New</button>

2. apply_stylesheet_media_default

Rails.application.config.action_view.apply_stylesheet_media_default = false

What

A stylesheet_link_tag can specify a media type. When omitting a media attribute, screen is no longer set as the default media value Rails Guide.

<%= stylesheet_link_tag "application" %>

Before

<link rel="stylesheet" href="...css" media="screen">

After

<link rel="stylesheet" href="...css">

3. verify_foreign_keys_for_fixtures

Rails.application.config.active_record.verify_foreign_keys_for_fixtures = true

What

Ensures all foreign key constraints are valid after fixtures are loaded in tests. Rails PR

Before

# test/fixtures/parrots.yml
george:
  name: "Curious George"
  pirate: redbeard

# test/fixtures/pirates.yml
blackbeard:
  name: "Blackbeard"

Fixtures can refer to a missing association.
parrots(:george).pirate will be nil

After

An error is raised when fixtures are loaded in tests.
"Foreign key violations found in your fixture data. Ensure you aren't referring to labels that don't exist on associations."

How to set-up Rails Hotwire live reload

thomasvanholder — Sat, 08 Jan 2022 09:25:31 +0000

Install Gem
Run install script
Listen to file changes

This tutorial will explore a modern way to live-reload a rails app set-up with css-bundling (tailwind) and js-bundling (esbuild).

1. Install Gem

Add to Gemfile

group :development do
  gem "hotwire-livereload"
end

bundle install

2. Run install script

rails livereload:install

3. Listen to file changes

View, helpers, and assets files are listened for by default.

If you use rails's css-bundling and js-bundling gems, find the bundled JS and CSS file app/builds.

The app/builds folder includes:

app/builds/application.css
app/builds/application.js

An additional watch process is needed to re-build the JS and CSS file after changes (see docs). Tailwind, for example, uses a Just-in-time compiler to only add classes to the CSS that are being used in your application. This requires specifying an additional path to listen for any (Just-in-time) changes.

# config/environments/development.rb

config.hotwire_livereload.listen_paths << Rails.root.join("app/assets/builds")

How to upgrade your Rails app to Ruby 3.1 with rbenv

thomasvanholder — Wed, 29 Dec 2021 12:55:57 +0000

Ruby 3.1 release documentation

Upgrade rbenv
Install Ruby 3.1.0
Set local Ruby version
Update Gemfile
Debug gem
New features

1. Upgrade rbenv

To include Ruby 3.1 as one of the available install options, first upgrade ruby-build:

brew update && brew upgrade ruby-build

See all available versions with rbenv install --list.

Ruby 3.1.0 should return in the result.

2. Install Ruby 3.1.0

rbenv install 3.1.0

3. Set local Ruby version

rbenv local 3.1.0

You can verify that the .ruby-version file in the root of your folder now lists version 3.1.0.

4. Update Gemfile

# old
ruby "3.0.3"

# new
ruby "3.1.0"

Tip: You can link to the ruby .ruby_version file instead to read the ruby version. A single source defines the ruby version and you avoid a discrepancy between the gemfile and .ruby_version file to occur.

ruby File.read('.ruby-version').strip

bundle install

You might run into the error cannot load such file -- net/smtp (LoadError). net-smtp has been removed from the default gems in ruby 3.1. As Action Mailbox depends on net/smtp temporarily add to your gemfile until the mail gem includes it as a dependancy.

gem "net-smtp", require: false

5. Debug gem

The debug gem is the new preferred debugger. Alternative gems like pry are no longer necessary. Rails 7 includes the debug gem by default.

Gemfile:

group :development, :test do
  # old
  gem 'pry'
  # new
  gem "debug", ">= 1.0.0"
end

Learn more in this video

6. New Features

Error highlighting examples
IRB auto-completion
Typeprof examples / vs code extension / video
Short Syntax Hash Values examples

How to upgrade Rails 6.1 to Rails 7

thomasvanholder — Wed, 22 Dec 2021 13:51:08 +0000

Update rails in gemfile
Upgrade rails packages
Add sprockets to gemfile
Run update rails task
Verify framework defaults
Verify depreciated methods

How to upgrade an exising application to Rails 7. Note that Rails 7 requires Ruby 2.7.0 or newer.

1. Update rails in gemfile

# old
gem "rails", "~> 6.1.4"

# new
gem "rails", "~> 7.0.0"

In the terminal run:

bundle update

2. Upgrade rails packages

In the package.json file, find all @rails packages and upgrade then one by one. For example:

yarn upgrade @rails/actioncable --latest
yarn upgrade @rails/activestorage --latest
yarn upgrade @rails/request.js --latest

3. Add sprockets to gemfile

When you are using the asset pipeline, assets related errors can pop up when running a rails command.
Example:

# - Don't know how to build task 'assets:precompile'
# - 'method_missing': undefined method `assets'

Add sprockets to the gem file as it's now an optional depedency.

gem "sprockets-rails"

bundle install

4. Run update rails task

bin/rails app:update

This will prompt you file by file to integrate the new rails 7 defaults.

Example:
Overwrite .../config/boot.rb? (enter "h" for help) [Ynaqdhm]
Note: press h to see the menu options.

Go through every file to inspect the difference between the default set-up of rails 7 and your current configuration.

You can open the files in your editor to compare when selecting merge (m). If you run into the following error:
Please specify merge tool to 'THOR_MERGE' env
Run the app:update command again with your editor specified.

For example (vs code)

THOR_MERGE=code bin/rails app:update

After completing the set-up run rails db:migrate to migrate the newly added active storage migration file.

❗️ If you have set-up other environments, non-default enviroments, like staging.rb make sure to update that file too.

5. Verify framework defaults

After completing the bin/rails app:update from the step 4, Rails creates a new_framework_defaults_7.0.rb file in config/initializers. This file helps you to make a big upgrade a little easier by flipping on the new default settings one-by-one in multiple deployments.

The application.rb file's setting load_defaults specifies which rails version's default settings to load. This means you can temporarily utilize the default configuration settings from Rails 6.1 while running Rails 7.

# Initialize configuration defaults for originally generated Rails version.
config.load_defaults 6.1

Then, gradually turn on each setting and verify your application is still working as intended. Once you've switched on every setting, you can remove the new_framework_defaults_7.0.rb and flip the load_defaults version in application.rb to 7.0.

How to turn on Rails 7 framework defaults (part 1)

# Initialize configuration defaults for originally generated Rails version.
config.load_defaults 7.0

6. Verify depreciated methods

Your application might use other depreciated features. Read through the Rails 6.1 to Rails 7 section to identify and fix any methods call or settings that are no longer supported.

How to upgrade Tailwind 2 to Tailwind 3

thomasvanholder — Tue, 14 Dec 2021 10:51:41 +0000

In package.json file, verify your current installed tailwind version. Find tailwind's complete upgrade guide, including all minor changes here.

This tutorial has as starting point:

Tailwind 2.2.16

Upgrade tailwind
Upgrade typography package
Upgrade forms package
Upgrade autoprefixer package
Upgrade postcss package
Remove aspect-ratio package
Replace purge option with content
Remove dark mode config

1. Upgrade tailwind

yarn upgrade tailwindcss --latest

2. Upgrade typography package

yarn upgrade @tailwindcss/typography --latest

3. Upgrade forms package

yarn upgrade @tailwindcss/forms --latest

4. Upgrade autoprefixer package

yarn upgrade autoprefixer --latest

5. Upgrade postcss package

yarn upgrade postcss --latest

6. Remove aspect-ratio package

Tailwind 3 comes with native aspect-ratio (7:42). This implies that the package.json can be slimmed down by removing the aspect ratio package if you had it installed.

yarn remove @tailwindcss/aspect-ratio

In the tailwind.config.js file, remove aspect-ratio from the plugins.

require('@tailwindcss/aspect-ratio'),

Search your codebase for the usage of legacy aspect ratio.
Replace with the new aspect ratio attributes.

7. Replace purge option with content

If after compiling the CSS, you see the warning message:
The "purge"/"content" options have changed in Tailwind CSS v3.0.

Replace the purge option in tailwind.config.js with content as mentioned here.

// old
module.exports = {
  purge: [...]
  ...
}

//new
module.exports = {
  content: [...]
  ...
}

8. Remove dark mode config

In the tailwind.config.js file, remove the dark mode setting if it's value is set to false.

// old
module.exports = {
  darkMode: false,
  ...
}

//new
module.exports = {
  ...
}

How to migrate Rails UJS to Hotwire (Turbo)

thomasvanholder — Sat, 11 Dec 2021 09:10:53 +0000

See Hotwire handbook

Update hotwired/turbo-rails
Remove rails/ujs
Replace link_to delete
Replace link_to data confirm
Replace button data disable with
Set status response in controller

1. Update hotwired/turbo-rails

In package.json, update @hotwired/turbo-rails package to 7.1.0 (or greater)

 "@hotwired/turbo-rails": "^7.1.0"

2. Remove rails/ujs

From the package.json file

yarn remove @rails/ujs

From the application.js entry point

require("@rails/ujs").start() // remove this line

3. Replace link_to delete

method: :delete
becomes
data: {turbo_method: :delete}

<%# Old %>
<% link_to "Destroy", task_path(@task), method: :delete %>

<%# New %>
<% link_to "Destroy", task_path(@task), data: {turbo_method: :delete} %>

4. Replace link_to data confirm

data: {confirm: 'Are you sure?'}
becomes
data: {turbo_confirm: 'Are you sure?'}

<%# Old %>
<% link_to "Destroy", task_path(@task), method: :delete, data: {confirm: 'Are you sure?'} %>

<%# New %>
<% link_to "Destroy", task_path(@task), data: {turbo_method: :delete, turbo_confirm: 'Are you sure?'} %>

5. Replace button data disable with

In Rails UJS, a form's submit button can be disabled and its text replaced by adding the data disable_with attribute.

<%= f.button "Search", data: { disable_with: "Searching..."} %>

With Turbo, you can set the text content based on the parent's button disabled status. Source

button             .show-when-disabled { display: none; }
button[disabled]   .show-when-disabled { display: initial; }

button             .show-when-enabled { display: initial; }
button[disabled    .show-when-enabled { display: none; }

<button>
  <span class="show-when-enabled">Submit</span>
  <span class="show-when-disabled">Submitting...</span>
</button>

Or if you use Tailwind, you can leverage Tailwind's group and disabled status to create a similar effect.

<%= f.button class: "group" do %>
   <span class="group-disabled:hidden">Search</span>
   <span class="hidden group-disabled:block group-disabled:cursor-wait">Searching...</span>
<% end %>

6. Set status response in controller

Respond with a 303 status code

class TasksController
 ...

  def destroy
    @task = Task.find(params[:id])
    @task.destroy
    redirect_to tasks_path, info: "Task deleted", status: :see_other
  end 
end

Import Class in Relative File into Tailwind CSS and Rails

thomasvanholder — Sat, 04 Dec 2021 08:37:30 +0000

To import a relative CSS file into Tailwind, the postcss-import is required.

Install postcss-import
Add postcss-config file
Add postcss to build script
Create a button class
Swap tailwind directive for import
Extract button class into seperate file

1. Install postcss-import

yarn add postcss-import

2. Add postcss.config.file

postcss.config.js
module.exports = {
  plugins: [
    require('postcss-import'),
    require('tailwindcss'),
    require('autoprefixer'),
  ]
}

3. Add postcss to build:css script

In package.json add --postcss

old

{
  "scripts": {
    "build:css": "tailwindcss -i ./app/assets/stylesheets/application.tailwind.css -o ./app/assets/builds/application.css"
  }
}

new

{
  "scripts": {
    "build:css": "tailwindcss --postcss -i ./app/assets/stylesheets/application.tailwind.css -o ./app/assets/builds/application.css"
  }
}

4. Create a button class

Add a button component in application.tailwind.css

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer components {
  .btn-blue {
    @apply text-white bg-blue-500 rounded-lg hover:bg-blue-700;
  }
}

Let's see it we get a blue button

 <button type="button" class="btn-blue">Save</button>

5. Swap tailwind directive for import

/* old */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* new */
@import "tailwindcss/base";
@import "tailwindcss/components";
@import "tailwindcss/utilities";

6. Extract button class into seperate file

in application.tailwind.css

@import "tailwindcss/base";
@import "tailwindcss/components";
@import "./components/buttons.css";
@import "tailwindcss/utilities";

in ./components/buttons.css

@layer components {
  .btn-blue {
    @apply text-white bg-blue-500 rounded-lg hover:bg-blue-700;
  }
}

A few notes from the Tailwind docs:

Don't mix custom css and imports in the same file
Wrap custom css in @layer components to avoid specificity issues

Display content with the 'only' class in Tailwind CSS

thomasvanholder — Fri, 26 Nov 2021 07:15:58 +0000

With Tailwind's JIT release, developers can act up HTML elements that are in a specific state. The only class is practical addition to display a HTML element if it has no sibling HTML elements. Under the tailwind-hood, the only class translates into the only-child selector.

empy state
only:block
refactored

Empty state

Imagine you want to display content only if it is stored in the database. The initial step is to create a conditional statement to render parts of the HTML based on the condition you provide. In the rails example below, the conditional check is @tasks.empty?. If the @tasks collection is empty, the empty state message is displayed.

<ul>
  <% if @tasks.empty? %>
    <% @tasks.each do |task| %>
      <%= render "task/task", task: task %>
    <% end %>

  <% else %>
    <p class="block">All tasks completed.</p>
  <% end %>
</ul>

only:block

Now, although the code above definitely works, you have added a(nother) conditional to your code.

An alternative is to handle this natively with CSS.

<ul>
  <% @tasks.each do |task| %>
      <%= render "task/task", task: task %>
  <% end %>

  <p class="hidden only:block">All tasks completed.</p>
</ul>

The empty state's element (p-tag) has a default state of hidden. The added only class change the display status to block when the element has no siblings.

Refactored

Or leverage the rails collection renderer to re-factor your code into:

<ul>
  <%= render @tasks %>

  <p class="hidden only:block">All tasks completed.</p>
</ul>

Click label to choose radio button Tailwind CSS's peer class

thomasvanholder — Sat, 20 Nov 2021 08:08:20 +0000

With Tailwind's release of its Just-In-Time compiler, the peer class has been introduced. The peer class is practical when changing an HTML element's behavior based on a previous sibling's state. Radio buttons chosen by label click are such a use-case.

How to choose radio by label click
Tailwind Peer class
Single radio button
Multiple radio buttons

How to choose radio by label click

A label click will select a radio by matching two attributes:

radio button: id
label: for

Tailwind Peer class

You can add peer behavior by adding two classes to the HTML.

Add the peer class to the HTML tag you want to observe the state for.
Add the peer-checked class, followed by the desired behavior change, to a sibling element.

Single radio button

Let's start with a single radio button.



<input class="sr-only peer" type="radio" value="yes" name="answer" id="answer_yes">

<label class="flex p-5 bg-white border border-gray-300 rounded-lg cursor-pointer focus:outline-none hover:bg-gray-50 peer-checked:ring-green-500 peer-checked:ring-2 peer-checked:border-transparent" for="answer_yes">Yes</label>

<div class="absolute hidden w-5 h-5 peer-checked:block top-5 right-3">
 👍
</div>

Once the input radio with a class peer is chosen, its sibling label and div will change:

The label gets a green border. Due to peer-checked:ring-green-500 peer-checked:ring-2 peer-checked:border-transparent
The icon, initially hidden, appears. Due to peer-checked:block

Multiple radio buttons

A single radio button does not make much sense, so let's add in 2 other options and display the radio buttons in a grid.



<ul class="grid grid-cols-3 gap-x-5 m-10 max-w-md mx-auto">
  <li class="relative">
    <input class="sr-only peer" type="radio" value="yes" name="answer" id="answer_yes">
    <label class="flex p-5 bg-white border border-gray-300 rounded-lg cursor-pointer focus:outline-none hover:bg-gray-50 peer-checked:ring-green-500 peer-checked:ring-2 peer-checked:border-transparent" for="answer_yes">Yes</label>

    <div class="absolute hidden w-5 h-5 peer-checked:block top-5 right-3">
      👍
    </div>

  <li class="relative">
    <input class="sr-only peer" type="radio" value="no" name="answer" id="answer_no">
    <label class="flex p-5 bg-white border border-gray-300 rounded-lg cursor-pointer focus:outline-none hover:bg-gray-50 peer-checked:ring-red-500 peer-checked:ring-2 peer-checked:border-transparent" for="answer_no">No</label>

    <div class="absolute hidden w-5 h-5 peer-checked:block top-5 right-3">
      👎
    </div>
   </li>

  <li class="relative">
    <input class="sr-only peer" type="radio" value="maybe" name="answer" id="answer_maybe">
    <label class="flex p-5 bg-white border border-gray-300 rounded-lg cursor-pointer focus:outline-none hover:bg-gray-50 peer-checked:ring-yellow-500 peer-checked:ring-2 peer-checked:border-transparent" for="answer_maybe">Maybe</label>

    <div class="absolute hidden w-5 h-5 peer-checked:block top-5 right-3">
      🤔
    </div>
  </li>
</ul>

You can combine multiple peer classes into a single document as long as a parent class (in this case, the <li>) acts as a separator.

That's it.

Purposeful radio buttons without any JS or a custom CSS class.

How to Migrate Environment Variables (ENV) to Rails Credentials

thomasvanholder — Sat, 13 Nov 2021 17:03:06 +0000

Why Should You Move From .Env to Credentials?
How it Works
Migrate From .Env to Rails Credentials
How to Use Credentials in Multiple File Formats
How to Share Keys With a Team

Initially published on Medium on Jan 26th 2020

One key rules them all

Rails credentials are the new gold standard. ENV files are an insecure ancestor. In this article, you’ll learn why and how to migrate, how to use API keys in Ruby, YML and js.erb, and how to share a single key once with your team.

DHH tweeted about its arrival nearly three years ago, but new technology often takes time to catch up. A wake-up call is when you find yourself too frequently juggling API keys between developers in your team. It might be time to take a second look at how to implement credentials in a rails app.

1. Why Should You Move From .Env to Credentials?

The further a project gets in its development cycle, the more services are integrated. Every external service has its API key. It usually doesn’t take too long before developers start hunting teammates for the latest API key. How annoying!

Or, just imagine when an API key gets refreshed. Every developer individually has to update it into local dotenv files. That seems anti-automation and anti-programmatic — and it is.

Stop throwing API keys through Slack or email and avoid a security breach of your keys. Luckily, rails credentials offer an easy and welcoming successor. Uploading your keys to Github.

Uploading to Github!? Yes, uploading to Github! A small annotation is that the API keys are fully encrypted.

The big win is that there is only a single key to share with your team. It never changes! Any new API keys added by your fellow developers as rails credentials are pulled from Github as you pull the latest main (prev. master).

You can find the key in the config/master.key folder.

2. How it Works

Running bin/rails credentials:edit in rails creates two files needed in the config folder:

credentials.yml.enc stores all your API keys. In case you were wondering, the .enc extension signifies encryption.
master.key is the key use to decrypt the encrypted.file (1.) Make sure to check the inclusion of the master.key in your .gitignore.yml file.

Credentials.yml.enc is safe and secure sent along with your repository to Github. The master key, however, is never sent along — guard it like your life depends on it!

3. Migrate From .Env to Rails Credentials

Open the credentials file by running the following in your terminal:
EDITOR='code --wait' bin/rails credentials:edit. Depending on the editor you currently use, replace code (VS Code). For example:

vim or vi= Vim
atom = Atom
subl or stt = Sublime

The credentials file automatically opens in the editor and waits to for you to update and close the file again. Migrate the ENV keys you are using in the .env file to the credentials.yml file.

Turn your legacy .ENV file:

STRIPE_PUBLISHABLE_KEY=pk_test_VG8LlUN82DcZS3cAOJVy0WyIR9Jwz0YZkq302MKc00t
STRIPE_SECRET_KEY=sk_test_VG8LlUN82DcZS3cAOJVy0WyIR9Jwz0YZkq302MKc00tgAAYF
STRIPE_WEBHOOK_SECRET_KEY=whsec_cZpB0VG8cZpB0VG8cZpB0VG8UrgA2gcZpB0VG8cZpB
CLOUDINARY_URL=cloudinary://15031853100444:XOr3XQ-DcZ4dBoan80@DcZ4Boan800U
GOOGLE_API_KEY=S3cAOJVy0WyS3cAOJVy0WyIR9AOJVy0WyIR92e

Into a credentials.yml:

stripe:
  publishable_key: pk_test_VG8LlUN82DcZS3cAOJVy0WyIR9Jwz0YZkq302MKc00tgAAYF
  secret_key: sk_test_VG8LlUN82DcZS3cAOJVy0WyIR9Jwz0YZkq302MKc00tgAAYF
  web_hook_secret_key: whsec_cZpB0VG8cZpB0VG8cZpB0VG8UrgA2gcZpB0VG8cZpB

google_api_key: S3cAOJVy0WyS3cAOJVy0WyIR9AOJVy0WyIR92e

cloudinary:
  cloud_name: abcdefg
  api_key: 12345678910
  api_secret: abc315-VG8Ll8VG8Ll8L

note: Cloudinary API key is split up as per documentation.

You are now all set. View credentials can run in the terminal.
Run bin/rails credentials:show.

4. How to Use Credentials in Multiple File Formats

Ruby

# nested key
Rails.application.credentials.stripe[:publishable_key]

# single key
Rails.application.credentials.google_api_key

YML

cloudinary:
  service: Cloudinary
  api_key: <%= Rails.application.credentials.dig(:cloudinary, :api_key) %>
  api_secret: <%= Rails.application.credentials.dig(:cloudinary, :api_secret) %>

for Cloudinary an additional config/cloudinary.yml file is needed

JavaScript

// ruby code only possible with js.erb format
const abc = "<%= Rails.application.credentials.google_api_key %>"

ERB

<!-- interpolate in script tag --> 
<script src="https://maps.googleapis.com/maps/api/js?key=<%= "#{Rails.application.credentials.google_api_key}"%>"</script

5. How to Share Keys With a Team

Share the key in master.key with fellow developers to enable decryption.
Each team member creates a master.key file locally in the config folder and pastes it in the shared key.

Conclusion

Coding is more fun without the hassle of chasing the correct API keys. Your app is up-to-date with security best practices. Share a master key once and be free of tedious copy-pasting.

Thanks for reading!