Rails 8 Propshaft: Migreren van Sprockets (Stap voor Stap)

Propshaft heeft Sprockets vervangen als standaard asset pipeline in Rails 8. Bij een upgrade van een bestaande app gaat de migratie niet automatisch — en de valkuilen kosten je uren als je ze niet kent. Hier is het volledige migratieproces, getest op drie productie Rails-apps met 50k tot 400k maandelijkse bezoekers.

Waarom Propshaft bestaat

Sprockets is gebouwd toen Rails-apps CoffeeScript moesten compileren, JavaScript-bestanden samenvoegen en assets van fingerprints voorzien. Dat was in 2011. Het JavaScript-ecosysteem is verder gegaan — Webpack, esbuild en import maps regelen JS-bundling nu. Sprockets werd een oplossing van 15.000 regels voor een probleem dat grotendeels verdwenen is.

Propshaft doet precies twee dingen: statische assets serveren en digest stamps toevoegen voor cache busting. Meer niet. Compilatie en transformatie laat het over aan gespecialiseerde tools die dat beter doen.

Het resultaat is aanzienlijk snellere asset-resolutie. In onze benchmarks op een middelgrote Rails-app (ongeveer 800 assets) daalde assets:precompile van 38 seconden met Sprockets naar 1,2 seconden met Propshaft. De opstarttijd verbeterde met ongeveer 400ms omdat Propshaft’s resolver een simpele hash-lookup is in plaats van Sprockets’ dependency graph walker.

Voordat je begint

Controleer je Sprockets-afhankelijkheden. Voer dit uit in je project root:

grep -r "//= require" app/assets/ vendor/assets/ lib/assets/ 2>/dev/null

Elke //= require directive is een Sprockets-specifieke feature die Propshaft niet ondersteunt. Je moet ze allemaal verwijderen voordat je overschakelt.

Controleer ook op asset-compilatie in je pipeline:

grep -rn "\.scss\|\.sass\|\.coffee\|\.erb" app/assets/stylesheets/ app/assets/javascripts/ 2>/dev/null

Als je .scss-bestanden gebruikt, heb je dartsass-rails nodig. CoffeeScript-bestanden moeten eerst naar JavaScript geconverteerd worden — daar is geen shortcut voor.

Stap 1: Propshaft toevoegen en Sprockets verwijderen

Update je Gemfile:

# Verwijder deze
# gem "sprockets-rails"
# gem "sprockets", "~> 4.0"

# Voeg dit toe
gem "propshaft"

# Als je Sass gebruikt:
gem "dartsass-rails"

Voer bundle install uit. Je ziet waarschijnlijk geen fouten in dit stadium — het wordt pas spannend als je de app opstart.

Stap 2: Sprockets-configuratie verwijderen

Verwijder deze bestanden als ze bestaan:

rm -f config/initializers/assets.rb
rm -rf app/assets/config/

Verwijder in config/application.rb alle Sprockets-configuratie:

# Verwijder regels zoals:
config.assets.paths << Rails.root.join("node_modules")
config.assets.precompile += %w[admin.js admin.css]
config.assets.compile = false

Propshaft serveert automatisch alles in app/assets/, lib/assets/ en vendor/assets/. Er is geen precompile manifest om bij te houden.

Stap 3: Asset-referenties in views repareren

Sprockets accepteerde kale bestandsnamen. Propshaft vereist paden relatief aan het asset load path.

<%# Sprockets-stijl - werkt niet %>
<%= stylesheet_link_tag "application" %>

<%# Propshaft-stijl - inclusief extensie %>
<%= stylesheet_link_tag "application.css" %>

Dit is de meest voorkomende migratiefout. Doorzoek je views:

grep -rn "stylesheet_link_tag\|javascript_include_tag" app/views/ | grep -v '\.\(css\|js\)'

Alle resultaten zonder bestandsextensies moeten worden aangepast.

Stap 4: Sprockets-directives vervangen

Als je Sprockets’ //= require directives gebruikte in JavaScript:

// Oude Sprockets-manier
//= require jquery
//= require_tree .

// Met import maps (Rails 8 standaard)
import "jquery"
import "controllers"

Voor CSS, vervang @import via Sprockets met standaard CSS-imports of schakel over naar dartsass-rails:

/* Oude Sprockets-manier */
/*= require normalize */
/*= require_tree . */

/* Standaard CSS */
@import url("normalize.css");

Als je Sass gebruikt, handelt dartsass-rails @use en @forward native af — geen Sprockets-betrokkenheid nodig.

Stap 5: Asset path helpers in CSS en JS aanpassen

Sprockets verwerkte ERB in CSS-bestanden (application.css.erb) om asset-paden te resolven. Propshaft gebruikt een ander mechanisme — het herschrijft url()-referenties in CSS automatisch.

/* Dit werkt in Propshaft zonder ERB */
.hero {
  background-image: url("hero-bg.png");
}

Propshaft resolvet url()-aanroepen relatief aan de locatie van het CSS-bestand en herschrijft ze met de digest. Geen ERB-templates nodig.

Als je asset_path in JavaScript gebruikte, schakel over naar data-attributen:

<%# In je view %>
<div id="app" data-logo-url="<%= asset_path('logo.png') %>">

// In je JS
const logoUrl = document.getElementById('app').dataset.logoUrl;

Stap 6: Deployment updaten

