[번역] Vite 플러그인 만들기

아래 게시물을 번역한 글임

https://www.vuemastery.com/blog/building-a-plugin-with-vite

Building a plugin with Vite | Vue Mastery

왜 Vite 플러그인을 만드나요?

Vite 플러그인을 사용하면 아래와와 같은 작업을 수행할 수 있습니다. 

• index.mycustomextension과 같은 커스텀 확장자를 index.js로 resolve하는 것
• 마크다운을 JSX로 변환하는 것

따라서 Vite 플러그인을 직접 만드는 방법이 궁금할 수 있습니다.

이 기사에서는 사용자 지정 Vite 플러그인의 기초 및 영감으로 사용할 수 있는 몇 가지 간단한 플러그인을 만드는 방법을 안내합니다.

---

Vite 플러그인이 뭔가요?

Vite 플러그인은 특정 문제를 해결하기 위해
Vite 위에 사용자 설정 기능을 추가할 수 있는 Vite 전용 훅과
몇 가지 옵션이 있는 롤업 플러그인입니다.

예를 들어 Astro는 Vite 플러그인을 사용하여 .astro 파일을 resolve합니다.

Vite 플러그인은 아래 컴포넌트를 하나 이상 갖고 있는 객체입니다.

• properties
• build hooks
• output generation hooks

const vitePluginExample = () => ({
	// properties
  name: 'vite-plugin-example', 
	// build hooks
  config: () => ({
    resolve: {
      alias: {
        foo: 'bar'
      }
    }
  }),
	// output generation hooks
	augmentChunkHash(chunkInfo) {
      if (chunkInfo.name === 'bar') {
        return Date.now().toString();
      }
    }
})

Vite Plugin을 개발하기 전에 위의 세 가지 컴포넌트의 기능을 간단하게 알아봅시다.

Properties

Vite 플러그인의 유일한 필수 속성은 플러그인의 이름인 name 속성입니다.
이는 디버깅 및 오류 메시지에 유용하기 때문에 필요합니다.

Build hooks

플러그인이 Vite의 빌드 프로세스와 상호 작용하는 기본 방법입니다.

Hooks는 빌드의 다양한 단계에서 호출되는 함수입니다.

Hooks를 사용하여

• 빌드가 실행되는 방식을 수정하거나,
• 빌드에 대한 정보를 수집하거나,
• 완료된 빌드를 수정할 수 있습니다.

Output generation hooks

이러한 훅은 생성된 번들에 대한 정보를 제공하고 빌드가 완료되면 결과물을 수정하는 데 사용할 수 있습니다.

---

Vite 플러그인 만들기

Vite 플러그인 생성을 시작하는 것은 vite.config.js 파일에 팩토리 함수를 지정하는 것입니다.

이 함수는 모든 플러그인 정의 및 논리를 포함하는 실제 플러그인 객체를 반환합니다.

그런 다음 이 함수를 defineConfig 개체의 플러그인 배열에 전달할 수 있습니다.

참고: 이 함수는 일반 함수이므로 사용자 영역에서 플러그인 동작을 사용자 정의할 수 있는 옵션을 허용할 수 있습니다.

플러그인 생성에 익숙해질 수 있도록 Vite 플러그인 작성 방법을 보여주는 세 가지 간단한 플러그인을 생성해 봅시다.

---

예제 1 : 플러그인 통계 출력하기

Vite 프로젝트의 플러그인에 대한 통계를 출력하는 플러그인을 만드는 것보다 더 나은 "hello world" 예제가 있을까요?

이 플러그인이 동작하는 방식은 npm run dev를 실행할 때 output-plugin-stats Hook의 출력을 확인하는 것입니다.
이는 프로젝트의 플러그인 수와 모든 플러그인의 테이블이 됩니다.

 

이를 생성하기 위해 먼저 터미널에서 다음 명령을 실행하여 Vanilla Vite 프로젝트를 인스턴스화합니다.

npm init create-vite@latest

프롬프트에서 Vanilla 사전 설정을 선택하고 언어로 JavaScript를 선택합니다.

다음으로 npm install 및 npm run dev를 실행하여 설정이 성공했는지 확인합니다.

npm install
npm run dev

이 작업이 완료되면 dev 서버를 종료하고 프로젝트의 루트에 vite.config.js 파일을 만들고 다음 코드를 추가하십시오.

📄 vite.config.js

import { defineConfig } from 'vite'

export default defineConfig({
  plugins: []
})

이제 우리는 플러그인 배열에 전달할 플러그인의 기능을 구현하기 위한 스켈레톤을 구성했습니다.

📄 vite.config.js

import { defineConfig } from 'vite'

const outputPluginStats = () => ({
  name: 'output-plugin-stats',
  configResolved(config) {
    const plugins = config.plugins.map((plugin) => plugin.name)
    console.log(`Your project has ${plugins.length} Vite plugins.`)
    console.table(plugins)
  }
})

export default defineConfig({
  plugins: [
    outputPluginStats()
  ]
})

플러그인 이름인 name 속성과 configResolved Vite 연관 훅이 있는 객체를 반환하는 outputPluginStats 함수가 있습니다.

