Amoxi는 Node.js용 풀스택 TypeScript 프레임워크로, 의존성 연결과 경로 설정 오류 등을 실행 전에 amoxi build에서 검사한다. 서버 렌더링 페이지와 필요한 부분만 브라우저에서 실행하는 아일랜드(islands), 백그라운드에서 재개되는 AI 에이전트를 한 프로젝트에서 구성할 수 있다고 제작자는 설명한다.
TypeScript 컴파일러가 데코레이터와 타입을 분석해 의존성 그래프를 검증하고 연결 코드를 생성한다. 따라서 런타임 리플렉션에 의존하지 않으며, 누락되거나 모호한 의존성, 순환 참조, 잘못된 경로, 브라우저 코드에서의 서버 전용 모듈 사용 등을 파일과 줄 번호가 포함된 오류로 빌드 단계에서 보고한다. 검증과 생성이 끝난 코드는 TypeScript 컴파일러가 다시 타입 검사한다.
페이지는 JSX를 서버에서 HTML 문자열로 렌더링한다. 상호작용이 필요한 부분은 별도로 번들링하는 아일랜드로 제공하고, 각 아일랜드는 사용되는 페이지에서 불러온다. React 컴포넌트도 아일랜드로 쓸 수 있지만 React는 React 아일랜드가 있는 페이지에서만 내려받는다. 같은 출처의 링크는 전체 페이지를 다시 불러오지 않고 이동하며, 마우스 오버·포커스·터치 때 페이지를 미리 가져올 수 있다. 느린 페이지 구역은 준비된 부분부터 스트리밍할 수 있다.
AI 에이전트는 HTTP 요청과 분리된 백그라운드 작업으로 실행된다. 모델 호출과 도구 결과를 저장해 서버가 중단된 뒤에도 마지막 단계부터 이어갈 수 있고, 사람의 승인이 필요한 도구는 결정이 내려질 때까지 멈춘다. 도구의 입력 스키마와 검증기는 TypeScript 타입에서 생성된다. 메모리와 문서 검색도 지원하며, 에이전트와 도구를 MCP 또는 A2A를 통해 다른 에이전트에 제공할 수 있다. 이 연동 기능은 기본적으로 꺼져 있다.
시작 조건과 주의할 점
새 프로젝트는 create-amoxi-app으로 만들며, 생성기는 web, agent, api 템플릿을 제공한다. web 템플릿에는 페이지·아일랜드·JSON API가, agent에는 여기에 스트리밍 채팅 에이전트가 추가된다. Node.js 22 이상이 필요하고 Windows, macOS, Linux에서 동작한다. 생성 프로젝트의 기본 개발 서버 주소는 http://localhost:8080이다.
npx create-amoxi-app@latest my-app
cd my-app
npm run dev
생성기에는 --template, --no-install, --no-git, --yes 옵션이 있다. --yes를 사용하거나 터미널 밖에서 실행하면 web 템플릿을 선택한다. 기본적으로 개발과 운영에 환경 변수가 필요하지 않지만, 실제 AI 모델을 쓰려면 .env에 제공자 API 키를 설정해야 한다. 키가 없을 때는 내장 오프라인 모델을 사용한다.
Amoxi는 아직 1.0 이전 버전이다. 1.0 전에는 마이너 버전 업데이트에도 호환성을 깨는 변경이 들어갈 수 있으며, 제작자는 변경 사항을 변경 기록에 안내한다고 밝혔다. 또한 세션 키는 체크아웃별로 생성되므로 CI나 Docker처럼 새 체크아웃에서 빌드하면 배포 후 사용자가 로그아웃될 수 있다. 배포 사이에 세션을 유지하려면 모든 인스턴스에 같은 AMOXI_SESSION_SECRET을 설정해야 한다. 기본 파일 기반 저장소는 로컬 사용에 맞춰져 있고, 여러 서버에서 실행할 때는 PostgreSQL과 pgvector 사용을 안내한다.
정적 내보내기는 페이지를 HTML 파일로 만들지만, 실행 중인 서버가 없으므로 API 경로, 업로드, WebSocket, 세션과 쿠키는 제공하지 않는다. 내보낸 페이지는 생성 시점의 스냅샷이다. 세션이나 쿼리 매개변수를 사용하는 페이지는 정적 파일에서 다르게 보일 수 있으며, --strict 옵션으로 이런 경우 내보내기를 실패시킬 수 있다.
제작자가 공개한 성능 측정은 Node.js 22의 단일 CPU 컨테이너에서 부하 생성기와 서버가 같은 코어를 공유한 조건에서 이뤄졌다. 제작자는 요청 처리량을 하한으로 보고 다른 장비의 결과와 비교하지 말라고 안내한다. 예제 앱의 시작 시간은 빈 3개 구성에서 약 14ms, 빈 12개 구성에서 약 9ms로 제시됐지만, 이 수치는 해당 측정 환경의 결과다.
Amoxi 저장소와 설치 안내 · 웹사이트와 문서 · 기여 안내
부록: 원문 예시
<Island of={Counter} start={3} load="visible" />
<Island of={AccentPicker} initial="#2F4A66" load="visible" />
댓글 (0)
로그인하면 이 기사에 내 생각을 남길 수 있어요