Als je deployt met Kamal of Capistrano, update je precompile-stap. Propshaft gebruikt dezelfde Rake-tasknaam:

RAILS_ENV=production bundle exec rails assets:precompile

De taak draait nu in ongeveer een seconde, dus je kunt eventuele precompile-caching voor Sprockets verwijderen. In een Kamal deployment setup betekent dit dat je build-stap merkbaar sneller wordt.

Je CDN-configuratie blijft hetzelfde — Propshaft schrijft digested bestanden naar public/assets/ net als Sprockets deed.

Stap 7: Alles verifiëren

Start je app op en controleer de browserconsole op 404-fouten bij assets. Veelvoorkomende problemen:

Ontbrekende fontbestanden: Verplaats fonts naar app/assets/fonts/ en verwijs ernaar met relatieve paden in CSS.

Kapotte afbeeldingsreferenties: Elke image_tag-aanroep zonder extensie moet er een krijgen.

Third-party CSS met absolute paden: Sommige CSS-bibliotheken verwijzen naar assets met absolute paden zoals /assets/icons/thing.svg. Deze krijgen geen digest stamps. Kopieer de assets naar je asset-directories en repareer de referenties.

Draai je testsuite — asset-gerelateerde fouten komen snel boven:

bundle exec rails test:system

Veelvoorkomende valkuilen

Gem-provided assets: Gems die Sprockets-stijl assets meeleveren (met //= require directives) werken niet met Propshaft. Controleer de documentatie van elke gem voor Propshaft-compatibiliteit. De meeste populaire gems zijn bijgewerkt — jquery-rails werkt, maar sommige oudere gems zijn niet aangepast.

Dynamische asset-compilatie in productie: Als je vertrouwde op config.assets.compile = true in productie (Sprockets’ lazy compilatie), dan heeft Propshaft dit concept niet. Alle assets moeten bestaan bij deployment. Dit is veiliger — Sprockets’ productie-compilatie was een bekende bron van memory leaks en request latency pieken.

De asset_host config: Propshaft respecteert config.asset_host op dezelfde manier als Sprockets. Geen wijzigingen nodig voor CDN-setups.

Prestatievergelijking

Gemeten op een Rails 8.0 app met 847 assets (CSS, JS, afbeeldingen, fonts):

Deze cijfers komen van een productie-app met Ruby 3.3 en YJIT ingeschakeld. Je resultaten variëren op basis van het aantal assets en of Sprockets compilatiewerk deed.

Moet je migreren?

Als je een nieuwe Rails 8 app start: Propshaft is al je standaard. Geen beslissing nodig.

Als je upgradet vanuit Rails 7: migreer naar Propshaft tijdens de upgrade. Sprockets werkt nog in Rails 8, maar het wordt niet meer onderhouden als standaard dependency, en gem-compatibiliteit zal na verloop van tijd afwijken.

Als je op Rails 6 of eerder zit: upgrade Rails eerst, en pak Propshaft daarna apart aan. Beide tegelijk doen creëert te veel variabelen bij het debuggen.

De migratie kostte ons ongeveer 4 uur op een grote app met veel Sprockets-maatwerk en minder dan een uur op een simpelere app. De winst in deploysnelheid en verminderde complexiteit is het waard.

Veelgestelde vragen

Kan ik Propshaft en Sprockets naast elkaar gebruiken tijdens de migratie?

Nee. Ze registreren zich allebei als de asset pipeline en conflicteren op de assets:precompile taak. Het is een schone wissel — verwijder Sprockets, voeg Propshaft toe, repareer wat breekt. Je kunt dit op een branch doen en grondig testen voordat je merget. De migratie is eenvoudig genoeg dat een parallelle draaiperiode niet nodig is.

Werkt Propshaft met Tailwind CSS?

Ja. Gebruik de tailwindcss-rails gem (versie 3.0+), die direct met Propshaft integreert. De gem draait de Tailwind CLI tijdens assets:precompile en produceert een standaard CSS-bestand dat Propshaft serveert. Geen Sprockets-dependency betrokken.

Wat gebeurt er met mijn source maps in productie?

Propshaft genereert geen source maps omdat het niets transformeert. Als je source maps nodig hebt voor JavaScript, genereert je JS-bundler (esbuild, rollup) ze. Voor Sass produceert dartsass-rails source maps. Propshaft serveert alle bestanden die in de asset-directories staan, inclusief source maps.

Hoe verschilt cache-invalidatie bij Propshaft van Sprockets?

Beide gebruiken content-based digest stamps toegevoegd aan bestandsnamen (application-a1b2c3d4.css). Het belangrijkste verschil is snelheid: Sprockets berekent digests door een dependency graph te doorlopen (traag bij grote apps), terwijl Propshaft direct een MD5 van de bestandsinhoud berekent. Het cache-invalidatiegedrag voor browsers en CDN’s is identiek — gewijzigde content krijgt een nieuwe digest, oude gecachte versies verlopen natuurlijk.

Breken mijn bestaande asset-tests?

Waarschijnlijk niet. Als je tests asset_path of asset_url helpers gebruiken, werken die identiek in Propshaft. Tests die rechtstreeks Sprockets-internals aanroepen (zoals Rails.application.assets.find_asset) breken wel en moeten worden bijgewerkt om Rails.application.assets.load_path.find te gebruiken.