# CLI reference (https://shareful.blode.md/cli)

Run with `npx` (no install needed) or install globally with `npm install -g shareful-ai`.

```bash
npx shareful-ai <command> [options]
```

## Commands

### `init`

Create a new shares repository.

```bash
npx shareful-ai init [name]
```

**Arguments:**

| Argument | Description |
| --- | --- |
| `name` | Directory name (defaults to `shares`) |

**What it creates:**

- `shares/` directory with an example share
- `.gitignore`, `README.md`, and `AGENTS.md`
- A git repository

**Example:**

```bash
npx shareful-ai init my-solutions
cd my-solutions
```

---

### `create`

Create a new `SHARE.md` file. Without flags, runs interactively.

```bash
npx shareful-ai create [options]
```

**Options:**

| Flag | Description |
| --- | --- |
| `-t, --title <title>` | Share title (max 128 characters) |
| `-p, --problem <problem>` | One-sentence problem description (max 256 characters) |
| `--tags <tags>` | Comma-separated tags (1-10, max 32 characters each) |
| `--type <type>` | Solution type: `fix`, `workaround`, `pattern`, `reference`, or `config` |

**Interactive mode:**

```bash
npx shareful-ai create
```

Prompts you for each field with validation.

**Non-interactive mode:**

Pass all four flags to skip prompts:

```bash
npx shareful-ai create \
  --title "Fix Prisma connection pool exhaustion" \
  --problem "Prisma exhausts connection pool under high concurrency" \
  --tags "prisma,database,performance" \
  --type fix
```

Creates `shares/<slug>/SHARE.md` with frontmatter and section templates.

---

### `search`

Search shareful.ai for community solutions.

```bash
npx shareful-ai search <query> [options]
```

**Arguments:**

| Argument | Description |
| --- | --- |
| `query` | Search query string (required) |

**Options:**

| Flag | Description | Default |
| --- | --- | --- |
| `--type <type>` | Filter by solution type | All types |
| `--tags <tags>` | Filter by tags (comma-separated) | No filter |
| `--limit <n>` | Maximum number of results | 5 |

**Examples:**

```bash
# Search for React hydration fixes
npx shareful-ai search "hydration mismatch"

# Search for authentication patterns
npx shareful-ai search "auth" --type pattern

# Search with tag filter
npx shareful-ai search "database" --tags prisma,postgres --limit 3
```

---

### `check`

Validate all `SHARE.md` files in the current repository.

```bash
npx shareful-ai check
```

Validates every `shares/*/SHARE.md` file: frontmatter fields, slug-directory match, and the four required body sections. Exits with code 1 if any share fails.

**Example output:**

```
  + fix-nextjs-hydration
  + prisma-connection-pooling
  x broken-share/SHARE.md - missing required field: tags

2 valid, 1 error(s)
```

---

### `skills`

Install the `shareful-search` and `shareful-create` agent skills. Works with Claude Code, Cursor, Windsurf, and others.

```bash
npx shareful-ai skills
```

---

### `--help`

Display help information.

```bash
npx shareful-ai --help
```

### `--version`

Display the current version.

```bash
npx shareful-ai --version
```

## Telemetry

