Skip to Content
DevPluginPlugin Store

플러그인 스토어

본 문서에서는 플러그인의 스토어를 생성하고, 사용하는 방법을 설명합니다. 플러그인의 스토어는 플러그인의 상태나 데이터를 임시로 저장해야 하는 용도에 적합합니다.1

스토어 생성하기

setup에서 반환한 값이 플러그인 상태가 되고, API/JS 영역에서 ctx.get(plugin.id)로 접근합니다.

import { AppContext, definePlugin } from "@muvel/core"
 
interface CounterState {
  count: number
}
 
interface CounterApi {
  inc: (ctx: AppContext) => void
}
 
const plugin = definePlugin<CounterApi, CounterState>("counter", {
  name: "counter",
  version: __VERSION__,
  dependencies: [],
  api: {
    inc: (ctx) => {
      const state = ctx.get(plugin.id)
      state.count += 1
    },
  },
  setup: async () => ({ count: 0 }),
  dispose: async () => {},
})

drpc.desktop처럼 간단한 상태 보관(current 등)에 적합합니다.

zustand 사용하기

모달/드로어/슬롯처럼 실시간 UI 상태를 자주 갱신할 때의 성능을 위해서나, Prosemirror 등 JS 외부 영역에서 플러그인 상태를 조회해야 할 필요가 있을 경우 zustand를 직접 사용할 수 있습니다.

import { createStore, type StoreApi } from "zustand"
 
type UiStore = {
  opened: boolean
  setOpened: (value: boolean) => void
}
 
type PluginState = {
  store: StoreApi<UiStore>
}
 
const store = createStore<UiStore>((set) => ({
  opened: false,
  setOpened: (value) => set({ opened: value }),
}))

slots, modal, drawer, workspace 플러그인이 이 방식을 사용합니다.

스토어 사용하기

플러그인 API에서

API 함수에서는 ctx.get(plugin.id)로 상태를 가져온 뒤 store를 읽거나 수정합니다.

api: {
  open: (ctx) => {
    const { store } = ctx.get(plugin.id)
    store.getState().setOpened(true)
  },
}

modal, drawer처럼 API에서 store.getState().open(...)/close(...)를 호출하는 구조가 대표적입니다.

React 내부에서

상태 유형에 따라 접근 방법이 다릅니다.

// zustand store
const { store } = ctx.get(plugin.id)
const opened = useStore(store, (s) => s.opened)

React에서 구독이 필요하면 useValues(settings-store) 또는 useStore(zustand)를 사용하세요.

JS 영역에서

렌더링 밖 로직(초기화, 이벤트 리스너, interval)에서는 구독/즉시 조회를 주로 사용합니다.

// settings-store
const enabled = store.get("enabled")
const unsubscribe = store.subscribeValues((value) => {
  // 설정 변경 처리
}, (state) => state.enabled)
// zustand
const value = store.getState().opened
const unsubscribe = store.subscribe((state) => {
  // 상태 변경 처리
})

타입 선언 가이드

definePlugin 제네릭

definePlugin<Api, State, BoundApi> 형태로 타입을 지정할 수 있습니다.

  • Api: 외부에서 호출할 플러그인 API
  • State: setup이 반환하는 상태 타입
  • BoundApi(선택): ctx가 바인딩된 형태의 API 타입 (예: modal)
const plugin = definePlugin<
  ModalApi,
  { store: StoreApi<ModalStore>; disposer: () => void },
  BoundModalApi
>(pluginId, { /* ... */ })

zustand store 타이핑

  • 상태 타입을 먼저 정의: type MyStore = { ... }
  • createStore<MyStore>((set) => ( ... ))로 생성
  • 플러그인 상태에 StoreApi<MyStore>를 명시

선택 기준 요약

  • 재시작 후에도 유지해야 하는 값: settings-store
  • 렌더링/상호작용 중심의 런타임 상태: zustand
  • 단순 내부 상태(작은 범위, API 내부 공유): definePlugin state

Footnotes

  1. 앱이 재시작되어도 유지해야 하는 값은 플러그인 설정 추가 문서를 참고하세요. ↩

Last updated on
UI 삽입하기Server