Skip to content
Shareful

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
---

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.

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

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+)

const posts = await prisma.post.findMany({
  relationLoadStrategy: "join",
  include: { author: true },
});

<Callout type="info">
**Good because:** Labeled options, recommended default, version noted in the label, complete code with language labels.
</Callout>

### 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.

<Callout type="info">
**Good because:** Explains root cause, not just "add include." Written as prose.
</Callout>

### 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 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+"
---

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

---
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
---

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.

Bad Solution section

## Solution

Just add `include` to your query. This should fix it.

```
prisma.post.findMany({ include: { author: true } })
```

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.

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.

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