preact-stinger
Procedural arsenal for preact-wasp-drone, the Wasp Nest's Preact 11 specialist. This stinger encodes the opinionated decision framework, the signals API (v2), the preact/compat compatibility surface, the third-party embed pattern, and the Astro/Fresh integration playbooks.
First-read priority: Start with guides/00-when-to-choose-preact.md. If you have already classified the scenario, jump to the relevant guide. The research summary is at research/research-summary.md.
When this stinger applies
Load this stinger when any of the following is true:
- The user is evaluating Preact vs React for a new project.
- The user is migrating an existing React codebase to Preact via
preact/compat.
- The user is building a third-party embed widget and bundle size is a constraint.
- The user is working in an Astro project and wants to use Preact islands.
- The user is working in a Fresh 2.x project.
- The user has Preact code to review, debug, or refactor.
- The user asks about signals (
signal, computed, effect, createModel).
Do NOT load for:
- Pure React architecture questions →
react-wasp-drone.
- Next.js App Router configuration →
react-wasp-drone (and warn: preact/compat + App Router is a footgun).
- Deno DevOps beyond Fresh (deploy configs, Docker, etc.) →
devops-wasp-drone.
- Design system or token decisions →
ux-ui-svelte-wasp-drone.
Scenario classification (read first)
Before applying any guide, classify the incoming request:
| Scenario |
Key signal |
Primary guide |
| New project, evaluating Preact |
"should I use Preact?", bundle size target, no existing React code |
guides/00-when-to-choose-preact.md |
| Signals authoring |
"signals", "signal()", "computed()", "createModel" |
guides/01-signals-api.md |
| React-to-Preact migration |
existing React codebase, preact/compat, alias setup |
guides/02-compat-migration.md |
| Third-party embed widget |
"embed", "third-party script", "widget", shadow DOM, bundle budget |
guides/03-embed-widget.md |
| Astro integration |
@astrojs/preact, client:* directives, Astro project |
guides/04-astro-integration.md |
| Fresh framework |
Fresh, Deno, islands/, deno.json |
guides/05-fresh-framework.md |
If the scenario is ambiguous, ask one targeted clarifying question before diving into code.
Critical directives
These are non-negotiables for preact-wasp-drone. Each has a one-line "why".
- Never recommend Preact without naming the concrete benefit. Why: "smaller bundle" is not a reason; the specific size delta, embed constraint, or signals preference must be stated.
- Always check
preact/compat compatibility before migrating. Why: React 19 use(), useTransition, RSC, and @types/react each break compat silently or noisily.
@types/react must NEVER be installed alongside preact/compat. Why: type conflicts are pervasive and hard to debug; use preact's built-in types only.
- Next.js App Router +
preact/compat = footgun. Stop and warn. Why: RSC requires React's fiber; compat wraps but does not replace it, producing silent failures.
- Scope signals to the specific use case. Why: mixing naive
useState patterns with signals produces tracking bugs; the mental model shift must be explicit.
- Defer to
react-wasp-drone for React architecture. Why: the two wasp-drones share JSX surface but own different mental models; crossing produces contradictory advice.
Version anchors (May 2026)
| Package |
Stable version |
Notes |
| preact |
10.x (v11 beta) |
v11 beta as of Aug 2025; check for stable |
| @preact/signals |
2.9.0 |
v2 API is current |
| preact-custom-element |
4.6.0 |
embed/web component wrapper |
| @astrojs/preact |
5.1.2 |
require >= 5.0.1 (useId bug fixed) |
| Fresh |
2.2.2 |
Vite-based; Fresh 1.x is esbuild |
Source: research/internal/2026-05-20-stinger-folder-context.md (source-repository research, not shipped with the plugin)
Folder layout
preact-stinger/
├── SKILL.md (this file — master index)
├── README.md (one-page human overview)
├── guides/
│ ├── 00-when-to-choose-preact.md (tradeoff matrix + honest "when React wins")
│ ├── 01-signals-api.md (v1 primitives + v2 model pattern)
│ ├── 02-compat-migration.md (alias setup, known gaps, migration checklist)
│ ├── 03-embed-widget.md (shadow DOM, IIFE bundle, size checklist)
│ ├── 04-astro-integration.md (client: directives, useId fix, compat in Astro)
│ └── 05-fresh-framework.md (islands, serializable props, signals state)
├── examples/
│ ├── happy-path-signals-component.md
│ └── compat-migration-vite.md
├── templates/
│ └── migration-checklist.md
├── reports/
│ └── README.md
└── research/ (authored by scripture-historian — do not modify)
├── research-plan.md
├── research-summary.md
├── index.md
├── external/
└── internal/
Forged by stinger-forge from preact-wasp-drone-command-brief.md and research/. Part of The Wasp Nest by Mario Aldayuz a.k.a @thenotoriousllama.
1---2name: preact-stinger-33license: AGPL-3.0-or-later4description: "Build Preact 11 apps and widgets. Use for signals, React compat migration, embeds, Astro islands, or Fresh. Read README.md for the guide map."5metadata:6 source: https://skillmd.com/skills/legioncodeinc/preact-stinger-37---89# preact-stinger1011Procedural arsenal for `preact-wasp-drone`, the Wasp Nest's Preact 11 specialist. This stinger encodes the opinionated decision framework, the signals API (v2), the `preact/compat` compatibility surface, the third-party embed pattern, and the Astro/Fresh integration playbooks.1213**First-read priority:** Start with `guides/00-when-to-choose-preact.md`. If you have already classified the scenario, jump to the relevant guide. The research summary is at `research/research-summary.md`.1415---1617## When this stinger applies1819Load this stinger when any of the following is true:2021- The user is evaluating Preact vs React for a new project.22- The user is migrating an existing React codebase to Preact via `preact/compat`.23- The user is building a third-party embed widget and bundle size is a constraint.24- The user is working in an Astro project and wants to use Preact islands.25- The user is working in a Fresh 2.x project.26- The user has Preact code to review, debug, or refactor.27- The user asks about signals (`signal`, `computed`, `effect`, `createModel`).2829Do NOT load for:30- Pure React architecture questions → `react-wasp-drone`.31- Next.js App Router configuration → `react-wasp-drone` (and warn: `preact/compat` + App Router is a footgun).32- Deno DevOps beyond Fresh (deploy configs, Docker, etc.) → `devops-wasp-drone`.33- Design system or token decisions → `ux-ui-svelte-wasp-drone`.3435---3637## Scenario classification (read first)3839Before applying any guide, classify the incoming request:4041| Scenario | Key signal | Primary guide |42|---|---|---|43| New project, evaluating Preact | "should I use Preact?", bundle size target, no existing React code | `guides/00-when-to-choose-preact.md` |44| Signals authoring | "signals", "signal()", "computed()", "createModel" | `guides/01-signals-api.md` |45| React-to-Preact migration | existing React codebase, `preact/compat`, alias setup | `guides/02-compat-migration.md` |46| Third-party embed widget | "embed", "third-party script", "widget", shadow DOM, bundle budget | `guides/03-embed-widget.md` |47| Astro integration | `@astrojs/preact`, `client:*` directives, Astro project | `guides/04-astro-integration.md` |48| Fresh framework | Fresh, Deno, `islands/`, `deno.json` | `guides/05-fresh-framework.md` |4950If the scenario is ambiguous, ask one targeted clarifying question before diving into code.5152---5354## Critical directives5556These are non-negotiables for `preact-wasp-drone`. Each has a one-line "why".5758- **Never recommend Preact without naming the concrete benefit.** Why: "smaller bundle" is not a reason; the specific size delta, embed constraint, or signals preference must be stated.59- **Always check `preact/compat` compatibility before migrating.** Why: React 19 `use()`, `useTransition`, RSC, and `@types/react` each break compat silently or noisily.60- **`@types/react` must NEVER be installed alongside `preact/compat`.** Why: type conflicts are pervasive and hard to debug; use `preact`'s built-in types only.61- **Next.js App Router + `preact/compat` = footgun. Stop and warn.** Why: RSC requires React's fiber; compat wraps but does not replace it, producing silent failures.62- **Scope signals to the specific use case.** Why: mixing naive `useState` patterns with signals produces tracking bugs; the mental model shift must be explicit.63- **Defer to `react-wasp-drone` for React architecture.** Why: the two wasp-drones share JSX surface but own different mental models; crossing produces contradictory advice.6465---6667## Version anchors (May 2026)6869| Package | Stable version | Notes |70|---|---|---|71| preact | 10.x (v11 beta) | v11 beta as of Aug 2025; check for stable |72| @preact/signals | 2.9.0 | v2 API is current |73| preact-custom-element | 4.6.0 | embed/web component wrapper |74| @astrojs/preact | 5.1.2 | **require >= 5.0.1** (useId bug fixed) |75| Fresh | 2.2.2 | Vite-based; Fresh 1.x is esbuild |7677> Source: `research/internal/2026-05-20-stinger-folder-context.md` (source-repository research, not shipped with the plugin)7879---8081## Folder layout8283```84preact-stinger/85├── SKILL.md (this file — master index)86├── README.md (one-page human overview)87├── guides/88│ ├── 00-when-to-choose-preact.md (tradeoff matrix + honest "when React wins")89│ ├── 01-signals-api.md (v1 primitives + v2 model pattern)90│ ├── 02-compat-migration.md (alias setup, known gaps, migration checklist)91│ ├── 03-embed-widget.md (shadow DOM, IIFE bundle, size checklist)92│ ├── 04-astro-integration.md (client: directives, useId fix, compat in Astro)93│ └── 05-fresh-framework.md (islands, serializable props, signals state)94├── examples/95│ ├── happy-path-signals-component.md96│ └── compat-migration-vite.md97├── templates/98│ └── migration-checklist.md99├── reports/100│ └── README.md101└── research/ (authored by scripture-historian — do not modify)102 ├── research-plan.md103 ├── research-summary.md104 ├── index.md105 ├── external/106 └── internal/107```108109---110111*Forged by `stinger-forge` from `preact-wasp-drone-command-brief.md` and `research/`. Part of The Wasp Nest by [Mario Aldayuz a.k.a @thenotoriousllama](https://github.com/thenotoriousllama).*