image
Akan.js
한국어
문서컨벤션레퍼런스Cheatsheet
image
Akan.js
Akan.js v2 문서가 새로 나왔습니다.v1 문서 보기
문서컨벤션레퍼런스Cheatsheet
MIT 라이선스 하에 배포되었습니다.
Akan.js 공식 컨설팅 서비스Akansoft
Copyright © 2026 Akan.js 모든 권리 보유.
시스템 관리자bassman
워크스페이스 규칙
• 구조
• 포맷 & 린트
앱 & 라이브러리 규칙
• 애셋 (public/ private/)
• 컴포넌트 (ui/)
• 서버 유틸리티 (srvkit/)
• 웹 유틸리티 (webkit/)
• 공통 유틸리티 (common/)
• akan.config.ts
도메인 규칙
• 개요
• model.constant.ts
• model.dictionary.ts
• model.document.ts
• model.service.ts
• model.signal.ts
• model.store.ts
• Model.Template.tsx
• Model.Unit.tsx
• Model.Util.tsx
• Model.View.tsx
• Model.Zone.tsx
스칼라 규칙
• 개요
• scalar.constant.ts
• scalar.dictionary.ts
• scalar.document.ts
• Scalar.Template.tsx
• Scalar.Unit.tsx
서비스 규칙
• 개요
• service.dictionary.ts
• service.service.ts
• service.signal.ts
• service.store.ts
• Service.Util.tsx
• Service.Zone.tsx
워크스페이스 규칙
• 구조
• 포맷 & 린트
앱 & 라이브러리 규칙
• 애셋 (public/ private/)
• 컴포넌트 (ui/)
• 서버 유틸리티 (srvkit/)
• 웹 유틸리티 (webkit/)
• 공통 유틸리티 (common/)
• akan.config.ts
도메인 규칙
• 개요
• model.constant.ts
• model.dictionary.ts
• model.document.ts
• model.service.ts
• model.signal.ts
• model.store.ts
• Model.Template.tsx
• Model.Unit.tsx
• Model.Util.tsx
• Model.View.tsx
• Model.Zone.tsx
스칼라 규칙
• 개요
• scalar.constant.ts
• scalar.dictionary.ts
• scalar.document.ts
• Scalar.Template.tsx
• Scalar.Unit.tsx
서비스 규칙
• 개요
• service.dictionary.ts
• service.service.ts
• service.signal.ts
• service.store.ts
• Service.Util.tsx
• Service.Zone.tsx
이전
구조
다음
애셋 (public/ private/)

포맷과 린트

Akan lint는 워크스페이스를 읽기 쉽고 깨지기 어렵게 유지하기 위한 장치입니다. 평소 작업에서는 몇 가지만 기억하면 됩니다. 스타일은 formatter에 맡기고, client 전용 코드는 server 파일에 넣지 말고, convention 파일에서 임의의 외부 import를 피하고, 작업을 공유하기 전에 lint를 실행하세요.
포맷은 도구에 맡기기
2칸 indentation, double quote, import 정리, class 정렬은 formatter 기준을 따릅니다.
서버 파일은 서버답게
서버에서 렌더링되어야 하는 파일에는 useState, useEffect, st, top-level use client를 넣지 않습니다.
Import는 의도적으로
컨벤션 파일은 외부 패키지를 바로 가져오기보다 relative path, Akan package, workspace alias를 우선 사용합니다.
공유 전 실행
수정한 앱이나 라이브러리에 lint를 실행하고, 넓은 범위 확인 전에는 lintAll을 사용합니다.

Akan lint 에러와 고치는 법

일부 lint 에러는 스타일 문제가 아닙니다. server UI, client UI, service code, shared utility가 잘못된 위치에 섞였을 때 발생합니다. 아래 예시를 기본 형태로 생각하세요. server page는 단순하게 유지하고, 브라우저 상호작용은 client component로 옮기고, 외부 도구는 내부 모듈 뒤로 감싸서 사용합니다.
서버 파일에서 client hook을 쓴 경우
server page나 서버 성격의 component에서 useState, useEffect, useMemo, useRef 같은 React client hook을 import할 때 발생합니다.
❌ Before
page.tsx
✅ After
page.tsx
LikeButton.tsx
서버 파일에 use client를 추가한 경우
작은 일부에 브라우저 상호작용이 필요하다고 해서 page 전체를 client component로 바꾸지 마세요.
❌ Before
page.tsx
✅ After
page.tsx
ScrollReset.tsx
서버 UI에서 함수 prop을 넘긴 경우
server component는 이벤트 동작이 아니라 데이터를 넘겨야 합니다. onClick 같은 callback은 client component 안으로 옮기세요.
❌ Before
page.tsx
✅ After
page.tsx
OrderCardAction.tsx
외부 패키지를 직접 import한 경우
convention 파일은 임의의 외부 패키지에 직접 의존하지 않는 것이 좋습니다. 먼저 내부 util이나 library 파일로 감싸서 사용하세요.
❌ Before
order.service.ts
✅ After
order.service.ts
@libs/util/id.ts
JavaScript private method를 쓴 경우
service class에서는 JavaScript #private method 대신 underscore 이름을 가진 TypeScript private method를 사용하세요. Service를 제외한 다른 class에서는 #private method를 사용할 수 있습니다.
❌ Before
order.service.ts
✅ After
order.service.ts
일부 framework 패턴에는 예외가 있지만, 일반적인 앱 코드를 작성할 때는 먼저 After 형태를 기본값으로 생각하세요. 의도적인 console 출력은 console.log 대신 console.info, console.warn, console.error를 사용하세요.

명령어

일반 개발 중에는 workspace lint 명령을 사용하세요. 특정 파일 하나를 검증하거나 포맷 문제를 디버깅할 때는 Biome check를 직접 사용할 수 있습니다.
Lint commands
포맷과 린트
Akan lint 에러와 고치는 법
명령어