Akan.js v3
Akan.js v3
릴리즈 노트 · 2026년 9월 25일
v2가 Akan에 하나의 런타임을 줬다면, v3는 모든 앱에 두 번째 사용자를 줍니다. 화면을 지키던 가드가 이제 그 화면을 AI 에이전트에게도 공개합니다. MCP 도구로, 프롬프트로, 그리고 페이지 안에서 일하는 어시스턴트로요. 그 아래 UI 계층은 네이티브 토큰과 레시피로 새로 지었고, 측정한 모든 지표에서 v2보다 빠릅니다. 무엇이 바뀌었는지, 개발할 때 중요한 순서대로 정리합니다.
01
POST /mcp가 기본으로 열립니다. 가드가 허용하는 모든 엔드포인트가 Claude, Cursor 같은 MCP 클라이언트가 부를 수 있는 도구가 되고, 화면과 똑같은 필드 마스킹과 가드를 거칩니다. 도구 설명은 이미 쓰고 있는 딕셔너리에서 나옵니다. libs/shared를 쓰는 앱은 OAuth 2.1 인가 서버도 함께 띄우므로, 에이전트는 사용자로 로그인해 정확히 그 사용자의 권한으로만 움직입니다.
관리해야 할 노출 목록은 없습니다. 가드가 곧 권한 결정입니다. mcp: false는 가드가 있는 엔드포인트를 에이전트 목록에서만 빼고, Person 가드는 사람만 해야 하는 행동을 모델로부터 떼어 놓습니다.
02
레이아웃에 <Agent.Chat />를 한 번 두면, 사용자는 렌더링된 화면을 읽고 사용자 자신의 브라우저 세션 안에서 같은 컨트롤로 화면을 조작하는 어시스턴트를 얻습니다. 도구는 그 도구가 움직이는 컨트롤 옆에 선언합니다. st.tool(...)이 onClick에 넘길 핸들러를 돌려주므로 사람과 에이전트가 같은 코드 경로를 씁니다. 폼은 setter를 참조로 넘기기만 하면 스스로 도구를 공개합니다.
사용자가 첨부한 이미지와 문서를 읽고, 듣고 말하며, 도구 호출을 묶어서 실행하고, 데이터를 바꾸기 전에는 승인을 받습니다. OpenAI 호환 호스트와 Anthropic 모두 option.ts에서 설정하며, 앱이 가드를 지정하기 전까지 릴레이는 모든 호출을 거절합니다.
03
page().prompt(name, description)는 화면 하나를 MCP 프롬프트로 공개합니다. 에이전트가 실행하면 페이지의 fetch가 호출자의 토큰으로 돌고, 렌더링은 하지 않습니다. 에이전트는 그 데이터를 리소스로, 페이지가 읽은 모듈의 도구를 함께 받습니다. 사람을 위해 만든 화면이 그대로 에이전트용 브리핑이 되고, 따로 맞춰야 할 두 번째 구현은 없습니다.
04
daisyUI가 빠졌습니다. 테마는 이제 page/styles.css의 시맨틱 토큰 값(background, foreground, primary, muted와 각각의 -foreground 짝)이고, 모든 모양은 tailwind-variants로 만든 서버 안전 레시피입니다. buttonRecipe, badgeRecipe, inputRecipe, 그리고 ui/Recipe/ 아래의 직접 만든 레시피까지. 린트가 색 어휘를 닫아 두므로 raw 팔레트 클래스나 hex 값은 테마를 무시한 색으로 배포되는 대신 빌드에서 걸립니다.
앱마다 레시피가 AGENTS.md에 색인되므로, 에이전트는 비슷한 모양을 새로 만들지 않고 있는 레시피를 다시 씁니다.
05
page/**/_overrides.tsx 매니페스트는 akanjs/ui 컴포넌트(Modal, Button, Table, Input, 에이전트 채팅의 부품, 레시피 슬롯까지)를 그 라우트 하위에서만 직접 만든 컴포넌트로 바꿉니다. 매니페스트는 레이아웃처럼 중첩되고 슬롯 단위로 합쳐지며 가장 가까운 것이 이깁니다. 이제 루트 레이아웃과 포털로 뜨는 오버레이까지 닿습니다. 2.3.11에서 처음 나왔고, v3에서 UI 전체를 덮게 됐습니다. 리디자인이 더는 포크를 뜻하지 않습니다.
06
라우트 파일은 체인 하나만 내보냅니다. page(), layout(), rootLayout()이고, 모든 설정은 .param(), .search(), .config(), .head(), .prompt(), .render() 같은 단계입니다. 인자는 타입이 붙어 들어옵니다. ID는 string, Int는 number, Date는 Dayjs이고, 타입이 거부한 경로 값은 not-found로 응답합니다. pageConfig 옆에 default export를 두던 예전 형태도 폐기 경고와 함께 계속 동작합니다.
더 빠르고 더 작게
에이전트, MCP, 새로운 UI 시스템을 더하면서 속도를 잃지 않았는지 확인하려고 v2 때와 같은 벤치마크를 다시 돌렸습니다. v3는 더 빠르고, 메모리를 덜 쓰고, 두 배 빨리 시작합니다.
| 지표 | v2 | v3 | 변화 |
|---|---|---|---|
| 초당 요청 수 | 112K | 123K | +10% |
| 응답 시간 (p99) | 1.30 ms | 1.04 ms | −20% |
| 시작 시간 | 204 ms | 102 ms | −50% |
| 대기 메모리 | 84 MB | 57 MB | −32% |
| 부하 중 메모리 | 105 MB | 85 MB | −19% |
앱이 요청을 받을 준비가 되기까지 v2의 절반 정도 시간이면 충분합니다. 배포, 재시작, 스케일 아웃 후 더 빨리 서비스에 복귀합니다.
같은 앱이 대기 상태에서 메모리를 약 3분의 1 덜 사용합니다. 같은 머신에 더 많이 올릴 수 있습니다.
처리량은 늘고 느린 응답은 더 빨라져, Akan.js는 가장 빠른 Bun 프레임워크들과 나란히 있습니다.
Akan.js는 단순한 라우터보다 훨씬 많은 일을 합니다. 데이터베이스, 인증, 서버 렌더링, 에이전트가 모두 내장되어 있는데도 가벼운 Bun 프레임워크들과 속도를 나란히 합니다.
초당 요청 수
| 프레임워크 | 시작 시간 | 대기 메모리 |
|---|---|---|
| raw Bun.serve(Bun) | 102.0 ms | 31.5 MB |
| ElysiaJS(Bun) | 104.0 ms | 37.0 MB |
| Hono(Bun) | 103.4 ms | 33.1 MB |
| Akan.js v3(Bun) | 102.2 ms | 57.2 MB |
| raw sqlite(Bun) | 101.9 ms | 35.8 MB |
| Fastify(Node) | 103.7 ms | 69.3 MB |
Apple M4 Pro MacBook Pro에서 production 빌드, 동시 사용자 50명으로 측정했습니다. Fastify는 Node에서 실행되어 런타임 차이가 일부 반영됩니다. 원시 데이터와 벤치마크 하네스는 benchmarks/api-benchmark에 있습니다.
26MB → 8.1MB
클라이언트 빌드 결과물, 청크 605개 → 258개
3.5ms → 0.9ms
클라이언트에서 1,000행 하이드레이션
−33%
50행 목록 쿼리 시간, 할당은 85% 감소
103KB → 13KB
이 사이트의 CSS 전송량, brotli 사전 압축
86MB → 6.2MB
이 사이트를 API 전용(web: false)으로 빌드한 이미지
v3는 어떤 릴리즈보다 많은 기능을 더했지만, 측정한 모든 지표에서 v2보다 빠릅니다. 업그레이드하면 앱이 더 빠르고, 가볍고, 빨리 시작합니다. 그 속도는 여러분의 코드가 아니라 프레임워크에서 옵니다.
07
fetch.init*, view*, edit*를 필드별 프로미스로 나눠 섹션마다 자기 경계 뒤에서 스트리밍합니다. akan quality ssr은 앱별 서버 렌더링 비율을 재고 필요 없는 “use client”를 짚어 줍니다.
08
필드에 text 역할을 주고 필터에 q.search(text)를 쓰면 됩니다. bm25 정렬의 SQLite FTS5이고, secret 필드에 역할을 주면 컴파일 에러입니다.
09
슬라이스에 .live()를 붙이면 그 목록을 보는 모든 화면에 들어옴·변경·나감 이벤트가 전달되고 Load.Units가 반영합니다. 폴링이 없고, 방은 슬라이스의 가드를 그대로 따릅니다.
10
수정·생성 셸이 사용자와 레코드별로 폼을 저장해 두고, 실수로 닫거나 라우트를 옮기거나 앱이 종료된 뒤에 다시 제안합니다. secret 필드는 저장하지 않습니다.
11
cascade: removeRef와 removeWith로 삭제가 어느 방향으로 번지는지 선언하고, 모든 필터가 삭제 부수효과가 없는 모델을 위한 쿼리 수준 remove와 update도 만들어 줍니다.
12
엔드포인트의 { timeout }이 호출 양 끝을 제한하고, { cache }는 인자 없는 쿼리를 가드 통과 뒤에 캐시하며, pubsub(Binary)는 웹소켓 바이너리 프레임으로 보내고, API와 웹소켓 prefix를 바꿀 수 있습니다.
13
레플리카가 하나면 게이트웨이 없이 한 프로세스로 돌고, web: false나 { csr: false }로 쓰지 않는 표면을 빼며, 생성되는 이미지는 앱이 선언한 것만 담습니다.
14
모든 로그 줄이 trace id를 가진 구조화된 레코드입니다. akan logs로 실행 중인 서버를 따라가며 거르고, ndjson stdout, SSE 스트림, 호출당 한 줄 요약, 플라이트 레코더는 env 하나로 켭니다.
15
akan start a,b로 여러 앱을 한 전체 화면 뷰에서 띄우고 앱마다 로그 파일을 남기며, akan tunnel이나 --share로 로컬 앱을 공개 URL에 올립니다.
16
모든 워크스페이스에 생성된 AGENTS.md, 번들 가이드라인, 계획 후 적용하는 워크플로 MCP, 그리고 이것들을 통해 일하는 터미널 코딩 에이전트 akan code가 들어 있습니다.
17
모바일 푸시 알림과 딥링크는 프레임워크 안이 아니라 akan.config.ts의 plugins 목록에 선언합니다.
18
클라이언트/서버 import 누수, 클라이언트 파일의 fetch.init*, 클라이언트 컴포넌트의 모델 타입 prop, raw Error throw를 배포 전에 잡는 규칙이 추가됐습니다.
손이 가야 하는 변경입니다. 대부분은 akan lint와 akan typecheck가 위치를 짚어 줍니다.
daisyUI 클래스와 raw 팔레트 클래스는 스타일 없이 렌더링됩니다. 시맨틱 토큰으로 옮기세요. 린트 페이지에 예전 클래스별 대체 표가 있습니다.
/conventions/workspace/lint라우트 파일은 page()…render()로 옮깁니다. .metadata()와 .gaTrackingId()는 제거됐고, head는 .head()의 JSX입니다.
/docs/core/routing/mcp가 기본으로 켜집니다. 모든 가드는 static scope를 선언하고, 모든 커스텀 엔드포인트는 guards를 명시하며, local 밖에서는 JWT_SECRET이 필수입니다. AKAN_MCP=false로 끌 수 있습니다.
/cheatsheet/interface/mcpdeleteMany는 removeMany가 됐고, countDocuments는 count로 대체되어 폐기 예정입니다.
/docs/core/data-layerRetry와 @CacheMethod는 제거되고 엔드포인트의 { timeout }, { cache }와 memory()로 대체됩니다. 모델 로더는 { cache }를 선언할 때만 캐시합니다.
/cheatsheet/performance/caching모델의 Date 필드는 프로토타입 접근자입니다. 모델 복사는 스프레드가 아니라 new cnst.X().set(model)로 합니다.
/conventions/module/constant생성되는 이미지에는 ca-certificates와 tzdata만 설치됩니다. ffmpeg나 Chromium은 docker.preRuns에 선언하세요.
/cheatsheet/dev/dockerlogger.log()는 .info()로, usePushNotification은 @libs/util/webkit으로 옮겨졌고, --ai CLI 명령은 akan code로 대체됐습니다.
/references/cli/codev3는 에이전트가 풀스택에 합류한 단계입니다. 다음은 세션과 사람, 앱을 넘나드는 에이전트 네트워크, 배포를 맡는 Akan Cloud, SSR·CSR 다음의 에이전틱 렌더링인 컨텍스트사이드 렌더링, 그리고 앱을 직접 변경·확장하는 레포지토리 엔진입니다.
로드맵 보기