E EmDash CMS Everything Guides, use cases, plugins, templates
한국어

EmDash 1.0으로 업그레이드

이 페이지

EmDash 1.0은 0.x 동안 지원 중단된 API를 제거하고, EmDash 자체만 불러오는 진입점을 emdash/internal/ 아래로 옮깁니다. 이 가이드는 호환성을 깨는 각 변경 사항과 사이트에서 업데이트해야 할 내용을 나열합니다.

의존성 업데이트

emdash와 사이트에서 사용하는 다른 EmDash 패키지를 최신 버전으로 업데이트한 다음 다시 빌드하세요. 다음 예시는 Cloudflare 사이트를 업데이트합니다.

pnpm up --latest emdash @emdash-cms/cloudflare
pnpm build

배포에서 emdash migrate를 실행한다면, 업그레이드 이후에 수행한 빌드가 생성한 .emdash/migrations.json에 대해 실행하세요. 이 명령은 이전 EmDash 버전이 작성한 매니페스트를 거부합니다.

업그레이드 후 추가 변경 없이 사이트가 빌드되고 실행될 수도 있습니다. 빌드가 실패하거나 시작할 때 EmDash가 오류를 보고하면 아래의 호환성을 깨는 변경 사항을 차례로 확인하세요.

각 패키지의 전체 변경 목록은 릴리스 페이지에서 해당 패키지 항목을 참조하세요.

호환성을 깨는 변경 사항

제거됨: cloudflareCache()

이전 버전에서는 @emdash-cms/cloudflare의 cloudflareCache()가 Cloudflare REST API를 통해 캐시된 페이지를 퍼지하는 라우트 캐시 프로바이더를 제공했습니다.

cloudflareCache()와 해당 진입점인 @emdash-cms/cloudflare/cache, @emdash-cms/cloudflare/cache/config가 제거되었습니다. 이를 임포트하는 사이트는 빌드에 실패합니다.

어떻게 해야 하나요?

Workers Cache를 사용하는 Astro Cloudflare 어댑터의 cacheCloudflare() 프로바이더로 교체하세요. 이 프로바이더를 설정하면 어댑터가 생성되는 배포 구성에서 Workers Cache를 활성화합니다.

다음 예시는 astro.config.mjs의 변경 사항을 보여 줍니다.

import { cloudflareCache } from "@emdash-cms/cloudflare";
import { cacheCloudflare } from "@astrojs/cloudflare/cache";

export default defineConfig({
	cache: {
		provider: cloudflareCache(),
		provider: cacheCloudflare(),
	},
});

Workers Cache는 cloudflare:workers의 cache.purge()로 퍼지하므로 Worker에서 CF_ZONE_ID와 CF_CACHE_PURGE_TOKEN 시크릿을 삭제할 수 있습니다. KV 오브젝트 캐시(kvCache())는 변경되지 않습니다.

제거됨: emdash/ui의 Comments와 CommentForm

이전 버전에서는 Comments와 CommentForm 컴포넌트가 emdash/ui와 emdash/ui/comments 양쪽에서 내보내졌습니다.

이제 emdash/ui/comments에서만 내보냅니다. 두 컴포넌트 중 하나라도 emdash/ui에서 임포트하는 사이트는 빌드에 실패합니다.

어떻게 해야 하나요?

임포트를 업데이트하세요. 컴포넌트 자체는 바뀌지 않았습니다.

---
import { Comments, CommentForm } from "emdash/ui";
import { Comments, CommentForm } from "emdash/ui/comments";
---

제거됨: emdash dev와 emdash auth secret

이전 버전에서는 emdash dev가 로컬 ./data.db를 사용하는 개발 서버를 시작했고, emdash auth secret은 EMDASH_AUTH_SECRET 값을 생성했습니다.

두 명령 모두 제거되었습니다. 어느 쪽을 실행해도 Unknown command와 함께 종료됩니다.

어떻게 해야 하나요?

emdash dev를 pnpm dev와 같은 사이트 자체의 dev 스크립트로 바꾸거나 astro dev를 실행하세요. 그러면 사이트는 구성에 있는 데이터베이스 어댑터를 사용합니다.

