DEV Community: Dominik

How I built @grodev/claude-chat-react — architecture notes

Dominik — Tue, 18 Aug 2026 12:59:38 +0000

TL;DR

A drop-in React chat widget on the Claude API — @grodev/claude-chat-react — with a headless hook (useClaudeStream) if you want to bring your own UI, or a <ClaudeChat/> component if you don't. 8 KB gzipped, zero runtime deps beyond React. Companion project to my vanilla-JS widget — same wire contract, same PHP proxy, different frontend stack.

This is a notes-from-the-build post: three decisions that shaped the API, and one thing I audited line-by-line because I don't trust the model with it.

Decision 1: Two ways in, not one

Every React library eventually gets asked "can I use just the state, not the UI?" — so I built both from day one:

// Drop-in — 5 lines
import { ClaudeChat } from '@grodev/claude-chat-react';
<ClaudeChat endpoint="/api/chat" accentColor="#1D9E75" />

// Headless — bring your own UI
import { useClaudeStream } from '@grodev/claude-chat-react';
const { messages, status, sendMessage } = useClaudeStream({ endpoint: '/api/chat' });

The hook does the streaming, state, and abort control; the component adds layout, dark mode, and a11y on top. Consumers who need a different look pay zero cost — they import only the hook and ~2 KB drops out of the bundle.

Decision 2: The API key never touches the browser (and I mean never)

Central design choice — the widget calls your server-side proxy, never api.anthropic.com directly. If you look at the source, there is no place where you can accidentally pass an API key as a prop. It's not in the type definitions. It's not a hidden config. The escape hatch does not exist.

This is the boring kind of security: not a validator that checks for keys, but an API shape where the wrong pattern isn't representable. Companion repo claude-chat-widget ships a working PHP proxy with the exact wire contract this library expects — copy it, deploy anywhere PHP runs, done.

Decision 3: Streaming with a real abort

The streaming loop looks like a hundred other SSE readers on GitHub. Three things I got specifically right:

AbortController lives in useRef, not useState. State would re-render every send, and downstream components would blink.
setMessages((prev) => ...) — never closure-based. Tokens arriving during a re-render need current state, not stale state, or you'll see torn text.
if (payload.error) throw — routes upstream errors through the same catch, so onError fires once with a real Error, not on each malformed frame.

The a11y I refuse to leave to Claude

When I let the model draft the JSX, it produced a working panel. It also produced a working panel without any of these:

role="dialog" on the panel
aria-live="polite" on the message log
aria-expanded on the launcher
Focus management (input focus on panel open, escape close)
Enter sends, Shift+Enter inserts a newline

Every one of these is in the final code. Every one was added by me after the draft, not before. LLMs don't skip a11y out of malice — they skip it because most tutorial code they trained on skipped it. If you don't audit specifically for the boring accessibility bits, you don't get them.

That pattern generalizes: audit the AI's work for what the training data underrepresents, not for what the model gets "wrong."

What's not in the package

Deliberately out of scope, documented in the README:

Rate limiting → add on your proxy
Retrieval-augmented context → your job; feed the system prompt from your data
Session persistence → the hook exposes messages, you decide where to store

Each of those turns a demo into a product, and each one is where your particular use case matters more than a shared abstraction.

Full write-up

Project decisions, human-vs-AI split, and the security checklist I run before every proxy change are in CLAUDE.md in the repo. Or the broader post about how I document AI-first workflow across all six of my repos.

I'm Dominik Groński / GroDev — a new studio in Poznań, Poland (JDG since May 2026), available for first paid deployments. This library is MIT.

How I document my AI-first workflow in every public repo

Dominik — Wed, 12 Aug 2026 06:10:46 +0000

TL;DR

In every one of my public repos I keep three artifacts that make my AI-first workflow visible from the file tree, not just claimed in a README:

CLAUDE.md — a literal table of "who did what" (human vs AI) per layer of the project, plus a list of things I rejected from the AI's draft, plus "known gotchas for the next AI pass."
.claude/commands/ — one slash command per repo, tuned to the most expensive failure mode (security review, math invariants, WebGL disposal, hook chain audit, React contract).
For one representative repo — a full CASE_STUDY.md: 90-minute build retrospective, step by step, threat model → SDK lookup → AI draft → line-by-line audit → hardening → in-browser verification → docs.

