# django-wireview > Phoenix LiveView 스타일의 Django 실시간 컴포넌트 라이브러리. 컴포넌트의 상태는 서버에 있고, 이벤트는 Django Channels WebSocket으로 올라가며, 서버가 렌더한 HTML의 diff가 내려와 DOM을 갱신한다. 이 목록은 django-wireview v1.1.0 문서다. 링크는 모두 각 페이지의 Markdown 원문이다. 이 라이브러리로 작업하는 AI 에이전트는 이 순서를 따른다. 1. 설치한다. ```bash pip install django-wireview daphne ``` 2. 프로젝트를 준비한다. 아래에서 말하는 시작하기 튜토리얼은 이 문서다: https://itda.work/wireview/tutorial/getting-started/index.md - 새 프로젝트면 스타터 템플릿으로 시작한다. 아래는 macOS·Linux 셸의 명령이고, Windows의 명령은 시작하기 튜토리얼에 있다. ```bash django-admin startproject mysite --template "$(python -c "import wireview, os; print(os.path.join(os.path.dirname(wireview.__file__), 'project_template'))")" ``` - 이미 있는 프로젝트면 시작하기 튜토리얼의 이 절을 먼저 적용한다: https://itda.work/wireview/tutorial/getting-started/#2-이미-있는-프로젝트에-붙이기 `INSTALLED_APPS` 맨 위에 `daphne`를 두고 `wireview`·`channels`를 더하며, `ASGI_APPLICATION`과 `CHANNEL_LAYERS`를 정하고, `asgi.py`가 WebSocket을 wireview로 보내게 하고, 루트 URLconf에 `include('wireview.urls')`를 넣는 일이다. `wireview`가 `INSTALLED_APPS`에 들어가기 전에는 3의 명령이 없다(`Unknown command`). 3. 프로젝트 디렉터리에서 `python manage.py wireview_agent_setup`으로 앱 개발자용 스킬을 `.claude/skills/wireview/`에 설치하고, 작업하기 전에 그 `SKILL.md`를 읽는다. 스킬은 무엇을 언제 읽을지와 조용히 실패하는 함정을 담는다. `.claude/skills/`를 읽지 않는 에이전트도 그 파일을 직접 읽으면 된다. 아래 "에이전트 스킬" 섹션은 같은 스킬의 게시본이다. 4. 컴포넌트를 만들거나 고칠 때마다 `python manage.py check`를 돌려 `wireview.W*` 경고가 없는지 확인한다. 세부 API는 아래 레퍼런스 섹션의 페이지에서 찾는다. 스킬의 각 참조 문서도 필요한 페이지를 가리킨다. ## 에이전트 스킬 - [django-wireview로 앱 만들기](https://itda.work/wireview/agent/wireview/SKILL.md): django-wireview로 실시간 앱을 만들 때 쓴다. 컴포넌트를 새로 만들거나 고칠 때, 이벤트 핸들러·라이프사이클·상태 필드를 작성할 때, 템플릿에 {% on %}·{% component %}·슬롯을 쓸 때, Streams·Presence·파일 업로드·비동기 로딩을 붙일 때, 컴포넌트 테스트를 쓸 때 사용한다. 조용히 실패하는 함정(핸들러가 async가 아님, 이름 충돌, JS 미로드, InMemory 레이어)을 미리 피하고 manage.py check로 확인하는 절차를 담는다. django-wireview 라이브러리 자체를 고치는 절차가 아니다. - [컴포넌트](https://itda.work/wireview/agent/wireview/references/component.md): 컴포넌트 클래스, 상태 필드, 이벤트 핸들러, 라이프사이클, 브로드캐스트, 비동기 - [Streams · Presence · 업로드](https://itda.work/wireview/agent/wireview/references/streams-uploads.md): 대용량 리스트(Streams), 온라인 표시(Presence), 파일 업로드 - [템플릿](https://itda.work/wireview/agent/wireview/references/templates.md): 템플릿 태그, `{% on %}` 수정자, 슬롯, 조건부 클래스, 리다이렉트 - [테스트](https://itda.work/wireview/agent/wireview/references/testing.md): 테스트 작성 ## 소개 - [Wireview - Django를 위한 Phoenix LiveView](https://itda.work/wireview/index.md): Wireview는 Django Channels를 사용하여 실시간 서버 렌더링 인터랙티브 UI를 구축할 수 있게 해주는 라이브러리입니다. Phoenix Framework의 LiveView와 유사합니다. ## 튜토리얼 - [Wireview Tutorials](https://itda.work/wireview/tutorial/index.md): django-wireview 단계별 학습 가이드입니다. - [시작하기](https://itda.work/wireview/tutorial/getting-started/index.md): 설치, 설정, 첫 컴포넌트 - [Counter 컴포넌트](https://itda.work/wireview/tutorial/counter-component/index.md): Component 기초, 이벤트, 상태 관리 - [Poll 앱 - 실시간 투표](https://itda.work/wireview/tutorial/poll-app/index.md): skip_render, 조건부 클래스, 실시간 투표 - [Rating 앱 - 별점 평가](https://itda.work/wireview/tutorial/rating-app/index.md): URL 상태, 키보드 이벤트, 별점 평가 - [Todo 앱](https://itda.work/wireview/tutorial/todo-app/index.md): CRUD, 모델 구독, 중첩 컴포넌트 - [Live Search - 실시간 검색](https://itda.work/wireview/tutorial/live-search/index.md): 디바운스, JS 명령, 검색 자동완성 - [Quiz 앱 - 퀴즈와 상태 머신](https://itda.work/wireview/tutorial/quiz-app/index.md): 상태 머신, mutation, 리더보드 - [Chat 앱](https://itda.work/wireview/tutorial/chat-app/index.md): Streams API, Presence API, 라이프사이클 훅 - [Dashboard](https://itda.work/wireview/tutorial/dashboard/index.md): AsyncResult, 복합 컴포지션 - [Notifications - 알림 센터](https://itda.work/wireview/tutorial/notifications/index.md): 사용자별 채널, 알림과 토스트, broadcast, JS 명령 체이닝 - [LiveComponent - 중첩 컴포넌트](https://itda.work/wireview/tutorial/live-components/index.md): 중첩 컴포넌트, 부모-자식 통신 - [Streams API 심화](https://itda.work/wireview/tutorial/streams-api/index.md): 성능 최적화, DOM ID 전략 - [Presence API 심화](https://itda.work/wireview/tutorial/presence-api/index.md): 다중 방, 스케일링 - [File Uploads 심화](https://itda.work/wireview/tutorial/file-uploads/index.md): 진행률, 보안 - [테스트 가이드](https://itda.work/wireview/tutorial/testing-components/index.md): mount(), pytest 활용 ## 가이드 - [django-wireview 아키텍처](https://itda.work/wireview/guide/index.md): 지금의 구조다. 클릭 하나가 브라우저에서 서버의 컴포넌트를 거쳐 DOM 갱신으로 돌아오기까지의 흐름과, 그 길에 있는 클래스·기능 모듈·프로토콜을 설명한다. - [성능 가이드](https://itda.work/wireview/guide/performance/index.md): wireview 앱이 느릴 때 어디를 볼지 정리했다. async/sync 전환이 왜 생기고 어떻게 찾는지, 피하는 코드, 튜닝할 설정, 재는 방법과 증상별 해결책 순서다. ## 레퍼런스 - [기능 레퍼런스](https://itda.work/wireview/reference/index.md): django-wireview의 주요 기능에 대한 상세 문서입니다. - [Component API](https://itda.work/wireview/reference/component-api/index.md): Component와 LiveComponent의 공개 멤버 전부다. 여기 없는 멤버는 밑줄이 없어도 내부이고, 마이너 릴리스에서 바뀔 수 있다(호환성 정책). 사용법은 표의 링크에 있다. - [설정](https://itda.work/wireview/reference/settings/index.md): settings.WIREVIEW의 키 전부다. 여기 적힌 키가 공개이고(호환성 정책), 기본값의 정본은 wireview/settings.py의 DEFAULT다. tests/test_settings_reference.py가 이 표와 DEFAULT를 대조한다. - [내비게이션](https://itda.work/wireview/reference/navigation/index.md): 컴포넌트가 브라우저 주소를 바꾸는 방법은 넷이다. 무엇이 다시 그려지고, 연결이 이어지는지가 다르다. - [JavaScript 없는 첫 렌더 (dead view)](https://itda.work/wireview/reference/dead-view/index.md): JavaScript가 꺼져 있거나 번들이 아직 오지 않은 브라우저, 검색 엔진, 일부 접근성 도구가 보는 것은 서버의 첫 HTTP 렌더뿐이다. wireview가 그 상태에서 약속하는 것과 약속하지 않는 것이다. Phoenix의 dead view에 해당한다 (GAP-034). - [temporary_assigns - 메모리 최적화](https://itda.work/wireview/reference/temporary-assigns/index.md): 렌더링 후 지정된 필드를 자동으로 초기화하여 서버 메모리를 절약합니다. - [HTML Diff](https://itda.work/wireview/reference/html-diff/index.md): 렌더 결과를 static/dynamic 파트로 나눠, 이벤트마다 바뀐 dynamic 값만 보낸다. - [플래시와 토스트](https://itda.work/wireview/reference/flash/index.md): 화면 한쪽에 잠깐 떴다 사라지는 메시지다. 그 화면의 사용자가 일으킨 것은 핸들러가 put_flash()로 띄우는 플래시이고, 다른 사용자·뷰·백그라운드 작업이 보낸 것은 toast()·atoast()로 보내는 토스트다. - [비동기 작업](https://itda.work/wireview/reference/async-operations/index.md): UI를 막지 않고 데이터를 읽어 오는 장치다. 읽는 동안 로딩 상태를 보여 주고, 성공·실패를 따로 다룬다. - [청크 업로드의 서버 쪽](https://itda.work/wireview/reference/chunked-uploads/index.md): 업로드의 청크가 서버에서 어떻게 처리되고, 워커가 여럿일 때 무엇을 공유해야 하는지를 다룬다(#83). - [External 업로드 (S3/GCS)](https://itda.work/wireview/reference/external-uploads/index.md): 파일을 Django 서버가 아니라 클라우드 스토리지로 직접 올린다. 서버 대역폭을 쓰지 않으므로 큰 파일에 유리하고, 청크 엔드포인트가 요구하는 공유 저장소 조건(chunked-uploads.md)에서도 자유롭다. - [Slots - 컴포넌트 콘텐츠 합성](https://itda.work/wireview/reference/slots/index.md): Phoenix LiveView 스타일의 슬롯 시스템 - [Function Components](https://itda.work/wireview/reference/function-components/index.md): 상태 없는 재사용 가능한 컴포넌트 함수 - [LiveComponent](https://itda.work/wireview/reference/live-component/index.md): 독립적인 상태를 가진 중첩 가능한 컴포넌트 - [라이프사이클 훅](https://itda.work/wireview/reference/lifecycle-hooks/index.md): 컴포넌트 사이에 공통 동작을 나눠 쓰는 장치다. 초기화 시점의 Meta.on_mount와, 이후 단계를 가로채는 attach_hook 둘로 나뉜다. - [페이지 이동 boost (`BOOST_PAGES`)](https://itda.work/wireview/reference/boost/index.md): 같은 사이트 안의 링크 이동을 전체 페이지 로드 없이 처리한다. WebSocket 연결은 끊기지 않고, 새 페이지의 컴포넌트가 그 연결로 join한다. - [live_session — 페이지 경계](https://itda.work/wireview/reference/live-session/index.md): live_session은 페이지 단위의 인증 경계다. 이름 하나에 정책 하나를 묶고, 그 이름을 단 페이지에 사는 모든 컴포넌트가 그 정책을 지나게 한다. 그리고 경계를 넘는 이동을 전체 페이지 로드로 만든다. - [세션 읽기](https://itda.work/wireview/reference/session/index.md): 컴포넌트는 self.session으로 Django 세션을 읽는다. Phoenix가 mount/3의 두 번째 인자로 세션을 넘기는 자리다. - [서버 오류 처리](https://itda.work/wireview/reference/errors/index.md): 컴포넌트 코드가 예외를 던지면 그 컴포넌트 하나만 대가를 치른다. 연결과 같은 페이지의 다른 컴포넌트는 그대로 동작한다(#94). - [Optimistic UI](https://itda.work/wireview/reference/optimistic-ui/index.md): 서버 왕복이 끝나기 전에 사용자에게 반응을 돌려주는 장치들이다. 로딩 클래스, wire-disabled-with, 그리고 즉시 실행되는 JS 명령 셋으로 나뉜다. - [폼 피드백](https://itda.work/wireview/reference/form-feedback/index.md): 검증 오류를 언제 보여 줄지 통제한다. 사용자가 아직 건드리지도 않은 필드에 빨간 글씨를 띄우지 않기 위한 장치다. - [CSP (Content Security Policy)](https://itda.work/wireview/reference/csp/index.md): 이벤트 바인딩이 인라인 스크립트가 아니라 데이터 속성이라, 'unsafe-inline' 없는 정책과 함께 돈다. - [JavaScript 훅](https://itda.work/wireview/reference/hooks/index.md): 서드파티 JS 라이브러리(Chart.js, Mapbox, CodeMirror 등)를 컴포넌트에 붙이는 장치다. Phoenix LiveView의 훅과 같은 모양이다. - [타입 스텁(.pyi) 자동 생성](https://itda.work/wireview/reference/type-stubs/index.md): 컴포넌트의 .pyi 스텁을 생성해 IDE 자동완성과 mypy·pyright의 정적 검사를 받게 한다. 파이썬 코드 쪽의 지원이다. 템플릿 쪽(컴포넌트·핸들러 이름의 자동완성과 진단)은 편집기 지원이 맡는다. - [편집기 지원 (템플릿)](https://itda.work/wireview/reference/editor-support/index.md): 템플릿을 편집하는 동안 컴포넌트·핸들러·수정자·슬롯·태그·필터의 이름을 편집기가 알게 한다. 이름을 틀리면 페이지를 그려 볼 때가 아니라 치는 자리에서 안다. - [Telemetry](https://itda.work/wireview/reference/telemetry/index.md): 운영 중인 앱이 wireview 내부 비용을 자기 모니터링에 연결하기 위한 옵트인 계측 훅이다. bench/가 재현 가능한 실험실 수치를 준다면, telemetry는 실제 트래픽에서의 수치를 준다. - [System Checks](https://itda.work/wireview/reference/checks/index.md): 에러 없이 조용히 실패하는 설정과 코드를 manage.py check가 wireview.W* 경고로 알리게 하는 Django system checks다. - [에이전트 스킬 — 앱 개발자용](https://itda.work/wireview/reference/agent-skill/index.md): AI 코딩 에이전트가 wireview 앱을 제대로 짜게 만드는 배포용 스킬 - [테스트 헬퍼](https://itda.work/wireview/reference/testing/index.md): wireview.testing이 주는 것 전체. 처음 배우는 순서는 테스트 가이드 튜토리얼이 낫고, 이 문서는 레퍼런스다. ## Optional - [배포 가이드](https://itda.work/wireview/deployment/index.md): django-wireview 앱을 운영에 올릴 때의 설정이다. - [업그레이드 가이드](https://itda.work/wireview/upgrade/index.md): 쓰던 django-wireview 버전에서 지금 버전으로 올릴 때 고칠 것을 버전 구간별로 모았다. 조용히 동작이 바뀌는 변경과 보안 조치가 필요한 변경은 그렇게 표시했다. - [호환성 정책](https://itda.work/wireview/upgrade/compatibility/index.md): 1.0부터 django-wireview는 여기서 공개라고 적은 것을 마이너·패치 릴리스에서 깨지 않는다. 공개가 아닌 것은 예고 없이 바뀔 수 있다. 1.0 전(0.x)에는 마이너 릴리스도 호환을 깰 수 있다.