Code To Pantry

Code to pantry

Nathan's pantry (github.com/nweii/pantry) is a personal collection of modular, self-contained code recipes. The goal is to capture the technique, stripped of its original context, in a form that can be dropped into any future project without modification.

Two directions, and the first is one command:

• Looking something up — he wants to know whether the pantry already has a thing, or wants it pulled into the current project. See Looking something up and stop there.
• Putting something in — he's pointing at code worth keeping. Work through Steps 1–4 below.

Looking something up

The pantry ships its own CLI, so neither direction needs the repo cloned:

bunx github:nweii/pantry list
bunx github:nweii/pantry add <name>

list prints every component with its description. add writes the component's source into the current directory — raw source he owns and edits, not a dependency — and names any packages to install.

Read the list before answering whether something exists, rather than answering from memory: the pantry changes without this skill changing. Where a component matches, name it and offer to add it. Where the match is partial, say what the existing one actually does and let him decide between adapting it and building fresh.

Nothing matching is a normal outcome — say so plainly and build the thing. If what gets built turns out to be worth keeping, that's the other direction, and Step 1 starts below.

What makes a good pantry entry

A pantry entry should be:

• Truly abstracted: no variable names, imports, comments, or usage examples that reference the source project. Someone reading the component cold should have no idea where it came from.
• Self-contained: all logic lives in one file; external dependencies are minimal and explicit
• Opinionated defaults: parameterized just enough for useful variation, with sensible defaults that work out of the box without configuration
• Named for the technique, not the use case (e.g., grain, not background-texture)

Step 1: Understand what to extract

Read the code the user is pointing at. If they haven't pointed at specific code, ask them to identify it.

Then identify:

• The core technique: what is the conceptual pattern, independent of the surrounding application?
• App-specific shell: what parts are wired to this specific app's state, routing, styling system, or data model?
• The stack: what language/framework is this? (React/TSX, plain JS/TS, CSS, Python, etc.)

Step 2: Design the abstraction — discuss before writing

Propose an abstraction plan and get Nathan's approval before writing any files. Cover:

1. Name: a short, lowercase, hyphenated identifier for the technique (this becomes the filename)
2. What gets extracted: the essential mechanism, described in one sentence
3. What gets dropped: app-specific assumptions, hardcoded values that don't generalize, framework boilerplate that isn't part of the technique
4. Props / API surface: what parameters make sense to expose? What should be hardcoded defaults?
5. ABOUTME line: a single sentence describing what the file does — this becomes the registry description. It must be generic; it cannot reference the source project.
6. Dependencies: list any non-trivial imports the extracted code will need

If the source code is deeply entangled with app-specific concerns, surface that tension explicitly. Sometimes the right call is to extract a narrower slice of the technique rather than trying to abstract everything at once.

Wait for approval before proceeding.

Step 3: Write the pantry entry

Finding the pantry repo

Try these in order until one works:

1. Check if a local clone exists by searching common developer paths (~/Developer, ~/code, ~/projects, etc.) for a directory named pantry with a registry.json
2. Use gh repo clone nweii/pantry to clone it to a temporary location
3. Use any available GitHub MCP/plugin tools to write files directly to the repo

Once you have local access, write to src/<name>.<ext> where <ext> matches the stack.

File conventions (all stacks)

• First line: // ABOUTME: <one-sentence description of what this file does> (use # for Python)
• The ABOUTME description must be generic — no references to the source project, app name, or context
• No inline comments that reference the source project or why the code was originally written
• Usage examples in comments must use placeholder/generic names (<MyComponent />, <div className="relative">, etc.)

React/TSX conventions

• Named exports only (no default exports)
• Props interface above the component
• All props optional with sensible defaults
• No dependencies beyond react (peer dep)
• Use useId() (React 18+) for any internally-generated IDs

Non-React conventions

Match the idioms of the target language. For plain TypeScript/JavaScript utilities: export named functions. For CSS: export as a standalone file with a usage comment at the top. For other languages/frameworks, use the standard module export pattern for that ecosystem.

Pantry-specific: the pre-commit hook

The pantry uses a pre-commit hook (scripts/sync.js) that auto-generates registry.json and src/index.ts. Do not edit those files manually — just commit and the hook handles them.

Step 4: Commit and push

From the pantry repo directory:

git add src/<name>.<ext>
git commit -m "add <name>"
git push

The pre-commit hook will stage registry.json and src/index.ts automatically as part of the commit.

Confirm to Nathan that the component is live and available via:

bunx github:nweii/pantry add <name>

Common pitfalls

• Over-abstracting: don't try to make something configurable that will always be the same. The right amount of parameterization is what the technique actually needs.
• Under-abstracting: don't leave in hardcoded values that only make sense in the source app's context.
• Naming for the use case: if you find yourself naming it after what the source app does with it, step back and name it for what the technique is.
• Leaking source context: scan all comments, JSDoc, and example code for any reference to the source project before writing.