Skip to content

Capistrano Deployment

Deploying a Hyvä theme with Capistrano requires configuring custom Rake tasks to generate the Tailwind CSS production stylesheet during deployment. capistrano-magento2 is a Ruby-based deployment tool commonly used for Magento projects that provides hooks into the deployment lifecycle.

This guide covers creating a custom Rake task for Tailwind compilation, configuring theme paths, and ensuring Node.js is available on your deployment servers.

Prerequisites

  • capistrano-magento2 configured for your project
  • Node.js and npm installed on deployment servers (see Server Requirements)
  • Your Hyvä theme's web/tailwind directory containing package.json and Tailwind configuration

Tailwind Stylesheet Generation

When the production Tailwind CSS stylesheet is not committed to version control, Capistrano must build it during deployment before the static content deployment phase runs.

Step 1: Create the Tailwind Rake Task

Create a file named tailwind.rake in your project's lib/capistrano/tasks directory. This custom Rake task iterates through configured theme paths, installs npm dependencies, and runs the Tailwind build command:

namespace :deploy do
    desc 'Build tailwindCSS'
    task :hyva_tailwind_build do
      on roles(:all) do
        fetch(:hyva_tailwind_paths, []).each do |tailwind_path|
          within release_path + tailwind_path do
            execute :npm, :ci
            execute :npm, :run, "build"
          end
        end
      end
    end
  end

Step 2: Configure Theme Paths

In your config/deploy.rb file, define the hyva_tailwind_paths variable with the paths to your Hyvä theme's Tailwind directories. Replace Vendor/ThemeName with your actual theme vendor and name:

set :hyva_tailwind_paths, [
  'app/design/frontend/Vendor/ThemeName/web/tailwind'
]

For multiple Hyvä themes, add each theme's Tailwind path to the array:

set :hyva_tailwind_paths, [
  'app/design/frontend/Vendor/ThemeOne/web/tailwind',
  'app/design/frontend/Vendor/ThemeTwo/web/tailwind'
]

Step 3: Register the Task in the Deployment Lifecycle

In the same config/deploy.rb file, register the Tailwind build task to run before Magento's static content deployment. This ensures stylesheets are ready before they are copied to pub/static:

before 'magento:setup:static-content:deploy', 'deploy:hyva_tailwind_build'

Server Requirements

The Tailwind build process requires Node.js and npm to be installed on your deployment servers. The Rake task uses npm ci to install dependencies and npm run build to generate the production stylesheet.

Optional: Managing Node.js Versions with NVM

If your deployment servers use NVM (Node Version Manager) to manage multiple Node.js versions, you can integrate Capistrano with NVM using the capistrano-nvm gem. This allows you to specify which Node.js version to use during deployment.

Step 1: Add the NVM Gem

Add the capistrano-nvm gem to your Gemfile:

gem 'capistrano-nvm', :git => 'https://github.com/koenpunt/capistrano-nvm.git', require: false

Step 2: Require the Module

Add the NVM module to your Capfile:

require 'capistrano/nvm'

Step 3: Configure NVM Settings

Add NVM configuration to your config/deploy.rb file. Set nvm_type to :user for per-user NVM installations or :system for system-wide installations:

set :nvm_type, :user
set :nvm_node, 'v20.19.5'