importmap-rails 이해하기

Source: Dev.to

위에 제공된 링크에 있는 글의 본문을 알려주시면, 해당 내용을 한국어로 번역해 드릴 수 있습니다. 코드를 포함한 마크다운 형식과 URL은 그대로 유지하면서 번역해 드리겠습니다. 부탁드려요!

소개

현대 JavaScript를 사용해 본 적이 있다면 ES 모듈과 import 구문에 익숙할 것입니다. Rails 애플리케이션은 이를 위해 esbuild(또는 vite 또는 bun)를 사용할 수 있지만, 기본(Rails‑way) 설정은 importmap‑rails입니다. 이를 통해 빌드 단계 없이 다음과 같이 작성할 수 있습니다

import { Controller } from "@hotwired/stimulus"

import map이란 무엇인가?

Import map은 브라우저가 베어 모듈 지정자(예: import React from "react" )를 어떻게 해석할지 알려주는 웹 표준입니다. 브라우저는 모듈을 로드하기 위해 절대 경로, 상대 경로 또는 HTTP URL이 필요합니다.

Import map은 이러한 변환을 제공하며, 예를 들어 다음과 같습니다:

{
  "imports": {
    "application": "/assets/application-abc123.js",
    "@hotwired/stimulus": "/assets/stimulus.min-def456.js",
    "controllers/application": "/assets/controllers/application-ghi789.js"
  }
}

JavaScript에서 import { Controller } from "@hotwired/stimulus" 라고 작성하면, 브라우저는 이 맵에서 "@hotwired/stimulus" 를 찾아 /assets/stimulus.min-def456.js 를 로드합니다.

importmap‑rails 사용하기

importmap-rails gem은 “ 태그를 자동으로 생성합니다. 레이아웃에 다음과 같이 포함하세요:

이 헬퍼는 config/importmap.rb를 읽고, import map을 출력하며, modulepreload 링크를 추가합니다(브라우저가 JavaScript 파일을 즉시 다운로드하도록). 그리고 애플리케이션 진입점을 삽입합니다.

핀 설정

config/importmap.rb에서 맵에 들어갈 내용을 정의합니다:

pin "application"
pin "@hotwired/turbo-rails", to: "turbo.min.js"
pin "@hotwired/stimulus",   to: "stimulus.min.js"
pin "@rails/request.js",    to: "@rails--request.js.js"

각 pin은 import map에 매핑(엔트리)을 생성합니다:

• 첫 번째 인수 – import 문에서 사용할 베어 모듈 지정자.
• to: 속성 – 에셋 파이프라인(보통 app/javascript 혹은 vendor/javascript 아래)에서 로드될 파일.

npm 패키지 핀하기

npm에서 패키지를 추가하려면 다음을 실행합니다:

./bin/importmap pin package-name

이 명령은 패키지 파일을 vendor/javascript에 다운로드하고 config/importmap.rb에 핀을 추가합니다. 기본적으로 JSPM.org를 CDN으로 사용하지만, 다른 소스를 지정할 수도 있습니다:

./bin/importmap pin react --from unpkg
./bin/importmap pin react --from jsdelivr

다운로드된 파일은 소스 컨트롤에 커밋되며, 애플리케이션의 에셋 파이프라인을 통해 제공됩니다.

전체 디렉터리 핀하기

파일을 하나씩 핀하는 대신, 전체 디렉터리를 매핑할 수 있습니다:

pin_all_from "app/javascript/controllers",          under: "controllers"
pin_all_from "app/javascript/turbo_stream_actions", under: "turbo_stream_actions"

under: 속성은 네임스페이스 접두사를 생성합니다. 디렉터리 안의 모든 파일은 해당 접두사를 사용해 import할 수 있게 됩니다.

• app/javascript/controllers/reposition_controller.js →

  import RepositionController from "controllers/reposition_controller"

• app/javascript/turbo_stream_actions/set_data_attribute.js →

  import set_data_attribute from "turbo_stream_actions/set_data_attribute"

Custom Turbo Stream actions

1. Map the directory in config/importmap.rb:

   pin_all_from "app/javascript/turbo_stream_actions", under: "turbo_stream_actions"

2. When Rails generates the import map (“), it scans that directory and creates entries such as:

   {
     "imports": {
       "turbo_stream_actions": "/assets/turbo_stream_actions/index-abc.js",
       "turbo_stream_actions/set_data_attribute": "/assets/turbo_stream_actions/set_data_attribute-xyz.js"
     }
   }

3. Create the custom action (app/javascript/turbo_stream_actions/set_data_attribute.js):

   export default function() {
     // your custom logic
   }

4. Register it in app/javascript/turbo_stream_actions/index.js:

   import set_data_attribute from "turbo_stream_actions/set_data_attribute"
   
   Turbo.StreamActions.set_data_attribute = set_data_attribute

5. Load the actions in your main entry point (app/javascript/application.js):

   import "turbo_stream_actions"

브라우저는 import map을 통해 "turbo_stream_actions/set_data_attribute"를 해석하고, 컴파일된 에셋을 가져와서 해당 액션을 사용할 수 있게 됩니다.

Stimulus 통합

1. 컨트롤러 디렉터리 고정:

   pin_all_from "app/javascript/controllers", under: "controllers"

2. app/javascript/controllers/index.js에서 Stimulus 부트스트랩:

   import { application } from "controllers/application"
   import { eagerLoadControllersFrom } from "@hotwired/stimulus-loading"
   
   eagerLoadControllersFrom("controllers", application)

3. 애플리케이션 정의 (app/javascript/controllers/application.js):

   import { Application } from "@hotwired/stimulus"
   
   const application = Application.start()
   application.debug = false
   window.Stimulus = application
   
   export { application }

eagerLoadControllersFrom 함수는 import map에서 "controllers/"로 시작하는 항목을 스캔하여 자동으로 가져오고 등록합니다. app/javascript/controllers 아래에 새 컨트롤러 파일을 추가하면 즉시 사용할 수 있게 되며, 별도의 설정이 필요하지 않습니다.

Summary

• Import maps는 번들러 없이도 브라우저가 베어 모듈 지정자를 해결하도록 합니다.
• importmap‑rails는 Rails 애플리케이션을 위한 import map과 modulepreload 링크를 생성합니다.
• 개별 파일에는 pin을, 전체 디렉터리에는 pin_all_from을 사용하고, npm에서 패키지를 가져오려면 ./bin/importmap pin을 사용합니다.
• under: 네임스페이스는 디렉터리 구조를 반영하는 깔끔한 import 접두사를 만들어 Turbo Stream 액션, Stimulus 컨트롤러 및 기타 JavaScript 모듈의 통합을 단순화합니다.