Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
PortalJS는 데이터 포털 구축에 특화된 AI 네이티브 프레임워크입니다. 사용자가 원하는 포털의 설명을 제공하면, 에이전트가 아키텍처 선택부터 스캐폴딩, 데이터 로드까지 자동화합니다. Next.js 기반으로 구현되어 있으며, Claude Code와 연동하여 개발 과정을 지원받을 수 있습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub Codex tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기포털 생성하기 — 한 번의 명령으로, Node 22+ 외에는 설치할 것이 없습니다:
npm create portaljs@latest my-portal
cd my-portal
npm run dev # → http://localhost:3000
샘플 데이터를 사용하여 홈(Home), 카탈로그(/search), 데이터셋 쇼케이스(/@<namespace>/<slug>)의 세 가지 화면을 얻게 됩니다. 순수하고 편집 가능한 Next.js이며, 종속성(lock-in)이 없습니다. datasets.json에 자체 CSV/JSON을 추가하면 자동으로 렌더링됩니다.
AI 어시스턴트와 함께 구축하기 — PortalJS는 조립 작업을 수행하는 Claude Code 스킬을 제공합니다. 이들을 한 번 설치하세요 (~/.claude/commands):
curl -fsSL https://raw.githubusercontent.com/datopian/portaljs/main/scripts/install-portaljs-skills.sh | bash
그 후, 임의의 디렉토리에서 Claude Code 세션에서 다음을 수행합니다:
/portaljs-architect 어떤 스택이 필요한지 모르겠나요? 여기서 시작하세요.
/portaljs-new-portal "Auckland Council 오픈 데이터 포털"
/portaljs-add-dataset ./data/air-quality.csv
/portaljs-new-portal는 세 가지 서피스(surfaces)를 스캐폴딩하고, /portaljs-add-dataset (또는 /portaljs-add-resource)은 데이터를 로드하며,
/portaljs-connect-ckan은 이를 CKAN 백엔드에 연결하고, /portaljs-deploy는 배포합니다. (모든 스킬 + 설치 →)
순수 템플릿을 선호한다면 — AI가 없고, 종속성(lock-in)이 없는 순수한 Next.js:
npx tiged datopian/portaljs/examples/portaljs-catalog my-portal
cd my-portal && npm install && npm run dev # → http://localhost:3000
홈(Home), 카탈로그(/search), 그리고 데이터셋 쇼케이스(/@<namespace>/<slug>)를 샘플 데이터로 얻을 수 있습니다. 자체 CSV/JSON 파일을 datasets.json에 추가하면 자동으로 렌더링됩니다.
⭐ 유용하다면, 별점을 주어 다른 사람들이 찾도록 도와주세요.
데이터 포털을 구축한다는 것은 항상 단순한 웹사이트 이상의 의미를 가집니다. 데이터가 어디에 저장될지, 어떻게 버전 관리될지, 사람들이 어떻게 검색할지, 어떻게 제공될지, 그리고 어떻게 거버넌스(governed) 될지를 결정해야 하며 — 그 위에 프런트엔드를 연결해야 합니다. 팀들은 필요한 것보다 무거운 데이터 웨어하우스(data warehouse)를 과도하게 구축하거나, 확장성이 없는 스크립트 더미 위에서 부족하게 구축하는 경향이 있습니다.
PortalJS는 데이터 팀이 데이터 포털을 구축하고, 개발하며, 배포하는 데 도움을 주는 오픈 소스 에이전틱(agentic) 스킬 프레임워크이며, 그 아래의 데이터 인프라까지 포함합니다. 이것은 단순히 프런트엔드만을 의미하지 않습니다. 이 스킬들은 두 가지 역할을 합니다:
이는 의견이 강하지만 개방적입니다: 권장되는 현대적인 경로는 git + 객체 스토리지(Cloudflare R2) + Parquet을 사용하고, 이를 DuckDB라는 오픈 레이크하우스로 쿼리하는 것입니다. 클래식 웨어하우스 대신에 말이죠. 살아있는 증분 테이블의 경우 DuckLake를 계층화할 수 있으며, 전통적인 데이터 저장소(CKAN, 웨어하우스)는 필요할 때 여전히 최상급 옵션으로 남아 있습니다. 사용자는 항상 순수한 코드를 소유합니다.
Datopian과 PortalJS 커뮤니티에 의해 오픈으로 구축 및 유지 관리됩니다.
🧑 사용자가 만들고 싶은 것을 설명함
│
▼
...
세 가지 표면(Three surfaces). 모든 데이터 포털은 세 가지 요소로 구축됩니다: 설명을 제공하고 검색을 제공하는 홈(Home) 페이지, 데이터셋을 발견하기 위한 카탈로그(Catalog)(/search), 그리고 하나의 데이터셋을 탐색하기 위한 쇼케이스(Showcase)(/@<namespace>/<slug>)입니다. 여기에는 메타데이터, 미리보기, 다운로드/API, 차트/지도 등이 포함됩니다. (핵심 개념 →)
하나의 연결 지점(One seam). 이 표면들은 오직 DataProvider를 통해서만 데이터를 읽기 때문에, 소스(오늘날 정적 파일, 내일 CKAN 또는 레이크하우스 백엔드)가 페이지에 손대지 않고 변경될 수 있습니다.
전체 모델과 어떻게 /portaljs-architect가 사용자의 요구사항을 스택으로 변환하는지에 대한 아키텍처 결정 프레임워크는 ROADMAP.md에서 확인하세요.
PortalJS는 간략한 설명(brief)을 작동하는 포털로 변환하는 Claude Code 스킬을 제공합니다.
이 스킬들을 개인 범위에 한 번 설치하여 모든 디렉토리에서 사용할 수 있도록 합니다:
curl -fsSL https://raw.githubusercontent.com/datopian/portaljs/main/scripts/install-portaljs-skills.sh | bash
Claude Code를 다시 시작하거나 새 세션을 열고 /를 입력하여 스킬들을 확인하세요. 다른 설치 옵션(버전별 플러그인 또는 이 저장소의 클론에서 바로 실행)은 .claude/INSTALL.md를 참조하세요.
포털을 어떻게 설정해야 할지 확신이 서지 않는다면, 먼저 어드바이저(advisor)를 사용한 다음 빌드를 시작하세요:
/portaljs-architect 우리는 분기별로 업데이트되는 약 200개의 공개 CSV 파일을 보유하고 있으며 DCAT-AP을 게시해야 합니다
/portaljs-new-portal "아클랜드 시의 오픈 데이터 포털"
/portaljs-add-dataset ./data/air-quality.csv
...
이 기술들은 **대화형(interactive)**입니다. 만약 요구사항이 불분명하더라도 오류를 내기보다는 짧은 라운드로 인터뷰를 진행합니다. /portaljs-architect는 스택을 추천하고 작업을 위임하며, /portaljs-new-portal은 세 가지 표면(surfaces)을 위한 기본 구조(scaffolds)를 제공하고, /portaljs-add-dataset은 datasets.json 매니페스트에 추가하며 쇼케이스는 /@<네임스페이스>/<슬러그>에서 자동으로 렌더링됩니다. npm run dev를 실행하면 포털이 완성됩니다.
직접 구축하는 것을 선호하나요? 이 기술들은 편의 기능일 뿐 필수 사항은 아닙니다. CLI를 사용하여 템플릿을 직접 기본 구조화(scaffold)할 수 있습니다:
npm create portaljs@latest my-portal
(또는 프롬프트 없이 베어 템플릿을 가져오려면: npx tiged datopian/portaljs/examples/portaljs-catalog my-portal.)
| 기술 (Skill) | 기능 설명 (What it does) |
|---|---|
/portaljs-architect | 자문(Advisory) — 구축하기 전에 사용자의 요구사항(데이터, 규모, 거버넌스)을 추천 아키텍처로 변환합니다. 스택이 불확실할 때 여기서 시작하세요. |
| ... |
대용량 데이터 확장(Large-data scaling)의 경우, 큰 파일들은 Git LFS를 통해 Cloudflare R2로 전송되며 이는 /portaljs-add-dataset에 이미 포함되어 있습니다. 메타데이터 스키마(Frictionless/DCAT), 더 많은 백엔드(OpenMetadata), 브라우저 DuckDB 쿼리 레이어, 접근 제어 등 더 많은 기술군들은 로드맵에 있습니다. 직접 작성하려면 .claude/AUTHORING.md를 확인하세요.
.claude/commands/ 에이전트 기술(agentic skills, 슬래시 명령어)
examples/ 참조 포털 — portaljs-catalog가 표준 템플릿입니다
packages/
...
표준 템플릿인 examples/portaljs-catalog는 세 가지 표면(surfaces)과 DataProvider 시야가 존재하는 곳입니다. 사용하기 전에 이 부분을 읽어보세요.
/portaljs-architect는 UI를 구성하는 것을 넘어 인프라 자체를 _결정_하도록 도와줍니다.DataProvider 계약을 제공합니다.참조 구현체는 examples/에 있습니다:
| 예시 | 백엔드 |
|---|---|
portaljs-catalog | 표준 템플릿 — 정적 매니페스트를 기반으로 홈 + 카탈로그 + 쇼케이스 구성 |
| ... |
PortalJS는 오픈 소스로 구축되었으며 모든 규모의 기여를 환영합니다 — 새로운 기술, 예제, 문서, 그리고 수정 사항을 포함합니다. 시작하려면 CONTRIBUTING.md를 참고하고, 프로젝트가 나아갈 방향은 ROADMAP.md와 VISION.md에서 확인하세요.