image
Akan.js
한국어
문서컨벤션레퍼런스Cheatsheet
image
Akan.js
Akan.js v2 문서가 새로 나왔습니다.v1 문서 보기
문서컨벤션레퍼런스Cheatsheet
MIT 라이선스 하에 배포되었습니다.
Akan.js 공식 컨설팅 서비스Akansoft
Copyright © 2026 Akan.js 모든 권리 보유.
시스템 관리자bassman
소개
• 시작하기
• 기본 개념
• 실습하기
튜토리얼
• 상세하게 보여주기
• 상태 변경하기
• 서비스 내에서 상호작용
• 슬라이스로 표시하기
• 페이지를 통한 UX
• 스칼라 사용하기
• 인사이트 사용하기
• 데이터 연결하기
핵심 개념
• Akan 런타임
• 파일 기반 라우팅
• 다중 클라이언트
• 앱 설정
• 폴더 규칙
• 파일 규칙
• 데이터 레이어
시스템 아키텍처
• 아키텍처 개요
• 런타임과 인프라
• UI 아키텍처
• 비즈니스 서비스
• 모바일 앱 아키텍처
• CSS와 스타일링
소개
• 시작하기
• 기본 개념
• 실습하기
튜토리얼
• 상세하게 보여주기
• 상태 변경하기
• 서비스 내에서 상호작용
• 슬라이스로 표시하기
• 페이지를 통한 UX
• 스칼라 사용하기
• 인사이트 사용하기
• 데이터 연결하기
핵심 개념
• Akan 런타임
• 파일 기반 라우팅
• 다중 클라이언트
• 앱 설정
• 폴더 규칙
• 파일 규칙
• 데이터 레이어
시스템 아키텍처
• 아키텍처 개요
• 런타임과 인프라
• UI 아키텍처
• 비즈니스 서비스
• 모바일 앱 아키텍처
• CSS와 스타일링
이전
Akan 런타임
다음
다중 클라이언트

파일 기반 라우팅

Akan은 파일 기반 라우팅을 사용합니다. page/ 아래에 파일을 만들면 폴더 구조가 페이지 URL이 됩니다. 대부분의 페이지에는 언어 파라미터가 자동으로 붙어서 하나의 파일이 다국어 URL을 처리할 수 있습니다.
파일이 라우트가 되는 방식
페이지 파일
page/(user)/project/[projectId]/_index.tsx
to
/:lang/project/:projectId
index 파일은 실제 라우트 진입점이 됩니다.
레이아웃 파일
page/(user)/project/[projectId]/_layout.tsx
to
wraps child pages
layout은 같은 폴더 아래의 페이지를 감쌉니다.
라우트 그룹
(user)
to
not in URL
괄호 폴더는 URL 세그먼트를 추가하지 않고 파일을 정리합니다.
파일 기반: 폴더와 파일이 URL 형태를 결정합니다.
다국어 지원: Akan이 [lang]을 자동으로 주입합니다.
명시적인 파일: 숨겨진 규칙보다 page와 layout 파일을 명시적으로 사용합니다.

파일 컨벤션

라우트 파일은 page 또는 layout이 될 수 있습니다. _index.tsx는 현재 세그먼트를 렌더링하고, _layout.tsx는 하위 세그먼트를 감싸며, route group은 URL을 바꾸지 않고 파일을 정리합니다.
page/
_index.tsx
파일이 위치한 폴더 자체의 페이지입니다.
_layout.tsx
아래에 있는 자식 페이지를 감싸는 레이아웃입니다.
(group)
URL 세그먼트를 추가하지 않고 파일을 정리합니다.
<path>.tsx
경로 세그먼트를 파일 하나로 선언하는 페이지입니다. project.tsx는 /:lang/project가 됩니다.
[<param>].tsx
동적 경로를 파일 하나로 선언하는 페이지입니다. [projectId].tsx는 /:lang/:projectId가 됩니다.

페이지 파일 구성

페이지 파일은 반드시 default component를 export해야 합니다. 필요하면 페이지 옵션, 메타데이터, 로딩 UI를 위한 export를 함께 사용할 수 있습니다.
page/(user)/project/[projectId]/_index.tsx
Static head example
default
페이지 컴포넌트입니다. 반드시 필요합니다.
pageConfig
화면 전환이나 모바일 safe-area 같은 클라이언트 페이지 옵션입니다.
head
페이지의 정적인 메타데이터입니다.
generateHead
라우트 파라미터를 사용할 수 있는 동적 메타데이터입니다.
Loading
페이지가 로딩되는 동안 보여줄 대체 UI입니다.

레이아웃 파일 구성

레이아웃 파일은 하위 페이지를 감쌉니다. 공통 헤더, 탭, 사이드바, 접근 제어, 페이지 껍데기 같은 UI를 둘 때 사용합니다.
page/(user)/project/[projectId]/_layout.tsx
레이아웃은 default, head, generateHead, Loading을 지원합니다. head가 선언되지 않은 child page에 대해서 layout의 head가 사용됩니다.

Base Path

앱이 akan.config.ts에서 base path를 정의하면 page 파일은 해당 base path 폴더 아래에 있어야 합니다. 여러 서비스나 여러 도메인을 가진 앱의 라우트를 명확하게 나누기 위한 규칙입니다.
apps/seon/akan.config.ts
page/
base path가 설정된 앱에서는 page/ 바로 아래에 페이지를 두면 올바르지 않습니다. Akan이 어떤 라우트 묶음에 속하는지 알 수 있도록 page/<basePath>/ 아래로 옮겨야 합니다.

Root Layout Exports

root _layout.tsx는 앱 전체의 동작을 설정할 수 있습니다. 기본적으로는 layout이지만, font, manifest, theme, analytics, mobile-style rendering 같은 앱 공통 설정을 추가로 export할 수 있습니다.
page/_layout.tsx
fonts
앱 전체에서 사용할 폰트를 등록합니다.
manifest
설치형 앱이나 PWA에 가까운 동작에 사용하는 웹 앱 manifest를 정의합니다.
theme
dark, light, system, css 같은 기본 테마 정책을 정합니다.
reconnect
클라이언트가 실시간 런타임 채널에 다시 연결할지 정합니다.
layoutStyle
바깥 페이지 컨테이너 스타일을 바꿉니다. 앱 같은 모바일 화면에는 mobile을 사용합니다.
gaTrackingId
앱에 Google Analytics 추적을 추가합니다.
파일 기반 라우팅
파일 컨벤션
페이지 파일 구성
레이아웃 파일 구성
Base Path
Root Layout Exports
head와 generateHead는 둘 중 하나만 사용합니다. 고정 메타데이터는 head를, 파라미터에 따라 제목이나 태그가 달라지면 generateHead를 사용하세요.
이 추가 export들은 root layout에서만 사용합니다. 일반 중첩 layout은 default, head, generateHead, Loading 중심으로 작성하세요.