The CLI collects anonymous, non-identifying usage events. Set `DISABLE_TELEMETRY=1` to opt out. See [configuration](./configuration#telemetry) for details.

## Next steps

- [Share format specification](./share-format) - field constraints and validation rules
- [Creating shares](./creating-shares) - writing tips and quality standards
- [Configuration](./configuration) - settings and environment variables

# Configuration (https://shareful.blode.md/configuration)

## User configuration

The CLI stores settings at `~/.shareful/config.json`.

| Field | Type | Description |
| --- | --- | --- |
| `sharesRepo` | string | Default path to your shares repository |

```json
{
  "sharesRepo": "/Users/you/code/my-shares"
}
```

When set, the CLI defaults to this repository path instead of the current directory.

## Telemetry

The CLI collects anonymous telemetry by default. No personal information, IP addresses, or device identifiers are collected.

**Events tracked:**

| Event | Data |
| --- | --- |
| `share` | Share slug, share count |
| `init` | Repository name |
| `check` | Valid count, error count |
| `add-skills` | None |

**To opt out**, set either variable in your shell profile:

```bash
# Add to ~/.bashrc, ~/.zshrc, or equivalent
export DISABLE_TELEMETRY=1
# or
export DO_NOT_TRACK=1
```

Or set it for a single command:

```bash
DISABLE_TELEMETRY=1 npx shareful-ai create
```

## Requirements

- **Node.js** 18 or later
- **Git** for version control
- **GitHub** repository (for indexing and discovery)

## Support

[Open an issue on GitHub](https://github.com/shareful-ai/shareful-ai) to report bugs or request features.

## Next steps

- [CLI reference](./cli) - all commands and flags
- [Creating shares](./creating-shares) - writing tips and quality standards
- [Finding shares](./finding-shares) - search tips and API

# Creating shares (https://shareful.blode.md/creating-shares)

For the full quickstart, see [Getting started](./).

## CLI flags

Skip prompts by passing all four flags:

```bash
npx shareful-ai create \
  --title "Fix ESLint flat config migration" \
  --problem "ESLint 9 flat config breaks existing plugin configurations" \
  --tags "eslint,config,migration" \
  --type fix
```

## Writing the body

After the CLI generates the file, fill in the four body sections. See the [format spec](./share-format#body-sections) for templates and anti-patterns.

- **Problem** -- Show the broken code and error message, not a description of the fix
- **Solution** -- Provide complete, runnable code with language labels on every code block
- **Why It Works** -- Explain the root cause in prose, don't restate the solution
- **Context** -- Use a bulleted list with version requirements first

## Choose the right solution type

Most shares use `fix`. See the [solution type reference](./share-format#solution_type) for all five options and their title conventions.

## Writing tips

**Be specific.** "Fix React error" is too vague. "Fix React hydration mismatch when using browser-only libraries with Next.js 14" tells readers exactly what this solves.

**Include complete code.** Show the full file or function, not just the changed line.

**Add error messages.** People search for exact error text. Include it verbatim.

**Keep it focused.** One share solves one problem. Multiple solutions? Create multiple shares.

**Tag thoughtfully.** Use specific, lowercase tags (`nextjs` not `next`, `typescript` not `ts`). Cover the framework, language, and key libraries.

**Start titles with a matching verb.** "Fix" for fixes, "Use" for patterns, "Configure" for configs.

## Validate before publishing

Run `npx shareful-ai check` to validate all shares. It checks frontmatter, body sections, and slug-directory alignment.

Human-judgment checklist (the CLI catches the rest):

- Title names the technology and problem, verb matches `solution_type`
- Problem includes the error message or observable symptom
- Code is complete and runnable, not fragments
- No placeholder content

For the full checklist, see [examples](./examples#quality-checklist).

## Next steps

- [Format specification](./share-format) - field constraints and validation rules
- [Examples](./examples) - annotated good and bad shares
- [CLI reference](./cli)

# Examples (https://shareful.blode.md/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
---
```

> [!INFO]
> **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.
```
```

<Callout type="info">
**Good because:** Minimal reproduction, quantified impact, no fix leakage.
</Callout>

### 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 },
});
```

```

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

> [!INFO]
> **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+"
---
```

> [!INFO]
> **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
---
```

> [!DANGER]
> **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.
```

> [!DANGER]
> **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 } })
```
````

> [!DANGER]
> **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.
```

> [!DANGER]
> **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.
```

> [!DANGER]
> **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

# FAQ (https://shareful.blode.md/faq)

## How do I install the CLI?

Run directly with `npx` (no install needed) or install globally:

```bash
npm install -g shareful-ai
```

## What Node.js version do I need?

Node.js 18 or later.

## Can I opt out of telemetry?

Yes. Set `DISABLE_TELEMETRY=1` or `DO_NOT_TRACK=1`. See [configuration](./configuration#telemetry) for details.

## How do I report a bug?

[Open an issue on GitHub](https://github.com/shareful-ai/shareful-ai).

# Finding shares (https://shareful.blode.md/finding-shares)

Your agent uses `shareful-search` to find solutions automatically. You can also search from the CLI or the API.

## Filter results

Narrow your search with flags:

```bash
# Only show fixes
npx shareful-ai search "auth" --type fix

# Filter by tags
npx shareful-ai search "database" --tags prisma

# Combine filters with a result limit
npx shareful-ai search "caching" --type pattern --tags redis --limit 3
```

### Available filters

| Flag | Description | Default |
| --- | --- | --- |
| `--type` | Filter by solution type (`fix`, `workaround`, `pattern`, `reference`, `config`) | All types |
| `--tags` | Filter by tags (comma-separated) | No filter |
| `--limit` | Maximum results to return | 5 |

## Search results

Each result includes:

| Field | Description |
| --- | --- |
| `title` | The share's title |
| `problem` | One-sentence problem description |
| `solution_type` | Type of solution |
| `tags` | Associated tags |
| `verified` | Whether the solution has been verified |
| `url` | Direct link to the share |

## Search tips

**Use error messages.** Paste the exact error text. Problem sections often contain the same text, so matches are strong.

```bash
npx shareful-ai search "Could not find plugin react"
```

**Be specific.** Include the framework name and version.

```bash
npx shareful-ai search "prisma connection pool nextjs"
```

**Try different types.** No fix? Search for workarounds or patterns.

```bash
npx shareful-ai search "rate limiting" --type workaround
npx shareful-ai search "rate limiting" --type pattern
```

## Search API

The search endpoint is publicly available:

```
GET https://shareful.ai/api/search?q=<query>&limit=5&type=fix&tags=react
```

### Query parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `q` | string | Search query (required) |
| `limit` | number | Maximum results (default: 5) |
| `type` | string | Filter by solution type |
| `tags` | string | Filter by tags (comma-separated) |

### Response format

```json
{
  "shares": [
    {
      "slug": "fix-nextjs-hydration-mismatch",
      "title": "Fix Next.js hydration mismatch with dynamic imports",
      "problem": "Next.js throws hydration errors when rendering browser-only components",
      "solution_type": "fix",
      "tags": ["nextjs", "react", "hydration"],
      "url": "https://github.com/username/my-shares/blob/main/shares/fix-nextjs-hydration-mismatch/SHARE.md",
      "verified": true
    }
  ],
  "total": 1
}
```

## Reporting outcomes

After applying a share, an agent can report the outcome:

```
POST https://shareful.ai/api/outcome
```

```json
{
  "share_path": "username/my-shares/fix-nextjs-hydration-mismatch",
  "outcome": "success"
}
```

Values: `success` or `failure`. Outcomes help rank solutions.

## Next steps

- [Create a share](./creating-shares) to contribute back
- [CLI reference](./cli) - all commands and flags

# Getting started (https://shareful.blode.md/)

Shareful is an open-source CLI that lets developers share verified coding solutions as markdown. Your AI agent discovers them on-demand.

## Quickstart

### 1. Install skills

```bash
npx shareful-ai skills
```

Installs two agent skills -- `shareful-search` and `shareful-create`. Works with Claude Code, Cursor, Windsurf, and others. No server, no extra dependencies.

### 2. Initialize a shares repository

```bash
npx shareful-ai init my-shares
cd my-shares
```

Creates a directory with a `shares/` folder and an example share. Push to GitHub as a public repo.

### 3. Create and share a solution

```bash
npx shareful-ai create
```

The CLI prompts you for each field. To skip prompts, pass flags:

```bash
npx shareful-ai create \
  --title "Fix Next.js hydration mismatch" \
  --problem "Component using window throws hydration mismatch error" \
  --tags "nextjs,react,hydration" \
  --type fix
```

Validate and push:

```bash
npx shareful-ai check
git add -A && git commit -m "Add share" && git push
```

Your shares are now indexed and discoverable on [shareful.ai](https://shareful.ai).

### 4. Find solutions

```bash
npx shareful-ai search "hydration mismatch nextjs"
```

The `shareful-search` skill finds verified fixes mid-conversation so your agent spends tokens solving, not searching.

## Why skills, not MCP?

Skills are plain CLI tools -- no server, no protocol negotiation, no extra dependencies. One command installs both. MCP requires a running server, connection management, and protocol-specific integration. Skills are lighter on tokens and work with any agent.

## Learn more

- [What is a share?](./what-is-a-share) - How shares work and why the format matters.
- [Creating shares](./creating-shares) - Write and publish a share step by step.
- [Finding shares](./finding-shares) - Search tips, filters, and the API.
- [Share format specification](./share-format) - Field constraints, validation rules, and writing guidance.

# Share format specification (https://shareful.blode.md/share-format)

## File structure

A share lives in a directory named after its slug inside the `shares/` folder:

```
shares/
  fix-nextjs-hydration-mismatch/
    SHARE.md
  prisma-connection-pooling/
    SHARE.md
```

Each `SHARE.md` file has two parts: YAML frontmatter and a markdown body with four required sections.

## Required frontmatter fields

The frontmatter contains structured metadata in YAML format, enclosed by `---` delimiters.

### `title`

| Constraint | Value |
| --- | --- |
| Type | string |
| Max length | 128 characters |
| Required | Yes |

Start with a verb that matches the `solution_type`:

| solution_type | Verb convention | Example |
| --- | --- | --- |
| `fix` | "Fix ..." | "Fix Prisma N+1 query problem with includes and joins" |
| `workaround` | "Workaround for ..." | "Workaround for Next.js 14 middleware redirect loop" |
| `pattern` | "Use ...", "Implement ..." | "Use TypeScript satisfies operator for type-safe config objects" |
| `reference` | "Guide to ...", "Reference for ..." | "Guide to PostgreSQL JSONB query operators" |
| `config` | "Configure ..." | "Configure ESLint flat config for TypeScript monorepos" |

Good titles:

```yaml
title: "Fix Docker build cache invalidation for node_modules"
title: "Use TypeScript satisfies operator for type-safe config objects"
```

Bad titles:

```yaml
title: "Fix bug"          # Too vague, no technology or symptom
title: "fix prisma"        # No capitalization, no specifics
```

### `slug`

A kebab-case identifier that doubles as the directory name and URL path.

| Constraint | Value |
| --- | --- |
| Type | string |
| Max length | 64 characters |
| Pattern | `/^[a-z0-9-]+$/` |
| Required | Yes |

Must match the parent directory name exactly. The CLI generates slugs from titles automatically:

1. Convert to lowercase
2. Strip characters that are not `a-z`, `0-9`, spaces, or hyphens
3. Replace spaces with hyphens
4. Collapse consecutive hyphens into one
5. Trim leading and trailing hyphens
6. Truncate to 64 characters

```
"Fix Prisma N+1 queries"       → fix-prisma-n1-queries
"Fix Docker build cache (v2)"  → fix-docker-build-cache-v2
"Fix Next.js hydration error"  → fix-nextjs-hydration-error
```

Good slugs:

```yaml
slug: fix-prisma-n-plus-one-queries
slug: fix-docker-node-modules-layer-cache
```

Bad slugs:

```yaml
slug: Fix-Prisma           # Uppercase not allowed
slug: fix_prisma_queries    # Underscores not allowed; use hyphens
```

### `tags`

| Constraint | Value |
| --- | --- |
| Type | string[] |
| Min items | 1 |
| Max items | 10 |
| Each max length | 32 characters |
| Case | Lowercase only |
| Required | Yes |

Cover three categories:

1. Primary technology
2. Problem domain
3. Descriptors

Good tags:

```yaml
tags: [prisma, database, performance, n-plus-one]
tags: [nextjs, react, hydration, ssr]
```

Bad tags:

```yaml
tags: []                    # At least 1 tag required
tags: [Prisma]              # Must be lowercase
```

### `problem`

| Constraint | Value |
| --- | --- |
| Type | string |
| Max length | 256 characters |
| Required | Yes |

One sentence describing the problem. Include the error message or symptom.

Good problem fields:

```yaml
problem: "Prisma makes hundreds of individual queries when loading related data in a loop"
problem: "Docker rebuilds node_modules from scratch on every code change, making builds slow"
```

Bad problem fields:

```yaml
problem: "Something is broken"    # No specifics, no error message
problem: "It doesn't work"        # Completely unhelpful
```

### `solution_type`

| Constraint | Value |
| --- | --- |
| Type | enum |
| Values | `fix`, `workaround`, `pattern`, `reference`, `config` |
| Required | Yes |

| Value | Description | When to use |
| --- | --- | --- |
| `fix` | A direct fix for a bug or error | The solution permanently resolves the root cause |
| `workaround` | A temporary workaround for a known issue | The root cause is upstream or unfixable; this bypasses it |
| `pattern` | A reusable coding pattern or architecture | The solution generalizes beyond a single error |
| `reference` | A lookup guide or cheat sheet | The content is informational, not fixing a specific error |
| `config` | A configuration change resolving a setup issue | The fix is entirely in config files, not application code |

Most shares are `fix`. When in doubt between `fix` and `pattern`, choose `fix`.

### `created`

| Constraint | Value |
| --- | --- |
| Type | string |
| Format | `YYYY-MM-DD` |
| Required | Yes |

Use today's date. Quote the value in YAML:

```yaml
created: "2026-02-08"
```

## Optional frontmatter fields

These fields add context but are not required for validation.

### `environment`

Technical context for the solution. Recommended.

```yaml
environment:
  language: typescript
  framework: nextjs
  version: "14+"
```

### `ai_provider`

Which AI assistant helped create or verify the solution. Set only if an AI was meaningfully involved.

### `related`

An array of slugs linking to related shares.

### `verified`

Whether the share has been verified. Set automatically from outcome reports -- do not set manually.

### `updated`

ISO date (`YYYY-MM-DD`) for when the share was last updated.

## Complete frontmatter example

```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
ai_provider: "claude"
related:
  - fix-postgres-connection-pooling-serverless
---
```

## Body sections

The markdown body must contain exactly four sections in this order. Total body must be under 300 lines. Aim for 60-150 lines.

### Problem

Show the broken state so readers can confirm they have the same issue.

**Must include:**

- Broken code
- Error message or symptom
- Impact

### Solution

Show the fix with complete, runnable code. If there are multiple options, label the recommended one.

### Why It Works

Explain the mechanism behind the fix. Do not just restate the solution.

### Context

List version requirements first, then add gotchas, alternatives, and related tools.

## Section length guidelines

# What is a share? (https://shareful.blode.md/what-is-a-share)

A share is a structured markdown file (`SHARE.md`) that captures a coding solution both humans and AI agents can discover, read, and apply. Each share documents a single fix, workaround, pattern, or configuration in a GitHub repository.

## How shares work

Shares follow a three-step lifecycle:

1. **Create** -- Capture a solution as a `SHARE.md` file using the CLI or by writing it directly.
2. **Index** -- Shareful indexes public shares and extracts metadata for search.
3. **Discover** -- Search for solutions by error message, technology, or problem domain.

## The SHARE.md file

Every share lives in a directory named after its slug inside a `shares/` folder:

```
shares/
  fix-nextjs-hydration-mismatch/
    SHARE.md
  prisma-connection-pooling/
    SHARE.md
```

A `SHARE.md` file has two parts:

- **Frontmatter** -- YAML metadata (title, slug, tags, problem, solution type) that powers search and filtering.
- **Body** -- four required sections:

| Section | Purpose |
| --- | --- |
| `## Problem` | Show the broken state with code and error messages |
| `## Solution` | Provide complete, working code |
| `## Why It Works` | Explain the root cause and why the fix resolves it |
| `## Context` | List version requirements, gotchas, and alternatives |

Minimal frontmatter example:

```yaml
---
title: Fix Next.js hydration mismatch with dynamic imports
slug: fix-nextjs-hydration-mismatch
tags: [nextjs, react, hydration]
problem: Component using window throws hydration mismatch error
solution_type: fix
created: "2025-01-15"
---
```

## Solution types

Every share has a `solution_type`. Most are `fix`. See the [solution type reference](./share-format#solution_type) for all five types and their title conventions.

## Why structured format matters

The structured format gives you four things:

- **Scannable** -- Error message, fix, explanation, and caveats are always in the same place.
- **Searchable** -- YAML frontmatter powers filtering by tags, type, and problem text.
- **Complete** -- Four mandatory sections prevent half-finished solutions.
- **AI-readable** -- Agents can parse, match, and apply shares programmatically.

## Next steps

- [Create your first share](./creating-shares)
- [See the full format spec](./share-format)