워크스페이스 구조
Akan 워크스페이스는 Bun 기반 모노레포 하나입니다. 코드가 루트의 어느 폴더에 있는지가 곧 그 코드의 성격입니다. 직접 실행하는 제품, 여러 앱이 나눠 쓰는 라이브러리, 패키지 중 하나입니다.
워크스페이스 루트는 이렇게 생겼습니다:
my-workspace/
코드는 어느 폴더에 두나요?
코드
apps/
libs/
pkgs/
제품 하나로 실행되는 코드
고객 사이트 · 관리자 포털 · 브랜드 앱
✓
따로 실행하고 배포하는 제품입니다.
앱 하나만 쓰는 비즈니스 코드
✓
그 앱의 페이지, 모듈, UI는 앱 안에 둡니다.
여러 앱이 함께 쓰는 코드
인증 · 업로드 · 결제 · 알림
✓
여러 제품에 똑같이 필요한 공통 도메인입니다.
공통 유틸리티와 UI
✓
여러 앱이 import하는 헬퍼와 컴포넌트입니다.
Akan 자체, 또는 설치형 패키지
프레임워크 · CLI · devkit · 런타임
✓
Akan 자체에 속한 코드와 패키지 수준의 도구입니다.
독립 패키지
✓
설치해서 쓰는 패키지처럼 동작해야 하는 코드입니다.
✓여기에 둡니다해당 없음
apps/에서 시작합니다. 제품 하나에 속한 코드는 그 앱 안에 둡니다. 두 번째 앱이 같은 코드를 필요로 할 때libs/로 옮깁니다.pkgs/는 마지막 선택지입니다. 코드가 설치형 패키지처럼 독립적이어야 할 때만 씁니다.libs/와pkgs/는 필요할 때 생깁니다. 새 워크스페이스는 앱 하나로 시작하고, 나머지 두 폴더는create-library,create-package로 만들 때 생깁니다.
루트에 있는 파일
파일설명
.env
AKAN_PUBLIC_ENV, 서비스 도메인 같은 워크스페이스 공통 설정으로, git에는 올리지 않습니다.package.json
루트 의존성과
dev, lint, test, build 같은 bun run 스크립트입니다.tsconfig.json
TypeScript 설정과
@apps/*, @libs/* import 별칭입니다.biome.json
모든 앱, 라이브러리, 패키지에 똑같이 적용하는 포맷·import·린트 규칙입니다.
bunfig.toml
Tailwind 플러그인과 브라우저용 환경 변수 접두사
AKAN_PUBLIC_*를 지정하는 Bun 설정입니다.AGENTS.mdCLAUDE.md
코딩 에이전트용 가이드로,
CLAUDE.md는 akan agent install이 갱신하는 AGENTS.md를 불러옵니다..akan/, dist/, node_modules/는 도구가 만들고 git에서 제외되는 폴더라서 직접 고치지 않습니다.워크스페이스 명령
워크스페이스 명령은 모노레포 전체를 대상으로 합니다. 워크스페이스와 그 안의 앱·라이브러리·패키지를 만들고, 린트와 sync로 상태를 맞춥니다.
자주 쓰는 명령은 다음과 같습니다:
Terminal
만들기
| 명령 |
|---|
| ↳ 결과 |
| akan create-workspace <name> |
| 첫 앱, 에이전트 규칙, MCP 설정까지 갖춘 새 워크스페이스 폴더입니다. |
| akan create-application <app-name> |
apps/<app-name>/에 실행 가능한 앱이 생깁니다. |
| akan create-library <lib-name> |
libs/<lib-name>/에 여러 앱이 공유할 라이브러리가 생깁니다. |
| akan create-package --name <pkg-name> |
pkgs/<pkg-name>/이 생기고, tsconfig.json에 <pkg-name> import 별칭이 추가됩니다. |
- 첫 단계는
bunx create-akan-workspace@latest입니다.akanCLI를 설치하고akan create-workspace를 대신 실행합니다.--libs true를 주면util,shared라이브러리도 함께 설치합니다. - 이름을 빼면 물어봅니다. 이름 없이 실행하면 CLI가 입력을 받습니다. 이름은 소문자로 바뀌고 공백은
-가 됩니다.
린트와 sync
명령
sync
lint
대상 하나
akan lint <target>
✓
✓
앱, 라이브러리, 패키지 하나를 다루며, 패키지는 sync 없이 린트만 합니다.
워크스페이스 전체
akan lint-all
✓
✓
모든 앱과 라이브러리를 sync한 뒤, 모든 앱·라이브러리·패키지를 린트합니다.
akan sync-all
✓
모든 라이브러리, 그다음 모든 앱을 sync하고 린트는 하지 않습니다.
✓실행함건너뜀
sync는 앱이나 라이브러리를 최신 상태로 맞춥니다. 소스를 다시 스캔해 생성 파일, 의존성, 설정을 새로 씁니다.- 명령 이름은 kebab-case입니다.
akan lintAll이 아니라akan lint-all입니다.
이 명령들은 워크스페이스 루트에서 실행합니다.
package.json, tsconfig.json, .env가 있는 폴더이며, 다른 곳에서는 오류를 내고 멈춥니다. 그 폴더를 만드는 create-workspace만 예외입니다.