Karrotframe에서 이사가기

Karrotframe과 Stackflow는 다음과 같은 멘탈모델의 차이가 존재해요.

Karrotframe의 경우,

  1. 노출되는 페이지를 "스크린"이라고 불러요.
  2. 일반적인 URL Path를 기반으로 라우팅해요. 필요한 파라미터가 있다면 패스 파라미터 또는 쿼리 파라미터로 담아요.
  3. 기본 UI를 포함하고 있어요. 따라서 각 스크린 컴포넌트는 껍데기안에 담길 내용만 포함해요.

Stackflow의 경우,

  1. 노출되는 페이지를 "액티비티"라고 불러요.
  2. 액티비티 이름을 기반으로 라우팅해요. 필요한 파라미터가 있다면 액티비티 파라미터로 담아요.
  3. 기본 UI를 포함하고 있지 않아요. 따라서 각 액티비티 컴포넌트는 basic-ui 등 껍데기도 포함해야해요.

이러한 멘탈 모델을 옮겨간다고 생각하고 이사를 하면 좋아요.

⚡️

기존 Path 기반의 라우팅을 Stackflow에서 사용하기 위해서는 @stackflow/plugin-history-sync 적용이 필요해요. 액티비티 이름과 URL 템플릿을 매핑하고, 액티비티 파라미터를 템플릿 내 패스 파라미터와 연결할 수 있어요.

⚠️

본 마이그레이션 가이드는 부분적인 컨셉을 담고있고 100% 기능을 커버하지 않아요. Karrotframe에서 쓰던 기능은 전부 다 옮겨왔으므로, 혹시 추가적으로 필요하다고 생각되는 기능이 있으시다면 문서를 찬찬히 살펴보시면 찾으실 수 있을거에요.

1. Stack으로 옮겨가기

다음과 같이 기존의 <Navigator /><Screen /> 컴포넌트를 통해 페이지를 등록하던 로직을 stackflow() 함수와 historySyncPlugin()을 통해 등록하는 과정으로 바꿔요.

/**
* as-is:
*/
const App = () => {
return (
<Navigator>
<Screen path="/my-page/:someid" component={MyPage} />
<Screen path="*" component={NotFoundPage} />
</Navigator>
);
};
/**
* to-be:
*/
const { Stack } = stackflow({
activities: {
MyPage,
NotFoundPage,
},
plugins: [
historySyncPlugin({
routes: {
MyPage: "/my-page/:someid",
},
fallbackActivity: () => "NotFoundPage",
}),
],
});
const App = () => {
return <Stack />;
};

2. useFlow(), useActivityParams() 사용하기

다음과 같이 기존에 네비게이팅을 담당하던 useNavigator()useFlow()로 변경해요.

/**
* as-is:
*/
const MyPage = () => {
const { push } = useNavigator();
const onClick = () => {
push("/something-page?foo=bar");
};
return <div>{/* ... */}</div>;
};
/**
* to-be:
*/
const MyPage = () => {
const { push } = useFlow();
const onClick = () => {
push("SomethingPage", {
foo: "bar",
});
};
return <div>{/* ... */}</div>;
};

기존에 useParams(), useQueryParams() 훅으로 파라미터를 받던 부분을 useActivityParams()로 교체해요.

/**
* as-is:
*/
const SomethingPage = () => {
const { foo } = useParams();
return <div>{/* ... */}</div>;
};
/**
* to-be:
*/
const SomethingPage = () => {
const { foo } = useActivityParams();
return <div>{/* ... */}</div>;
};

3. 각 루트 컴포넌트에서 @stackflow/plugin-basic-ui<AppScreen /> 컴포넌트를 사용하기

Stackflow는 기본적으로 UI를 포함하고 있지 않아요. 따라서 껍데기 컴포넌트를 각 액티비티에 넣어주어야해요.

/**
* as-is:
*/
const SomethingPage = () => {
return <div>Hello, World!</div>;
};
/**
* to-be:
*/
const SomethingPage = () => {
return (
<AppScreen>
<div>Hello, World!</div>
</AppScreen>
);
};
⚡️

<AppScreen /> 컴포넌트에 필요한 Props는 여러 부분에서 반복될 수 있어요. 따라서 <AppScreen /><MyLayout /> 같은 컴포넌트를 만들고, 한번 감싸서 활용하시는걸 추천드려요.