Akan.js
한국어 | Docs | v3 release note | npm
<img width="600" alt="Akan.js — one line of business code, every face." src="https://raw.githubusercontent.com/akan-team/akanjs/HEAD/apps/akan/public/jelly/og.jpg" />
에이전트가 포함된 타입스크립트 (TypeScript) 프레임워크입니다. Bun으로 구동됩니다.
화면을 구축하면 에이전트가 사용할 수 있습니다. 서버를 구축하면 어떤 AI라도 실행할 수 있습니다.
도구 스키마(tool schemas), 작성해야 할 MCP 서버, 두 번째 권한 모델이 필요 없습니다. 사람들을 위해 구축하는 앱 자체가 사용자가 선택한 모델에서 AI가 사용할 수 있는 앱입니다. 단 한 줄의 비즈니스 코드가 모든 계층을 통과하고, 6개 플랫폼으로 배포되며, 이를 사용하는 모든 사용자—사람과 에이전트 모두에게 도달합니다.
빠른 시작 (Quick Start)
코딩 에이전트를 사용하여
Claude Code 또는 Codex를 빈 디렉터리에서 열고 다음 프롬프트를 붙여넣으세요. 여기에 워크스페이스와 앱 이름을 추가하거나, 에이전트가 질문하도록 할 수 있습니다.
Set up a new Akan.js workspace for me (https://akanjs.com).
1. Check that Bun 1.4.4 or newer is installed (`bun --version`). If it isn't, install or upgrade it as https://bun.sh describes.
...
새로운 워크스페이스에는 에이전트가 작업하는 내용물인 AGENTS.md와 CLAUDE.md, Cursor 규칙, 그리고 Claude Code, Codex 및 Cursor용으로 등록된 Akan MCP 서버가 이미 포함되어 있습니다. 따라서 워크스페이스 내부에서 에이전트를 다시 열어 로드하도록 하세요.
터미널에서
Bun >=1.4.4가 필요합니다.
bunx create-akan-workspace@latest
cd <workspace-name>
akan start <app-name> --open
생성자는 워크스페이스 이름과 앱 이름을 요청하고, akan CLI와 워크스페이스의 종속성을 설치하며, 샘플 앱을 생성합니다. 이 앱은 http://localhost:8282에서 열립니다.
모든 것이 단 한 줄입니다 (All Of It Is One Line)
export class ProductInput extends via((field) => ({
name: field(String),
})) {}
1줄 × 8개 계층 × 6개 플랫폼 × 사람 및 에이전트.
- 1 줄. 필드를 추가하는 것은 하나의 선언으로 충분합니다: 이름과 타입만 지정하면 됩니다.
- × 8 계층(layers). 이 한 줄은 스키마(schema), 쿼리(query), 서비스(service), API, 페치(fetch), 클라이언트 타입(client type), 상태(state), UI prop을 거칩니다. 일반적인 스택에서는 수동으로 변경해야 하는 여덟 군데이며, 하나라도 빠지면 타입이 깨지거나 런타임에 실패합니다. 여기서는 이들이 함께 변경됩니다.
- × 6 플랫폼(platforms). 동일한 코드가 SEO 최적화가 가능한 웹, iOS 및 Android 앱, 그리고 macOS, Windows 및 Linux 데스크톱 앱으로 배포되며, 단순히 감싼 웹사이트가 아니라 네이티브 수준의 화면 전환을 제공합니다.
- × 사람 및 에이전트(people & agents). 모든 보호된 엔드포인트(guarded endpoint)는 MCP 도구가 되고, 화면상의 모든 컨트롤은 사용자가 통과하는 것과 동일한 보호 장치 뒤에 있는 인페이지 에이전트 도구가 됩니다.
당신이 구축하는 화면이 곧 에이전트의 인터페이스입니다
export const Order = () => {
const { l } = usePage();
const icecreamOrderForm = st.use.icecreamOrderForm();
...
- 작성하려던 화면을 그대로 작성합니다. 필드는 세터(setter)를 통해 게시됩니다. 버튼의 핸들러는 하나의
st.tool 라인을 가진 도구가 되며, 이는 버튼이 호출하는 함수와 동일합니다.
- 에이전트는 픽셀(pixels)이 아닌 도구(tools)를 인식합니다. 연결한 모든 컨트롤은 자신이 받는 인자(arguments)와 함께 고유한 이름으로 게시됩니다. 화면에 없는 것은 목록에도 없습니다.
- 사용자의 자체 탭에서 세션과 함께 작동하며, 클릭하는 것과 정확히 같습니다.
- 중요한 것은 '예'를 기다립니다.
confirm으로 선언된 도구는 승인 카드(approval card)에서 멈춥니다.
설정은 레이아웃에 하나의 <Agent.Chat />만 추가하고, option.ts 파일에 모델 키를 지정하면 됩니다. OpenAI와 호환되는 호스트 및 Anthropic 모두 작동합니다.
당신의 서버는 이미 MCP 서버입니다
serveIcecreamOrder: mutation(cnst.IcecreamOrder, {
guards: [Admin],
})
...
- 어떤 MCP 클라이언트든 앱에 연결할 수 있습니다.
POST /mcp는 기본적으로 활성화되어 있습니다. 호출자를 허용하는 가드(guard)가 있는 모든 엔드포인트는 이미 작성한 딕셔너리에 의해 설명되는 도구입니다.
- 로그인 및 동의는 앱에서 처리됩니다. OAuth 2.1은
libs/shared와 함께 제공됩니다. AI는 한 사용자에게 대한 토큰을 받으며, 이는 해당 사용자의 권한과 정확히 일치하고 언제든지 취소할 수 있습니다.
- 해서는 안 되는 일을 할 수 없습니다.
refundIcecreamOrder는 Person에 의해 가드되어 있어 절대 실행되지 않습니다. AI에게는 마치 존재하지 않는 도구와 똑같이 보입니다.
- 페이지가 프롬프트가 됩니다.
page().prompt(name, description)은 화면을 MCP 프롬프트로 게시합니다. 이 과정에서 가져오기(fetches)는 호출자의 토큰 하에 실행되며, 에이전트는 동기화하기 위해 별도의 구현체를 유지할 필요 없이 데이터를 받게 됩니다.
하나의 규칙, 세 가지 유형의 사용자
엔드포인트당 한 번 가드를 작성합니다. 이 가드는 화면에 있는 사람, 탭에 있는 에이전트, 그리고 MCP를 통해 호출하는 AI에게 각각 적용됩니다.
- 거절은 아무것도 노출하지 않습니다. 에이전트가 사용할 수 없는 도구는 존재하지 않는 도구와 정확히 같은 방식으로 응답합니다.
- 호출자별 속도 제한(Rate-limited). MCP 호출은 호출자당 분당 120회, 동시에 8회로 제한됩니다.
- 비밀 정보는 안전하게 유지됩니다. 숨겨진 필드와 비밀 필드는 모델에 도달하기 전에 제거됩니다(stripped).
- 연결은 사용자가 종료할 때 끝납니다. 연결을 취소하면 다음 호출이 거부됩니다. 채팅 릴레이는 세션이나 기록(transcript)을 유지하지 않습니다.
에이전트도 구축합니다.
AI 코딩은 일정 크기를 넘어서면 스파게티처럼 변합니다. 에이전트가 빠르게 작성할수록 파일 경로, 이름, 구조 및 선언 스타일이 더 많이 분산됩니다. Akan은 엄격한 규칙을 통해 이 근원에서 이를 방지합니다.
- 설정 지옥(Config hell)이 끝납니다. 모든 것이
akan.config.ts에서 구성되며, 빈 파일이라도 정상적으로 실행됩니다.
- 엄격한 규칙과 통일된 스타일. 파일 경로, 이름, 구조 및 선언이 일관성을 유지하며, 린트(lint)가 이를 강제하므로 마치 한 사람이 작성한 것처럼 코드가 읽힙니다.
- 에이전트가 우회할 수 없는 규칙. 모든 워크스페이스는 생성된
AGENTS.md, 번들링된 가이드라인, 계획 후 적용(plan-then-apply) 워크플로우 MCP, 그리고 이들을 통해 작동하는 터미널 코딩 에이전트인 akan code를 제공합니다.
- 고정 블록(Fixed blocks). 업로드, 로그인, 관리자, 채팅, 보드 및 알림은 즉시 사용 가능한 블록으로 준비되어 있어 에이전트가 이 위에 일관된 코드를 생성할 수 있습니다.
도메인 모듈 (The Domain Module)
코드는 기술 계층(technical layer)별이 아닌 user, product, ticket 또는 project와 같은 비즈니스 도메인을 중심으로 구성됩니다.
lib/product/
├── product.constant.ts # 모델, 스칼라, 열거형(enum), 스키마 정의
├── product.dictionary.ts # i18n 레이블, 설명, 오류
...
flowchart LR
ConstantDictionarySignal["constant + dictionary + signal"] --> DocumentService["document + service"]
ConstantDictionarySignal --> StoreComponents["store + UI components"]
...
v2보다 빠르다 (Faster Than v2)
v3는 에이전트, MCP 및 새로운 UI 시스템을 추가했으며, 측정된 모든 지표에서 여전히 v2보다 빠릅니다.
| Metric | v2 | v3 | Change |
|---|
| Requests per second | 112K | 123K | +10% |
| ... | | | |
- 클라이언트 빌드 출력: 26MB → 8.1MB (605 청크에서 258청크로 감소).
- 클라이언트에서 1,000개 행 하이드레이션(Hydrating): 3.5ms → 0.9ms.
- 50개 행 목록 조회: 시간은 −33% 단축되었으며, 할당량(allocations)은 85% 감소했습니다.
Apple M4 Pro MacBook Pro에서 프로덕션 빌드 및 동시 사용자 50명으로 측정되었습니다. 벤치마크 도구와 원본 데이터는 benchmarks/api-benchmark에 있습니다.
빌드부터 라이브 URL까지 (From Build To A Live URL)
Akan Cloud는 Akan 앱을 위해 구축된 배포 플랫폼입니다.
akan login # 장치에서 Akan Cloud에 로그인합니다
akan tunnel <app> # 실행 중인 앱을 공개 URL로 공유합니다
akan build <app> # Akan Cloud가 실행할 프로덕션 아티팩트를 빌드합니다
당신과 에이전트를 위한 문서 (Docs For You And Your Agent)
- akanjs.com/docs에서 문서를 읽어보세요. 모든 문서 페이지에는 인페이지 에이전트가 포함되어 있어, 주제에 대해 질문하면 해당 페이지를 열 수 있습니다.
- Claude Code 또는 Cursor를
https://akanjs.com/mcp에 연결하면, AI가 코드를 작성하는 동안 문서(listDocPages, searchDocPages, readDocPage)를 읽어줍니다.
llms.txt는 모든 모델을 위해 문서를 색인화합니다.
하나의 패키지, 여러 경계 (One Package, Many Boundaries)
Akan은 단일 npm 패키지인 akanjs로 게시됩니다. 루트 임포트(root import)는 의도적으로 작게 유지되었으며, 서브패스 임포트(subpath imports)를 통해 서버 전용(server-only), 클라이언트 전용(client-only), UI 및 툴링 영역을 분리합니다.
import { Int, dayjs } from "akanjs/base";
import { via } from "akanjs/constant";
import { endpoint } from "akanjs/signal";
...
@import "akanjs/ui/styles.css";
| 서브패스 (Subpath) | 용도 (Purpose) |
|---|
akanjs/base | 핵심 기본값(Core primitives), 스칼라(Int, Float, ID, Binary, enumOf), dayjs, 환경 헬퍼. |
| ... | |
툴링은 별도의 패키지인 @akanjs/cli (즉, akan 명령어), @akanjs/devkit (빌드 러너, 코드 생성, lint 규칙) 및 create-akan-workspace로 제공됩니다.
CLI 개요 (CLI Overview)
akan create-workspace
akan create-application <app>
akan create-module
...
- 작업 공간 (Workspace): 작업 공간을 생성하고, lint를 수행하며, 동기화(sync)하고,
akan doctor를 실행합니다.
- 애플리케이션 (Application): 웹, 모바일 및 데스크톱 앱을 시작하고, 빌드하고, 타입 검사(typecheck)하고, 테스트하며, 패키징합니다.
- 라이브러리 (Library): 공유 라이브러리를 생성하고, 설치하고, 동기화하고, 푸시(push)하며, 풀(pull)합니다.
- 모듈 및 스칼라 (Module and scalar): 도메인 모듈, 모델, 뷰, 단위(units), 템플릿, 저장소(stores)를 생성합니다.
- 에이전트 (Agents):
akan code, akan mcp, akan mcp-install, akan workflow, akan guideline.
- 클라우드 및 릴리스 (Cloud and release):
akan login, akan tunnel, 배포 자산(deployment assets), 패키지 업데이트.
애플리케이션 설정(Application Configuration)
akan.config.ts는 앱 수준 설정을 위한 유일한 위치입니다. 이 파일은 비어 있는 상태로 시작할 수 있으며, 앱이 라우트(routes), 도메인(domains), 기본 경로(base paths), 데이터베이스 모드(database modes) 또는 네이티브 앱 설정(native app settings)이 필요할 때만 확장됩니다.
import type { AppConfig } from "akanjs";
const config: AppConfig = {
...
기여자 참고 사항(Contributor Notes)
이 저장소는 Bun을 우선하는 모노레포(monorepo)입니다. 프레임워크 코드는 pkgs/akanjs 아래에, 툴링은 pkgs/@akanjs 아래에, 애플리케이션은 apps 아래에, 공유 라이브러리는 libs 아래에, 배포 자산은 infra 아래에 위치합니다. apps/akan이 https://akanjs.com 자체입니다.
이 저장소 내에서, bun run akan을 실행하면 소스 코드로부터 CLI를 빌드하고 실행합니다:
bun run akan start <app>
bun run akan lint <app>
bun run akan typecheck <app>
...
AGENTS.md는 에이전트 코딩과 기여자 모두를 위한 가이드입니다. 프레임워크 코드를 수정할 때는 확립된 서브 경로(subpaths)를 선호하고 루트 akanjs 진입점(entrypoint)을 작게 유지하는 것이 좋습니다. 패키지 경계는 런타임 설계(runtime design)의 일부입니다.
오픈 소스 참고 사항(Open Source Notes)
