Every row in this table maps to a real customer-reported failure mode. If your integration looks broken, scan symptoms first — odds are it's already documented here.
TIP
Currently on the latest SDK? Check your installed version with npm ls @vlozi/blog. Many of the rows below resolve simply by upgrading to @vlozi/blog@^2.1.6.
Symptom, cause, fix
| # | Symptom | Cause | Fix |
|---|---|---|---|
| 1 | Headings render as body text. No list markers. Body looks like a wall of unformatted text. The title above <BlogContent> looks fine, but the body inside is flat. |
Most common: @vlozi/blog/styles.css is imported after your globals.css, OR you have a global heading reset (Tailwind preflight, * { margin: 0 }, shadcn text-base cascading) that overrides the SDK's .vlz-content h1/h2/h3 rules. |
(a) Move import "@vlozi/blog/styles.css" to the first line of app/layout.tsx. (b) DevTools → inspect a heading → Computed tab → if the SDK rule is crossed-out, scope your reset under :not(.vlz-content). (c) Tailwind users: put your reset inside @layer base so unscoped SDK CSS still wins. |
| 2 | Bold / italic don't render | <BlogContent> not used — you're rendering with raw dangerouslySetInnerHTML, so the .vlz-content class isn't on the wrapper. |
Always use <BlogContent html={post.content!} /> for post bodies. It applies the wrapper class plus sanitization and hydration. |
| 3 | Task-list checkboxes mis-aligned with their labels | Pre-2.1.6 prose-margin leak. | pnpm add @vlozi/blog@^2.1.6 |
| 4 | Code blocks render in a single color (no syntax highlighting) | Either (a) syntaxHighlighting: false in provider config, or (b) the blog-service Worker hasn't been redeployed for 2.1.6 yet — server-side tokenization is part of the Worker deploy, not the npm publish. |
(a) Remove the flag (default is true); (b) re-deploy the blog-service Worker. |
| 5 | Inline body images render as plain <img> even though I passed imageComponent |
Body-image hydration only triggers when imageComponent reaches <BlogContent> — either threaded as a prop or supplied through provider config. |
Pass it explicitly: <BlogContent imageComponent={SmartImage} />. Or set it on the provider: <VloziProvider config={{ imageComponent: SmartImage }}>. |
| 6 | Mermaid blocks render as raw flowchart LR … text inside a beige box |
Mermaid peer not installed, or you're on @vlozi/blog@2.1.5 (loader regression). |
(a) pnpm add mermaid; (b) upgrade to @vlozi/blog@^2.1.6. |
| 7 | YouTube embed shows as an empty 16:9 box (no video) | The renderer emitted a non-allowlisted iframe src (e.g. youtube.com/watch?v=…) and the SDK's sanitizer stripped it. Pre-2.1.6 also stripped the wrapper. |
(a) Re-deploy the blog-service Worker — URL normalization lives there, not in the npm package; (b) instant fix: use <BlogContent transformHtml={…}> to rewrite watch URLs client-side. |
| 8 | Carousels render as a flat stack of images instead of a swipeable carousel | Known renderer gap — the blog-service renderer doesn't emit the <div data-type="carousel"> wrapper. The SDK runtime is fine; it just never sees the marker. |
Tracked internally. Until the renderer fix ships, build your own with the standalone <Carousel> from @vlozi/blog/react. |
| 9 | TypeScript error: Property 'id' does not exist on type 'Post' |
Pre-2.1.6 the SDK had an id?: string in the type that the API never emitted. Removed in 2.1.6. |
Use post.slug as your React key. |
| 10 | Build fails with Module not found: 'mermaid' |
Pre-2.1.6 bundler-resolution bug. | Upgrade to @vlozi/blog@^2.1.6. |
| 11 | next build crashes with apiKey is required |
Pre-2.1.5 the VloziClient constructor threw synchronously on empty values, breaking next build when env vars weren't wired yet. |
Upgrade to @vlozi/blog@^2.1.5. The typed VloziConfigError now fires only on the first API call. |
| 12 | useVlozi must be used within a VloziProvider |
A hook or hook-using component is rendering outside <VloziProvider>. |
Mount <VloziProvider client={client}> at the route layout level. Server-side fetching (RSC, generateMetadata, generateStaticParams) does NOT need a provider — only hooks and client components do. |
| 13 | Featured images 404 in production | next.config.js images.remotePatterns doesn't include the upload host. |
Add the upload host to remotePatterns in next.config.js. |
| 14 | Two different VloziConfig shapes show up in IDE autocomplete |
Naming collision: @vlozi/blog exports VloziConfig (client config) AND @vlozi/blog/react exports a VloziConfig (provider config). |
TypeScript resolves them by import path automatically. To use both in one file, alias one: import type { VloziConfig as VloziProviderConfig } from "@vlozi/blog/react". |
| 15 | pre { background: … } styles a mermaid host the wrong color |
Mermaid is portal-mounted into the original <pre> after the rest of the page. Your global CSS still applies to the host. |
Scope your code-block rules: .vlz-content pre:not([data-vlz-hydrated]) { background: … }. The hydration scanner stamps data-vlz-hydrated on hosts so you can opt out of styling them. |
Still stuck?
- Re-read Quickstart — the four hard rules. 9 in 10 reported integration failures map to one of those four.
- Run the verification fixture: render a post containing every construct (
#–###,**bold**,*italic*,`code`, lists, blockquote, code fence) and visually confirm each one styles distinctly. - Check your installed SDK version:
npm ls @vlozi/blog. Anything below 2.1.6 is missing the post-2.1.5 fix bundle. - Open DevTools → Computed tab on a misbehaving element. If a
.vlz-contentrule is crossed-out, the cause is CSS specificity / load order — not the SDK itself.