Decision authority (architecture, security posture, API contract, cost engineering, what to reject) stays with the human. AI gets boilerplate and first drafts. This post shows the how, with links to five working repos as reference.

Why publish this at all

Because AI-augmented work isn't worth hiding. Developers who cover it up today will be the ones saying "I don't do computers" in two years. Companies hiring devs already write "AI-first (Claude, Copilot, Cursor)" straight into job posts — and they want to see evidence, not statements.

But "evidence of AI-first work" isn't "I have ChatGPT open in a tab." It's artifacts in the file tree. This post shows three concrete ones I've deployed across every public repo I own.

Artifact 1: `CLAUDE.md` with a human/AI split

CLAUDE.md is the file Claude Code reads as project context (analogous to .cursorrules or AGENTS.md). But I use it for two audiences at once:

For the next AI pass — so the model knows what's sacred and what's flexible in this repo.
For humans — so anyone browsing the file tree (a client, a recruiter, a teammate) sees, in black and white: who did what.

The table shape I use in every repo:

Layer	Who did it	Why
Threat model & architecture (proxy, not client-side call)	Human	The whole reason this repo exists. Delegating "should the API key touch the browser?" to an AI is how you ship a leaked-key incident. Not negotiable.
Server-side proxy skeleton	AI-drafted, human-reviewed line by line	Claude wrote the first pass; I audited every line for four things: (1) key never in response headers or logs, (2) `role` validated, not trusted, (3) input length capped, (4) SSE framing correct.
Widget UI (vanilla JS, ~6 KB)	AI-drafted, human-styled	Dependency-free was a hard constraint from me. `textContent` (not `innerHTML`) on user text is mine — XSS prevention isn't a call to leave to the model's discretion.
Prompt caching decision	Human	Cost engineering — the difference between $10/mo and $1/mo of API spend.

Three things make this useful and not fluff:

The "Why" column is the part most people skip. It's also the only place you can tell the author understood why they delegated (or didn't).
A "What I rejected from the AI's draft" section — I write out, in plain text, what Claude proposed, what I refused to merge, and why. This is what separates "I use AI" from "I use AI well." An example from one of my repos:

Rejected two things Claude proposed initially:
(1) logging the request body — would log user PII to a plain file. Removed.
(2) falling back to $_ENV['ANTHROPIC_API_KEY'] if getenv() returned false — unnecessary, and on some hosting stacks it could pick up stale values. Removed.

A "Known gotchas for the next AI pass" section — spots where the next iteration of AI would do something dumb. This protects both me and the model — because Claude reads this file as context, so the next round it won't re-propose an idea that's already been rejected.

Working examples:
CLAUDE.md in claude-chat-widget ·
claude-chat-react ·
booking-slots-php ·
woocommerce-custom-product-data ·
threejs-product-configurator-starter.

Artifact 2: A case study — one build, step by step

CLAUDE.md tells you what someone did. A case study tells you how and in what order. Two different documents, both needed.

The case study I wrote for claude-chat-widget has eight sections, each one concrete step of a 90-minute build:

Threat model and architecture (human, before writing a single line of code)
Looking up the exact SDK shape (human, from the claude-api skill) — because the model's training data may be stale for SDK APIs
AI drafts the proxy skeleton (Claude, ~10 min)
Line-by-line audit + hardening (human, ~20 min) — the most important section
AI drafts the widget (Claude, ~10 min)
Widget audit + hardening (human, ~15 min) — XSS, dark mode, mobile, UX
Verification in a real browser (human, ~10 min)
Documentation (human, ~15 min) — because LLMs write generic READMEs

This format has one unexpected side effect: it forces honesty. When you write "AI wrote 60% of the lines, human made every load-bearing decision" — you have to say which decisions those were. Suddenly it's visible where you actually did the work, versus where you just signed off on a generated file.

Full case study: CASE_STUDY.md.

Artifact 3: `.claude/commands/` — automating the review

Claude Code (and most agents) support slash commands — Markdown files under .claude/commands/ invoked in a session as /name. They load as part of the prompt, so I can save a checklist and pull it up with one word.

