Question 1

새로 스캐폴딩된 content-editor 플러그인이 "contentAccess is required when any cms.content.* permission is granted" 오류로 lint에 실패하는 이유는 무엇인가요?

Accepted Answer

스캐폴드는 플러그인 config에 `contentAccess`를 기록하지만, `definePlugin`의 `DefinePluginConfig` 타입에는 `contentAccess` 키가 없고 manifest 조립 과정에서도 이를 전달하지 않으므로, 생성된 `cms.content.*` 권한이 여전히 해당 키를 필요로 하는 동안 키가 아무런 알림 없이 삭제됩니다. 임시 해결 방법: `instatic-plugin lint` 또는 빌드를 실행하기 전에 조립된 manifest에 `contentAccess`를 다시 주입하세요. 예를 들어 repo 소스는 그대로 둔 채, manifest를 후처리하여 `contentAccess: [{ table: 'pages', modes: ['read', 'write'] }]`를 추가하는 config를 가진 임시 복사본을 lint/빌드합니다. 영구 수정: `definePlugin.ts`의 `DefinePluginConfig`에 `contentAccess`를 추가하고 manifest 조립 시 이를 전달하여 스캐폴드가 수정 없이 lint를 통과하도록 하세요.

Question 2

왜 빌드된 스타일시트에서 제 min-width 미디어 쿼리가 더 작은 브레이크포인트에 의해 덮어씌워지나요?

Accepted Answer

빌더는 min-width 미디어 쿼리 블록을 가장 큰 것부터 출력합니다(예: `@media (min-width: 1024px)`가 `@media (min-width: 768px)`보다 먼저). 따라서 특이성이 동일한 경우 소스 순서로 인해 1024px 이상의 모든 뷰포트에서 더 좁은 768px 블록이 우선 적용되며, 모바일 우선 CSS가 사실상 역전됩니다. `site_read_styles`로 규칙을 다시 읽거나 빌드된 스타일시트를 검사하여 확인하세요. 저장된 CSS는 작성된 그대로 보이지만 출력 순서는 뒤바뀌어 있습니다. 패치되기 전까지의 해결 방법: 동일한 특이성에서 같은 속성을 여러 min-width 브레이크포인트로 나누지 마세요. 모든 데스크톱 재정의를 가장 작은 단일 데스크톱 브레이크포인트 하나로 통합하거나, 더 넓은 브레이크포인트 규칙의 특이성을 높여 소스 순서가 더 이상 적용 결과를 결정하지 않도록 하세요. 영구적인 수정 방법은 빌드 시 출력되는 컨텍스트를 정렬하는 것입니다. min-width는 오름차순으로, max-width는 내림차순으로 정렬해야 합니다.

Question 3

content.entry.created 플러그인 이벤트가 공개 양식 제출 시 발생하지 않는 이유는 무엇이며, 어떻게 해결할 수 있나요?

Accepted Answer

퍼블릭 폼 핸들러(`server/forms/handler.ts`)는 `createDataRow(...)`를 통해 행을 생성하지만, 관리자 쓰기 경로(`server/handlers/cms/data/tables.ts:344`, `rows.ts:190/220/239`)와 달리 이후 emit 헬퍼를 호출하지 않습니다. 수정 옵션 1 (가장 작은 변경): 퍼블릭 경로에서 행이 생성된 직후 `emitContentEntryCreated(db, row.id, { kind: 'system' })`를 호출하세요. 수정 옵션 2 (폼 전용 플러그인에 더 적합): `{ formId, pageId, tableSlug, entryId }`를 전달하는 전용 `forms.submission.created` 코어 이벤트를 추가하세요. 패치되기 전까지 플러그인 측 우회 방법: 프론트엔드 에셋에서 `window.fetch`를 래핑하여 제출 응답을 감시하고, JavaScript가 비활성화된 방문자를 위한 폴백으로 예약된 reconcile sweep을 실행하세요.

Question 4

플러그인 FrontendAsset의 `attrs`가 `type`, `rel`, `href`를 제거하는 이유는 무엇이며, JSON-LD 구조화 데이터(`application/ld+json`)를 출력하려면 어떻게 해야 하나요?

Accepted Answer

