v7로 마이그레이션
이 가이드에서는 Blockstudio 6에서 7로 업그레이드할 때 필요한 변경 사항을 설명합니다.
ES 모듈 가져오기
새 npm: 접두사(권장)
Blockstudio 7에서는 ES 모듈 가져오기에 사용할 새 npm: 접두사를 도입하여 Deno의 npm 지정자 규칙에 맞췄습니다.
이전(v6):
import { h, render } from "blockstudio/preact@10.15.1";
import htm from "blockstudio/htm@3.1.1";
import confetti from "blockstudio/canvas-confetti@1.6.0";
이후(v7):
import { h, render } from "npm:preact@10.15.1";
import htm from "npm:htm@3.1.1";
import confetti from "npm:canvas-confetti@1.6.0";
CSS 가져오기
CSS 가져오기에도 같은 변경 사항이 적용됩니다.
이전(v6):
import "blockstudio/swiper@11.0.0/swiper.min.css";
이후(v7):
import "npm:swiper@11.0.0/swiper.min.css";
이전 버전과의 호환성
blockstudio/ 접두사는 이전 버전과의 호환성을 위해 계속 지원됩니다. 기존 코드는 변경 없이 계속 작동합니다. 다만, 더 넓은 JavaScript 생태계와 일관성을 유지하려면 npm: 접두사로 마이그레이션하는 것을 권장합니다.
npm: 접두사에는 다음과 같은 장점이 있습니다.
- 생태계와의 일관성 – Deno에서 확립된 규칙과 일치합니다
- 명확성 – npm에서 가져오는 것임을 즉시 알 수 있습니다
- 미래 대비 – 향후 주요 버전에서
blockstudio/접두사가 더 이상 사용되지 않을 수 있습니다
훅 이름
Blockstudio 7에서는 모든 PHP 훅 이름을 camelCase 대신 snake_case를 사용하도록 표준화하여 WordPress 핵심 규칙에 맞췄습니다.
변경된 훅 이름
| 이전 이름(v6) | 새 이름(v7) |
|---|---|
blockstudio/blocks/components/useblockprops/render |
blockstudio/blocks/components/use_block_props/render |
blockstudio/blocks/components/innerblocks/render |
blockstudio/blocks/components/inner_blocks/render |
blockstudio/blocks/components/innerblocks/frontend/wrap |
blockstudio/blocks/components/inner_blocks/frontend/wrap |
blockstudio/blocks/components/richtext/render |
blockstudio/blocks/components/rich_text/render |
blockstudio/assets/process/scss/importPaths |
blockstudio/assets/process/scss/import_paths |
blockstudio/settings/assets/process/scssFiles |
blockstudio/settings/assets/process/scss_files |
blockstudio/settings/editor/formatOnSave |
blockstudio/settings/editor/format_on_save |
blockstudio/settings/blockEditor/disableLoading |
blockstudio/settings/block_editor/disable_loading |
blockstudio/settings/blockEditor/cssClasses |
blockstudio/settings/block_editor/css_classes |
blockstudio/settings/blockEditor/cssVariables |
blockstudio/settings/block_editor/css_variables |
blockstudio/settings/ai/enableContextGeneration |
blockstudio/settings/ai/enable_context_generation |
이전 버전과의 호환성
이전 camelCase 훅 이름은 이전 버전과의 호환성을 위해 계속 지원됩니다. 기존 코드는 변경 없이 계속 작동합니다. 다만 일관성을 위해 새 snake_case 이름으로 마이그레이션하는 것을 권장합니다.
마이그레이션 예시:
// Before (v6)
add_filter('blockstudio/settings/blockEditor/cssClasses', function() {
return ['my-stylesheet'];
});
// After (v7)
add_filter('blockstudio/settings/block_editor/css_classes', function() {
return ['my-stylesheet'];
});
표준 블록 태그
Blockstudio 7.6에서는 프로젝트 접두사와 정확한 별칭을 런타임 확장 지점으로 유지하지만, 예시, 카탈로그 출력, 렌더 선언 및 진단 메시지에서는 <bs:namespace-slug>을 표준 표기로 사용합니다. 표준 태그에는 실제로 등록된 블록 이름이 포함되며 호스트별 필터에 의존하지 않습니다.
brand => ["theme-components"] 및 ui => ["bsui"]을 사용하는 프로젝트의 경우:
<!-- Legacy project shorthand -->
<brand-card>
<ui-input />
</brand-card>
<!-- Canonical output -->
<bs:theme-components-card>
<bs:bsui-input />
</bs:theme-components-card>
독립형 마이그레이션 명령은 기존 프로젝트의 항목을 조사하고 축약 표기를 표준 표기로 바꿉니다. 보고서를 먼저 생성하고, 해결되지 않은 사례가 있으면 중단하며, 태그 이름만 변경합니다. 명령, 입력 및 안전 동작에 대한 자세한 내용은 블록 태그 마이그레이션을 참조하세요.
에셋 파일 이름 지정
Blockstudio 7에서는 에셋 파일 접미사에 점 표기법을 도입하여 기존 대시 표기법을 권장 규칙에서 대체합니다.
변경된 파일 이름
| 이전 이름(v6) | 새 이름(v7) |
|---|---|
*-inline.(s)css |
*.inline.(s)css |
*-inline.js |
*.inline.js |
*-editor.(s)css |
*.editor.(s)css |
*-editor.js |
*.editor.js |
*-scoped.(s)css |
*.scoped.(s)css |
*-view.js |
*.view.js |
이전 버전과의 호환성
이전 대시 표기법은 이전 버전과의 호환성을 위해 계속 지원됩니다. 파일 이름을 바꾸지 않아도 기존 파일은 계속 작동합니다. 다만 새 블록에는 점 표기법으로 마이그레이션하는 것을 권장합니다.
마이그레이션 예시:
my-block/
├── block.json
├── index.php
├── style.css
├── style-inline.css → style.inline.css
├── style-scoped.css → style.scoped.css
├── style-editor.css → style.editor.css
├── script.js
├── script-inline.js → script.inline.js
├── script-editor.js → script.editor.js
└── script-view.js → script.view.js
필드 스위치
switch 속성의 기본값이 true에서 false로 변경되었습니다. v6에서는 모든 필드의 왼쪽 가장자리에 기본적으로 활성화된 보이지 않는 토글이 있었습니다. v7에서는 스위치를 선택적으로 사용하며 필드 레이블에 표시되는 눈 아이콘을 사용합니다.
변경 사항
- 이제 기본값은
false입니다:"switch": true을 명시적으로 설정하지 않으면 필드에 스위치가 없습니다. - 눈 아이콘 표시: 숨겨진 왼쪽 클릭 영역 대신 레이블 영역에 눈 아이콘 버튼이 표시됩니다.
- 비활성화 오버레이: 필드를 비활성화하면 불투명도만 낮아지는 대신 "이 필드는 비활성화되었습니다"라는 문구가 있는 흐림 오버레이가 표시됩니다.
마이그레이션
v6에서 기본 스위치 동작을 사용했다면 명시적으로 활성화해야 합니다.
{
"id": "title",
"type": "text",
"label": "Title",
"switch": true
}
이전에 토글을 비활성화하려고 "switch": false을 설정했다면 이제 false이 기본값이므로 해당 설정을 삭제할 수 있습니다.
Tailwind CSS
Blockstudio 7은 v6 Tailwind 방식을 완전히 대체합니다. v6에서는 편집기에서 CDN를 통해 Tailwind CSS를 클라이언트 측에서 컴파일하고 게시물을 저장할 때 디스크에 저장했습니다. v7에서는 모든 프런트엔드 요청마다 TailwindPHP을 통해 서버 측에서 Tailwind CSS를 컴파일하고 파일 기반 캐싱을 자동으로 수행합니다.
새 시스템에 대한 자세한 내용은 Tailwind CSS문서를 참조하세요.
항상 활성화되는 서버 측 컴파일
tailwind.enabled이 true이면 모든 프런트엔드 요청이 서버 측에서 컴파일됩니다. 컴파일 흐름은 다음과 같습니다.
- WordPress이 전체 페이지 HTML를 출력 버퍼로 렌더링합니다.
- HTML에서 CSS 클래스 후보를 추출합니다(빠른 정규식, 컴파일 없음).
- 후보를 정렬하고 CSS 설정으로 해시하여 캐시 키를 생성합니다.
- 캐시 적중 시 캐시된 CSS 파일을 읽어 삽입합니다.
- 캐시 미스 시 TailwindPHP이 CSS을 컴파일하고, Blockstudio의 공유 런타임 캐시에
tailwind범위로 기록한 다음 삽입합니다.
컴파일된 CSS는 </head> 앞에 인라인 <style id="blockstudio-tailwind"> 태그로 삽입됩니다. 여기에는 Tailwind의 프리플라이트와 일치하는 모든 유틸리티 클래스가 포함됩니다.
CDN 스크립트는 실시간 미리보기용으로 편집기에서만 활성 상태를 유지합니다. 프런트엔드에는 제공되지 않습니다.
config 형식 변경
config 속성이 Tailwind v3인 JSON 객체에서 Tailwind v4 CSS 우선 구문을 사용하는 CSS 문자열로 변경되었습니다.
이전(v6):
{
"tailwind": {
"config": {
"theme": {
"extend": {
"colors": {
"primary": "pink"
}
}
}
}
}
}
이후(v7):
{
"tailwind": {
"config": "@theme { --color-primary: pink; }"
}
}
customClasses 설정 제거
customClasses 배열 설정이 제거되었습니다. Tailwind v4의 CSS 우선 방식에서는 @layer utilities를 사용해 config 문자열에 사용자 지정 유틸리티 클래스를 직접 정의합니다.
이전(v6):
{
"tailwind": {
"customClasses": [
{ "className": "btn", "value": "px-4 py-2 rounded-lg font-medium" },
{ "className": "card", "value": "bg-white rounded-xl shadow-lg p-6" }
]
}
}
이후(v7):
{
"tailwind": {
"config": "@layer utilities { .btn { @apply px-4 py-2 rounded-lg font-medium; } .card { @apply bg-white rounded-xl shadow-lg p-6; } }"
}
}
여러 줄 구성에는 필터를 사용할 수도 있습니다.
add_filter('blockstudio/settings/tailwind/config', function () {
return <<<CSS
@layer utilities {
.btn { @apply px-4 py-2 rounded-lg font-medium; }
.card { @apply bg-white rounded-xl shadow-lg p-6; }
}
CSS;
});
blockstudio/settings/tailwind/custom_classes 필터도 제거되었습니다. 사용자 지정 CSS 규칙을 추가하려면 blockstudio/tailwind/css 필터를 사용하세요.
REST 엔드포인트 제거
POST /blockstudio/v1/editor/tailwind/save 엔드포인트가 제거되었습니다. 이제 편집기에서 컴파일된 CSS를 저장하지 않습니다. 사용자 지정 코드에서 이 엔드포인트를 호출하고 있었다면 안전하게 제거할 수 있습니다.
캐싱
Blockstudio은 후보 기반 캐싱 전략을 사용합니다. 전체 페이지 HTML를 해시하면 nonce와 타임스탬프 때문에 매 요청마다 캐시가 무효화되므로, CSS 클래스 후보만 해시합니다. 따라서 다음과 같은 효과가 있습니다.
- CSS 클래스가 같은 두 페이지는 캐시 파일을 공유합니다.
- 동적 콘텐츠(nonce, 관리 도구 모음, 타임스탬프)는 캐시를 무효화하지 않습니다.
- CSS 클래스 집합이나 설정이 변경될 때만 캐시가 무효화됩니다.
캐시 파일은 sites/{network-blog}/{runtime-identity}/tailwind/ 아래에 구성된 Blockstudio 런타임 루트를 사용합니다. 강제로 다시 컴파일하려면 Blockstudio\Runtime_Cache::purge('tailwind')를 호출하세요.
필터 변경 사항
| 이전 이름(v6) | 새 이름(v7) |
|---|---|
blockstudio/tailwind/on_demand/css |
blockstudio/tailwind/css |
blockstudio/tailwind/assets/dir |
제거됨 |
blockstudio/settings/tailwind/custom_classes |
제거됨 |
제거된 파일 및 등록 항목
v7에서는 이전에 Tailwind CSS를 외부 스타일시트(blockstudio-tailwind, blockstudio-tailwind-preflight)로 등록했습니다. v6에서는 모든 CSS를 출력 버퍼를 통해 인라인으로 삽입합니다. 프런트엔드의 Tailwind에는 링크 태그나 등록된 스타일시트가 없습니다.
블록 라이브러리
내장 “Blockstudio 요소” 라이브러리가 제거되었습니다. blockstudio.json의 library 설정과 blockstudio/settings/library 필터는 더 이상 영향을 주지 않습니다.
라이브러리 블록(Gallery, Slider, Image Comparison, Code, Icon)을 사용하고 있었다면 v6 설치 디렉터리의 includes/library/blockstudio-element/ 디렉터리에서 블록 폴더를 복사해 테마의 blockstudio 디렉터리에 넣고, 해당 block.json 파일의 이름과 카테고리를 새 값으로 업데이트하세요.