Every repo I own has one such file, tuned to the class of failure I most want to catch:

security-review.md (claude-chat-widget) — 6-invariant audit of the proxy's security posture (key only in Anthropic\Client(apiKey:), role validated, length capped, X-Accel-Buffering: no, etc.). Runs before every merge to server/chat.php.
react-security-review.md (claude-chat-react) — 8-invariant audit for the React version (no @anthropic-ai/sdk import in src/, no dangerouslySetInnerHTML, setMessages(prev => ...) never closure-based, AbortController in a ref not state, react in peerDependencies, a11y attributes preserved).
verify-slot-math.md (booking-slots-php) — audit of the overlap math (half-open intervals [start, end), < not <=, symmetric buffer). Because booking bugs come from off-by-one errors right there.
hook-audit.md (woocommerce-custom-product-data) — audit of the three-hook WooCommerce chain.
webgl-review.md (threejs-product-configurator-starter) — geometry disposal (so WebGL doesn't leak) and "no build step" invariant (so nobody sneaks Vite in).

The effect: repeatable code review that doesn't depend on my discipline on a given day. Instead of remembering all six points every time I touch the proxy, I type /security-review and get the checklist.

Why these three artifacts

Because they cover the three levels of question anyone evaluating your AI-first work actually asks:

Question	The artifact that answers it
"What specifically did you do vs the AI?"	`CLAUDE.md` — one-screen table
"What does your process look like — order of decisions, what you reject from AI drafts?"	`CASE_STUDY.md` — one build retrospective
"Can you configure agents, or do you just type in a chat?"	`.claude/commands/` — config tuned to a specific failure class

A recruiter reviewing 40 GitHub profiles a week isn't going to read your code. They are going to scan your file tree. If they see CLAUDE.md, CASE_STUDY.md, and .claude/commands/ there — they immediately know they're looking at someone who actually practices the workflow, not someone who put it in their CV.

The philosophy I'm trying to make routine

AI is a fast typist and a reasonable reviewer. Decision authority — architecture, threat model, validation strategy, dependency selection, what to reject — stays with the human. When I hand decision authority to a model, I get a repo that lints clean and blows up in production.

This philosophy works well enough that I shipped 5 working public repos (a WordPress plugin, a PHP booking-slots engine, a Three.js configurator starter, a vanilla-JS chat widget, and a React chat widget on Claude API) — each with a full CLAUDE.md, docs, badges, and a pinned v1.0.0 release. Every load-bearing decision documented, every AI draft audited before merge.

Full profile: github.com/GronskiDeveloper. Fork any repo and check what CLAUDE.md looks like in practice.

I build websites, e-commerce, custom 3D configurators and AI assistants — see grodev.pl or grodev.pl/ai. Poznań, Poland, remote across PL and EU.

Building a 3D Product Configurator in Three.js — Lessons From 9 Client Deployments

Dominik — Wed, 05 Aug 2026 06:47:15 +0000

Over the last year I shipped 9 production 3D configurators for polish manufacturers — pools, garage doors, saunas, pergolas, greenhouses, packaging, decorative lamps, terrace roofs, and light-boxes. Each one runs live on its own subdomain of my studio at grodev.pl.

Some of the lessons were obvious in hindsight. Some cost me a weekend of debugging. Sharing the non-obvious ones here.

1. Draco compression is not optional for CAD-heavy models

Manufacturers send you STEP or SolidWorks files exported to glTF. Raw output is 40–120 MB per variant. On 4G mobile that's a 20-second load with an empty white canvas.

Draco compression brings that to 2–5 MB with no visible quality loss on product shots:

import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'
import { DRACOLoader } from 'three/examples/jsm/loaders/DRACOLoader.js'

const dracoLoader = new DRACOLoader()
dracoLoader.setDecoderPath('/draco/')  // self-hosted, don't use CDN

const loader = new GLTFLoader()
loader.setDRACOLoader(dracoLoader)

loader.load('/models/pool-3.5m.glb', (gltf) => {
  scene.add(gltf.scene)
})

Self-host the decoder — Google's CDN version added ~600 ms to first paint in my measurements. Copy node_modules/three/examples/jsm/libs/draco/ to your public/ folder.

Tooling: gltf-pipeline -i model.glb -o model.draco.glb --draco.compressionLevel 10

2. Instancing beats individual meshes past ~200 objects

A pergola with 40 louvres × 3 tilt positions × user color picker = 120 meshes updating on every frame. Naive approach tanks FPS to 12 on mid-range phones.

InstancedMesh batches identical geometry into one draw call:

const geo = new THREE.BoxGeometry(1, 0.05, 3)
const mat = new THREE.MeshStandardMaterial()
const louvres = new THREE.InstancedMesh(geo, mat, 40)

const dummy = new THREE.Object3D()
for (let i = 0; i < 40; i++) {
  dummy.position.set(0, 0, i * 0.15)
  dummy.rotation.x = userTilt  // update per frame is fine
  dummy.updateMatrix()
  louvres.setMatrixAt(i, dummy.matrix)
}
louvres.instanceMatrix.needsUpdate = true
scene.add(louvres)

Same for basen tiles, brama slats, sauna wall boards. One material change updates all instances.

3. Ship the price calculator to the server, not the client

Every configurator eventually needs a "Show price" button. Tempting to compute client-side — you already have all the state.

Don't. Manufacturers change prices monthly. Every hardcoded PHP-in-JS multiplication is a redeploy. Also: users open DevTools.

Instead:

// Only what changed goes over the wire
const config = {
  model: 'pool-3.5m',
  finish: 'granite-grey',
  extras: ['lighting', 'cover'],
}

const { price, currency, deliveryWeeks } = await fetch('/api/quote', {
  method: 'POST',
  body: JSON.stringify(config)
}).then(r => r.json())

Server (Laravel in my case) hits a pricing_rules table with monthly-updated coefficients. Client only knows what a valid config looks like, never the pricing logic.

Bonus: the same endpoint powers the "email me a PDF quote" flow. Zero duplication.

4. Mobile is your target device, not a "nice to have"

70% of my configurator traffic is mobile. Sauna buyers browse on the couch, pool buyers browse at the site. Any deployment that assumes desktop-first will feel broken.

Concrete mobile survival kit:

renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2)) — clamping to 2 saves ~40% GPU on retina phones
Detect WEBGL_lose_context and reload cleanly when the browser tab is backgrounded on iOS
Preload one hero material, lazy-load the rest — first paint at 400 ms feels instant even if full swatch library is still coming

