Question 1

Why does a newly scaffolded content-editor plugin fail lint with "contentAccess is required when any cms.content.* permission is granted"?

Accepted Answer

The scaffold writes `contentAccess` into the plugin config, but `definePlugin`'s `DefinePluginConfig` type has no `contentAccess` key and its manifest assembly never forwards it, so the key is silently dropped while the generated `cms.content.*` permission still requires it. Workaround: before running `instatic-plugin lint` or build, re-inject `contentAccess` into the assembled manifest — e.g. lint/build a throwaway copy whose config post-processes the manifest to add `contentAccess: [{ table: 'pages', modes: ['read', 'write'] }]`, leaving repo sources untouched. Permanent fix: add `contentAccess` to `DefinePluginConfig` in `definePlugin.ts` and forward it during manifest assembly so scaffolds pass lint unchanged.

Question 2

Why is my min-width media query being overridden by a smaller breakpoint in the built stylesheet?

Accepted Answer

The builder emits min-width media query blocks largest-first (e.g. `@media (min-width: 1024px)` before `@media (min-width: 768px)`), so when specificity is equal, source order makes the narrower 768px block win at every viewport above 1024px — mobile-first CSS effectively inverts. Verify by reading back the rule with `site_read_styles` or inspecting the built stylesheet: the stored CSS looks exactly as authored, but emission order is reversed. Workaround until patched: do not split the same property across multiple min-width breakpoints at equal specificity — consolidate all desktop overrides into a single, smallest desktop breakpoint, or raise the specificity of the wider-breakpoint rule so source order no longer decides the winner. The permanent fix is to sort emitted contexts at build time: min-width ascending, max-width descending.

Question 3

Why doesn't the content.entry.created plugin event fire for public form submissions, and how to fix it?

Accepted Answer

The public form handler (`server/forms/handler.ts`) creates the row via `createDataRow(...)` but never calls the emit helper afterwards, unlike admin write paths (`server/handlers/cms/data/tables.ts:344`, `rows.ts:190/220/239`). Fix option 1 (smallest change): call `emitContentEntryCreated(db, row.id, { kind: 'system' })` right after the row is created on the public path. Fix option 2 (better for form-specific plugins): add a dedicated `forms.submission.created` core event carrying `{ formId, pageId, tableSlug, entryId }`. Until patched, plugin-side workaround: wrap `window.fetch` in a frontend asset to watch for the submit response, plus run a scheduled reconcile sweep as a fallback for visitors with JavaScript disabled.

Question 4

Why does the plugin FrontendAsset `attrs` drop `type`, `rel` and `href`, and how do I emit JSON-LD structured data (`application/ld+json`) anyway?

Accepted Answer

Cause: `formatAttrs` in `server/publish/frontendInjections.ts` globally reserves `src`, `href`, `rel`, `type`, `defer`, `async` and `data-plugin-id`, so those keys in `attrs` are silently stripped. The only code path that emits a `type` is `strategy: 'module'`, which exists only on `kind: 'script'` — inline scripts and `kind: 'link'` have no route to these attributes, so the documented `{ "kind": "link", "attrs": { "rel": "preconnect", "href": "..." } }` example renders as an empty ``. Workaround for JSON-LD: declare a classic inline script and inject the JSON-LD node at runtime instead of relying on `attrs.type`: ```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 renders JavaScript and picks up dynamically injected structured data, so this validates the same as a static tag. Note the page CSP is already relaxed to `script-src 'self' 'unsafe-inline'` whenever an inline script asset exists, so no extra CSP change is needed. For `` there is no in-manifest workaround — both keys are reserved and the `kind: 'link'` branch adds nothing back. The permanent fix (tracked in issue #392) is per-kind attribute reservation: `src` reserved only on `script`, `href`/`rel` only on `link`, and `type` only when `strategy: 'module'` is set.

Question 5

Why do CSS classes toggled by JavaScript disappear from the stylesheet after publishing?

Accepted Answer

The publish step prunes any CSS rule whose class is not attached to a node in the authored document — including modifier classes (e.g. `.mobilenav--open`) that only exist at runtime via JS toggling. The rule reads back correctly via `site_read_styles` before publish but is stripped from the published stylesheet, so the element keeps its base state (e.g. `display: none`) no matter what the script does. Workarounds: (1) Keep a reference to the class in the authored document — attach the modifier class to at least one node (even a hidden dummy element) so the pruner treats it as used and the rule survives publish. (2) Apply runtime state as inline styles from the script instead of class toggling (e.g. `el.style.display = 'flex'`) — this works but loses the cascade: no media queries, pseudo-states, or theming on that state. To diagnose, diff the `site_read_styles` output against the published stylesheet; any rule present in the former but absent in the latter was pruned.

Instatic

Core Features

What It Can't Do

Use Cases

Tags

Getting Started

Similar Projects