Common 개요

common 폴더는 서버와 클라이언트 환경 양쪽에서 실행될 수 있는 로직을 담습니다. browser 전용 API나 server 전용 API에 의존하지 않는 순수 helper, shared formatting, validation, metadata builder, transform에 사용합니다.

서버 전용 로직은 srvkit, 브라우저 또는 웹 렌더링 로직은 webkit, service, signal, page, component가 함께 쓰는 cross-runtime 로직은 common에 둡니다.

Common에 두는 것

Formatter

bytes, packets, money, short label처럼 service output과 UI display에서 모두 쓰는 formatting 로직입니다.

common/formatBytes.ts

Validator

서버와 브라우저에서 동일하게 동작해야 하는 validation 또는 predicate helper입니다.

common/isHttpUri.ts

Random/string utility

random code, padding, shuffle, 짧은 문자열 변환처럼 작은 범용 helper입니다.

common/randomCode.ts

Metadata builder

query, filter, display metadata를 특정 runtime에 묶지 않고 표현하는 작은 object 또는 builder class입니다.

common/getQueryMeta.ts

Content transform

editor JSON에서 plain text를 추출하는 것처럼 저장된 content를 다른 형태로 변환하는 순수 transform입니다.

common/extractTextFromSlateJson.ts

Barrel, 최적화 import, 권장 구조

common 폴더도 ui와 webkit처럼 barrel folder입니다. shared helper를 index.ts에서 export하고 barrel에서 import합니다. Akan은 import를 최적화해서 페이지가 실제로 사용하는 common helper만 bundle에 포함할 수 있습니다.

1개 파일, 1개 export, 파일명과 export명을 일치시키는 것을 권장합니다. 이렇게 하면 cross-runtime helper를 찾기 쉽고 최적화하기도 쉬워집니다.

common/randomCode.ts

common/index.ts

서버와 클라이언트 사용

common helper는 service 코드와 page/client 코드 양쪽에서 사용할 수 있습니다. window, document, Bun, fs, process.env, vendor SDK처럼 한쪽 runtime에만 있는 API에 의존하지 않도록 유지하세요.

order.service.ts

page.tsx

실전 규칙

같은 로직이 service/signal 코드와 page/component 코드 양쪽에서 동작해야 한다면 common을 사용합니다.

helper가 server-only API를 필요로 한다면 srvkit을 사용합니다.

helper가 browser-only API를 필요로 한다면 webkit을 사용합니다.

common helper는 작고 순수하게 유지하고 barrel에서 import합니다.

Common 개요

Common에 두는 것

Barrel, 최적화 import, 권장 구조