5. The integration is 60% of the project

Building the WebGL viewer takes 2–3 weeks. Making it actually feed the manufacturer's WooCommerce / CRM / ERP takes another 4–6 weeks — and the client only sees the shiny part.

Budget accordingly. I now quote 12–55k PLN depending on catalog depth and integration surface, not per screen.

Live examples if you want to see any of these techniques in production:

basen3d.grodev.pl — pool configurator (Draco + PWA)
pergola3d.grodev.pl — bioclimatic pergola (InstancedMesh louvres)
lampy3d.grodev.pl — decorative lamp (white-label)

Full studio at grodev.pl — happy to chat if you're integrating similar for a manufacturer.

What tripped you up on your first Three.js production project? Reply — always curious about other people's disaster stories.

DEV Community: Dominik

How I built @grodev/claude-chat-react — architecture notes

TL;DR

Decision 1: Two ways in, not one

Decision 2: The API key never touches the browser (and I mean never)

Decision 3: Streaming with a real abort

The a11y I refuse to leave to Claude

What's not in the package

Full write-up

How I document my AI-first workflow in every public repo

TL;DR

Why publish this at all

Artifact 1: CLAUDE.md with a human/AI split

Artifact 2: A case study — one build, step by step

Artifact 3: .claude/commands/ — automating the review

Why these three artifacts

The philosophy I'm trying to make routine

Building a 3D Product Configurator in Three.js — Lessons From 9 Client Deployments

1. Draco compression is not optional for CAD-heavy models

2. Instancing beats individual meshes past ~200 objects

3. Ship the price calculator to the server, not the client

4. Mobile is your target device, not a "nice to have"

5. The integration is 60% of the project

Artifact 1: `CLAUDE.md` with a human/AI split

Artifact 3: `.claude/commands/` — automating the review