플러그인 게시

플러그인을 빌드한 후, EmDash 마켓플레이스에 게시하여 다른 사이트들이 관리자 대시보드에서 설치할 수 있도록 할 수 있습니다.

사전 요구사항

게시하기 전에, 플러그인이 다음을 충족하는지 확인하세요:

"." 내보내기가 플러그인 진입점을 가리키는 유효한 package.json을 보유
고유한 id와 유효한 semver version을 사용하는 definePlugin()을 사용
해당 capabilities(액세스가 필요한 API)를 선언

번들 형식

게시된 플러그인은 다음을 포함하는 .tar.gz tarball로 배포됩니다:

파일	필수	설명
`manifest.json`	예	`definePlugin()`에서 추출된 플러그인 메타데이터
`backend.js`	아니요	번들된 샌드박스 코드 (자체 포함 ES 모듈)
`admin.js`	아니요	번들된 관리자 UI 코드
`README.md`	아니요	플러그인 문서
`icon.png`	아니요	플러그인 아이콘 (256x256 PNG)
`screenshots/`	아니요	최대 5개의 스크린샷 (PNG/JPEG, 최대 1920x1080)

manifest.json은 definePlugin() 호출에서 자동으로 생성됩니다. 여기에는 플러그인 ID, 버전, capabilities, 훅 이름, 경로 이름 및 관리자 구성이 포함되지만 실행 코드는 포함되지 않습니다.

번들 빌드

emdash plugin bundle 명령은 플러그인 소스에서 tarball을 생성합니다:

cd packages/plugins/my-plugin
emdash plugin bundle

이 명령은 다음을 수행합니다:

진입점을 찾기 위해 package.json을 읽음
매니페스트를 추출하기 위해 tsdown으로 메인 진입점 빌드
backend.js 번들 (최소화, 트리 쉐이킹, 자체 포함)
"./admin" 내보내기가 존재하는 경우 admin.js 번들
자산 수집 (README, 아이콘, 스크린샷)
번들 검증 (크기 제한, backend에 Node.js 내장 모듈 없음)
dist/에 {id}-{version}.tar.gz 작성

진입점 해결

번들 명령은 package.json 내보내기를 통해 코드를 찾습니다:

json title="package.json"
{
  "exports": {
    ".": { "import": "./dist/index.mjs" },
    "./sandbox": { "import": "./dist/sandbox-entry.mjs" },
    "./admin": { "import": "./dist/admin.mjs" }
  }
}

내보내기	목적	빌드 방식
`"."`	메인 진입점 — 매니페스트 추출에 사용	외부 종속성: `emdash`, `@emdash-cms/*`
`"./sandbox"`	샌드박스에서 실행되는 백엔드 코드	완전 자체 포함 (외부 종속성 없음)
`"./admin"`	관리자 UI 컴포넌트	완전 자체 포함

"./sandbox"가 누락된 경우, 명령은 대체 경로로 src/sandbox-entry.ts를 찾습니다.

옵션

emdash plugin bundle [--dir <path>] [--outDir <path>]

플래그	기본값	설명
`--dir`	현재 디렉토리	플러그인 소스 디렉토리
`--outDir`, `-o`	`dist`	tarball 출력 디렉토리

검증

번들 명령은 다음을 확인합니다:

크기 제한 — 전체 번들은 5MB 미만이어야 함
Node.js 내장 모듈 없음 — backend.js는 fs, path, child_process 등을 가져올 수 없음 (샌드박스 코드는 Node.js가 아닌 V8 격리 환경에서 실행됨)
아이콘 크기 — icon.png는 256x256이어야 함 (잘못된 경우 경고, 그래도 포함)
스크린샷 제한 — 최대 5개, 최대 1920x1080

게시

emdash plugin publish 명령은 tarball을 마켓플레이스에 업로드합니다:

emdash plugin publish

이 명령은 dist/ 디렉토리에서 가장 최근의 .tar.gz 파일을 찾아 업로드합니다. tarball을 명시적으로 지정하거나 게시 전에 빌드할 수도 있습니다:

# Explicit tarball path
emdash plugin publish --tarball dist/my-plugin-1.0.0.tar.gz

# 먼저 빌드한 후 게시
emdash plugin publish --build

인증

처음 게시할 때, CLI는 GitHub를 통해 사용자를 인증합니다:

CLI가 브라우저에서 GitHub의 디바이스 인증 페이지를 염
터미널에 표시된 코드를 입력
GitHub가 액세스 토큰 발급
CLI가 이를 마켓플레이스 JWT로 교환 (~/.config/emdash/auth.json에 저장)

토큰은 30일 동안 유효합니다. 만료된 후 다음 게시 시 다시 인증하라는 메시지가 표시됩니다.

인증을 별도로 관리할 수도 있습니다:

# Log in without publishing
emdash plugin login

# 로그아웃 (저장된 토큰 삭제)
emdash plugin logout

최초 등록

플러그인 ID가 아직 마켓플레이스에 존재하지 않는 경우, emdash plugin publish는 첫 번째 버전을 업로드하기 전에 자동으로 등록합니다.

버전 요구사항

게시된 각 버전은 이전 버전보다 높은 semver를 가져야 합니다. 기존 버전을 덮어쓰거나 다시 게시할 수 없습니다.

보안 감사

게시된 모든 버전은 자동화된 보안 감사를 거칩니다. 마켓플레이스는 backend.js와 admin.js를 다음에 대해 스캔합니다:

데이터 유출 패턴
설정을 통한 자격 증명 수집
난독화된 코드
리소스 남용 (암호화폐 채굴 등)
의심스러운 네트워크 활동

감사는 통과, 경고, 실패의 판정을 생성하며, 이는 플러그인의 마켓플레이스 목록에 표시됩니다. 마켓플레이스의 시행 수준에 따라 실패 판정은 게시를 완전히 차단할 수 있습니다.

옵션

emdash plugin publish [--tarball <path>] [--build] [--dir <path>] [--registry <url>]

플래그	기본값	설명
`--tarball`	`dist/`의 최신 `.tar.gz`	명시적 tarball 경로
`--build`	`false`	게시 전 `emdash plugin bundle` 실행
`--dir`	현재 디렉토리	플러그인 디렉토리 (`--build`와 함께 사용)
`--registry`	`https://marketplace.emdashcms.com`	마켓플레이스 URL

전체 워크플로우

다음은 일반적인 게시 주기입니다:

# 1. Make your changes
# 2. Bump the version in definePlugin() and package.json
# 3. Bundle and publish in one step
emdash plugin publish --build

또는 번들을 먼저 검사하려는 경우:

# Build the tarball
emdash plugin bundle

# 출력 확인
tar tzf dist/my-plugin-1.1.0.tar.gz

# 게시
emdash plugin publish