package.json의 emdash 아래에 url 키가 있다면 삭제하세요. 원격 사이트에서 타입을 생성하려면 emdash types --url <site-url>를 실행하거나 EMDASH_URL을 설정하세요.

스크립트에서 emdash auth secret을 제거하세요. 사이트에 이미 EMDASH_AUTH_SECRET이 설정되어 있다면 그대로 두세요. 저장된 댓글 작성자의 IP 해시가 안정적으로 유지되도록 EmDash가 계속 이 값을 읽습니다. 플러그인 시크릿을 저장 시 암호화하려면 emdash secrets generate로 암호화 키를 생성하세요.

제거됨: experimental.registry

이전 버전에서는 emdash() 옵션의 experimental.registry로 플러그인 레지스트리를 구성할 수 있었습니다.

이 옵션은 experimental 옵션 자체와 함께 제거되었습니다. 여전히 experimental.registry를 설정한 사이트는 최상위 registry 옵션을 지목하는 오류와 함께 시작에 실패합니다.

어떻게 해야 하나요?

값을 그대로 최상위 registry 옵션으로 옮기세요. 동일한 URL 문자열 또는 구성 객체를 받습니다.

emdash({
	experimental: {
		registry: {
			aggregatorUrl: "https://registry.example.com",
			policy: { minimumReleaseAge: "48h" },
		},
	},
	registry: {
		aggregatorUrl: "https://registry.example.com",
		policy: { minimumReleaseAge: "48h" },
	},
});

빈 experimental: {} 블록이 남았다면 삭제하세요. TypeScript 구성에서는 오류로 보고됩니다.

변경됨: 내부 진입점이 emdash/internal/로 이동

이전 버전에서는 emdash가 emdash/routes/*, emdash/middleware/*, emdash/db/sqlite-migrations, emdash/plugin-test-runtime처럼 EmDash 자체만 불러오는 진입점을 노출했습니다.

이러한 진입점은 emdash/internal/ 아래에 있습니다. @emdash-cms/cloudflare의 D1 및 Hyperdrive 마이그레이션 실행기도 마찬가지이며, @emdash-cms/cloudflare/internal/db/ 아래에 있습니다. 이들은 공개 API가 아니며 내보내기는 어떤 릴리스에서든 바뀔 수 있습니다. astro.config.mjs의 emdash()로 EmDash를 구성하는 사이트는 영향을 받지 않습니다.

어떻게 해야 하나요?

프로젝트가 이러한 경로를 직접 임포트한다면 공개 API로 임포트를 교체하세요.

  • 데이터베이스, 오브젝트 캐시, 미디어 프로바이더를 구성하려면 emdash/db의 sqlite(), libsql(), postgres(), emdash/astro의 memoryCache(), emdash/media의 localMedia()를 사용하세요.
  • 플러그인을 테스트하려면 emdash/plugin-test-runtime 대신 @emdash-cms/plugin-test를 사용하세요.
  • EmDash의 미들웨어보다 먼저 자체 미들웨어를 실행하려면 emdash()의 middleware.outer 옵션을 설정하세요.

내부 인증, 설정, 리디렉션, 요청 컨텍스트 미들웨어에는 공개 대체 수단이 없습니다.

지원 중단

지원 중단: 이전 플러그인 기능 이름

이전 버전에서는 플러그인이 read:content, network:fetch, page:inject 같은 이름으로 경고 없이 기능(capability)을 선언할 수 있었습니다.

이러한 지원 중단된 이름을 선언한 플러그인마다 EmDash는 시작할 때 경고를 로그에 기록하고, 각각에 대한 현재 대체 이름(예: read:content → content:read)을 나열합니다. 지원 중단된 이름은 1.x 전체에서 계속 동작합니다.

어떻게 해야 하나요?

사용하는 플러그인이 경고를 발생시키면 현재 이름을 사용하는 버전으로 업데이트하거나 작성자에게 해당 버전을 게시해 달라고 요청하세요. 플러그인을 직접 유지 관리한다면 매니페스트의 기능 이름을 바꾸세요. 현재 이름은 기능 및 보안을 참조하세요.