> ## Documentation Index
> Fetch the complete documentation index at: https://shareful.blode.md/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Examples
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
```yaml
---
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
```markdown
## 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
```markdown
## 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**
```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 the 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 a single query with joined relation loading.
**Good because:** Explains root cause, not just "add include." Written as prose.
### Context section
```markdown
## 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 DataLoader patterns
- `select` is more efficient than `include` when you don't need all columns
```
**Good because:** Version requirements first. Includes debugging tip and related patterns.
## Good example: pattern type
```yaml
---
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.
The body follows the same structure: Problem shows type widening with a concrete `Routes` type, Solution demonstrates `satisfies`, and Why It Works explains why literal inference is preserved.
## Common mistakes
### Bad frontmatter
```yaml
---
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. Wrong date format.
### Bad Problem section
```markdown
## 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.
### Bad Solution section
````markdown
## Solution
Just add `include` to your query. This should fix it.
```
prisma.post.findMany({ include: { author: true } })
```
````
**Problems:** No language label. Incomplete snippet. Explanation mixed into text instead of code comments.
### Bad Why It Works section
```markdown
## Why It Works
It works because we added `include: { author: true }` to the query. This tells Prisma to include the author in the results.
```
**Problems:** Restates the solution instead of explaining the mechanism.
### Bad Context section
```markdown
## 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.
```
**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 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_type` matches 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
**Context section:**
- Formatted as a bulleted list
- Version requirements listed first
- Includes at least one gotcha or limitation
## Next steps
- [Share format specification](./share-format) - field constraints and validation rules
- [Creating shares](./creating-shares) - writing tips