플러그인 작성하기

Stackflow는 플러그인 인터페이스를 통해 다른 사람이 작성한 확장 로직을 쉽게 내 어플리케이션과 연동할 수 있도록 도와요. 플러그인을 통해 나의 문제를 해결하고, 이를 예쁘게 감싸서 다른 사람과 공유해보세요.

프리셋 만들기#

Stackflow 플러그인을 출판하는 가장 쉬운 방법은 다른 사람이 만든 플러그인들을 조합해서 프리셋으로 제공하는 것이에요. 다음과 같이 여러 플러그인을 Array로 묶어서 나만의 프리셋을 만들 수 있어요.

import { basicRendererPlugin } from "@stackflow/plugin-renderer-basic";
import { historySyncPlugin } from "@stackflow/plugin-history-sync";
import { stackflow } from "@stackflow/react";

const myPlugin = ({ ... }) => [
  basicRendererPlugin(),
  historySyncPlugin({ ... }),
];

stackflow({
  // ...
  plugins: [myPlugin()],
});

기본 인터페이스#

플러그인은 함수의 형태로 아래와 같은 값을 필수로 반환해야해요.

반환 값#

내 앱에 나만의 첫 플러그인 개발을 시도해보려면 다음과 같이 inline 함수로 시작해보세요. (어렵지 않아요!)

import { basicRendererPlugin } from "@stackflow/plugin-renderer-basic";
import { stackflow } from "@stackflow/react";

stackflow({
  // ...
  plugins: [
    basicRendererPlugin(),
    basicUIPlugin({
      theme: "cupertino",
    }),
    () => {
      return {
        key: "my-plugin",
      };
    },
  ],
});

렌더링 추가하기#

렌더링을 새로 추가하고 싶다면, render API를 사용할 수 있어요. Stack 상태를 이용해 어떻게 DOM을 최적화할지 결정하고 싶거나, 때에 따라 새로 얹을 새로운 DOM 트리가 필요하다면 render API를 활용하세요.

stackflow({
  // ...
  plugins: [
    () => {
      return {
        key: "my-plugin",
        render({ stack }) {
          return (
            <div className="my-rendering">
              {stack.render().activities.map((activity) => (
                <div className="my-activity" key={activity.id}>
                  {activity.render()}
                </div>
              ))}
            </div>
          );
        },
      };
    },
  ],
});

다음과 같이 UI에 전달되는 스택 상태를 덮어 쓸 수도 있어요.

stackflow({
  // ...
  plugins: [
    () => {
      return {
        key: "my-plugin",
        render({ stack }) {
          return (
            <div className="my-rendering">
              {stack
                .render({
                  // 여기서 stack 상태를 덮어쓸 수 있어요.
                })
                .activities.map((activity) => (
                  <div className="my-activity" key={activity.id}>
                    {activity.render({
                      // 여기서 activity 상태를 덮어쓸 수 있어요.
                    })}
                  </div>
                ))}
            </div>
          );
        },
      };
    },
  ],
});

스택 감싸기#

최상단에 Context API Provider를 추가하고 싶거나, 최상단을 특정 DOM으로 감싸고 싶다면 wrapStack 인터페이스를 활용하세요.

stackflow({
  // ...
  plugins: [
    () => {
      return {
        key: "my-plugin",
        wrapStack({ stack }) {
          // 여기서 인자로 가져온 stack 정보를 활용할 수 있습니다
          return <div className="my-plugin">{stack.render()}</div>;
        },
      };
    },
  ],
});

액티비티 감싸기#

각 액티비티를 Context API Provider를 추가하고 싶거나, 특정 DOM으로 감싸고 싶다면 wrapActivity 인터페이스를 활용하세요.

stackflow({
  // ...
  plugins: [
    () => {
      return {
        key: "my-plugin",
        wrapActivity({ activity }) {
          // 여기서 인자로 가져온 activity 정보를 활용할 수 있습니다
          return <div className="my-activity">{activity.render()}</div>;
        },
      };
    },
  ],
});

초기화 시점에 동작 주입하기#

<Stack /> 컴포넌트가 최초로 초기화 될 때 로직을 호출하고 싶다면 onInit 훅을 사용해요.

stackflow({
  // ...
  plugins: [
    () => {
      return {
        key: "my-plugin",
        onInit() {
          console.log("Initialized!");
        },
      };
    },
  ],
});

이펙트 훅#

기능을 확장하거나 외부의 상태와 동기화하고 싶으신가요? 스택 상태가 변화할때마다 특정 동작을 하거나, 또는 스택 상태가 변경되기 이전에 함수를 호출할 수 있어요.

스택 상태는 유저의 행동으로 인해, push, replace, pop이 호출됐을때 변화하기 시작해요. 해당 시점부터 스택 상태가 변화하기 전(Pre-effect)과 변화한 뒤 UI까지 반영된 이후 (Post-effect)에 특정 동작을 수행할 수 있어요.

Post-effects#

Post-effect 훅에는 onPushed, onReplaced, onPopped, onChanged가 있어요. Post-effect 훅은 UI까지 모두 반영된 이후에 호출되기 때문에, 해당 변화를 다시 돌이키거나 취소할 수 없어요. Post-effect 훅은 다음과 같은 인자를 사용할 수 있어요.

stackflow({
  // ...
  plugins: [
    () => {
      return {
        key: "my-plugin",
        onPushed(actions, effect) {
          // actions.getStack()
          // actions.dispatchEvent(...)
          // 를 활용할 수 있어요
          console.log("Pushed!");
          console.log("Effect:", effect);
        },
      };
    },
  ],
});

Pre-effects#

Pre-effect 훅에는 onBeforePush, onBeforeReplace, onBeforePop이 있어요. Pre-effect 훅은 아직 Core에 해당 이벤트가 전달되기 전에 호출되기 때문에, 해당 이벤트를 취소할 수 있어요. Pre-effect 훅은 다음과 같은 인자를 사용할 수 있어요.

첫 액티비티 결정하기#

initialPushedEvent API를 통해 기존에 존재하는 initialActivity 동작을 덮어쓸 수 있어요. (이벤트에 대한 자세한 설명은 원칙과 설계 문서를 참고하세요)

import { makeEvent } from "@stackflow/core";

stackflow({
  // ...
  plugins: [
    () => {
      return {
        key: "my-plugin",
        initialPushedEvent() {
          return makeEvent("Pushed", {
            // ...
          });
        },
      };
    },
  ],
});

여기까지 전부 이해하셨다면, Stackflow에 대한 기본적인 내용은 잘 숙지하셨을거에요. 만약 추가적인 정보가 필요하시거나, 이슈 제보 또는 도움이 필요하시다면 GitHub Issues를 활용해주세요.