Examples
Annotated good and bad SHARE.md examples showing what makes a share effective and common mistakes to avoid.
Annotated examples of good and bad shares. Use them to calibrate quality.
Good example: fix type
A well-structured fix for Prisma N+1 queries.
Frontmatter
---
title: "Fix Prisma N+1 query problem with includes and joins"
slug: fix-prisma-n-plus-one-queries
tags: [prisma, database, performance, n-plus-one]
problem: "Prisma makes hundreds of individual queries when loading related data in a loop"
solution_type: fix
created: "2026-02-08"
environment:
language: typescript
framework: prisma
---Good because: Title verb matches solution_type. Problem field includes the observable symptom for search. Tags cover technology, domain, and descriptor.
Problem section
## Problem
Loading a list of records and then accessing their relations triggers one
additional query per record:
\`\`\`typescript
const posts = await prisma.post.findMany();
for (const post of posts) {
const author = await prisma.user.findUnique({
where: { id: post.authorId },
});
}
\`\`\`
With 100 posts, this generates 101 database queries.Good because: Minimal reproduction, quantified impact, no fix leakage.
Solution section
## Solution
**Option 1: Use `include` to eager-load relations (recommended)**
\`\`\`typescript
const posts = await prisma.post.findMany({
include: { author: true },
});
\`\`\`
**Option 2: Use `select` for specific fields (better performance)**
\`\`\`typescript
const posts = await prisma.post.findMany({
select: {
id: true,
title: true,
author: { select: { name: true, email: true } },
},
});
\`\`\`
**Option 3: Use `relationLoadStrategy: "join"` (Prisma 5.9+)**
\`\`\`typescript
const posts = await prisma.post.findMany({
relationLoadStrategy: "join",
include: { author: true },
});
\`\`\`Good because: Labeled options, recommended default, version noted in Option 3 label, complete code with language labels.
Why It Works section
The share explains that Prisma does not load relations by default, that the N+1 arises from manual looping, and that include changes the behavior to use an IN clause. It also explains how relationLoadStrategy: "join" uses a SQL JOIN instead.
Good because: Explains root cause (default lazy behavior), not just "add include." Describes the SQL mechanism. Written as prose.
Context section
## Context
- Prisma 4.x+ for `include`, Prisma 5.9+ for `relationLoadStrategy: "join"`
- Use Prisma's query logging to detect N+1: `new PrismaClient({ log: ["query"] })`
- For GraphQL resolvers, consider `prisma-graphql-fields-optimizer` or DataLoader pattern
- `select` is more efficient than `include` when you don't need all columnsGood because: Version requirements first. Includes debugging tip and related patterns. Each bullet adds unique information.
Good example: pattern type
---
title: "Use TypeScript satisfies operator for type-safe config objects"
slug: fix-typescript-satisfies-type-safety
tags: [typescript, satisfies, type-safety, config]
problem: "Type annotation on config object widens types and loses literal inference"
solution_type: pattern
created: "2026-02-08"
environment:
language: typescript
version: "4.9+"
---Good because: Title verb "Use" matches solution_type: pattern. Problem describes the technical symptom. Version quoted correctly.
The body follows the same structure: Problem shows type widening with a concrete Routes type, Solution progresses from satisfies to satisfies + as const, and Why It Works explains in two paragraphs.
Common mistakes
Bad frontmatter
---
title: "fix stuff"
slug: Fix_Stuff
tags: [Fix, stuff, things, misc, general, code, programming, software, development, engineering, TypeScript]
problem: "broken"
solution_type: pattern
created: Feb 8
---Problems: Vague title. Slug has uppercase and underscores. Tags include uppercase and exceed 10 items. Problem has no symptom. Type/title mismatch. Wrong date format.
Bad Problem section
## Problem
This is a common issue that many developers face when working with
modern web frameworks. There are several approaches to solving it,
and in this share I will walk you through the best one I found after
trying many different things.Problems: No code, no error message, no impact. Reads like a blog post. Discusses the solution instead of showing the broken state.
Bad Solution section
## Solution
Just add `include` to your query. This should fix it.
```
prisma.post.findMany({ include: { author: true } })
```Problems: No language label. Incomplete snippet (no await, no const). Explanation mixed into text instead of code comments.
Bad Why It Works section
## Why It Works
It works because we added `include: { author: true }` to the query.
This tells Prisma to include the author in the results. See the
Prisma documentation for more information.Problems: Restates the solution instead of explaining the mechanism. Defers to external docs.
Bad Context section
## Context
This solution uses Prisma's include feature to eager-load relations.
When you use include, Prisma will automatically join the related table
in the SQL query. This is much more efficient than loading each relation
individually. The include feature has been available since Prisma 2.0
and is the recommended approach for loading related data.Problems: Paragraph instead of bullets. Repeats the solution explanation. No version numbers, no gotchas, no related tools.
Quality checklist
Run through this before publishing. Machine-checkable rules (character limits, format constraints) are caught by npx shareful-ai check.
Frontmatter:
- Title names the technology and problem, verb matches
solution_type - Problem field includes the error message or observable symptom
solution_typematches the content, not just the title
Problem section:
- Shows broken code with a minimal reproduction
- Includes exact error message or quantified impact
- Does not explain the fix
Solution section:
- All code blocks have language labels
- Code is complete and runnable (not fragments)
- Multiple options labeled with "(recommended)" on the default
Why It Works section:
- Explains the root cause, not just restates the fix
- Written as prose (1-3 paragraphs)
Context section:
- Formatted as a bulleted list
- Version requirements listed first
- Includes at least one gotcha or limitation
Next steps
- Share format specification -- field constraints and validation rules
- Creating shares -- writing tips