Rails Engine에서 Sprockets 및 Propshaft 지원하기

Rails Engine Assets: Making Your Gem Work with Sprockets and Propshaft

작성자
HackerNews
발행일
2025년 07월 25일
원문 보기
avohq.io

핵심 요약

  • 1 본 문서는 Rails Engine에서 구 버전 Sprockets와 신 버전 Propshaft 자산 파이프라인을 모두 지원하는 방법을 다룹니다.
  • 2 핵심은 `engine.rb` 파일을 통해 자산 경로를 설정하고, 번들링된 자산 외 이미지, SVG, CSS 내 자산 참조 등을 노출하는 것입니다.
  • 3 Propshaft는 자동 노출에 강점이 있으나 Sprockets는 명시적인 사전 컴파일 또는 `manifest.js`를 통한 설정이 필요함을 강조합니다.

도입

Rails 프레임워크는 애플리케이션의 자산을 관리하기 위해 Sprockets와 Propshaft라는 두 가지 주요 자산 파이프라인을 제공합니다. 2022년에 도입된 Propshaft는 Sprockets의 개선된 대안으로, 더 효율적인 자산 관리를 목표로 합니다. 이러한 변화는 기존 Sprockets 기반 앱 사용자들에게 업그레이드 필요성을 제기했으며, 특히 라이브러리 및 Rails Engine 개발자들에게는 두 시스템 모두를 지원해야 하는 과제를 안겨주었습니다. 본 문서는 Avo(Ruby on Rails용 관리자 패널 프레임워크)의 사례를 통해 Rails Engine에서 Sprockets와 Propshaft를 동시에 지원하는 구체적인 방법을 제시하며, 이는 라이브러리의 호환성을 극대화하고 사용자 경험을 개선하는 데 필수적입니다.

Rails Engine에서 Sprockets와 Propshaft를 모두 지원하기 위한 핵심 작업은 engine.rb 파일 내에서 이루어집니다. 이 파일은 Rails Engine이 메인 애플리케이션에 연결되는 진입점 역할을 합니다.

먼저, 자산 번들링을 위해 cssbundling-rails 및 jsbundling-rails 젬을 사용합니다. 이 젬들을 통해 번들링된 CSS 및 JS 파일은 app/assets/builds 디렉토리에 저장되며, 이 디렉토리의 모든 자산은 Sprockets와 Propshaft 모두에 자동으로 노출됩니다. 이는 가장 기본적인 자산 노출 방식입니다.

그러나 app/assets/builds 디렉토리 외부에 위치한 자산, 예를 들어 개발 편의성을 위해 별도 디렉토리에 보관되는 이미지, SVG 파일 등은 명시적인 노출 과정이 필요합니다. 이를 위해 engine.rb 파일 내에서 initializer 콜백을 생성하고, app.config.assets.paths에 Engine.root.join("app", "assets", "images").to_s와 같이 이미지 및 SVG 디렉토리를 추가해야 합니다. 이렇게 설정하면 image_tag '엔진명/로고.png'와 같은 헬퍼가 Sprockets와 Propshaft 환경 모두에서 정상적으로 작동하게 됩니다.

CSS 파일 내에서 url() 함수를 통해 자산을 참조하는 경우에도 차이가 발생합니다. Propshaft는 app.config.assets.paths 설정만으로도 스마트하게 해당 자산을 찾아 처리하며, 심지어 접두사 없이 url('로고.png')처럼 사용해도 작동합니다(단, 충돌 방지를 위해 엔진명 접두사 사용 권장). 반면 Sprockets는 자산에 접근하기 위해 명시적인 사전 컴파일 경로 설정이 필요합니다.

Sprockets에서 자산을 노출하는 방법은 두 가지가 있습니다:

  1. app.config.assets.precompile 배열 사용: engine.rb 파일 내에서 app.config.assets.precompile += %w[ 엔진명/로고.png ]와 같이 개별 파일을 배열에 추가하거나, 보다 프로그램적인 방식으로 지정된 디렉토리 내의 모든 파일을 찾아서 상대 경로로 추가할 수 있습니다. Sprockets는 자산의 상대 경로를 요구하므로, app/assets/images/엔진명/로고.png와 같은 전체 경로가 아닌 엔진명/로고.png 형태로 제공해야 합니다. 이는 문서화되지 않은 중요한 부분입니다.

  2. manifest.js 파일 사용: app/assets/config 디렉토리에 엔진명_manifest.js 파일을 생성하고, 이 파일 내에서 //= link_tree ../builds, //= link_tree ../images와 같이 link_tree 지시어를 사용하여 자산 디렉토리를 연결합니다. 이후 engine.rb에서 Sprockets가 이 매니페스트 파일을 사전 컴파일하도록 app.config.assets.precompile += %w[엔진명_manifest.js]를 추가합니다. 이 방법은 Sprockets의 전통적인 자산 관리 방식과 유사합니다.

마지막으로, 모범 사례로서 최종(번들링된) 자산 및 이미지, SVG 파일 등의 디렉토리에 엔진 이름을 네임스페이스로 부여하는 것을 권장합니다. 예를 들어, app/assets/builds/ENGINE_NAME, app/assets/images/ENGINE_NAME와 같이 구성하여 다른 애플리케이션의 자산과의 충돌을 방지하고 명확성을 높일 수 있습니다.

결론

결론적으로, Rails Engine이 Sprockets와 Propshaft라는 두 가지 자산 파이프라인을 모두 원활하게 지원하기 위해서는 `engine.rb` 파일 내에서 세심한 자산 경로 설정과 Sprockets에 특화된 사전 컴파일 전략이 필수적입니다. Propshaft는 현대적인 접근 방식으로 대부분의 자산을 자동으로 처리하는 반면, Sprockets는 `app.config.assets.precompile` 배열이나 `manifest.js` 파일을 통한 명시적인 지시가 요구됩니다. 이러한 차이점을 이해하고 각 시스템의 요구사항에 맞춰 자산을 노출함으로써, 라이브러리 개발자는 다양한 Rails 애플리케이션 환경에서 안정적인 호환성을 보장하고 사용자에게 최적의 경험을 제공할 수 있습니다. 또한, 엔진 이름을 활용한 디렉토리 네임스페이스 부여는 자산 관리의 효율성과 명확성을 크게 향상시키는 중요한 모범 사례입니다.

관련 글들

Ruby on Rails 프런트엔드 자산 관리: 진화와 현재 권장 사항

Ruby on Rails의 프런트엔드 자산 관리는 수년간 Sprockets, Webpacker, Import Maps 등으로 진화해왔습니다.

06/17 읽어보기 →

Rails Asset Pipeline의 효과적인 활용 및 Rails 플러그인 개발

Rails Asset Pipeline의 역사적 배경과 번들링, 핑거프린팅, 트랜스파일링 등 핵심 기능을 설명합니다.

07/24 읽어보기 →

루비 온 레일즈 프론트엔드 개발의 현대적 접근

루비 온 레일즈 프론트엔드 개발은 Rails 6의 '암흑기'를 넘어 Rails 7에서 '르네상스'를 맞이했습니다.

01/13 읽어보기 →

댓글 0

댓글 작성

0/1000
정중하고 건설적인 댓글을 작성해 주세요.

아직 댓글이 없습니다

첫 번째 댓글을 작성해보세요!