원인: `server/publish/frontendInjections.ts`의 `formatAttrs`가 `src`, `href`, `rel`, `type`, `defer`, `async` 및 `data-plugin-id`를 전역적으로 예약하므로, `attrs`에 있는 해당 키들은 아무런 경고 없이 제거됩니다. `type`을 출력하는 유일한 코드 경로는 `kind: 'script'`에만 존재하는 `strategy: 'module'`이며 — 인라인 스크립트와 `kind: 'link'`에는 이러한 속성에 도달할 경로가 없으므로, 문서화된 `{ "kind": "link", "attrs": { "rel": "preconnect", "href": "..." } }` 예제는 빈 ``로 렌더링됩니다. JSON-LD에 대한 해결 방법: `attrs.type`에 의존하는 대신 클래식 인라인 스크립트를 선언하고 런타임에 JSON-LD 노드를 주입하세요: ```ts { kind: 'script-inline', placement: 'head-end', content: `var s=document.createElement('script');s.type='application/ld+json';s.textContent=JSON.stringify({"@context":"https://schema.org","@type":"Article"});document.head.appendChild(s);` } ``` Googlebot은 JavaScript를 렌더링하고 동적으로 주입된 구조화된 데이터를 감지하므로, 이 방법은 정적 태그와 동일하게 검증됩니다. 인라인 스크립트 애셋이 존재할 때마다 페이지 CSP가 이미 `script-src 'self' 'unsafe-inline'`으로 완화되므로, 별도의 CSP 변경은 필요하지 않습니다. ``의 경우 매니페스트 내에서 가능한 해결 방법이 없습니다 — 두 키 모두 예약되어 있고 `kind: 'link'` 분기는 아무것도 다시 추가하지 않습니다. 영구적인 수정(issue #392에서 추적 중)은 종류별 속성 예약입니다: `src`는 `script`에서만, `href`/`rel`은 `link`에서만 예약하고, `type`은 `strategy: 'module'`이 설정된 경우에만 예약합니다.

Question 5

## The usual culprit: CSS purging at build time

Most modern build pipelines (Tailwind CSS in JIT mode, PurgeCSS, UnCSS, and many bundlers/frameworks) automatically remove "unused" CSS classes when you publish, to keep the stylesheet small. They decide what's "used" by **statically scanning your files for class name strings**.

Classes toggled only via JavaScript often get purged because:

1. **The scanner doesn't see them.** If the tool only scans HTML/template files, classes referenced only in `.js` files are treated as unused.
2. **Dynamically constructed names can't be detected.** Code like `el.classList.add('status-' + type)` produces no literal `status-active` string anywhere, so the scanner can't extract it.

## How to fix it

**1. Safelist the dynamic classes**

Tailwind (`tailwind.config.js`):
```js
module.exports = {
  content: ['./src/**/*.{html,js,jsx,ts,tsx}'],
  safelist: [
    'active',
    'open',
    { pattern: /status-(active|inactive|pending)/ },
  ],
}
```

PurgeCSS:
```js
new PurgeCSSPlugin({
  paths: glob.sync('src/**/*', { nodir: true }),
  safelist: ['active', 'open', /^status-/],
})
```

**2. Include your JS files in the scan paths**

Often the tool *can* detect `classList.toggle('active')` — the literal string `'active'` is there — but your JS files simply aren't in the `content`/`paths` config. Add them.

**3. Never concatenate class names**

Write full class names so static analysis can find them:
```js
// Bad — scanner misses these
el.classList.add('theme-' + mode);

// Good — literal strings are detectable
el.classList.add(mode === 'dark' ? 'theme-dark' : 'theme-light');
```

## How to confirm this is your problem

- Search the published/minified CSS file for the missing class name. If it's absent, something purged it.
- Check your build config for `purgecss`, `purge:`, `safelist`, or Tailwind's `content` array.
- Verify it works in dev but breaks in production — dev builds usually skip purging.

If you're **not** using any purge tool, other possibilities are: a CMS/site builder (e.g., Webflow) removing "unused" styles on publish, or CSS being overwritten by a later-loaded stylesheet. But in the vast majority of cases, it's the build-time purger.

Accepted Answer

publish 단계는 작성된 문서에서 어떤 노드에도 연결되지 않은 클래스를 가진 모든 CSS 규칙을 제거합니다 — JS 토글을 통해 런타임에만 존재하는 modifier 클래스(예: `.mobilenav--open`)도 여기에 포함됩니다. 해당 규칙은 publish 전에는 `site_read_styles`를 통해 올바르게 읽히지만, publish된 스타일시트에서는 제거되므로, 스크립트가 무엇을 하든 요소는 기본 상태(예: `display: none`)를 유지합니다. 우회 방법: (1) 작성된 문서에 해당 클래스에 대한 참조를 유지하세요 — modifier 클래스를 최소 하나의 노드(숨겨진 더미 요소라도)에 연결하면 pruner가 이를 사용 중인 것으로 처리하여 규칙이 publish 후에도 살아남습니다. (2) 클래스 토글 대신 스크립트에서 런타임 상태를 인라인 스타일로 적용하세요(예: `el.style.display = 'flex'`) — 이 방법은 동작하지만 cascade를 잃게 됩니다. 즉, 해당 상태에는 미디어 쿼리, pseudo-state, 테마 적용을 사용할 수 없습니다. 진단하려면 `site_read_styles` 출력과 publish된 스타일시트를 diff하세요. 전자에는 존재하지만 후자에는 없는 규칙이 제거된 규칙입니다.

Instatic

주요 기능

할 수 없는 것

사용 사례

태그

시작하기

유사한 프로젝트