위젯 집합 개발과 미리보기

Dev mode는 게시 자산 대신 개발 서버의 코드를 자신의 사용자 계정에서만 보여 줍니다. 다른 사용자는 게시된 버전을 계속 사용합니다.

위젯 집합과 소스 코드가 준비되어 있어야 합니다. 새 위젯은 게시 전에도 playground와 Code Workspaces에서 볼 수 있지만 Workshop 선택기에 넣으려면 먼저 한 번 게시해야 합니다.

개발 서버

환경	준비와 명령
로컬	저장소를 복제하고 사용자 생성 토큰을 환경변수로 공급합니다. npm run dev를 사용합니다.
VS Code Workspaces	저장소를 작업 공간에서 엽니다. 인증은 Foundry가 관리하며 npm run dev:remote를 사용합니다.

로컬

Foundry Code Repository는 Work locally 안내로 복제합니다. 사용자 생성 토큰을 비공개 방식으로 준비하고 FOUNDRY_TOKEN 환경변수로 자식 프로세스에 전달되도록 설정합니다. 다음 명령은 이미 공급한 값을 요구하며 토큰을 코드나 명령 예제에 기록하지 않습니다.

프로젝트 루트에서 실행합니다.

: "${FOUNDRY_TOKEN:?FOUNDRY_TOKEN 환경변수를 먼저 공급하세요}" && npm install && npm run dev

서버를 켜 둔 채 터미널에 표시된 setup 링크를 엽니다. 링크가 위젯 집합에 개발 서버를 연결하고 개요를 엽니다. 위젯을 선택하여 playground에서 보고 소스를 수정해 저장합니다.

개발 서버와 dev mode 연결 링크를 표시하는 터미널

변경이 보이지 않으면 서버가 계속 실행 중인지와 가장 최근 setup 링크를 열었는지 먼저 확인합니다.

VS Code Workspaces

저장소를 작업 공간에서 열고 시작이 끝날 때까지 기다립니다. 위젯 집합 템플릿은 개발 서버를 자동으로 시작합니다. 실행 중이 아니라면 프로젝트 디렉터리에서 시작합니다.

npm run dev:remote

VS Code preview 패널에서 위젯을 선택한 뒤 코드를 수정하고 저장합니다.

VS Code 작업 공간의 개발 서버로 보는 위젯

같은 서버를 playground와 Workshop에도 연결할 수 있으므로 두 번째 서버가 필요하지 않습니다.

Dev mode 상태

상태	보이는 버전과 조치
Disabled	게시 버전입니다. 개발 서버를 시작하고 dev mode를 켭니다.
Enabled	개발 버전입니다. localhost 또는 작업 공간이 출처로 표시됩니다.
Enabled (inactive)	게시 버전입니다. 현재 보는 위젯에 override가 없는 상태입니다. 개발하려는 대상이라면 서버와 포함 위젯을 확인하고 다시 적용합니다.
Paused	게시 버전입니다. Resume으로 개발 버전으로 돌아갑니다.

Start dev mode를 선택하기 전에 서버를 시작해야 override를 찾을 수 있습니다.

개발 서버 연결을 시작하는 Start dev mode

다른 집합의 위젯을 비교하거나 일부 위젯만 개발하는 Workshop 화면에서는 inactive가 정상일 수 있습니다. 실제로 그 위젯을 개발하려는 경우에만 서버와 override를 확인합니다.

현재 위젯에 개발 override가 없는 inactive 상태

일시정지 중 Resume은 개발 버전으로 복귀하고 Stop은 세션을 끝내 게시 버전을 사용합니다.

일시정지한 개발 세션의 Resume과 Stop

활성 세션은 개발 소스도 표시합니다.

localhost 개발 서버가 연결된 상태

VS Code 작업 공간 서버가 연결된 상태

Dev mode는 개인용 임시 세션이며 24시간 뒤 만료됩니다.

미리보기 환경

환경	확인할 내용
Playground	위젯 크기, 매개변수값, 이벤트 및 매개변수 갱신 로그입니다.
Workshop	실제 변수/이벤트 바인딩과 주변 위젯 및 앱 레이아웃입니다.
VS Code preview	개발 작업 공간을 벗어나지 않고 표시를 확인합니다.

매개변수 입력과 메시지 로그를 가진 playground

Workshop의 실제 바인딩 안에서 개발 버전을 표시한 화면

코드와 구성 변경

컴포넌트 코드나 스타일은 파일을 저장하면 개발 서버가 자동 반영합니다. 매개변수 또는 이벤트 정의를 바꾸었다면 저장한 뒤 dev mode를 다시 적용해야 합니다.

로컬 서버는 터미널의 setup 링크를 다시 엽니다.
VS Code Workspaces는 preview 패널을 새로고침합니다.

매개변수와 이벤트 변경 미리보기에는 @osdk/widget.vite-plugin 3.34.0 이상이 필요합니다. main.config.ts의 구성 예는 다음과 같습니다. id는 프로젝트에서 선택한 위젯의 고유 식별자와 맞춥니다. 입력 자료형과 이벤트 호출은 매개변수와 이벤트에 설명합니다.

import { defineConfig } from "@osdk/widget.client";

export default defineConfig({
  id: "status",
  name: "Status",
  description: "Displays a heading, a warning option, and todo items",
  type: "workshop",
  parameters: {
    headerText: { displayName: "Widget title", type: "string" },
    showWarning: { displayName: "Show warning callout", type: "boolean" },
    todoItems: { displayName: "Todo items", type: "array", subType: "string" },
  },
  events: {
    updateHeader: { displayName: "Update header", parameterUpdateIds: ["headerText"] },
    updateTodoItems: { displayName: "Update todo items", parameterUpdateIds: ["todoItems"] },
  },
});

런타임 범위

브라우저 저장소인 localStorage, sessionStorage와 IndexedDB는 지원하지 않습니다. 위젯 간 상태는 Workshop 변수 같은 호스트 매개변수로 공유합니다. 지원하는 변수의 저장 상태 또는 온톨로지에 쓰는 방식으로 보관할 수 있습니다.

Dedicated Web Worker는 지원하여 메인 스레드를 막지 않는 계산에 사용할 수 있습니다. Shared Worker와 Service Worker는 지원하지 않습니다.

Workshop은 기본적으로 위젯이 든 레이아웃을 숨기면 unmount하므로 iframe 안의 상태가 사라집니다. 표시 최적화로 유지할 수 있습니다.

런타임의 CSP는 제한적이며 사용자가 바꿀 수 없습니다. 임의 외부 요청과 허용 목록 밖의 Foundry API는 지원하지 않습니다. Admin 엔드포인트 5개는 사용할 수 있으며, Ontology APIs를 활성화하면 Ontologies와 Functions 네임스페이스의 모든 엔드포인트 및 Upload Media도 사용할 수 있습니다. 객체 집합 구독은 지원하지 않습니다. 외부 서비스는 함수나 webhook처럼 요청을 감싸는 Foundry 리소스로 연결합니다.

부모 앱의 색상 테마는 CSS media query나 JavaScript로 감지합니다. 구현 예는 밝은 테마와 어두운 테마, 브라우저 중단과 성능 문제는 응답성 문제에 설명합니다.

Keyboard shortcuts

팔란티어 플랫폼 한국어 해설