The most important thing I can tell you? Your workflow should emerge from your needs, not from copying mine. Take what resonates, ignore the rest, and adapt everything to your context.
Before diving into workflows and tooling, let's talk about the directories that anchor my AI collaboration.
This is a gitignored directory where Claude Code and I brainstorm, plan, and explore ideas without cluttering the repository. Think of it as a scratch space—it lives alongside my codebase but stays local.
I might start drafting an implementation plan here, iterate on architecture decisions, or just work through complex problems without worrying about commit history. It's messy, it's temporary, and that's exactly the point.
While ai-swap/ is ephemeral, docs-ai/ is permanent. This directory contains documentation specifically written for Claude Code to consume:
architecture.md)development-patterns.md)style-guide.md)data-flow.md, state-management.md)The key insight: docs-ai/ gets updated as part of the development cycle, not as an afterthought. When I merge a PR that introduces a new pattern or makes an architectural decision worth documenting, updating docs-ai/ is part of the process.
This version-controlled documentation evolves with the project, giving Claude Code the context it needs to make better suggestions and maintain consistency.
Let me walk you through how I typically approach a feature from start to finish.
1. Think
Before touching Claude Code, I spend time thinking through what I actually want. Mostly the desired outcome, though sometimes I'll have implementation ideas worth suggesting.
2. Explore
I start Claude Code in chat mode and talk through the feature. What are we trying to achieve? What constraints exist? What are the possible approaches?
This is conversation, not instruction. I'm exploring the solution space, not prescribing solutions.
3. Design
Once we've explored options, I switch to plan mode and ask for an implementation plan. If there's a UI component, I'll request ASCII diagrams to visualize the layout.
For non-trivial plans, we break everything down into steps so we can implement them one at a time and change direction if needed. This incremental approach keeps options open.
The plan might stay in ai-swap/ for my reference, or it might become GitHub or Linear issues if I'm working with a team.
4. Review and edit
I read the plan carefully and edit as needed. This often involves a few rounds of iteration with Claude Code alongside manual edits—I'm the one who knows the project's hidden constraints and long-term direction.
5. Branch or worktree
Usually a branch is enough. But when I'm exploring multiple options simultaneously or juggling multiple features, I'll create git worktrees. This gives me clean, isolated environments and makes it easy to switch contexts without stashing changes.
6. Iterate
Now we implement in auto mode. When the requirements are clear and I know the inputs and outputs, I'll use red-green-refactor (TDD). But often I'm exploring, and that's okay—we'll implement, adjust, refactor, and commit frequently.
7. Commit frequently
Lots of small commits create rewind points. If we take a wrong turn, we can easily back up without losing much work. (Claude Code has a /rewind command for this too, but I prefer using git.)
8. Create PR
Once the implementation feels right, I create a pull request.
9. Critical review
This is an area where I'm constantly experimenting. Right now I'm testing a team of specialized agents—each focused on different facets of the review (security, accessibility, performance, test coverage)—rather than a single agent reviewing everything. But here's what doesn't change: I review the code myself. The AI-assisted review surfaces issues and perspectives I might miss, but ultimately I'm responsible for what gets merged, regardless of how the code was generated.
10. Address feedback
I work through the review feedback, making changes where they make sense and pushing back where they don't.
11. Update docs-ai/
If this PR introduced new patterns or made architectural decisions worth documenting, I update docs-ai/ before merging.
12. Merge to main
Ship it!
Did you notice something about that development cycle? I'm intentionally vague about how to implement things.
There are two modes of working with Claude Code: delegation and collaboration. I prefer collaboration, but delegation has its place.
Delegation mode:
Create a pie chart that breaks down the line items of capex and opex, and add radio buttons to toggle between the two charts. When I hover over each pie piece, I want to see the actual dollar amount as a tooltip. Also, there should be callouts showing the percentage of each pie piece.
Collaboration mode:
I want to create visualizations for capex and opex that I can toggle between
The first approach is delegation—I've already decided on the solution and I'm asking Claude Code to implement my specific design. This is perfectly valid when I know exactly what I want and how it should work.
But I usually prefer collaboration. The second approach states the goal and invites Claude Code to explore the solution space with me. Maybe a pie chart isn't the best visualization. Maybe radio buttons aren't the most intuitive toggle. By focusing on the outcome rather than the implementation, we can discover options I might not have considered.
Choose delegation when you know the solution. Choose collaboration when you want to explore possibilities.
I mentioned red-green-refactor earlier, but that's not always the right approach. Let me explain when I use which strategy.
This works well when:
With Claude Code, TDD becomes incredibly efficient. Write a failing test, let Claude Code implement it, verify it passes, refactor if needed. Repeat.
But sometimes I don't want TDD. I use exploratory implementation when:
This isn't sloppiness—it's intentionality about the development approach. Sometimes the best way forward is to try something, see how it feels, and adjust.
Now let's talk about the tools I've built around Claude Code. These fall into three categories, each serving a distinct purpose.
I use slash commands for workflows that need LLM decision-making—tasks that would be hard to script because they require judgment calls at each step.
My most-used commands:
Notice what these have in common: they're all workflows that require making decisions based on context. A bash script could approximate these, but it would need complex branching logic to handle all the cases. With a slash command, Claude Code makes those judgment calls.
You could also use slash commands as a prompt library (shortcuts to frequently-used prompts), though I don't primarily use them that way.
MCP servers give Claude Code access to tools it can't reach via bash commands alone.
Examples of what I use:
My strategy: only enable MCP servers when I need them. I might keep them configured in my session but disabled. This prevents context bloat (wasting Claude Code's token budget on unused tool descriptions) while maintaining quick access when I do need them.
(Shameless plug: I built ccmcp to make managing MCP server configurations easier. Check it out if you find yourself juggling multiple MCP setups.)
Here's where my thinking shifted: I initially thought of agents as task delegation tools. But the real value represents a fundamental shift in how I think about AI collaboration—agents aren't just about saving time, they're about saving context.
Example: docs-lookup agent
Instead of the main Claude Code instance reading through all my docs-ai/ files (consuming valuable context tokens), I have an agent that specializes in that task. The orchestrator asks the agent a question, the agent searches the docs and returns an answer, and the orchestrator continues with its work.
The agent has its own context window, which means the orchestrator's context stays focused on the implementation task at hand.
Skills are a brand new primitive in Claude Code, and I'm still figuring out how they fit into my workflow. I'm experimenting with them, but haven't yet found their natural place in my development process the way I have with slash commands, MCP servers, and agents.
Claude Code's token budget is generous, but it's not infinite. My strategy is minimal but ready:
docs-ai/ focused and conciseWhy does this matter? Because a cleaner context means better responses. When Claude Code isn't wading through dozens of tool descriptions it won't use, it can focus on the task at hand.
Since we're talking about practical workflows, let me touch on how this all integrates with git:
This isn't revolutionary—it's just being intentional about how AI assistance fits into a solid development workflow.
Here's the thing: this workflow evolved through lots of trial and error. I tried things, kept what worked, and discarded what didn't. Your context is different than mine. Your projects have different constraints. Your thinking style might prefer different approaches.
Start with one or two ideas from this article that resonate with you. Try them out. Adapt them. Break them if they don't work. Add your own innovations.
The tools are flexible. Claude Code supports slash commands, MCP servers, agents, different modes—but there's no single "right" way to use them. The best workflow is the one you'll actually use consistently.
Some questions to guide your experimentation:
Your answers will lead you to different solutions than mine. And that's exactly how it should be.
The goal isn't to copy my workflow. The goal is to find the workflow that makes you more effective, more creative, and maybe even more excited about the work you're doing.
Now go experiment.
]]>unified ecosystem and custom plugins.]]>My goal was to generate both RSS and Atom feeds that accurately represented the site's articles, which are written in MDX. This meant addressing several key requirements:
import statements) and dynamic React components that wouldn't work in a feed.<content:encoded> or <content>) was clean, valid, and accurately reflected the article structure.Astro provides an official @astrojs/rss package for generating feeds. Initially, this seemed like the obvious solution to use.
// Example using @astrojs/rss (Conceptual)
import rss from "@astrojs/rss";
import { getCollection } from "astro:content";
import sanitizeHtml from "sanitize-html";
import MarkdownIt from "markdown-it";
const parser = new MarkdownIt();
export async function GET(context) {
const posts = await getCollection("blog");
return rss({
// ... feed options
items: posts.map((post) => ({
// ... item options
content: sanitizeHtml(parser.render(post.body)), // Problematic for MDX
})),
});
}
However, this approach quickly proved insufficient for several reasons:
@astrojs/rss relies on tools like markdown-it and sanitize-html, which are designed for standard Markdown (.md), not MDX (.mdx). These tools don't understand JSX or imports/components embedded within the content. My attempts to render MDX to HTML using Astro's internal tools specifically for the feed proved complex and unreliable.<mark> tags used for highlighting) correctly for feed output.unified EcosystemTo gain the necessary control over the MDX-to-HTML transformation pipeline specifically for feeds, I turned to the unified ecosystem. This powerful framework processes content through Abstract Syntax Trees (ASTs), giving precise control at each transformation stage:
remark: For parsing and transforming Markdown/MDX into a Markdown AST (MDAST).rehype: For parsing and transforming HTML into an HTML AST (HAST).For structuring and generating the final XML output, I chose the feed library. It offers a clean and effective API for creating both RSS 2.0 and Atom 1.0 feeds once the content is properly prepared.
The core task was creating a function, mdxToHtml, to convert raw MDX article content and the description into clean, valid, feed-friendly HTML. Let's look at how this pipeline works:
import type { Root as HastRoot, RootContent } from "hast";
import type { Root as MdastRoot } from "mdast";
import type { Plugin } from "unified";
import { Buffer } from "node:buffer";
import minifyHtml from "@minify-html/node";
import rehypeStringify from "rehype-stringify";
import remarkMarkers from "remark-flexible-markers";
import remarkMdx from "remark-mdx";
import remarkParse from "remark-parse";
import remarkRehype from "remark-rehype";
import { unified } from "unified";
type UrlLike = URL | string;
export async function mdxToHtml(
mdxContent: string,
site: UrlLike,
): Promise<string> {
const result = await unified()
.use(remarkParse) // 1. Parse Markdown/MDX text -> MDAST
.use(remarkMdx) // 2. Handle MDX specific syntax (JSX, imports/exports)
.use(remarkMarkers, { markerClassName: () => [] }) // 3. Handle <mark> correctly
.use(remarkRemoveToc) // 4. Custom: Remove "Table of Contents" headings
.use(remarkRemoveImports) // 5. Custom: Remove JS import/export statements
.use(remarkRehype) // 6. Bridge: Convert MDAST -> HAST
.use(rehypeAbsoluteUrls, site) // 7. Custom: Convert relative URLs -> absolute
.use(rehypeStringify) // 8. Convert HAST -> HTML string
.process(mdxContent);
// 9. Minify the HTML safely
return minifyHtml
.minify(Buffer.from(result.toString()), { keep_closing_tags: true })
.toString();
}
// Custom remark plugin to remove JS imports/exports
const remarkRemoveImports: Plugin<[], MdastRoot> = () => {
return (tree) => {
tree.children = tree.children.filter((node) => node.type !== "mdxjsEsm");
return tree;
};
};
// Custom remark plugin to remove "Table of Contents" headings
const remarkRemoveToc: Plugin<[], MdastRoot> = () => {
// ... (implementation filters out h2 nodes matching "Table of Contents")
return (tree: MdastRoot) => {
tree.children = tree.children.filter((node) => {
if (node.type === "heading" && node.depth === 2) {
const text = node.children
.filter((child) => child.type === "text")
.map((child) => child.value)
.join("")
.trim();
const tocRegex = /(table[ -]of[ -])?contents?|toc/i;
return !tocRegex.test(text);
}
return true;
});
return tree;
};
};
// Custom rehype plugin to make URLs absolute
const rehypeAbsoluteUrls: Plugin<[UrlLike], HastRoot> = (baseUrl) => {
// ... (implementation traverses HAST, updates href/src)
return (tree) => {
const visit = (node: RootContent | HastRoot) => {
if (node.type === "element") {
if (node.tagName === "a" && node.properties?.href) {
node.properties.href = createUrl(
node.properties.href as string,
baseUrl,
);
}
// Note: A complete implementation would also handle `img[src]`, etc.
}
if ("children" in node) {
node.children.forEach(visit);
}
};
visit(tree);
return tree;
};
};
// Helper to create absolute URLs
export function createUrl(path: string, baseUrl: UrlLike): string | null {
try {
const fullUrl = new URL(path, baseUrl);
return fullUrl.href;
} catch (error) {
console.error("Invalid path or base URL:", error);
return null;
}
}
Key Plugins and Customizations:
remark-parse & remark-mdx: Essential for correctly parsing the MDX source into an Abstract Syntax Tree (MDAST).remark-flexible-markers: Allows using ==highlighted text== syntax, which is correctly processed, unlike <mark> elements that remark-mdx can mistake for JSX components.remarkRemoveToc (Custom Plugin): Removes the auto-generated "Table of Contents" often included in articles, which is unnecessary and potentially confusing in a feed item.remarkRemoveImports (Custom Plugin): Strips out MDX import and export statements (mdxjsEsm nodes in the AST), which are invalid and unnecessary in feed content.remark-rehype: Converts the processed Markdown AST (MDAST) into an HTML AST (HAST).rehypeAbsoluteUrls (Custom Plugin): Traverses the HAST and uses the site's base URL to convert relative href attributes in <a> tags to absolute URLs—crucial for links to work correctly when viewed in feed readers.rehype-stringify: Serializes the final HAST back into an HTML string.Even with the powerful unified ecosystem, I encountered several challenges that we need to solve:
remark-smartypants for typographic enhancements (curly quotes, em-dashes) resulted in mangled characters in the final feed output. Unable to properly debug the encoding conflicts, I omitted remark-smartypants from the feed generation pipeline to ensure feed validity.rehype-preset-minify to reduce HTML size. However, its default settings proved too aggressive, sometimes removing optional closing tags (like </p>) which, while valid in browsers, could break stricter XML parsers used by some feed readers. Switching to @minify-html/node with the keep_closing_tags: true option provided safe and effective minification.export async function mdxToHtml(
mdxContent: string,
site: UrlLike,
): Promise<string> {
const result = await unified()
// ... remark/rehype pipeline
.use(rehypeStringify)
.process(mdxContent);
return minifyHtml
.minify(Buffer.from(result.toString()), { keep_closing_tags: true })
.toString();
}
With the mdxToHtml utility handling the complex content transformation, the final feed generation logic became much cleaner and more maintainable.
The generateFeed function in feeds/index.ts orchestrates the process:
import type { APIContext } from "astro";
import type { Author, FeedOptions } from "feed";
import { getCollection } from "astro:content";
import { Feed } from "feed"; // Use the 'feed' library
import { createUrl, mdxToHtml } from "./utils"; // Import our custom utils
// ... Author interface
export async function generateFeed(context: APIContext): Promise<Feed> {
const site = context.site!.toString();
const author: SiteAuthor = {
/* ... author details */
};
const feed = createFeedInstance(site, author); // Initialize Feed object
await addArticlesToFeed(feed, site, author); // Add processed articles
return feed;
}
function createFeedInstance(site: string, author: SiteAuthor): Feed {
const feedOptions: FeedOptions = {
/* ... feed metadata */
};
return new Feed(feedOptions);
}
async function addArticlesToFeed(
feed: Feed,
site: string,
author: SiteAuthor,
): Promise<void> {
const articles = (await getCollection("articles")).sort(
(a, b) => b.data.published.valueOf() - a.data.published.valueOf(),
);
for (const article of articles) {
const link = createUrl(`/articles/${article.slug}`, site) as string;
feed.addItem({
title: article.data.title,
id: link,
link,
published: article.data.published,
date: article.data.updated || article.data.published, // Use updated if available
author: [author],
// Process description and body using our custom mdxToHtml
description: await mdxToHtml(article.data.summary, site),
content: await mdxToHtml(article.body || "", site),
});
}
}
Finally, simple Astro API endpoints (pages/atom.xml.ts and pages/rss.xml.ts) call generateFeed and use the appropriate methods from the feed library to return the XML:
import type { APIContext } from "astro";
import { generateFeed } from "@/data/feeds";
export async function GET(context: APIContext) {
const feed = await generateFeed(context);
return new Response(feed.atom1(), {
headers: { "Content-Type": "application/atom+xml" },
});
}
import type { APIContext } from "astro";
import { generateFeed } from "@/data/feeds";
export async function GET(context: APIContext) {
const feed = await generateFeed(context);
return new Response(feed.rss2(), {
headers: { "Content-Type": "application/xml" },
});
}
While Astro's standard RSS package works well for simpler sites using standard Markdown, the complexities of MDX content required a more tailored approach. The unified toolchain, combined with custom remark and rehype plugins, provided the granular control needed to:
<mark> tags)The primary job of our feed generation pipeline is to transform complex MDX content into clean, valid HTML that works reliably in feed readers while preserving the essence of our articles.
Pairing this custom pipeline with the robust feed library resulted in valid, clean, and content-rich Atom and RSS feeds that work reliably across feed readers. This solution successfully addressed one of the key challenges in my migration from Gatsby to Astro, ensuring content syndication remained a first-class feature of the site.
<datalist> element can create simple yet powerful combo boxes with dynamic suggestions.]]>For a search feature, we're storing the 100 most recently used ("MRU") search terms. In the search box, we want to auto suggest based on the MRU terms, but not restrict the input to just those terms.
<datalist>Until recently, I didn't know about the <datalist> element until I read Peter Bengtsson's article. According to MDN:
The HTML
<datalist>element contains a set of<option>elements that represent the permissible or recommended options available to choose from within other controls.
Sounds exactly like what we need.
Let's start with a basic implementation:
const [term, setTerm] = React.useState("");
const [mruTerms, setMruTerms] = React.useState([]);
React.useEffect(() => {
fetch("https://random-word-api.herokuapp.com/word?number=100")
.then((response) => response.json())
.then((data) => setMruTerms(data));
}, []);
return (
<main>
<form
autoComplete="off"
onSubmit={(e) => {
e.preventDefault();
const term = e.currentTarget.term.value;
if (term.trim() !== "") {
setTerm(term.trim());
setMruTerms([...new Set([term.trim(), ...mruTerms])].slice(0, 100));
}
}}
>
<label htmlFor="term">Search term</label>
<input list="mru-terms" id="term" name="term" />
<datalist id="mru-terms" key={term}>
{mruTerms.map((term) => (
<option key={term} value={term} />
))}
</datalist>
<button>Search</button>
</form>
<p>Submitted term: {term}</p>
</main>
);
term), and the list of MRU terms (mruTerms).mruTerms when the component is first rendered. In a real app, this can be fetched from a service, upstream app state, or localStorage.<option> elements of the <datalist> are generated from mruTerms. Notice the entire <datalist> component is replaced every time term changes since we bind it to the key prop. mruTerms update cycle to changes in term, as a new array is generated whenever term changes.term and mruTerms are updated (and persisted in a real app).With very little code, our autosuggest feature already works pretty well. Let's refactor our code so all context data is handled within a single object:
const useInitialize = () => {
const [{ term, mruTerms }, dispatch] = React.useReducer(reducer, initialData);
React.useEffect(() => {
fetch("https://random-word-api.herokuapp.com/word?number=100")
.then((response) => response.json())
.then((payload) => dispatch({ type: "init", payload }));
}, []);
const actions = {
updateTerm: (payload) => dispatch({ type: "updateTerm", payload }),
};
return { term, mruTerms, actions };
};
const initialData = { term: "", mruTerms: [] };
const reducer = (data, { type, payload }) => {
const { term, mruTerms } = data;
switch (type) {
case "init":
return { term, mruTerms: payload };
case "updateTerm":
if (payload.trim() === "") return data;
return {
term: payload.trim(),
mruTerms: [...new Set([payload.trim(), ...mruTerms])].slice(0, 100),
};
default:
return data;
}
};
useStates, we consolidate into a single useReducer.For our purposes, the search terms "ice cream", "Ice Cream", and " ICE CREAM " are all considered equivalents. We want to store the last version used (minus the surrounding spaces) without duplicates in mruTerms.
Let's create a couple of helper functions first:
const addMruTerm = (mruTerms, term) =>
[term, ...mruTerms]
.reduce(
(unique, item) =>
unique.some((e) => trimLower(e) === trimLower(item))
? unique
: [...unique, item.trim()],
[],
)
.slice(0, 100);
const trimLower = (term) => term.trim().toLowerCase();
Then we change how we update mruTerms in the reducer:
mruTerms: addMruTerm(mruTerms, payload);
Our autosuggest feature is starting to work nicely. You'll notice that Chrome and Firefox sort suggestions in the mruTerms array order. I think a better experience would be to sort by three major sections. For example, if the search term is "cr":
Within each section, we can further sort alphabetically.
In order to accomplish this, we need to update <datalist> as we type the search term. This means we need to keep track of a couple of additional pieces of context data: draft and sortedMruTerms:
const initialData = { draft: "", term: "", mruTerms: [], sortedMruTerms: [] };
We also add another helper function sortMruTerms, and adjust the reducer accordingly:
const reducer = (data, { type, payload }) => {
const { draft, mruTerms } = data;
switch (type) {
case "init":
return { ...data, mruTerms: payload, sortedMruTerms: payload };
case "updateDraft":
return {
...data,
draft: payload,
sortedMruTerms: sortMruTerms(mruTerms, payload),
};
case "updateTerm":
if (draft.trim() === "") return data;
return {
...data,
term: draft.trim(),
mruTerms: addMruTerm(mruTerms, draft),
};
default:
return data;
}
};
const sortMruTerms = (mruTerms, term) => {
const partial = trimLower(term);
if (partial === "") return mruTerms;
let terms = [...mruTerms];
let sorted = [];
sortFilters(partial).forEach((filter) => {
sorted = [...sorted, ...terms.filter(filter).sort()];
terms = terms.filter((t) => !sorted.includes(t));
});
return sorted;
};
const sortFilters = (partial) => [
(t) => trimLower(t).startsWith(partial),
(t) => RegExp(`\\b${partial}`, "i").test(t),
(t) => RegExp(partial, "i").test(t),
];
sortedMruTerms.updateDraft, which is called each time the search term changes.updateTerm no longer requires a payload, since we can calculate new context values based on draft.Lastly, some minor adjustments in the JSX and we're done:
<input
value={draft}
onChange={(e) => actions.updateDraft(e.currentTarget.value)}
list="mru-terms"
id="term"
name="term"
/>
<datalist id="mru-terms" key={draft}>
{sortedMruTerms.map((term) => (
<option key={term} value={term} />
))}
</datalist>
<input> into a controlled component, binding its value to draft and event handling to updateDraft.<datalist> is now replaced every time draft changes, and its values come from sortedMruTerms.As you can see, by abstracting the logic out from the component, we can easily tweak the behavior while minimizing changes to the component itself. We can also test the utility functions independently. Composition FTW 🙌.
Can you think of other improvements to this feature? Fork one of the CodeSandboxes and see what you come up with.
Weston Thayer and I had a discussion about accessibility for the datalist element. He pointed out the following issues and resources for further investigation.
There are potentially some accessibility issues that may prevent you from using this technique, specifically screen readers do not convey datalist changes. This may be acceptable in the case of auto suggest, since the user is free to enter whatever they like—the auto suggest feature is a nice-to-have.
For a React-specific alternative, check out Reach UI's Combobox. Also read 24 Accessibility's "<select> Your Poison" article for an in-depth discussion of why this is a hard-to-solve problem.
It occurred to me that this technique can be used in situations where you want to normalize data as much as possible, while still allowing the user to freely enter anything they like.
In a recent article, I talked about the issue of HR asking for personal pronouns. HR would like the data to be as consistent as possible, but the right thing to do is to allow people to enter whatever they want. Here's a possible implementation that fulfills both requirements:
<datalist> element first.Another person in the channel, who is part of the community impacted by this issue, suggested a couple of changes:
Remove "preferred" from the label
Affected person: Remove the word preferred from the "Preferred Personal Pronoun" label, since preference implies that it can be ignored.
HR manager: "Hmm, I didn't pick up on it that way," but will look into removing the word from the label.
Possible intention: Trying to be more inclusive.
Unintended outcome: Your offhand remark invalidates my feelings and experiences. It makes me feel like my gender identity is something I have to justify, when most people are moving through life without having to even think about it.
Use a text field instead of select-one
Affected person: Use a text field instead of select-one to allow people to put whatever they want as their pronoun.
HR manager: Will look into adding an "other" selection with a text box.
Possible intention: Good point—there, problem solved.
Unintended outcome: Other? Can I feel even more, well, othered?
Of course, I don't know exactly how either person felt. The situation is far more nuanced than can be neatly summarized, but hopefully, the point is clear: words matter.
It may seem like an exaggeration when you're part of the privileged group, but interactions like this can make a person feel further marginalized, dehumanized, and even attacked, regardless of the best intentions.
Another trope reinforced by this interaction is that the affected person is, once again, in the position to do the educating, rather than the privileged person doing their own research and critical thinking. Regardless of intention, it makes the effort seem meaningless and the outcome careless.
In a private follow-up conversation with the affected person, I asked for feedback on my own interactions with her. She pointed out that during the hiring process, the company doesn't formally ask candidates for their pronouns, and that I asked for her pronouns well after an offer was extended. She made a couple of suggestions:
By not taking these simple steps, I reinforced harmful gender normative behaviors. I certainly never asked for pronouns from other people we've interviewed or hired. Why is that?
From her perspective, these are the mistakes I made:
I had to ask myself, in my entire life, how many times have I been asked for my pronouns in a way that questioned my gender? How many times have I had to struggle with myself about what my pronouns are? Exactly zero. By assuming my experience is the normal experience, I actively caused harm to another person that I care about.
She suggested Natalie Reed's excellent The Null HypotheCis article as a more in-depth exploration of reframing the gender question. I encourage you to take the time and space to read, reflect, and gain a bit more empathy.
You may think, why make a mountain out of a molehill? Wasn't it great when things were simple and clear-cut? The fact is that things are not, and never were, simple and clear-cut. They were only conveniently simple and clear-cut when you choose to go along, perhaps even a little uncomfortably, with the side that wields the power.
Most of us wield power of some kind, even if we belong to a marginalized group. None of us can do the right thing all the time. I mess up, and you'll mess up too. The key is to listen, recognize, acknowledge, educate, and activate.
Keep learning how to accept critical feedback graciously, even if it makes you feel bad. Keep learning how to spot injustices, big or small. Keep learning about injustices and expanding your own capacity to make meaningful changes to correct them.
One month after the Slack exchange, the select-one field with three choices is still labeled "Preferred Personal Pronoun" in the HR system.
After another misstep in changing the pronoun field as a response to this article, and an impassioned follow-up by the affected person in the Slack channel, the HR system now has a text field labeled "Personal Pronoun."
One. Step. At. A. Time.
]]>useReducer and basic reducer patternsSo far in parts 1 and 2 of this series, we've learned that:
In part 3, we'll look at the most common pattern for reducers and actions you'll find in documentation and online examples, and we'll model a state chart using a reducer.
useReducer PatternMost React.useReducer examples you encounter dispatch actions resembling { type, payload }. Their reducer functions typically consist of a switch statement that matches on type and uses payload to calculate the next state.
Remember, the reducer signature is (currentState, action) => nextState. A switch-statement-based reducer looks like this:
const reducer = (count, { type, payload }) => {
switch (type) {
case "add":
return count + payload;
case "reset":
return initialValue;
default:
throw new Error();
}
};
To trigger this reducer, there are two possible actions we can dispatch.
dispatch({ type: "add", payload: 5 });
dispatch({ type: "reset" });
We can encapsulate these two possibilities with bound action creators:
const add = (payload) => dispatch({ type: "add", payload });
const reset = () => dispatch({ type: "reset" });
Action creators are optional; you can dispatch actions directly where needed instead. However, they offer a cleaner interface for the hook's user by hiding the reducer's implementation details.
The complete useReducer definition looks like this:
const initialValue = 0;
const reducer = (count, { type, payload }) => {
switch (type) {
case "add":
return count + payload;
case "reset":
return initialValue;
default:
throw new Error();
}
};
const [count, dispatch] = React.useReducer(reducer, initialValue);
const add = (payload) => dispatch({ type: "add", payload });
const reset = () => dispatch({ type: "reset" });
Our hook interface is now count, plus the add() and reset() functions.
So far, we've explored several reducer and action patterns, but we haven't discussed why we use useReducer. In fact, you can express the previous example more clearly using a useState hook:
const initialValue = 0;
const [count, setCount] = React.useState(initialValue);
const add = (value) => setCount(count + value);
const reset = () => setCount(initialValue);
useState is optimized for managing a single state value. This implies that useReducer excels when we need to manage multiple related state values.
What if we want to add an undo function to retrieve previous counts? One way to do this is to track the count history. Instead of only tracking the latest count, our state object now looks like this:
const initialState = { count: 0, history: [] };
We update the reducer with the following changes:
count to the history stack.case to handle the undo action.const reducer = (state, { type, payload }) => {
const { count, history } = state;
switch (type) {
case "add":
if (payload === 0) return state;
return { count: count + payload, history: [...history, count] };
case "reset":
return initialState;
case "undo":
if (history.length === 0) return state;
const lastCount = [...history].pop();
return { count: lastCount, history: history.slice(0, -1) };
default:
throw new Error();
}
};
Lastly, we add another bound action creator to handle undo():
const undo = () => dispatch({ type: "undo" });
Putting it all together:
const initialState = { count: 0, history: [] };
const reducer = (state, { type, payload }) => {
const { count, history } = state;
switch (type) {
case "add":
if (payload === 0) return state;
return { count: count + payload, history: [...history, count] };
case "reset":
return initialState;
case "undo":
if (history.length === 0) return state;
const lastCount = [...history].pop();
return { count: lastCount, history: history.slice(0, -1) };
default:
throw new Error();
}
};
const [{ count, history }, dispatch] = React.useReducer(reducer, initialState);
const add = (payload) => dispatch({ type: "add", payload });
const reset = () => dispatch({ type: "reset" });
const undo = () => dispatch({ type: "undo" });
We see that count and history are tightly coupled. When we add a value, we update count and add the previous count to the history stack. When we undo, we replace count by popping the last item from the history stack.
Did you know you can nest a switch statement inside the case clause of another switch statement? Using this technique, you can implement sophisticated logic with the useReducer hook, especially when combined with useEffect.
Let's create a seemingly simple form with a single input and a couple of buttons:
[A-Za-z] charactersSimple, right? That's often how forms start, but complexity arises when you consider:
How can you satisfy all these requirements? Should you try to capture all the logic imperatively? Should you use one of the many React form libraries? I believe state charts offer a great way to declaratively satisfy all these requirements.
Our state chart has four states—editing, submitting, resolved, rejected—with clear transitions defined among the states, e.g. we transition from editing to submitting state by performing the submit action.
First, let's define what our useReducer hook state looks like. Note that the hook's state is distinct from the state chart's state. Our hook state looks like this:
const initialState = {
value: "editing",
context: {
previousValue: "",
value: "",
isValid: true,
submitAllowed: false,
isSuccessful: undefined,
},
};
The value property holds our state chart's current state. We also have a separate context property that tracks the extended state.
const reducer = (state, { type, payload } = {}) => {
const { value, context } = state;
// Top-level switch based on the state chart's current state (state.value)
switch (value) {
case "editing":
// Nested switch based on the action type (transition)
switch (type) {
case "change":
const isValid = /^[A-Za-z]*$/.test(payload);
const submitAllowed = isValid && context.previousValue !== payload;
return {
value,
context: { ...context, value: payload, isValid, submitAllowed },
};
case "reset":
return {
value,
context: {
...context,
value: context.previousValue,
isValid: true,
submitAllowed: false,
},
};
case "submit":
if (context.submitAllowed) return { value: "submitting", context };
return state;
default:
return state;
}
case "submitting":
switch (type) {
case "resolve":
return { value: "resolved", context };
case "reject":
return { value: "rejected", context };
default:
return state;
}
case "resolved":
return {
value: "editing",
context: {
...context,
previousValue: context.value,
isSuccessful: true,
submitAllowed: false,
},
};
case "rejected":
return {
value: "editing",
context: {
...context,
isSuccessful: false,
},
};
default:
return state;
}
};
Notice the top-level switch statement evaluates the state.value (the state chart's current state). For the editing and submitting states, we use a nested switch based on action.type (representing the state chart transition). Why is this done? This guarantees that, for example, the submit transition is only valid when the state chart is in the editing state. Practically, this means that if the form is already in the submitting state, it cannot be submitted again, regardless of user actions (solving the multiple button click issue, even if the submit button isn't explicitly disabled).
If you compare the code to the diagram, you'll see that each case clause corresponds to a transition—seven transitions mean seven case clauses that return the next state.
Notice that the default clauses always return the original state unmodified. This aligns with how state machines typically work: attempting an invalid transition leaves the state unchanged.
Looking at each case clause, you'll notice we're performing a couple of tasks:
state.value.state.context as appropriate for a given transition.const [state, dispatch] = React.useReducer(reducer, initialState);
const transitions = {
change: (payload) => dispatch({ type: "change", payload }),
reset: () => dispatch({ type: "reset" }),
submit: () => dispatch({ type: "submit" }),
};
To trigger transitions, we use the dispatch() function returned by the useReducer hook. Transitions can be triggered manually (e.g., by a user clicking a button) via event handlers, or automatically (e.g., when state changes) via useEffect.
Discussing complex state chart topics in depth is beyond the scope of this article. What we're demonstrating here is that you can model fairly complex systems using reducers, if somewhat awkwardly.
If you're curious about state charts, I highly recommend checking out XState.
React.useReducer when you need to manage multiple tightly-coupled state values.useReducer hook more user-friendly by providing action creators.As demonstrated in this series, useReducer is a hook pattern capable of solving a wide variety of problems, from simple to moderately complex. Now that the potentially intimidating aspect of the pattern (reducers) is hopefully less daunting, I encourage you to use useReducer more frequently and creatively.
useReducer and basic reducer patternsIn part 1, we looked at reducer patterns that didn't use any parameters or only used the current state to calculate the next state. We also learned that the primary job of a reducer is to produce a new state.
Let's continue exploring other reducer patterns.
actionRemember that (currentState, action) => newState is the complete reducer signature. In the patterns we've explored so far, we haven't used the action parameter. We know the hook automatically supplies the current state to the reducer, but how does a reducer receive its action parameter? It receives the action parameter via the dispatch function returned by the hook: [state, dispatch] = useReducer(reducer). The dispatch function takes a single optional parameter: dispatch(action).
currentState and action ParametersLet's look at an example where we use both parameters with the reducer function.
const reducer = (count, valueToAdd) => count + valueToAdd;
const [count, addToCount] = React.useReducer(reducer, 0);
return (
<main>
<div>Count: {count}</div>
<form
onSubmit={(e) => {
e.preventDefault();
const valueToAdd = Number(e.currentTarget.numberToAdd.value);
addToCount(valueToAdd);
}}
>
<label>
Add to count:{" "}
<input
name="numberToAdd"
type="number"
defaultValue={1}
style={{ width: "4em" }}
/>
</label>
<button>Add</button>
</form>
</main>
);
What's happening? When we submit the form, we dispatch (addToCount) an action (the value from <input name="numberToAdd">). The reducer takes the current state (count) and the action (valueToAdd) to produce a new state (count + valueToAdd).
Many examples of actions you've seen use the shape { type, payload }. While this is a common convention, an action can be anything you like (including undefined). In this example, an action is simply a number.
action Param OnlyJust like how we can choose to only use the currentState param in a reducer, we can choose to only use the action parameter.
const reducer = (_, newCount) => newCount;
const [count, setCount] = React.useReducer(reducer, 0);
return (
<main>
<div>Count: {count}</div>
<form
onSubmit={(e) => {
e.preventDefault();
const valueToAdd = Number(e.currentTarget.numberToAdd.value);
setCount(count + valueToAdd);
}}
>
...
</form>
</main>
);
By switching up a few lines, our reducer now only relies on the action (newCount) to calculate its new state.
🤔 Wait a minute, that looks a lot like React.useState.
useStateReplace
const reducer = (_, newCount) => newCount;
const [count, setCount] = React.useReducer(reducer, 0);
with
const reducer = (_, newState) => newState;
const useState = (initialState) => React.useReducer(reducer, initialState);
const [count, setCount] = useState(0);
We have ourselves a simple useState! You can see that React.useState is syntactic sugar for React.useReducer, simplifying the common use case of updating a single state value. A complete re-implementation of useState is a few more lines of code. See Kent C. Dodd's "How to implement useState with useReducer" if you're interested in an in-depth explanation.
We have a user profile form that allows users to change each value in the state object.
One elegant solution is to use the object spread syntax to create the next state.
const reducer = (info, updates) => ({ ...info, ...updates });
const initialValue = {
name: "Pat Doe",
twitter: "@pdough",
email: "pat@pdough.me",
website: "https://pdough.me",
};
const [info, update] = React.useReducer(reducer, initialValue);
return (
<main>
<pre>{JSON.stringify(info, null, 2)}</pre>
<form>
{Object.entries(info).map(([key, value]) => (
<label key={key} style={{ display: "block" }}>
{key}:{" "}
<input
value={value}
onChange={(e) => update({ [key]: e.currentTarget.value })}
/>
</label>
))}
</form>
</main>
);
Wait, say what? 🤔
const reducer = (count, action) => action(count);
const [count, dispatch] = React.useReducer(reducer, 0);
const add = (value) => dispatch((count) => count + value);
const subtract = (value) => dispatch((count) => count - value);
return (
<main>
<div>Count: {count}</div>
<form>
<label>
Change count by:{" "}
<input
name="modifier"
type="number"
defaultValue={1}
style={{ width: "4em" }}
/>
</label>
<button
type="button"
onClick={(e) => add(Number(e.currentTarget.form.modifier.value))}
>
Add
</button>
<button
type="button"
onClick={(e) => subtract(Number(e.currentTarget.form.modifier.value))}
>
Subtract
</button>
</form>
</main>
);
Yup, as stated earlier, an action can be anything you like. In this example, we're dispatching callback functions! 🤯
undefined, a value, an object, or even a function.action parameter is the value shared between the dispatch() and reducer() functions, acting as their private contract.You can implement a reducer in any way you like, as long as it fulfills the contract of ([currentState], [action]) => newState. You have complete freedom in deciding what an action looks like, and how you want to calculate the new state.
We've explored different ways of writing the reducer function, and we haven't even come across the familiar switch statement yet. Don't worry, we'll get to that in part 3.
useReducer patterns for writing clear and effective reducers, starting with no-param and current state-only approaches.]]>useReducer in favor of multiple useState calls. I suspect this stems partly from the simplicity of the useState API and partly from an assumed complexity due to its association with Redux. In practice, useReducer has much more in common with useState than Redux.useState and useReducerThe useState API has two parts: the state and the state setter. When you want to update the state, you replace it using the state setter.
The useReducer API has three parts: the state, an action dispatcher, and a reducer to produce the new state.
When you want to update the state:
useReducer takes care of steps 2 and 4. You're responsible for steps 1 and 3.
These are all valid signatures for reducer functions:
(currentState, dispachedAction) => newState
(currentState) => newState
() => newState
As you can see, the primary job of a reducer is to produce a new state, optionally taking into account the current state and the dispatched action.
The signature of useReducer is:
const [state, dispatch] = useReducer(reducer, initialState);
You pass in a reducer function (and optionally an initialState) to set up a useReducer hook. What you get back is a read-only state and a dispatch function which you'll use to trigger the reducer.
This is one of the key differences when compared to useState—a useReducer hook computes the next state internally using a reducer function, while a useState hook relies entirely on external calculations for its next state.
For the rest of the article, we'll focus on different reducer (a.k.a. "new state" calculator) implementation patterns.
() => newState
The primary job of a reducer is to return a new state. In its simplest form, a reducer doesn't even need to accept any parameters.
const reducer = () => new Date();
const [date, update] = React.useReducer(reducer, new Date());
return (
<main>
<div>
Now: {date.toLocaleDateString()} {date.toLocaleTimeString()}
</div>
<button onClick={update}>Update</button>
</main>
);
The names state, dispatch, and reducer are conceptual. In practice, you can name them anything you like. In this example, they are date (state), update (dispatch), and reducer.
Notice that we invoke update() without passing any parameters. The dispatch function signals the hook to run the reducer function; it's up to you whether you need to send an action along with the signal. In this case, the hook actually runs reducer(currentState, undefined).
That's right. In JavaScript, just because you pass parameters to a function, doesn't mean it needs to accept them.
const sayHi = () => "hi";
const result = sayHi(1, 2, 3);
// result === "hi"
(currentState) => newState
This form of reducer is useful when you need the current state to calculate the next state.
const reducer = (count) => count + 1;
const [count, addOne] = React.useReducer(reducer, 0);
return (
<main>
<div>{count}</div>
<button onClick={addOne}>Add 1</button>
</main>
);
Once again, the dispatch function, addOne(), doesn't need to pass an action to reducer—the reducer is capable of computing the next state entirely based on the current state.
([currentState], [dispatchedAction]).dispatch() signals the useReducer hook to invoke the reducer.😅 Whew, let's take a break for now. In part 2, we'll explore reducers that use actions, as well as reducers that use both actions and the current state.
]]>toLocaleDateString()—no extra libraries required!]]>I'm displaying a date with each article on this site. The source of the date is an ISO date string, which looks like
While ISO format is excellent for data exchange, it's not user-friendly for display. Let's localize it instead.
const isoDateString = "2020-07-10T14:16:40.463Z";
const date = new Date(isoDateString);
const locale = typeof window === "undefined" ? "en" : navigator.language;
If we're not in a browser environment (like during SSR), default to English.
const formattedDate = date.toLocaleDateString(locale, {
year: "numeric",
month: "long",
day: "numeric",
});
See the Intl.DateTimeFormat() constructor for details on the parameters.
It's a bit more code than using one of the libraries, but your users will thank you for the smaller bundle size.
OK, they probably won't—but you'll have the satisfaction of knowing you've done your part to improve their experience.
]]>Suppose you have a JavaScript object received from a source (e.g., retrieved from an API):
const restaurant = {
name: "Nong's Khao Man Gai",
address: "609 SE Ankeny St",
phone: "503-740-2907",
secretKeyLocation: "somewhere",
};
You want to remove secretKeyLocation before passing the object on to the next part of the workflow.
Use a combination of object destructuring and object literal spread/rest syntax.
const { secretKeyLocation, ...rest } = restaurant;
doSomethingWith(rest);
With this, you now have three variables:
secretKeyLocation with the value of "somewhere"
rest, a new object with the secretKeyLocation property removed:
{
name: "Nong's Khao Man Gai",
address: "609 SE Ankeny St",
phone: "503-740-2907",
}
It's worth noting that rest can be any valid variable name; the name rest itself has no special meaning.
restaurant remains untouched and retains its original value. Immutability FTW 🙌!
That was never in the cards for you, was it? I don't know how you started your first years of life, but your life with me started abandoned, starved, and shell-shocked. You had the worry and suspicion forced into you, most likely from abuse, that remained with you for the rest of your life.
At first you just seemed like a timid creature, needing a cat 50 pounds lighter than you to show that the stairs were nothing to be afraid of. You were never able to overcome your fear of metal grates and decided the upstairs bedrooms were just not worth the risk.
As you regained your strength, your frightfulness became something frightening—you were uncontrollably violent toward other dogs. At home, you were Henry Jekyll, and to the rest of the world (at least other dog owners), Edward Hyde. All of a sudden, your world became small again and that was the second time my heart broke for you.
Severe fear aggression, the behaviorists diagnosed. You scored as an un-adoptable dog in multiple temperament tests—a dog that should have been put down at the shelter.
You dragged me reluctantly into the world of canine behavior. I'll admit, Lola, it was all a bit too much for me. I didn't sign up for this, I didn't know how or want to manage your behavioral problems. I just wanted a dog who would follow me around, fetch my slippers, and occasionally get into minor trouble. So many times I felt rejected and angry and sad and resentful as the frustration and stress wore down my body and my emotions.
But every day, no matter how high or low it was, you always showed me with some gesture that yes, we made it through another day, and that it was okay. I depended on you to provide me that assurance, and you never once failed me.
Two and a half years, Lola. Two and a half years of consulting with numerous behaviorists, of learning all about your species, of pre-dawn off-leash training, of stressful dog park conditioning sessions. Two and a half years of ups and downs, ups and downs. I guess during that time I earned your trust, even though I still couldn't trust you to not make undesirable decisions on your own.
On May 10, 2006, 6:15 in the morning, just as the sun was rising, we were at the beach by ourselves. It was probably your reward for a good training session. All of a sudden I heard movements behind me and it was a large male Ridgeback. I instinctively reached for the leash so I could maintain control, but you turned to check in with me (thank you), asking me what you should do. In that split second, I decided to let you go. Maybe I saw something in your eyes, maybe I was being selfish and wanted to prove that all the effort paid off—who knows, who cares, because the next moments were among the most heart-stopping, happy, breathtaking, beautiful moments I've ever experienced. You started playing with Jaaco.
You started playing with another dog.
You chased Jaaco, then you ran and swam with Jaaco's sister, (the other) Lola. You were born again, (my) Lola. Do you have any idea what this meant? Do you? This was your true birthday.
I must have seemed like a delirious person to your other human when we got home. I still have no words today to describe how relieved, how grateful, how happy. From that moment on, May 10, 2006, 6:15am, you started living a much more fulfilling life. You started really living.
The next many years were filled with morning walks, evening walks, dogs that you loved to play with, dogs that you avoided, long hikes that tired you out, trips to the beach where you swam (you were such a terrible swimmer). We even took a road trip where you were uncertain, then curious, then ecstatic at the snow. You opened so many places inside me that allowed me to accept not just you, but other people and experiences as well.
You were always with me to observe the changes in the water, the horizon, the skies of the bay. You never complained but you wouldn't stick around that long either. I didn't mind you wandering off but sometimes you would lose sight of me and I would see you frantically running back and forth looking for me. I would smile and whistle and you always, always came rushing back.
You were never the self-assured or independent dog. You had confidence but only if I was around. It took a very long time for me to grasp that you had your own source of confidence, it's just not one that I understand. You were so confident that no matter what, I would be there for you, I would make the right decision for you when you didn't want to, I would help you navigate this society full of rules and judgment that you couldn't understand. You had no pretense, you had no agenda, you simply said, "hey you, do your best to take good care of me."
I did try my best to take good care of you, Lola. There was nothing I could do to protect you from your own mutated cells in the end, though. By the time the oral melanoma was symptomatic, the cells had already taken over in places where surgery was impossible. By the time there was a treatment plan (radiation and immunotherapy), the vicious disease had already spread into your lymph nodes and your lungs.
The last few nights of your life, you weren't able to sleep at all. Your nostrils were stuffed up, your mouth was filled with infectious blood, and your lymph nodes had swollen to the point where you couldn't breathe unless you held your head up. Every breath sounded as if you took a step summiting Mount Everest. You were so loud that I had to leave you by yourself upstairs so I could steal a few restless hours of sleep. I had to, Lola. I hated it but I had to. I had to make sure my mind was clear so I could make the best decisions for you.
As I sat by your side, by your bed, I would listen to your labored breathing, watch your eyes slowly close, then your head drop suddenly because you were tired, so tired. You looked peaceful, as if nothing was wrong and you were just sleeping normally. I became hopeful that you could rest, just rest. However, I could see that the muscles were working but there was no air getting into your lungs.
One one thousand.
Two one thousand.
You violently jerked your head straight up to gasp for air, to stay alive.
Five more breaths. Breathless sleep. Violent gasp. Over and over and over and OVER.
Each time my heart squeezed tighter, my own breath taking in less air.
You also stopped eating and were barely drinking water on your own. Your lean, low-fat body mass now worked against you as your body literally consumed your muscles to sustain itself. Your eyes became sunken from severe dehydration. Your nose and mouth crusted with dry, old blood.
I felt so helpless. I couldn't provide any relief or comfort. I dutifully wiped your nose and mouth, changed your bloody bedding. All I could do was to let you know that I was there, close by.
You were so strong, Lola, so strong. Even as you were enduring unimaginable pain, you stood up to find your humans in the kitchen when we ate lunch, you plopped your head into my lap because that's how I liked you to sit with me. Maybe you did all of these things out of habit, maybe you needed to be around us just as much as we needed to be around you. All I know is you didn't have to make the effort, but you did.
I couldn't ask any more of you. You've learned to look to me to make decisions for you when you didn't want to. And here was a decision you couldn't make, but I had to. There was no right answer, there were only impossible choices. We had to let you go while you still knew that you were loved and respected. We had to let you go while you were still able to enjoy the last car ride to the vet. We had to let you go while you still had the capacity to know that we decided to end your life.
There is no way for me to know if you understood, or were capable of understanding, all my thoughts and feelings for you. In the end, it doesn't really matter for I could never truly speak your language or understand all your intentions. Whether your anthropomorphic behaviors were intuitive or instinctual, it doesn't really matter. I related to you as a soulful companion. I tried as much as I could to maintain your dogginess. You were my family.
I miss you, Lola. With time, there will come more days when I don't cry for you (for me, really) anymore. Indeed, there will be days when I won't even consciously think of you. Like all creatures, I was born, and I will die. When I do, we will have shared another experience together. We will be equals.
]]>