configResolved는 Vite 설정이 완료된 후 호출되며, 이를 사용하여 최종적으로 resolved된 구성을 읽고 저장할 수 있습니다.

위의 코드에서 수행하는 작업을 살펴보겠습니다.

const plugins = config.plugins.map((plugin) => plugin.name)

config.plugins에서 플러그인 이름을 plugins라는 배열로 반환합니다.

console.log(`Your project has ${plugins.length} Vite plugins.`)

위의 줄은 Array.prototype.length를 사용하여 플러그인 배열의 플러그인 수를 출력합니다.

마지막으로 플러그인 배열을 테이블로 출력합니다.

console.table(plugins)

플러그인을 정의한 후 Vite 설정 객체의 플러그인 배열에 플러그인을 등록합니다.

export default defineConfig({
  plugins: [
    outputPluginStats()
  ]
})

---

예제 2: Vite 서버 요청 분석

다음 예에서는 서버가 요청을 처리하기 전에 실행되는 함수인 미들웨어를 Vite connect 서버에 추가하여 서버가 처리하는 요청을 기록합니다.

이를 위해 vite.config.js 파일에 다음 함수를 추가해 보겠습니다.

📄 vite.config.js

const requestAnalytics = () => ({
  name: 'request-analytics',
  configureServer(server) {
    return () => {
      server.middlewares.use((req, res, next) => {
        console.log(`${req.method.toUpperCase()} ${req.url}`)
        next()
      })
    }
  }
})

위의 플러그인에서 Vite 서버에 미들웨어를 추가하기 위해 vite의 configureServer 훅을 사용하고 있습니다.

위 코드의 각 라인이 수행하는 작업에 대해 자세히 살펴보겠습니다.

먼저 플러그인의 이름을 설정합니다.

name: 'request-analytics'

그런 다음 configureServer 훅을 사용하여 Vite 서버를 설정할 수 있습니다.

configureServer(server) {
    return () => {
      server.middlewares.use((req, res, next) => {
        console.log(`${req.method.toUpperCase()} ${req.url}`)
        next()
      })
    }
  }

마지막으로 next() 호출을 사용하여 요청을 다음 핸들러로 전달합니다.
다음과 같이 플러그인 배열에 우리가 개발한 플러그인을 등록합니다.

📄 vite.config.js

export default defineConfig({
  plugins: [
    outputPluginStats(),
    requestAnalytics()
  ]
})

이제 npm run dev를 실행하여 Vite 서버를 시작하고 http://localhost:5173/을 방문하면 아래 출력이 표시됩니다.

GET /index.html

우리는 Vite 서버에서 제공한 파일을 알려주는 일종의 요청 분석을 만들었습니다.

---

예제 3: Hot Update Report

콘솔을 통해 HMR을 통해 업데이트된 모듈을 보고한다고 가정해 보겠습니다.

이를 위해 hotUpdateReport라는 플러그인을 빌드해 보겠습니다.

다음과 같이 handleHotUpdate 훅을 사용하면 됩니다.

📄 vite.config.js

const hotUpdateReport = () => ({
  name: 'hot-update-report',
  handleHotUpdate({file, timestamp, modules}) {
    console.log(`${timestamp}: ${modules.length} module(s) updated`)
  }
})

업데이트된 모듈 수와 타임스탬프를 기록하기 위해 handleHotUpdate 훅을 사용하고 있습니다.

handleHotUpdate 훅은 file, timestamp 및 module 속성을 포함한 HmrContext 객체를 제공합니다.

 

다음과 같이 플러그인을 등록하기만 하면 됩니다.

📄 vite.config.js

export default defineConfig({
  plugins: [
    outputPluginStats(),
    requestAnalytics(),
    hotUpdateReport()
  ]
})

이제 index.html, main.js 또는 style.css를 업데이트하면 콘솔에 보고서가 표시됩니다.

---

Vite 플러그인 퍼블리시하기

플러그인을 작성한 후 NPM을 통해 설치할 수 있는 독립 실행형 패키지로 공유하고 싶다면 다음과 같은 절차를 따릅니다.

• 플러그인에는 vite-plugin- 접두사가 붙은 명확한 이름이 있어야 합니다.
• package.json에 vite-plugin 키워드가 포함되어야 합니다.

{
  "name": "building-a-plugin-with-vite",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "keywords": ["vite-plugin"],
}

• 플러그인을 문서화할 때 Vite 플러그인 전용(Rollup 플러그인이 아님)인 이유를 설명하는 섹션을 포함하세요.
  • 플러그인이 Vite 전용인 일반적인 이유는 일부 Vite 전용 플러그인 훅을 사용하기 때문입니다.
• 마지막으로, 플러그인이 특정 프레임워크에서만 작동하는 경우 프레임워크 이름은 플러그인 이름 접두사의 일부여야 합니다(예: vite-plugin-svelte-, vite-plugin-react-, vite-plugin-react-, vite-plugin-lit). -, 등.

앞으로 더 공부할 것들

롤업을 이용한 플러그인 개발

https://rollupjs.org/guide/en/

rollup.js

Vite를 공부하기

https://vitejs.dev/

Vite