![\"XKCD](\"/_next/image?url=%2F_next%2Fstatic%2Fimmutable%2Fmedia%2Fdependency_2x.3-ro_8pmtd3fz.png&w=750&q=75\"/)
Imagine a small task tracker — the kind of kanban board every team eventually\nbuilds. There are columns (Todo, In Progress, Done), cards you drag between\nthem, an order within each column, and tasks can block other tasks. Each card has\na status, a position, and maybe some blockers. You drag a card to a new\ncolumn, it moves, the server is told. Simple.
I've used React Query for years, and my reflex for mutations has always been the\nsame: fire the mutation, then invalidateQueries to get the real deal from the\nserver. That reflex is correct — for forms. It fell apart the moment I made the\nboard draggable, and digging into why taught me more about mutations than years of\nCRUD forms ever did.
A create/update/delete form is slow and deliberate. The user clicks submit, waits,\nsees the result. You want server truth — generated ids, computed fields, side\neffects — so you just invalidate:
\nconst invalidate = () => queryClient.invalidateQueries({ queryKey: ['tasks'] })\n \nuseMutation({ mutationFn: createTask, onSuccess: invalidate })
Nothing wrong with this. The round-trip is fine because the human is already\nwaiting on it. The mistake is assuming this is the pattern for mutations rather\nthan one pattern, suited to one kind of interaction.
\nDrag is the opposite of a form. It's fast, it's optimistic (the card must move\nnow, not after a round-trip), and you can fire several before any of them\nsettle. Drag card A to Done, then immediately drag card B to In Progress, then nudge\nA up a slot. Three mutations in flight at once.
\nWith "invalidate on settle" the board started thrashing — cards visibly\nsnapping back to where they'd been a moment ago, then forward again. Two distinct\nbugs were hiding in there.
\ninvalidateQueries doesn't just mark data stale — it forces an immediate\nrefetch of any active query. (If you pause your polling with refetchInterval,\nnote that invalidation ignores it.) So with two drags in flight:
n.n+1.n (has A, not B).A list GET is a global replace — a stale snapshot clobbers changes it knows\nnothing about. The fix isn't to stop invalidating; it's to only invalidate after\nthe last mutation in the burst settles (more on the exact check below).
\nThe subtler one. If you reconcile by writing the server response into the cache\nin onSuccess, two mutations on the same card can resolve out of order:
A per-id onSuccess patch is perfectly safe across different cards (each touches\nits own row). It's only the same card, mutated twice, that bites. And it bites\nprecisely because we're treating the response as the source of truth.
Here's what unlocked it. For a drag, the value I'm optimistically writing is\nexactly what I'm persisting. I compute the new status and position on the client,\nwrite them to the cache, and send the very same thing to the server. The server\njust stores it and echoes it back. The response carries no new information.
\nSo I shouldn't apply the response at all. The optimistic writes already happen in\ninteraction order (drag 1, then drag 2), so the latest one wins by construction.\nDrop onSuccess entirely and the same-card race disappears — there's nothing left\nto land out of order.
\n\nThe exception that proves the rule: reconcile from the response only when the\nserver mints data the client didn't have — a generated id, a server-computed\nfield. And even then, merge it by id; don't replace the list.
\n
Putting it together, an optimistic drag mutation looks like this:
\nconst KEY = ['tasks', 'status-move'] // shared across all the drag mutations\n \nuseMutation({\n mutationKey: KEY,\n mutationFn: moveTask,\n onMutate: async (vars) => {\n // 1. cancel first — abort any in-flight GET so it can't land on top\n // of our optimistic write. THIS is what makes optimism safe, not invalidate.\n await queryClient.cancelQueries({ queryKey: ['tasks'] })\n // 2. write the new state immediately\n queryClient.setQueryData(['tasks'], (old) => applyMove(old, vars))\n // 3. no snapshot — see onSettled\n },\n // no onSuccess: the optimistic write is authoritative\n onSettled: () => invalidateIfLastMove(queryClient),\n})
And the gated invalidate:
\nfunction invalidateIfLastMove(qc: QueryClient) {\n // imperative isMutating() — NOT the useIsMutating() hook (stale closure)\n if (qc.isMutating({ mutationKey: ['tasks', 'status-move'] }) === 1) {\n void qc.invalidateQueries({ queryKey: ['tasks'] })\n }\n}
A few things worth calling out:
\ncancelQueries in onMutate is the load-bearing call. It's not the\ninvalidate that makes optimistic updates safe — it's cancelling the in-flight\nread so a poll or earlier fetch can't overwrite what you just wrote.=== 1, not === 0. When onSettled runs, this mutation is still counted\nas pending — query-core dispatches success/error only after the onSettled\ncallbacks finish. So 1 means "I'm the last one standing," which is exactly when\nit's safe to refetch. I only believed this after reading the source.onSettled runs on success and error. So a failed drag's wrong optimistic\nvalue self-heals on the same refetch. No manual rollback.onMutate can clobber a later\nsuccessful drag of the same card. A refetch gives true current state; a snapshot\ngives a stale guess.refetchInterval on useIsMutating(...) > 0 —\nfalse while a move is in flight, your normal interval otherwise. The\nuseIsMutating hook is right here (render-time, wants reactivity); the\nimperative qc.isMutating() is right inside the callback.The single post-burst refetch isn't wasted, either — it catches server-side side\neffects the response wouldn't include. Closing a blocker can flip its dependents\nfrom Blocked to Ready in other columns; the gated reconcile picks that up.
\nOnce the bugs were gone, the bigger lesson was about placement. A useMutation\nruns through a fixed sequence of handlers, and knowing the order tells you where\neach concern goes:
Two things fall out of this order. By the time your await returns, the hook's\nonMutate and onSettled have already run — so a success toast is purely\ncosmetic, fired after the reconcile is already kicked off. And because onSettled\nruns on both paths, the reconcile (and any cleanup) belongs there, not duplicated\nacross onSuccess/onError.
This is the part I'd push hardest on. The hook should own what changed (cache and\nstate); the component should own telling the user (toasts, banners,\nnotifications). The way you get that separation is to call the mutation with\nawait mutateAsync(...) and handle UX in the surrounding try/catch:
Same hook, two call sites, completely different feedback. Because the hook never\nimports a toast library, it stays portable — you can lift it into another screen,\nor another app, and it just works. If the toast lived inside the hook, you'd be\nforking it the first time a second screen needed a different message.
\nPrefer mutateAsync over mutate for this. await gives you a linear flow —\nsuccess line, then a catch for the error — right where the component already has\nits notification API in scope. The one rule you can't forget: mutateAsync rejects\non error, so it must be wrapped in try/catch (or a .catch), or you get an\nunhandled rejection. The hook's onSettled still runs either way.
\n\nWhen plain
\nmutateis fine: an interaction whose only feedback is the optimistic\nchange itself, where errors self-heal via the gated refetch — there's no toast to\nshow, andmutatecan't throw. Just don't reach formutateAsyncand then\nignore the returned promise; that's the worst of both.
All of this leans on query keys, and there's one behaviour worth internalising.\nA hierarchical key factory:
\nconst taskKeys = {\n all: ['tasks'] as const,\n list: (q) => ['tasks', 'list', q] as const,\n detail: (id) => ['tasks', 'detail', id] as const,\n}
invalidateQueries, cancelQueries, and the isMutating/isFetching filters all\nmatch partially by default — a query matches if its key starts with the key\nyou pass. That prefix behaviour is the entire point of the factory: one key, many\nblast radii.
| You pass | Matches |
|---|---|
['tasks'] | every tasks query — all boards and all details |
['tasks', 'list'] | all boards, any filter |
taskKeys.list(q) | that one filtered board |
['tasks', 'detail', id] | a single task |
Two gotchas. Objects inside a key are matched partially too (a subset match, not\nby reference), so an under-specified object filter can hit more queries than you\nmeant. And when a prefix would catch siblings you want to leave alone, pin it with\n{ exact: true }. My rule of thumb: invalidate at the broadest key that's still\ncorrect. A board move uses ['tasks'] deliberately, because a move can ripple\ninto other columns — the wide prefix is the right radius, and the gated call keeps\nit to a single refetch per burst.
"Just invalidate" is a fine default until interactions get fast and concurrent.\nThen the questions change: cancel the in-flight read first, decide whether the\noptimistic value or the response is the source of truth (for a drag, it's the\noptimistic value), gate the reconcile to the last mutation in the burst, and let\nerrors heal by refetching rather than by restoring a stale snapshot. Keep all of\nthat in the hook, and keep the toast at the call site so the hook stays reusable.
\nA checklist I now run before shipping any mutation:
\nonMutate does cancelQueries before setQueryData?onSuccess reconcile (unless the server returns new data)?qc.isMutating(...) === 1?mutationKey, and polling pauses on it?await mutateAsync in a try/catch, not in the hook?Much of this is distilled from TkDodo's excellent\nConcurrent Optimistic Updates in React Query\nand Practical React Query — both\nworth reading in full.
", "url": "https://alexmchan.com/blog/2026-06-29-concurrent-optimistic-updates", "title": "Drag, drop, and the optimistic update race", "summary": "My usual React Query reflex — just invalidate to get the real deal — fell apart the moment I added drag-and-drop to a kanban board. Here's what concurrent optimistic updates actually require, and where each concern belongs.", "date_modified": "2026-06-29T00:00:00.000Z", "author": { "name": "Alex Chan" } }, { "id": "https://alexmchan.com/blog/2026-03-07-architecture-decisions", "content_html": "After years working with software, I've developed a set of principles that guide my architectural decision-making. These aren't hard rules — they're lenses to look through when faced with choices that will outlast the sprint they were made in. After each section I've added some questions to ask yourself or your llm.
\nPrefer simple APIs over complex ones. A smaller surface area and a more focused role make a system easier to understand, reason about, and eventually replace.
\n\n\nEverything should be as simple as it can be, but not simpler\n― Einstein
\n
If something offers a larger surface area, stay in the simpler parts of the API rather than reaching for complex features — indexes in Postgres carry less lock-in than stored procedures, for instance. Prefer proxy APIs that allow for simpler switching later.
\n\n\nPerfection is achieved not when there is nothing more to add, but when there is nothing more to remove.\n— Antoine de Saint-Exupéry
\n
Grug puts it more bluntly:
\n\n\nThe eternal enemy: Complexity
\ngiven choice between complexity or one on one against t-rex, grug take t-rex: at least grug see t-rex
\n
Everything is on a spectrum, and "correct" can mean different things depending on your goals, timelines, and constraints. This is why it's worth spending a little time upfront to save days or years of pain — and why writing down the why behind a decision matters, so you can re-evaluate it later. Understand that there's sometimes different solutions for the short, medium and long term.
\nStarting from the best solutions in the space gives you the chance of landing on the right one.
\nMake sure decisions are evaluated against the top competitors, and that you have clear criteria for why you're choosing one thing over another. Check real-world reports of each in production use, and build a proof of concept — of the candidate and its competitors. Even a mental walkthrough of how an API or tool would be used in practice is more valuable than committing to a full implementation.
\nAlways explain why you recommend what you do and what you considered along the way.
\nNote that some people skip this step -- some of it might come down to satisficing vs. maximising — we'd all be stuck forever trying to find the optimal solution. Still, it's worth understanding why people make the choices they do and why we ourselves might skip it. LLMs are a good starting point if we ensure that they search for the most up to date information and not use only the knoweldge cutoff.
\nFavour open standards, small API surface areas, and simple libraries over entirely proprietary solutions.
\nDatabases are boring technology — and that's usually a good thing. MySQL, Postgres, and Redis (Valkey) are typically better choices than something like FaunaDB unless there's an order-of-magnitude performance gain or a meaningful speed-to-develop advantage and an easy migration off.
\nReturning to simplicity and implementation cost: can this be walked back in a week, a month, a quarter, or a year? Can migration be automated, or does it require a dedicated team effort?
\nIf it's a two-way decision, it's safer to try it and back out with your learnings intact. If it's a one-way decision, are you taking enough time to be happy living with it for much longer?
\nThis talk covers the idea of reversible vs. irreversible decisions well — worth the watch.
\nChoosing none of the above is always valid — but be honest about its costs and trade-offs. Sometimes thinking through the "do nothing" path is exactly what helps clarify the why behind whichever direction you eventually choose.
\nWeight more toward projects whose maintainers have a long history of support. In the absence of that, prefer open-source projects or APIs close enough to a competitor that switching remains feasible. Prefer funded, profitable ventures over brand-new ones, and consider whether self-hosting is possible if needed.
\nAll else being equal, the larger, more established community will usually be the safer bet.
\nOne genuine exception to the "boring tech" guideline is personal, low-impact projects, or intentionally cutting-edge experiments. Testing bleeding-edge ideas in a low-risk environment is one of the best ways to learn — you hit real-world problems while picking up new ways of thinking, and those learnings carry back into the main work.
\nDevelopment and support time, onboarding speed, LLM familiarity (is it in the training data, or does context cost thousands of tokens?), documentation quality, build-vs-buy trade-offs, upgrade burden, security, testability, observability, tooling integration, and usability all factor into total cost of ownership.
\nWhat are the uptime risks? How proven is this, and are there real production adopters?
\nROI matters too. Spending $20 to save $100 is making money — if your estimates are correct. Measure before you adopt and monitor after to validate your assumptions. Spending money isn't wasting money if the alternative is burning time or compounding technical debt.
\nUsually when there's pure hype without substance — the tool hasn't passed the tests above, or it has the wrong abstraction for your context. It's also possible that someone hasn't measured the right things, or has weighted them differently than you would.
\nActively seek out dissenting opinions to stress-test your assumptions. Sometimes two people can both be right about the same thing — it's about weighing the trade-offs and planning for the risks. Look for the most critical takes and ask honestly whether you can live with those trade-offs.
\nWhen is the crowd right? Sometimes they actually are, so cross-check whether you've missed anything. Critical mass and community knowledge have real value: shared knowledge is searchable, baked into LLMs, and means more people have already faced — and solved — the problems you're about to hit.
\nCheck whether your assumptions held as you move forward. Watch for friction, and don't be afraid to choose a different path — but try to converge on a single solution rather than maintaining multiple approaches in parallel. The principles of one-way vs. two-way decisions and simple APIs should support you here. Does it actually speed things up? Keep a decision registry and look back to understand when you were right or wrong and more importantly why.
\n![\"XKCD](\"/_next/image?url=%2F_next%2Fstatic%2Fimmutable%2Fmedia%2Fstandards_2x.18wm0wftiwc1z.png&w=1080&q=75\"/)
One way to ensure that these decisions are revisited is to create an architectural decision record. This is a document that outlines the decision, the context, the criteria, the options, and the reasoning behind the decision. Make sure there's a recommendation even on first draft so that people reviewing know what your initial thoughts are and then the discussion can begin. When people differ on a given point that's when the interesting discussions happen. The thing to remember is that people are basing their decisions on both a different past and team/timeframe/constraints and the future may have different estimates when people are basing things from feelings or even estimates. ADRs are a whole topic on their own but the main thing is to create one, even if it's just for yourself to refer to later.
\n\n\n“When the facts change, I change my mind - what do you do, sir?”\n― John Maynard Keynes
\n
Good architectural decisions help narrow down the range of possible solutions in an unpredictable world. Ideally they balance risk, cost and reward but ultimately they're about being intentional, comparing honestly, and setting yourself up to either change course or commit with confidence. Know what you're optimising for, write down the why, and revisit when the world changes. Good luck!
\nDo you agree or disagree on some points? Why? What things do you value and why? Hopefully this helps you think about your own design principles.
", "url": "https://alexmchan.com/blog/2026-03-07-architecture-decisions", "title": "Architectural Decisions", "summary": "Architectural decisions shape codebases for years. Here are the principles I've developed over 25 years to make better ones — covering simplicity, vendor lock-in, reversibility, and total cost of ownership.", "date_modified": "2026-03-07T00:00:00.000Z", "author": { "name": "Alex Chan" } }, { "id": "https://alexmchan.com/blog/2026-02-25-submit-button-outside-form", "content_html": "Modal and dialog layouts usually look something like this:
\n\n┌─────────────────────────────────┐\n│ Header │\n├─────────────────────────────────┤\n│ Content (scrollable) │\n│ <YourForm /> │\n├─────────────────────────────────┤\n│ Footer │\n│ [Cancel] [Save Changes] │\n└─────────────────────────────────┘\n
The <form> lives in the scrollable content area. The Save button lives in the footer — which is a sibling of the content in the DOM, not a descendant of the form. So type="submit" won't trigger it.
The usual workarounds are either ugly (call form.submit() imperatively, or lift state up) or they force you to restructure your JSX in awkward ways just to get the button inside the form.
form attributeHTML has had a solution for this forever. Any <button>, <input>, <select>, or <textarea> can be associated with a form anywhere on the page using the form attribute — just point it at the form's id:
<form id="my-form" onsubmit="...">\n <!-- fields -->\n</form>\n \n<!-- completely elsewhere in the DOM -->\n<button type="submit" form="my-form">Save</button>
Clicking that button behaves exactly as if it were inside the form. The browser handles it natively.
\nThis plays perfectly with RHF. Give your form an id, put that same id on the external button, and everything — validation, error messages, the handleSubmit wrapper — works as normal:
function MyForm({ id }: { id: string }) {\n const { register, handleSubmit, formState: { errors } } = useForm<Fields>({\n resolver: zodResolver(schema),\n });\n \n return (\n <form id={id} onSubmit={handleSubmit(onSubmit)}>\n <input {...register('name')} />\n {errors.name && <p>{errors.name.message}</p>}\n </form>\n );\n}\n \nfunction MyModal({ onClose }: { onClose: () => void }) {\n const formId = useId(); // stable unique ID — safe with SSR\n \n return (\n <div className="modal">\n <div className="modal-content">\n <MyForm id={formId} />\n </div>\n <div className="modal-footer">\n <button type="button" onClick={onClose}>Cancel</button>\n <button type="submit" form={formId}>Save Changes</button>\n </div>\n </div>\n );\n}
The footer button triggers RHF's handleSubmit, which validates first and only calls onSubmit if everything passes. No imperative refs, no lifted state.
useId() for the IDReact 18's useId is the right tool here. It generates a stable ID that's unique per component instance, works with SSR, and avoids collisions if the modal can be mounted more than once simultaneously.
const formId = useId();
Don't just hardcode id="my-form" unless you're certain only one instance will ever exist.
One other pattern worth knowing: if you have a multi-tab modal with a single Save button in the footer, some tabs might not have a form at all (e.g. a read-only info tab). You can render a stub form with the same ID that just calls onClose:
// Read-only tab — no real form, but footer button still needs to work\n<form\n id={formId}\n onSubmit={(e) => {\n e.preventDefault();\n onClose();\n }}\n/>
This keeps the footer button consistent across all tabs without special-casing the click handler.
\nLet's face it: you're probably not going to read this. Just point your LLM here and let it work its magic. If you're curious about what it's going to do, read ahead.
\nTL;DR for humans: The fastest way to build a CLI in 2026 isn't learning all the libraries—it's teaching an LLM your stack preferences once. This guide is optimized for LLM consumption but works for humans too.
\nIf you're using Claude Code, you can install the CLI skill to get all these best practices automatically:
\nnpx skills add alexanderchan/cli-skill
Then just use /cli and describe what you want to build. The skill encapsulates all the patterns from this post into a reusable prompt template.
After years of iteration, here's an iteration for a modern TypeScript CLI:
\ncommander)prompts or @inquirer/prompts library)You might ask: "Why not just write a bash script?" Fair question. Here's why TypeScript or Go is often better:
\nMaintainability: Shell scripts become unreadable quickly. Complex logic with proper error handling, JSON parsing, and conditionals turns into a mess of [[, $(()), and cryptic syntax.
# Shell script complexity escalates fast\nif [[ -f "$CONFIG_FILE" ]]; then\n VALUE=$(cat "$CONFIG_FILE" | jq -r '.key // empty')\n if [[ -z "$VALUE" ]]; then\n echo "Error: key not found" >&2\n exit 1\n fi\nfi
vs TypeScript:
\nconst config = JSON.parse(await fs.readFile(configFile, 'utf-8'))\nif (!config.key) {\n console.error('Error: key not found')\n process.exit(1)\n}
LLM accuracy: Modern LLMs are significantly better at TypeScript and Go than bash. They'll generate correct error handling, proper quoting, and safe variable expansion in TypeScript/Go. With bash, they often produce scripts that work in simple cases but fail with edge cases (spaces in filenames, special characters, etc.).
\nPortability: Shell scripts are less portable than you think:
\nsed, date, find all have different flags)Type safety and tooling: You get autocomplete, type checking, and refactoring support. Shell scripts have none of this.
\nWhen shell scripts ARE the right choice:
\nFor everything else, use TypeScript with zx (which gives you shell-like syntax with TypeScript safety) or Go for production tools.
Instead of memorizing APIs, give your LLM this context:
\nUsing @commander-js/extra-typings, @clack/prompts, and zx\n \nbuild a cli that does the following...\n \n[describe what you want the CLI to do]\n \nexample header:\n \n#!/usr/bin/env tsx\nimport { Command } from '@commander-js/extra-typings'\nimport * as p from '@clack/prompts'\nimport { $ } from 'zx'\n \n$.verbose = true
That's it. Modern LLMs know these libraries well and will generate working code.
\nPlain commander has TypeScript types, but they're generic. The extra-typings package adds inferred types based on your actual option and argument definitions:
// With plain commander - opts is generic\nimport { Command } from 'commander'\nconst program = new Command()\n .option('-p, --port <number>', 'port number')\n .action((opts) => {\n // opts is just Record<string, any>\n opts.port // no autocomplete ❌\n })\n \n// With extra-typings - opts is inferred\nimport { Command } from '@commander-js/extra-typings'\nconst program = new Command()\n .option('-p, --port <number>', 'port number')\n .action((opts) => {\n // opts.port is automatically typed! ✅\n opts.port // full autocomplete\n })
The types build up as you chain methods, giving you full IntelliSense.
\nThe older prompts library hasn't been updated in 4 years. @clack/prompts is actively maintained and offers:
import * as p from '@clack/prompts'\n \np.intro('My CLI Tool')\n \nconst name = await p.text({\n message: 'What is your name?',\n validate: value => !value ? 'Name is required' : undefined\n})\n \nconst confirmed = await p.confirm({\n message: 'Are you sure?'\n})\n \np.outro('Done!')
While execa is great for programmatic command execution, zx is better for replacing shell scripts because:
await $\\cat file.txt | grep pattern``// Complex pipelines just work\nawait $`docker ps | grep my-app | awk '{print $1}'`\n \n// Template literals handle variables naturally\nconst tag = 'v1.0.0'\nawait $`git tag ${tag} && git push origin ${tag}`
If you want something more opinionated than Commander, check out brocli from the Drizzle team. It has a cleaner API for defining commands and better built-in help generation.
\nHere's what you might ask an LLM:
\nUsing @commander-js/extra-typings, @clack/prompts, and zx\n \nBuild a CLI that:\n- Accepts a list of git repos as arguments or from a --repos-file\n- For each repo, checks if there are uncommitted changes\n- If clean, creates a branch (default name: YYYY-MM-DD-update-deps)\n- Runs npm update or yarn upgrade depending on package manager\n- Creates a PR using gh CLI if there are changes\n \nInclude proper error handling and a spinner for long operations.
The LLM will generate a complete, working CLI with proper types, error handling, and user feedback.
\nDevelopment:
\nchmod +x script.ts\n \n# Run with tsx (recommended)\ntsx script.ts\n \n# Or with bun\nbun script.ts\n \n# Or with node + tsx loader (slower)\nnode --import tsx script.ts
Distribution (add to package.json):
\n{\n "bin": {\n "my-cli": "./dist/cli.js"\n },\n "scripts": {\n "build": "esbuild --bundle --platform=node --target=node22 src/cli.ts --outfile=dist/cli.js"\n }\n}
For multiple CLIs with esbuild, you need to build each separately:
\n{\n "bin": {\n "my-cli": "./dist/my-cli.js",\n "another-cli": "./dist/another-cli.js",\n "third-cli": "./dist/third-cli.js"\n },\n "scripts": {\n "build": "npm run build:my-cli && npm run build:another-cli && npm run build:third-cli",\n "build:my-cli": "esbuild --bundle --platform=node --target=node22 src/cli/my-cli.ts --outfile=dist/my-cli.js",\n "build:another-cli": "esbuild --bundle --platform=node --target=node22 src/cli/another-cli.ts --outfile=dist/another-cli.js",\n "build:third-cli": "esbuild --bundle --platform=node --target=node22 src/cli/third-cli.ts --outfile=dist/third-cli.js"\n }\n}
This works but gets verbose quickly. That's where tsdown shines.
\nFor projects with multiple CLI entry points, tsdown provides a cleaner config-based approach:
\nnpm install -D tsdown
Create tsdown.config.js:
import { defineConfig } from "tsdown";\n \nexport default defineConfig({\n entry: [\n "./src/cli/my-cli.ts",\n "./src/cli/another-cli.ts",\n ],\n format: "commonjs",\n});
Update package.json:
{\n "bin": {\n "my-cli": "./dist/my-cli.js",\n "another-cli": "./dist/another-cli.js"\n },\n "scripts": {\n "build": "tsdown",\n "build:watch": "tsdown --watch"\n },\n "files": ["dist"]\n}
Benefits of tsdown:
\nThen npm publish or npm link for local testing.
Bun has a built-in bundler that's extremely fast and has great defaults for building CLIs:
\nbun install
For a single CLI:
\n{\n "bin": {\n "my-cli": "./dist/cli.js"\n },\n "scripts": {\n "build": "bun build --compile --target=node --outfile=dist/cli.js src/cli.ts"\n }\n}
For multiple CLIs:
\n{\n "bin": {\n "my-cli": "./dist/my-cli.js",\n "another-cli": "./dist/another-cli.js",\n "third-cli": "./dist/third-cli.js"\n },\n "scripts": {\n "build": "bun build --target=node --outdir=dist src/cli/*.ts"\n }\n}
Benefits of bun build:
\nsrc/cli/*.ts automatically creates multiple outputs--minify flag for smaller bundles--compile creates a single executable with bun runtime embedded (great for distribution)Creating standalone executables (no Node.js required):
\n# Build a completely standalone binary\nbun build --compile --target=bun src/cli.ts --outfile=my-cli\n \n# Now distribute the single binary - no runtime needed!\n./my-cli
This creates a single executable that includes the Bun runtime, making distribution incredibly simple - just ship one file.
\nFor development, you can still use bun run:
bun run src/cli.ts
When to use bun build over esbuild/tsdown:
\nTypeScript is great for quick scripts and Node.js ecosystems, but if you're building a production CLI that needs to be distributed as a standalone binary, Go is the superior choice. Here's the modern Go CLI stack based on real-world production use:
\nflag - Built-in flag parsing (or cobra for complex CLIs)Single binary distribution: Compile once, run anywhere. No runtime dependencies.
\n# Build for all platforms from one machine\nGOOS=darwin GOARCH=arm64 go build -o alex-runner-darwin-arm64\nGOOS=linux GOARCH=amd64 go build -o alex-runner-linux-amd64\nGOOS=windows GOARCH=amd64 go build -o alex-runner-windows-amd64.exe
No CGO = Easy cross-compilation: Using pure Go libraries like modernc.org/sqlite means you can cross-compile without C toolchains:
// go.mod\nrequire (\n modernc.org/sqlite v1.34.4 // Pure Go - no CGO!\n)
Fast startup: Go binaries start in milliseconds, not hundreds of milliseconds like Node.js.
\nSmall binaries: With proper build flags, Go binaries are 5-15MB. TypeScript bundles + Node.js runtime are much larger.
\nUse GoReleaser for automated multi-platform builds and releases:
\n# .goreleaser.yaml\nversion: 2\n \nbuilds:\n - id: my-cli\n main: ./cmd/my-cli\n binary: my-cli\n env:\n - CGO_ENABLED=0 # Pure Go - no CGO!\n goos:\n - linux\n - darwin\n - windows\n goarch:\n - amd64\n - arm64\n ldflags:\n - -s -w # Strip debug info for smaller binaries\n - -X main.version={{.Version}}\n - -X main.commit={{.Commit}}\n \narchives:\n - formats: [tar.gz]\n format_overrides:\n - goos: windows\n formats: [zip]
GitHub Actions integration:
\n# .github/workflows/release.yml\nname: Release\non:\n push:\n tags:\n - 'v*'\n \njobs:\n goreleaser:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: actions/setup-go@v5\n with:\n go-version: '1.23'\n - uses: goreleaser/goreleaser-action@v5\n with:\n version: latest\n args: release --clean\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Push a tag, get binaries for all platforms automatically.
\nAlways prefer pure Go implementations to avoid CGO complexity:
\n| Need | ❌ CGO Version | ✅ Pure Go Version |
|---|---|---|
| SQLite | mattn/go-sqlite3 | modernc.org/sqlite |
| Image processing | Avoid C libs | golang.org/x/image |
| Compression | C libraries | compress/* (stdlib) |
Why avoid CGO?
\ngo get simplicity\nmy-cli/\n├── cmd/\n│ └── my-cli/\n│ └── main.go # Entry point\n├── internal/\n│ ├── ui.go # Bubble Tea UI\n│ ├── db.go # Database logic\n│ ├── completion.go # Shell completion\n│ └── *_test.go # Tests\n├── .goreleaser.yaml # Release config\n├── Makefile # Build shortcuts\n└── go.mod\n
Makefile for common tasks:
\n.PHONY: build test install\n \nbuild:\n\tgo build -o my-cli ./cmd/my-cli\n \ntest:\n\tgo test ./internal/... -v\n \ninstall:\n\tgo install ./cmd/my-cli
Go makes it easy to generate shell completions:
\n// In your main.go\nfunc generateCompletion(shell string) string {\n switch shell {\n case "bash":\n return bashCompletionScript\n case "zsh":\n return zshCompletionScript\n case "fish":\n return fishCompletionScript\n }\n return ""\n}\n \n// Usage:\n// my-cli --generate-completion bash > /etc/bash_completion.d/my-cli
Even for Go projects, use Changesets for version management:
\n# Install changesets\npnpm add -D @changesets/cli\n \n# Add a changeset during development\npnpm changeset\n \n# Release (bumps version, updates changelog)\npnpm release
This works great with GoReleaser - changesets manage the version, GoReleaser builds the binaries.
\nCheck out alex-runner - a production-ready frecency-based npm/pnpm/yarn script runner that demonstrates all these best practices:
\nmodernc.org/sqliteKey files to study:
\n.goreleaser.yaml - Multi-platform build config with CGO_ENABLED=0internal/ui.go - Bubble Tea interactive UI implementationinternal/completion.go - Shell completion generation for bash/zsh/fishinternal/db.go - Pure Go SQLite usage with modernc.org/sqlitecmd/alex-runner/main.go - Flag parsing and command structureThe entire project is a great reference for building production CLIs in Go.
\nChoose Go when:
\nChoose TypeScript when:
\nJust like with TypeScript, teach your LLM the Go stack once:
\nUsing Go with Bubble Tea, Lip Gloss, and modernc.org/sqlite\n \nBuild a CLI that does the following...\n \n[describe what you want]\n \nExample structure:\n \npackage main\n \nimport (\n "flag"\n tea "github.com/charmbracelet/bubbletea"\n "github.com/charmbracelet/lipgloss"\n)\n \nfunc main() {\n // Flag parsing\n var verbose bool\n flag.BoolVar(&verbose, "v", false, "verbose output")\n flag.Parse()\n \n // Run Bubble Tea program\n p := tea.NewProgram(initialModel())\n if _, err := p.Run(); err != nil {\n log.Fatal(err)\n }\n}
When building CLIs, it's worth following established best practices for user experience and interface design. Two excellent resources:
\nThese resources will help you build CLIs that feel natural to experienced command-line users while remaining accessible to newcomers.
\nBe non-destructive by default. Always prompt before mutating operations:
\nimport * as p from '@clack/prompts'\n \nconst shouldDelete = await p.confirm({\n message: `Delete ${files.length} files?`,\n initialValue: false\n})\n \nif (!shouldDelete) {\n p.cancel('Operation cancelled')\n process.exit(0)\n}
Support --yes or --non-interactive mode for CI/CD and automation:
import { Command } from '@commander-js/extra-typings'\n \nconst program = new Command()\n .option('-y, --yes', 'skip confirmation prompts')\n .option('--non-interactive', 'run in non-interactive mode')\n .action(async (opts) => {\n const shouldProceed = opts.yes || opts.nonInteractive\n ? true\n : await p.confirm({ message: 'Continue?' })\n \n if (!shouldProceed) return\n // ... do the work\n })
Store config in standard locations using well-known formats:
\nimport { homedir } from 'os'\nimport { join } from 'path'\nimport { readFileSync, writeFileSync } from 'fs'\n \n// Simple config: JSON or YAML in ~/.config/package-name/\nconst configDir = join(homedir(), '.config', 'my-cli')\nconst configPath = join(configDir, 'config.json')\n \n// For complex state: SQLite\nimport Database from 'better-sqlite3'\nconst dbPath = join(configDir, 'data.db')\nconst db = new Database(dbPath)
For Go:
\nimport (\n "os"\n "path/filepath"\n)\n \n// Get config directory\nconfigDir, _ := os.UserConfigDir() // Returns ~/.config on Unix\nappConfigDir := filepath.Join(configDir, "my-cli")\n \n// Simple config: JSON\nconfigPath := filepath.Join(appConfigDir, "config.json")\n \n// Complex state: SQLite with modernc.org/sqlite\ndbPath := filepath.Join(appConfigDir, "data.db")
Keep project-local scripts separate from distributed CLIs:
\nTypeScript projects: Use ./scripts for local utilities:
# Project-local scripts (not distributed)\n./scripts/\n├── dev-setup.ts # Project-specific setup\n├── migrate-data.ts # One-off migrations\n└── generate-types.ts # Build-time codegen\n \n# Run with tsx directly\ntsx scripts/dev-setup.ts\n \n# Global tools (distributed via npm)\nnpm install -g my-cli
TypeScript project structure:
\n\nmy-ts-project/\n├── scripts/ # Project-local utilities (not published)\n│ ├── setup.ts\n│ └── migrate.ts\n├── src/\n│ └── cli/ # Publishable CLIs (if any)\n│ └── my-tool.ts\n└── package.json\n {\n "scripts": {\n "setup": "tsx scripts/setup.ts" // Local scripts\n },\n "bin": {\n "my-tool": "./dist/my-tool.js" // Global CLI\n }\n }\n
Go projects: Use cmd/ for all CLIs (both local and distributed):
\nmy-go-project/\n├── cmd/\n│ ├── my-cli/ # Main distributed CLI\n│ │ └── main.go\n│ └── dev-setup/ # Project-local utility\n│ └── main.go\n├── internal/ # Shared internal packages\n│ ├── ui.go\n│ └── db.go\n└── go.mod\n\n# Run local utilities during development\ngo run ./cmd/dev-setup\n\n# Install distributed CLI globally\ngo install github.com/user/my-go-project/cmd/my-cli@latest\n
The distinction:
\nscripts/ for maintainers, bin/ for end userscmd/ for both, but only main CLIs get published/documentedIn 2026, building CLIs is less about memorizing APIs and more about:
\nThe tools have matured, the LLMs know them well, and you can focus on what your CLI should do rather than how to build it.
\nFor more detailed examples and utilities, check out my original CLI guide which covers additional libraries for specific use cases (file processing, config loading, parallelization, etc.).
", "url": "https://alexmchan.com/blog/2026-01-25-updated-cli", "title": "Modern CLI Tips for LLMs (and Curious Humans)", "summary": "Modern CLI development with TypeScript, Go, and AI assistance - a guide optimized for LLMs", "date_modified": "2026-01-25T00:00:00.000Z", "author": { "name": "Alex Chan" } }, { "id": "https://alexmchan.com/blog/2025-10-21-pragmatic-eslint", "content_html": "ESLint can feel like it's fighting you. Red squiggles everywhere. Auto-fix battles with Prettier. Rules that seem arbitrary. After many years I have this philosophy:
\nHere's the configuration I've converged on, and will update it as time goes on. I try to keep it minimal unless a rule matches one of the above points.
\nBefore we dive into the configuration, let's establish some principles:
\nErrors should prevent bugs - If something is marked as an error, it should represent a real problem that could break your application or confuse developers.
\nStyle is Prettier's job - ESLint shouldn't fight with Prettier over formatting. One tool for style, one for logic.
\nMake migration practical - Perfect is the enemy of shipped. Use grandfathering and incremental adoption to get your team on board.
\nGrandfather old code, enforce new standards - When introducing strict rules, it's often impractical to fix everything at once. Allow existing violations while preventing new ones.
\nThis uses ESLint 9's new flat config format with the latest typescript-eslint recommendations:
\n// eslint.config.mjs\n// @ts-check\nimport eslint from "@eslint/js"\nimport { defineConfig } from "eslint/config"\nimport tseslint from "typescript-eslint"\nimport reactHooks from "eslint-plugin-react-hooks"\nimport noOnlyTests from "eslint-plugin-no-only-tests"\n \nexport default defineConfig(\n eslint.configs.recommended,\n tseslint.configs.recommended,\n tseslint.configs.stylistic,\n {\n plugins: {\n "react-hooks": reactHooks,\n "no-only-tests": noOnlyTests,\n },\n rules: {\n "react-hooks/rules-of-hooks": "error",\n "react-hooks/exhaustive-deps": "error",\n "no-console": [\n "error",\n { allow: ["info", "warn", "error", "dir", "table"] },\n ],\n "no-warning-comments": [\n "error",\n {\n terms: ["fixme"],\n location: "anywhere",\n },\n ],\n "@typescript-eslint/no-unused-vars": [\n "error",\n {\n args: "all",\n argsIgnorePattern: "^_",\n caughtErrors: "all",\n caughtErrorsIgnorePattern: "^_",\n destructuredArrayIgnorePattern: "^_",\n varsIgnorePattern: "^_",\n ignoreRestSiblings: true,\n },\n ],\n "@typescript-eslint/no-explicit-any": "off",\n "no-only-tests/no-only-tests": [\n "error",\n {\n focus: ["only", "skip"],\n },\n ],\n },\n },\n {\n ignores: ["dist/**", "node_modules/**", "*.config.js", "jest.config.js"],\n },\n)
"react-hooks/rules-of-hooks": "error",\n"react-hooks/exhaustive-deps": "error",
Why errors? Violating the Rules of Hooks causes runtime bugs that are confusing to debug. Missing dependencies in useEffect leads to stale closures that silently use old values.
What about legacy code? Use the grandfathering script (see appendix below) to add eslint-disable-next-line comments to existing violations. This lets you enforce the rule going forward while giving you time to fix old code.
Why not warnings? Warnings get ignored. If something matters enough to catch, make it an error that blocks your CI/CD pipeline.
\n"@typescript-eslint/no-explicit-any": "off",
Why off? In real codebases, there are legitimate uses for any - especially when dealing with third-party libraries without types, or truly dynamic data structures. The strict prohibition creates friction without much value.
Best practice: Even though it's off, avoid any where possible. Consider using:
unknown when you don't know the type yetas SomeTypeFuture consideration: You could enable this as a warning and use eslint-disable-next-line any comments for legitimate cases. This makes any usage explicit and searchable.
Leaving implicit any as an error forces you to type that any and feel guilty about it. And you should feel guilty (especially those llms which like to cheat this).
"no-warning-comments": [\n "error",\n {\n terms: ["fixme"],\n location: "anywhere",\n },\n],
Why? FIXME comments are incredibly useful during development - they mark technical debt that you must address before committing. Making this an error ensures you can't forget about them.
\nWorkflow:
\n// FIXME: handle error case freely// TODO: ... if it's truly future workWhy not TODO? TODO comments document intended future improvements. FIXME comments document current problems that shouldn't ship. Use them sparingly and have a plan to do them or remove them from the code. Adding dates can help and there are lint rules that even error when the date is too old.
\n"no-console": [\n "error",\n { allow: ["info", "warn", "error", "dir", "table"] },\n],
Why block console.log? It's a debugging tool. You added it to figure something out, but it shouldn't stay in production code.
\nWhat about logging? Use the allowed methods for intentional logging:
\nconsole.info() - Informational messagesconsole.warn() - Warnings that users should seeconsole.error() - Error messagesconsole.dir() / console.table() - Rich debugging that's intentionally left inFrontend logging: For production frontend logging, use a proper logger (logger.debug(), logger.info(), etc.) that can be configured per environment.
"no-only-tests/no-only-tests": [\n "error",\n {\n focus: ["only", "skip"],\n },\n],
Why? It's incredibly easy to use .only while debugging a test, then forget to remove it. This breaks the entire test suite - but only in CI, after you've pushed.
Similarly, .skip can accumulate forgotten tests that no longer run. They should only be used for flaky tests that we should come back to fixing later. If the test is no longer useful just delete it.
Why the plugin? The old approach using no-restricted-syntax highlighted the entire test block in red. The eslint-plugin-no-only-tests plugin only highlights the .only or .skip portion, making it much easier to spot and fix.
Legitimate uses? Use an inline disable comment:
\n// eslint-disable-next-line no-only-tests/no-only-tests\nit.only('should debug this specific case', () => {\n // ...\n})
This makes the exception explicit and searchable.
\n// Using default from @typescript-eslint/recommended\n"@typescript-eslint/no-unused-vars": "error",
Why error? I've experimented with making this a warning in the past. People ignored warnings and things that aren't in PR checks. Unused variables pollute the codebase and create confusion:
\nMaking it an error forces the cleanup. The cost is minimal - just remove the variable or prefix it with underscore if it's intentionally unused:
\nconst [_data, setData] = useState() // Intentionally unused
What's missing? Notice we're not using @typescript-eslint/stylistic rules for things like:
Why? This is Prettier's job. Running both ESLint stylistic rules and Prettier creates conflict:
\nSingle source of truth: Prettier handles all formatting. ESLint handles logic and bug prevention. No overlap, no conflicts.
\nWhile ESLint handles logic, Prettier handles style. The beauty of Prettier is captured in the Go community's saying about gofmt:
\n\n"Gofmt is no one's favorite, yet gofmt is everyone's favorite."
\n
Prettier embodies this philosophy. You might not agree with every decision, but having one decision that everyone follows is more valuable than having the "perfect" style.
\nHere's my minimal Prettier config:
\n{\n "semi": false,\n}
That's it. Everything else uses Prettier's defaults.
\nsemi: false?You'll often hear these arguments for why semicolons are "best practice" in JavaScript:
\n\n\nClarity and Readability - Explicit semicolons clearly delineate the end of a statement, making the code easier to read and understand.
\nAvoiding Ambiguity and Bugs - ASI can sometimes lead to unexpected behavior or subtle bugs, particularly when line breaks are placed in unusual locations. Explicit semicolons eliminate this ambiguity.
\nConsistency with C-style Languages - If you work with other C-style languages (like Java, C++, or C#) that require semicolons, using them in JavaScript maintains consistency.
\nTeam Standards and Linters - Many professional development environments and teams adopt coding style guides that mandate the use of semicolons to ensure code quality and consistency.
\n
These sound reasonable, but I've found the opposite to be true in practice. I picked up the no-semicolon approach from StandardJS, which provides compelling arguments along with links to these three deep-dives:
\n"Clarity and readability" - Actually, semicolons add visual noise for a character that's not needed. Removing them makes code cleaner and faster to parse.
\n"Avoiding ambiguity and bugs" - This hasn't caused a bug for me or my teams in the last 10 years of not using semicolons. Automatic semicolon insertion handles edge cases, and unreachable code on returns is quite obvious. When semicolons are actually needed, Prettier automatically inserts them, so we can see explicitly where they've been injected purposefully.
\n"Consistency with C-style languages" - Go, which I consider one of the best designed modern languages, also forgoes semicolons (and Python, though do we even count that?). To be fair, Rust has chosen semicolons, but Go is a modern C-style language that explicitly chose to remove them from their standard formatter.
\nIt's worth noting that Go's designers — Robert Griesemer, Rob Pike, and Ken Thompson — had extensive experience with C and systems programming. Ken Thompson co-created the C programming language and Unix, and Rob Pike worked at Bell Labs on Plan 9. Their deep understanding of C's strengths and weaknesses heavily influenced Go's design, including the decision to drop mandatory semicolons.
\nAs explained in Automatic Semicolon Insertion in Go:
\n\n\nWhat is the reason for language designers to even start working on getting rid of tokens like semicolons? The answer is quite simple. It's all about readability. The less artifacts code has, the easier it's to work with. It's important since once written piece of code will be probably read many times by different people.
\n
"Team standards and linters" - Prettier is exactly what this is for, so the style is what's in the repo.
\n1. Code clarity - Knowing where semicolons are needed and removing visual clutter makes code appear cleaner and easier/faster to parse.
\n2. Moving code around is easier - Without trailing semicolons, refactoring becomes more fluid. Think about operations like .map().filter() where you're constantly adding, removing, or reordering chains.
Consider this common scenario:
\n// With semicolons - awkward to refactor\nconst users = getUsers();\nconst activeUsers = users.filter(u => u.active);\n \n// Want to chain another operation? You need to:\n// 1. Remove the semicolon from line 1\n// 2. Add your new operation\nconst users = getUsers()\n .filter(u => u.active);
// Without semicolons - natural refactoring\nconst users = getUsers()\nconst activeUsers = users.filter(u => u.active)\n \n// Want to chain? Just move the code\nconst users = getUsers()\n .filter(u => u.active)
When copying and pasting code, adding filters, or splitting chains, semicolons create friction. Remove them, and code movement becomes fluid.
\nJavaScript's Automatic Semicolon Insertion (ASI) handles this automatically, and TypeScript catches the edge cases where ASI might cause problems.
\nNote: I'll change code to use semicolons just to speed things up when needed, but more for saving time from bikeshedding this one and less because I think they're necessary.
\nBiome is a newer formatter that's gaining traction. It's:
\nBiome's philosophy: "A formatter should have as few options as possible." They provide even less configuration than Prettier, which is a good thing - fewer decisions mean less bikeshedding.
\nIf you're starting a new project and want bleeding-edge tooling, Biome is worth considering. For existing projects, Prettier's ecosystem maturity is hard to beat.
\nPick one formatter (Prettier or Biome), configure it minimally, and enforce it everywhere. The specific choices matter less than everyone using the same tool.
\nThe hardest rule to adopt is react-hooks/exhaustive-deps. In a large codebase, you might have hundreds of violations. Fixing them all at once is impractical and risky.
Here's the strategy:
\neslint-disable-next-line to all existing violationsSave this as scripts/eslint-one-time-allow.ts:
// This script reads all the .ts and .tsx files in the src directory and disables\n// all the eslint errors of a specific rule (default: react-hooks/exhaustive-deps).\n// This is intended to be used to grandfather existing problems so that future\n// problems can be fixed. It may also be useful to disable other future eslint\n// errors that need to be allowed until such a time that they can be fixed.\n \n// usage: tsx scripts/eslint-mass-allow.ts --add-allow-comments\n// usage: tsx scripts/eslint-mass-allow.ts --rule @typescript-eslint/no-unused-vars --add-allow-comments\n \nimport { Command } from "@commander-js/extra-typings"\nimport * as fs from "fs"\nimport { ESLint } from "eslint"\n \nconst program = new Command()\n \nprogram\n .name("eslint-mass-allow")\n .description("Mass fix ESLint errors by adding disable comments")\n .option("--add-allow-comments", "Actually add the allow comments (dry run by default)")\n .option(\n "--rule <rule>",\n "ESLint rule to allow",\n "react-hooks/exhaustive-deps"\n )\n .parse()\n \nconst options = program.opts() as { addAllowComments?: boolean; rule: string }\n \nasync function main() {\n const eslint = new ESLint()\n const results = await eslint.lintFiles(["src/**/*.ts", "src/**/*.tsx"])\n \n let totalErrors = 0\n let filesToFix = 0\n \n for (const result of results) {\n if (result.errorCount > 0) {\n const targetErrors = result.messages.filter(\n (message: any) => message.ruleId === options.rule\n )\n \n if (targetErrors.length > 0) {\n filesToFix++\n totalErrors += targetErrors.length\n \n console.log(\n `${result.filePath}: ${targetErrors.length} ${options.rule} errors`\n )\n \n if (options.addAllowComments) {\n const fileContent = fs.readFileSync(result.filePath, "utf-8")\n .split("\\n")\n let offset = 0 // Track the number of lines added\n \n for (const message of targetErrors) {\n const lineIndex = message.line - 1 + offset\n fileContent.splice(\n lineIndex,\n 0,\n `// eslint-disable-next-line ${message.ruleId}`\n )\n offset++\n }\n \n fs.writeFileSync(result.filePath, fileContent.join("\\n"), "utf-8")\n }\n }\n }\n }\n \n console.log(`\\nSummary:`)\n console.log(`Files with ${options.rule} errors: ${filesToFix}`)\n console.log(`Total errors: ${totalErrors}`)\n \n if (!options.addAllowComments) {\n console.log(\n `\\nThis was a dry run. Use --add-allow-comments to apply the changes.`\n )\n } else {\n console.log(`\\nAdded allow comments for ${totalErrors} errors in ${filesToFix} files.`)\n }\n}\n \nmain()\n .then(() => {\n console.info("Done")\n })\n .catch((error) => {\n console.error("Error:", error)\n })
# Dry run - see what would be allowed\nnpx tsx scripts/eslint-mass-allow.ts\n \n# Actually add the allow comments\nnpx tsx scripts/eslint-mass-allow.ts --add-allow-comments\n \n# Allow a different rule (e.g., unused variables)\nnpx tsx scripts/eslint-mass-allow.ts --rule @typescript-eslint/no-unused-vars --add-allow-comments
This approach lets you:
\nYou might have noticed we're using defineConfig() instead of the older tseslint.config():
import { defineConfig } from "eslint/config"\n \nexport default defineConfig(\n eslint.configs.recommended,\n tseslint.configs.recommended,\n // No spread operators needed!\n)
This is the new recommended approach from typescript-eslint. Benefits:
\nIf you're still using the old format:
\nexport default tseslint.config(\n eslint.configs.recommended,\n ...tseslint.configs.recommended, // Spreading required\n)
Update to the new format. It's a simple find-and-replace.
\nLINTING.md file explaining each custom ruleInline disable comments are fine when:
\nJust make it explicit:
\n// We need any here because the API returns dynamic structure\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nconst data: any = await fetchDynamicData()
Run linting before tests:
\n- name: Lint\n run: npm run lint\n \n- name: Type Check\n run: npm run typecheck\n \n- name: Test\n run: npm test
Fast feedback on code quality issues.
\nThe configuration above uses tseslint.configs.recommended. For deeper type checking, consider:
export default defineConfig(\n eslint.configs.recommended,\n ...tseslint.configs.recommendedTypeChecked,\n {\n languageOptions: {\n parserOptions: {\n project: './tsconfig.json',\n },\n },\n },\n)
This enables rules like:
\n@typescript-eslint/no-floating-promises - Catch unhandled promises@typescript-eslint/no-misused-promises - Type-check async/await usage@typescript-eslint/await-thenable - Only await actual promisesTrade-off: Significantly slower linting (requires full TypeScript compilation).
\nFor new projects with no legacy code:
\nexport default defineConfig(\n eslint.configs.recommended,\n tseslint.configs.strict, // Instead of recommended\n tseslint.configs.stylistic,\n // ... your rules\n)
The strict preset includes more opinionated rules that catch subtle bugs.
defineConfig() with ESLint 9This configuration has been battle-tested across multiple teams and projects. It:
\nMost importantly, developers don't fight it. When ESLint complains, there's usually a good reason.
\nHave a different approach to ESLint configuration? I'd love to hear what works for your team!
", "url": "https://alexmchan.com/blog/2025-10-21-pragmatic-eslint", "title": "Pragmatic ESLint: My recommendations", "summary": "A philosophy-driven approach to ESLint configuration that catches bugs without getting in your way, with practical migration strategies for real codebases.", "date_modified": "2025-10-21T00:00:00.000Z", "author": { "name": "Alex Chan" } }, { "id": "https://alexmchan.com/blog/2025-10-17-msw-jest-vite", "content_html": "If you've tried setting up Mock Service Worker (MSW) v2 with Jest, you've probably hit this error:
\n\nSyntaxError: Unexpected token 'export'\n
I spent an afternoon figuring out why, and the answer reveals something important about the JavaScript testing ecosystem in 2024.
\nMSW v2 embraced modern JavaScript by shipping as ESM (ECMAScript Modules). This is great for the ecosystem, but it creates a challenge: most test runners still operate in a CommonJS world.
\nWhen Jest tries to run your tests, it encounters ESM code in node_modules and doesn't know what to do with it. By default, Jest ignores everything in node_modules - it assumes packages are pre-compiled and ready to run.
But MSW v2 isn't. Neither is its dependency until-async. They contain raw export statements that Node's CommonJS loader can't parse.
My first attempt was the standard advice you'll find online:
\ntransformIgnorePatterns: [\n 'node_modules/(?!(msw)/)',\n]
Result: Still broken. The error was coming from until-async, a transitive dependency.
Okay, let me enumerate all the ESM packages:
\ntransformIgnorePatterns: [\n 'node_modules/(?!(msw|@mswjs|@open-draft|until-async|...)/)',\n]
Result: Still broken. The regex wasn't matching packages in pnpm's nested structure: node_modules/.pnpm/until-async@3.0.2/node_modules/until-async/
transformIgnorePatterns: []
Finally! Tests pass. But now Jest is transforming everything in node_modules, including all of axios, and any other package. This works but doesn't scale.
The breakthrough was understanding that the pattern needs to match the package name anywhere in the path, not just immediately after node_modules/:
transformIgnorePatterns: [\n 'node_modules/(?!.*(msw|until-async))',\n]
This pattern:
\nHere's what you actually need for Jest + MSW v2:
\n// jest.config.js\nmodule.exports = {\n preset: 'ts-jest',\n testEnvironment: 'node',\n setupFilesAfterEnv: ['<rootDir>/src/setupTests.ts'],\n \n // The critical part: transform MSW's ESM dependencies\n transformIgnorePatterns: [\n 'node_modules/(?!.*(msw|until-async))',\n ],\n \n // ts-jest needs to transform both TS and JS files\n transform: {\n '^.+\\\\.tsx?$': 'ts-jest',\n '^.+\\\\.jsx?$': ['ts-jest', {\n tsconfig: {\n allowJs: true, // Allow ts-jest to process JavaScript\n },\n }],\n },\n};
Why the JS transform matters: By default, ts-jest only transforms TypeScript files. But MSW's dependencies are JavaScript. The explicit transform config with allowJs: true tells TypeScript's compiler to process those JS files too.
Want to skip all that complexity? Here's the equivalent Vitest config:
\n// vitest.config.ts\nimport { defineConfig } from 'vitest/config';\n \nexport default defineConfig({\n test: {\n globals: true,\n environment: 'node',\n setupFiles: ['./src/setupTests.ts'],\n include: ['src/**/*.test.ts'],\n },\n});
That's it. No transformIgnorePatterns. No special handling for ESM. No listing dependencies.
Vitest uses Vite under the hood, which was designed for the ESM era. It handles MSW's modern module format natively.
\nI ran the same two tests with both runners:
\n| Test Runner | Time | Configuration Complexity |
|---|---|---|
| Jest | 1.08s | High (transform patterns, allowJs, etc.) |
| Vitest | 0.38s | Low (basic test config only) |
Vitest is 2.8x faster and requires significantly less configuration.
\ntransformIgnorePatterns breakthroughThe pattern 'node_modules/(?!.*(msw|until-async))' is the key. It matches package names at any nesting level, so it works with:
node_modules/msw/lib/index.jsnode_modules/.pnpm/until-async@3.0.2/node_modules/until-async/lib/index.jsI initially listed 8+ packages in the transform pattern. In reality, only msw and until-async needed it.
Principle: Add packages to the transform list only when you encounter actual errors. This keeps your config maintainable and your transform step fast.
\nJest was designed in 2014 when CommonJS was the standard. It works great, but it shows its age when dealing with ESM.
\nVitest was designed in 2021 with ESM as a first-class citizen. The difference is striking.
\nallowJs: trueWhen using ts-jest, you need to explicitly allow JavaScript transformation:
'^.+\\\\.jsx?$': ['ts-jest', {\n tsconfig: { allowJs: true },\n}],
Without this, ts-jest skips the ESM files in node_modules, and they remain unparseable.
\nFor new projects: Use Vitest. The simplicity speaks for itself.
\nFor existing Jest projects: Use the optimized pattern shown above. It scales well and works across package managers.
\nWhen debugging: If you hit ESM errors, check the actual file path in the error message. That tells you exactly which package needs to be added to your transform pattern.
\nWant to see the full setup? Check out the demo repo: jest-with-msw
\nThe repo includes:
\nThe JavaScript ecosystem is in a transition period. ESM is the future, but CommonJS is still deeply embedded in our tooling.
\nJest remains an excellent test runner - mature, feature-rich, and widely adopted. But when dealing with modern ESM packages like MSW v2, you'll need to bridge that gap with careful configuration.
\nVitest represents the next generation: built for ESM from day one, faster by default, and refreshingly simple to configure.
\nThe choice depends on your constraints. But after spending an afternoon wrestling with transformIgnorePatterns, I know which one I'll reach for next time.
What's your experience with Jest and ESM? Have you made the switch to Vitest? Let me know in the comments!
", "url": "https://alexmchan.com/blog/2025-10-17-msw-jest-vite", "title": "Fixing msw with jest compilitation", "summary": "MSW is great just takes some additional config for jest for esm support", "date_modified": "2025-10-17T00:00:00.000Z", "author": { "name": "Alex Chan" } }, { "id": "https://alexmchan.com/blog/2024-10-19-ten-things-i-learnt-from-go-as-a-js-developer", "content_html": "There's always been enough changing in the Javascript and TypeScript ecosystem that there's always been another thing to learn. Although I knew go would be faster, I had always thought that it would complicate the stack as a single developer or even a small team of developers to have to clutter the stack with another language.
\nWhat I found was that once past the initial learning curve, the speed and simplicity of go made it a great addition to my toolbelt. Here are ten things I learnt that made me a better JS developer.
\nGo actually has a relatively small surface area. It has fewer choices in many areas because the go team and community have made so many decisions and placed a lot into the standard library.
\nComing from languages like javascript there are always the option to use classes. Interfaces provide a clean way to implement a contract without the need for classes. If it walks like a duck and talks like a duck, it's a duck (ok Ruby I know you taught that to us too but classes tempt everyone to the dark side).
\nI've never loved inheritance and it's great to see that you can design great things without them entirely. Rust is also a modern language that has completely done away with classes.
\nThere's no try catch in go. The preferred interface is to return an error as a second argument. This means a few things:
func main() {\n result, err := doSomething()\n if err != nil {\n log.Fatal(err)\n }\n fmt.Println(result)\n \n sum, err := doSomethingElse()\n if err != nil {\n log.Fatal(err)\n }\n}
The main thing to note here is that the result can be used without the problem in javascript of defining a value outside of a closure. Also we don't have a giant catchall that has to figure out far from the error what the error was.
\nThe more javascript equivalent would be:
\nfunction main() {\n let result\n try {\n result = doSomething()\n } catch (err) {\n console.error(err)\n }\n console.log(result)\n \n let sum\n try {\n sum = doSomethingElse()\n } catch (err) {\n console.error(err)\n }\n}
But in reality we normally see a giant try catch block around the entire function and so many errors are silently ignored.
In JS I've experimented with neverthrow which definitely helps to use a more explicity return type but there's definitely a learning curve to the rest of the team and while the small try catch loop is a bit ugly, there's not necessarily as much to learn. Which leads me to...
It's better to have simpler code, fewer good ways to do something, and have code look the same than to have hundreds and everyone doing something different.
\nA better api is often the simpler one.
\nThis is a hard one for me, I've always liked descriptive names but in go it's common to have short variable names. This is because the scope of the variable is often very small and the type is often very clear. Lean to having smaller more focused scopes and good interfaces describing the variables. Even declaring a func is shortened!
Early return isn't just recommended, it's the norm. This is because the error handling is so explicit and the return values are so clear that it's easy to see what's happening. This helps prevent a lot of nested if's and code that is hard to follow because it's not clear what the return value is or has shifted so much to the right.
\nComments are just // in go. There's no go doc special formatting to learn. If the comment appears above a function, it magically becomes the documentation for it.\nfunc add(a int, b int) example:
// Adds two numbers together\nfunc add(a int, b int) {\n return a + b\n}
contrast this with jsdoc
\n/**\n * Adds two numbers together\n * @param {number} a\n * @param {number} b\n * @returns {number}\n */\nfunction add(a, b) {\n return a + b\n}
Context is a special concept in go that allows to pass around both values (which is normal but not idiomatic in js), but also a way to timeout or cancel a request. This is a great way to handle timeouts and cancellations in a way that is built into the language.
\n\nfunc main() {\n ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)\n defer cancel()\n \n result, err := doSomething(ctx)\n if err != nil {\n log.Fatal(err)\n }\n fmt.Println(result)\n}\n \nfunc doSomething(ctx context.Context) (string, error) {\n select {\n case <-ctx.Done(): // this check allows a function to check for the timeout and exit gracefully\n return "", ctx.Err()\n default:\n return "done", nil\n }\n}
Ordered params are ok in other languages but I've long held the belief that named params are better. In go, the idiomatic way is to use ordered params. This is because the function signature is often very clear and the function is often very small.
\nSo I've updated my belief that if the function is small and the params are clear, ordered params are ok. I'm still going to dread refactoring back to a named param function (or single interface in go) when I want to go back.
\nThis is not a hard and fast rule but something I learned from more people in the go community than not. This is because it's often better to have a small package that does one thing well and is easy to understand. This is a great way to keep the codebase clean and easy to understand.
\nThis post from Dave Cheney explains it well.
\n\n\nName your packages after what they provide, not what they contain.
\n
There's still a few thorns in the roses.
\nconst { a = 1 } = {} in go.There's far more to like about go than dislike, and I'm glad I took the time to learn it. It's made me a better JS developer and I'm sure it will make me a better developer in general. I'm looking forward to using it more in the future.
", "url": "https://alexmchan.com/blog/2024-10-19-ten-things-i-learnt-from-go-as-a-js-developer", "title": "Ten things I learnt from go as a JS developer", "summary": "I avoided learning go thinking it was too different from JS. Here are ten things I learnt that made me a better JS developer.", "date_modified": "2024-10-19T00:00:00.000Z", "author": { "name": "Alex Chan" } }, { "id": "https://alexmchan.com/blog/2024-10-14-more-cli-tips", "content_html": "It's even faster than I originally described for a fast one off script.
\nThe prompt is
\nUsing @commander-js/extra-typings and @inquirer/prompts, and jsdoc typescript types\n \nbuild a cli that does the following...\n \n[describe the cli]\n \nexample header\n \n#!/usr/bin/env node\n// @ts-check\nimport { Command } from '@commander-js/extra-typings'\nimport { confirm } from '@inquirer/prompts'\nimport { $ } from 'zx'\n \n$.verbose = true
brocli looks very nice interface to a cli than commander.
\nexecaExeca works well for simple cases but it had a few extra protections when just wanting to replace a shell script.
\nThis included
\n|)These were enough gotchas to want to use zx instead. The extra escaping might be useful if you are running user input,\nbut that seems incredibly scary and would want to avoid that for most cases so for now zx as the default seems ok.
I've written a package that does this and more: https://cache.alexmchan.com, features include
\nIf one wants cross request cache queries in a node server, one can use a simple cache api inspired by react-query with only a redis library implementation.
\nimport Redis from 'ioredis'\n// or setup a redis connection in a separate file with creds etc\n// import { redis } from '@/server/redis' // ioredis instance redis = new Redis()\n \nconst redis = new Redis()\n \ntype CacheOptions = {\n ttlInSeconds: number // seconds\n skipCache?: boolean\n}\n \n// An api similar to react query's useQuery\nexport async function cacheQuery<T>({\n queryKey,\n queryFn,\n options = {\n ttlInSeconds: 60 * 5,\n skipCache: false,\n },\n}: {\n queryKey: QueryKey\n queryFn: () => Promise<T>\n options?: CacheOptions\n}): Promise<T> {\n const key = hashKey(queryKey)\n \n if (!options?.skipCache) {\n const cached = await redis.get(key)\n if (typeof cached === 'string') {\n try {\n if (process.env.LOG_LEVEL === 'debug') {\n console.log('Cache hit', key)\n }\n const parsed = JSON.parse(cached)\n return parsed as T\n } catch (e) {\n console.error('Error parsing cached data', e)\n }\n }\n }\n \n return queryFn?.().then(async (data) => {\n if (process.env.LOG_LEVEL === 'debug') {\n console.log('Cache miss', key)\n }\n try {\n await redis?.set?.(key, JSON.stringify(data), 'EX', options?.ttlInSeconds)\n } catch (e) {\n console.error('Error caching data', e)\n }\n return data\n })\n}\n \n/**\n * Default query & mutation keys hash function.\n * Hashes the value into a stable hash.\n * https://github.com/TanStack/query/blob/69d37f33bdee50d73d0f05256f243113a857a1ee/packages/query-core/src/utils.ts#L177\n */\nexport type QueryKey = ReadonlyArray<unknown>\n \nexport function hashKey(queryKey: QueryKey): string {\n return JSON.stringify(queryKey, (_, val) =>\n isPlainObject(val)\n ? Object.keys(val)\n .sort()\n .reduce((result, key) => {\n result[key] = val[key]\n return result\n }, {} as any)\n : val\n )\n}\n \nfunction hasObjectPrototype(o: any): boolean {\n return Object.prototype.toString.call(o) === '[object Object]'\n}\n \n// Copied from: https://github.com/jonschlinkert/is-plain-object\nexport function isPlainObject(o: any): o is Object {\n if (!hasObjectPrototype(o)) {\n return false\n }\n \n // If has no constructor\n const ctor = o.constructor\n if (ctor === undefined) {\n return true\n }\n \n // If has modified prototype\n const prot = ctor.prototype\n if (!hasObjectPrototype(prot)) {\n return false\n }\n \n // If constructor does not have an Object-specific method\n if (!prot.hasOwnProperty('isPrototypeOf')) {\n return false\n }\n \n // Most likely a plain Object\n return true\n}\n \nexport function isPlainArray(value: unknown) {\n return Array.isArray(value) && value.length === Object.keys(value).length\n}
Remember that this is a simple cache and either needs user id validation prior and caching with the user id or a more complex cache key generation.
", "url": "https://alexmchan.com/blog/2024-06-17-node-cache", "title": "A simple node cache api", "summary": "Trying a react-query inspired node cache", "date_modified": "2024-06-17T00:00:00.000Z", "author": { "name": "Alex Chan" } }, { "id": "https://alexmchan.com/blog/2023-12-08-cli-tip-package-managers", "content_html": "They're great. The only problem is when I don't remember which I chose for a project.
\nAdd this to your .zshrc or .bashrc and give the command an alias that you like.
function p {\n # Get the root of the Git repo for mono-repos\n local git_root\n git_root=$(git rev-parse --show-toplevel 2>/dev/null)\n \n # If the Git root is empty, then we're not in a Git repo so use the current folder\n if [ -z "$git_root" ]; then\n git_root="."\n fi\n \n local lock_file\n if [ -e "$git_root/yarn.lock" ]; then\n lock_file="yarn.lock"\n elif [ -e "$git_root/pnpm-lock.yaml" ]; then\n lock_file="pnpm-lock.yaml"\n elif [ -e "$git_root/package-lock.json" ]; then\n lock_file="package-lock.json"\n else\n echo "No lock file found in the Git root. Initialize the project with Yarn, pnpm, or npm."\n fi\n \n # Run the command with the lock file\n if [ "$lock_file" = "yarn.lock" ]; then\n # shortcut to make this more like npm i, yarn doesn't have yarn i so we'll add it in to mirror that functionality\n if [ "$1" = "i" ]; then\n shift\n yarn install "$@"\n else\n yarn $*\n fi\n elif [ "$lock_file" = "pnpm-lock.yaml" ]; then\n pnpm $*\n elif [ "$lock_file" = "package-lock.json" ]; then\n npm $*\n else\n echo "No lock file found in the Git root. Initialize the project with Yarn, pnpm, or npm. Falling back to pnpm"\n pnpm $*\n fi\n}
Pre-emptive pluralization is described by swyx here. The TLDR is that we should try to assume plurality where we can since going from plural to handle singular is easier than the reverse.
\nHere's a few concrete examples of quick wins that can pre-emptively pluralize your react code.
\nThere's a few ways to declare functions.
\nOption 1) There's ordered functions:
\nfunction doWork(first: string, second: number, third?: boolean) {}
Option 2) the next version is a single prop with everything:
\nfunction MyComponent({\n first,\n second = 5,\n third,\n}: {\n first: string\n second?: number\n third?: boolean\n}) {\n //..\n}
Option 3) The last is a mix of the two:
\ntype Props = {\n first: string\n options: { second: number; third?: boolean }\n}\n \nfunction MyComponent(\n first: string,\n options: { second: number; third?: boolean }\n) {\n //..\n}
Which do we choose and why? In almost all cases, it's easier to start with and never change option 2) a single prop with everything. This has the advantages of:
\n({ orderId, customerId }) can be safer than (customerId, orderId) if the function is typed (orderId: string, customerId: string) => nullThe only downside is that it's a bit more verbose and there's more typing. Edit 2025: LLMs often prefer to declare ordered props, however they can be instructed to prefer named via memory (cursor rules etc).
\nWhy avoid the third option with a convenience mandatory field and then options next? Just going by react-query's recent move they shifted to having named parameters for everything. This helps clarify the intent and makes it easier to add new options. It's also easier to add new options without breaking existing code.
\nThe other reason to start with option 2) is that it takes away the guesswork, should I start with ordered then move to plural? What's the magic number where it's better? Do I really want to refactor when I come in next time and try to replace all the instances where this is called? What do I do when I want to make one of the first parameters optional?
\nStart with a single prop and don't look back.
\nThis is a bit of a weird one but it's worth doing. If you have a file with a single export, it's worth naming it. This is because if you ever need to add a second export, it's as easy as adding a second export. If you don't name it, you need to go back and change all the imports. This is a bit of a pain and it's easier to just name it from the start. They also have the advantage of not forcing the user to guess the filename and can help with autocomplete (but this is better now with many editors).
\nPopular libraries that have started with defaults and moved to named include zod, immer and even react.
Default exports are the most useful for frameworks where the default indicates something of importance such as the page in nextjs, if this isn't you, it's better to start pluralized here.
\n// bad\nexport default const Something = () => {}\n \n// prefer\nexport function Something() { }\n \n// import\nimport { Something } from './something'
React says this about exports:
\n\n\nPeople often use default exports if the file exports only one component, and use named exports if it exports multiple components and values
\n
However, we as developers have a lot of decisions to make and starting with named exports means we can always have the same rule and never have to refactor when we go from default to named. Predicting the future is hard and I like having the decision that supports faster iteration. As an added bonus, you don't need to type default! Win win!
This one is actually a little harder to do. When building an api it's sometimes tempting to return just the singular version of an item. /api/items/:id. But in reality it's probably good to plan for an array of items /api/items?ids=. This is because it's easier to go from an array to a single item than the other way around. It's also easier to add a second item to an array than to change a single item to an array. The plural case also handles the singular case.
undefined or null - multiple undefined typesThis is plan for the plurality of undefineds (a stretch I know). In js it's typically better to use optional chaining to access anything outside of the direct control of the current function and especially for any api out of one's control. The easiest way to do that is to use optional chaining where the data?.item?.value is accessed rather than throwing and making the entire application unusable for an unplanned undefined. Usually it's better to have most of the app work than just a subsection. If it's really important to have errors when this happens, use zod to define the schema and throw an error if it's not valid.
What we've seen is that most of the larger js tooling that uses config ends up moving towards a .js or ts file at least as an option rather than just a pure .json file. The reason for this is the plurality of environments and configuration. This is actually relatively easy to do up front by using something like cosmicconfig. Here we can provide the options of ts, js, mjs, and even yaml for yaml lovers (all 3 of you). Examples of this are eslint, babel, webpack, prettier and tailwind. These files allow imports, plugins, dynamic setup, and code based configuration and merging of external config. This is a huge win for plurality by just using cosmicconfig.
I bet you didn't think we could fit more @tanstack/react-query into this, but there's a subtle plurality hidden within this that we can't get by managing requests ourselves and that's out of order requests (race conditions) as well as automatic retries for network failures. TkDodo's blog post on this goes in depth.
\nThere's a lot of quick wins that don't cost much in the land of preemptive pluralization. It's worth doing them early and often. It's also worth doing them even if you don't think you'll need them. In many cases it can be easier to go from plural to singular than the other way around so starting with more options early can save time in the long run.
", "url": "https://alexmchan.com/blog/2023-11-08-named-props-and-plurality", "title": "Small plans for plurality in react and ts", "summary": "Some plans for plurality have a low cost so it is worth doing them even if you are not sure if you will need them.", "date_modified": "2023-11-08T00:00:00.000Z", "author": { "name": "Alex Chan" } }, { "id": "https://alexmchan.com/blog/2023-10-10-cli", "content_html": "I recently noticed that shadcn's cli is really well organized. Sometimes it's useful to have a single one off command to run in a project. There's also a lot of useful utilities to use within scripts but finding the right library can be challenging.
\nThere's lots of other options in cli frameworks such as ink and oclif but commander can often solve a lot of the one off script writing issues quickly and with the template below we can require minimal doc reading before getting the part we all came for, writing the script. clipanion, yargs and others have all been on the menu at some stage but I keep coming back to commander. It's pretty easy to get setup, has a decent default help setup, and has support for multiple commands.
By using Commander, dotenv and zod (or extra-typings) we can make a type safe command really quickly. Also we'll go into a set of useful utility libraries to solve some more common cli issues. I'll try to update this as I find more useful libraries.
\nI've had to write a lot of bash scripts and I much prefer writing conditionals, handling async work, and writing the helpfiles in ts for anything beyond a few lines of shell scripts.
\nIf you don't want to learn all of the libs, most modern llms recognize them although the npm prompts library can be sometimes wrong.
write a ts shell script that takes an array of directories and an array packages to bump.\n \ngit clone each repo\ncd into each repo\ncheckout a branch provided from the cli for the name and default to yyyy-mm-dd-hhmmss-update-deps\ncreate a pr if there are changes with the gh cli\nmake sure to check the package directory to know which package manager to use\nalso accept --repo-file that has each repo on a new line\nthe checkout will be into the current directory by default but it can be specified with --checkout-directory\n \nuse these libraries:\n \nimport prompts from 'prompts' // https://www.npmjs.com/package/prompts\nimport ora from 'ora' // for spinners\nimport { $ } from 'execa' // for executing external cli items, zx is sometimes better for stdout processing\nimport { Command } from '@commander-js/extra-typings'
Then just install and run the ts file with tsx, bun or deno
yarn/pnpm add dotenv commander and zod
Setup the cli, customize the schema and add the command.
\n#!/usr/bin/env node\n \nimport { config } from 'dotenv'\nimport { Command } from 'commander'\nimport { z } from 'zod'\n \nconfig() // initialize anything from .env\n \nconst exampleCommand = new Command()\n .command('example-command')\n .argument('[toppings...]', 'toppings args') // [optional...] array of strings\n .description('example command')\n .option('-e, --example <example>', 'example option', 'default')\n // The action handler gets passed a parameter for each `argument` declared, and two additional parameters which are the parsed options and the command object itself.\n .action(async (toppings, opts, command) => {\n try {\n const exampleCommandSchema = z.object({\n toppings: z.array(z.string()).optional(),\n example: z.string().optional(),\n })\n \n const options = exampleCommandSchema.parse({\n toppings,\n ...opts,\n })\n \n // do something with those options\n console.log({ options, command })\n } catch (error) {\n console.error(error)\n process.exit(1)\n }\n })\n \nconst program = new Command()\n .name('example-program')\n .description('example program')\n \nprogram.addCommand(exampleCommand, { isDefault: true })\nprogram.parse(process.argv)
actionThe action handler gets passed a parameter for each argument declared, and two additional parameters which are the parsed options and the command object itself. So when we copy a command we need to be careful of the position of the arguments to the action handler.
const argsParseExample = new Command()\n .command('args-parse-example')\n .description('another way to parse args')\n // these determine the order of the arguments to the action handler\n .argument('<source>', 'topping arg') // <required>\n .argument('[destination]', 'oven') // [optional]\n // these are all in the second to last options parameter\n .option('-e, --example <example>', 'example option', 'default')\n .action(async (...args) => {\n try {\n const [source, destination, opts, command] = args\n // if we only are ever interested in opts and command we can always take them from the end of the args array\n // const opts = args?.[args.length - 2]\n // const command = args?.[args.length - 1]\n \n const exampleCommandSchema = z.object({\n source: z.string(),\n destination: z.string().optional(),\n example: z.string().optional(),\n })\n \n const options = exampleCommandSchema.parse({\n source,\n destination,\n ...opts,\n })\n \n // do something with those options\n console.log({ options, command })\n } catch (error) {\n console.error(error)\n process.exit(1)\n }\n })
If we don't want to use zod, we can use the extra-typings package.
\n#!/usr/bin/env node\nimport { Command } from '@commander-js/extra-typings'\n \nconst program = new Command()\n .argument('[toppings...]', 'toppings args')\n .description('example command')\n .option('-e, --example <example>', 'example option', 'default')\n // The action handler gets passed a parameter for each `argument` declared, and two additional parameters which are the parsed options and the command object itself.\n .action(async (toppings, opts, command) => {\n try {\n // do something with those options\n console.log({ toppings, opts })\n } catch (error) {\n console.error(error)\n process.exit(1)\n }\n })\n \nprogram.parse(process.argv)
Adding more commands just takes adding a new command and calling the addCommand method. As this expands, the commands can be moved into their own files as we can see from shadcn's cli.
#!/usr/bin/env node\nimport { add } from '@/src/commands/add'\nimport { diff } from '@/src/commands/diff'\nimport { init } from '@/src/commands/init'\nimport { Command } from 'commander'\n \nimport { getPackageInfo } from './utils/get-package-info'\n \nprocess.on('SIGINT', () => process.exit(0))\nprocess.on('SIGTERM', () => process.exit(0))\n \nasync function main() {\n const packageInfo = await getPackageInfo()\n \n const program = new Command()\n .name('shadcn-ui')\n .description('add components and dependencies to your project')\n .version(\n packageInfo.version || '1.0.0',\n '-v, --version',\n 'display the version number'\n )\n \n program.addCommand(init).addCommand(add).addCommand(diff)\n \n program.parse(process.argv)\n}\n \nmain()
If there aren't any types defined, a .mjs and adding a "type": "module" to the package.json will allow the command to be run.
When using a .ts file, tsx, bun or ts-node --swc can be used to run the command.
# pick your favorite runner\n$ tsx ./src/example-cli.ts\n$ ts-node --swc ./src/example-cli.ts\n$ bun ./src/example-cli.ts
Optionally include the shebang to run the command directly and chmod +x the file.
\n#!/usr/bin/env ts-node --swc
Running from cli will require some bundling, adding a build script, a bin.
"scripts": {\n "build:cli": "esbuild --bundle --outdir=dist --platform=node --target=node18 ./src/example-cli.ts"\n },\n "bin": {\n "examplecommand": "./dist/example-cli.js",\n },
Then publishing to npm or run npm link from the package folder if there's only have a repo. If using volta and npm link to link the package, use volta which example-cli to find the package location afterwards.
I've been using zx from google to run external commands. It's a nice way to run external commands and scripts. Other options in this space are execa which also supports the scripts interface which is a really nice alternative for calling other bash shell commands. (2024 update: I've been preferring zx more and more as it's a bit more flexible and has a nicer interface.)
import { $ } from 'zx'\n \nawait $`docker build -f ${dockerfile} -t ${imageUri} ${dockerContext}`
Use prompts to get user input. Don't forget those types.
\n$ pnpm add prompts @types/prompts
import prompts from 'prompts'\n \nconst response = await prompts({\n type: 'number',\n name: 'howMuch',\n message: 'How much would you pay for this?',\n validate: (value) =>\n value < 5 ? `Sorry, please spend a bit more to run this cli` : true,\n})\n \nconsole.log(response.howMuch)
Try ora for spinners.
\nimport ora from 'ora'\nimport { $ } from 'execa'\n \nconst spinner = ora(`Working...`).start()\nawait $`sleep 2`\nspinner.text = 'More work...'\nawait $`sleep 2`\nspinner.succeed(`Done.`)
Use chalk for colors.
\nimport chalk from 'chalk'\n// import { chalk } from 'zx' // also included with zx\nconsole.log(chalk.green('Success!'))
Copy text to clipboard for mac/windows/wsl.
\nimport clipboardy from 'clipboardy'\nimport isWsl from 'is-wsl'\n \nexport function writeToClipboard({ text }) {\n if (isWsl) {\n exec(`echo "${text}" | clip.exe`)\n } else {\n clipboardy.write(text)\n }\n}
It's often useful to list a pattern of files or all files in a subdirectory using a wildcard. Fast glob patterns are a nice way to specify everything within a subdirectory.
\nimport fg from 'fast-glob'\nimport zlib from 'zlib'\nimport { z } from 'zod'\nimport fs from 'fs'\nimport { Command } from 'commander'\n \nconst program = new Command()\n .name('list of files')\n .option(\n '-f, --files <file>',\n 'file glob see https://github.com/mrmlnc/fast-glob ',\n './src/**/*.tsx'\n )\n .action(async (opts) => {\n try {\n const fileGlobSchema = z.object({\n files: z.string().min(1),\n })\n \n const options = fileGlobSchema.parse(opts)\n \n const filesGlob = await fg([options.files], { dot: false })\n filesGlob.forEach((filePath) => {\n console.log(filePath)\n \n let fileContents = ''\n if (filePath.endsWith('.gz')) {\n fileContents = zlib.gunzipSync(fs.readFileSync(filePath)).toString()\n } else {\n fileContents = fs.readFileSync(filePath, 'utf8').toString()\n }\n })\n } catch (error) {\n console.error(error)\n process.exit(1)\n }\n })\n .parse(process.argv)
When config goes beyond a .env file, cosmicconfig helps to load all forms of config, including functions from js or ts files and not just json.
\nimport { cosmiconfig } from 'cosmiconfig'\n \nasync function getConfig({ region }) {\n const moduleName = 'example'\n const explorer = cosmiconfig(moduleName)\n \n try {\n const result = await explorer.search()\n \n let config = result.config\n if (typeof result.config === 'function') {\n const accountId = await getAccountId()\n config = await result.config({ region, accountId })\n }\n \n return {\n ...result,\n config,\n }\n } catch (error) {\n console.log(`Error parsing or no ${moduleName} config found. Searched\n 'package.json',\n .${moduleName}rc,\n .${moduleName}rc.json,\n .${moduleName}rc.yaml,\n .${moduleName}rc.yml,\n .${moduleName}rc.js,\n .${moduleName}rc.cjs,\n .${moduleName}rc.ts,\n ${moduleName}.config.js,\n ${moduleName}.config.ts,\n ${moduleName}.config.cjs,`)\n console.error(error)\n \n return null\n }\n}
If there's a lot of work to be done, execution in parallel can speed things up. One thing to keep in mind while doing this is that we also don't want to overwhelm the target or hit api limits. p-map allows for concurrency limits.
\nimport pMap from 'p-map'\nimport { setTimeout } from 'node:timers/promises'\n \nconst responses = await pMap(\n items,\n async (item) => {\n console.log(item?.id)\n await setTimeout(1000)\n },\n {\n concurrency: 5,\n stopOnError: false, // this will still reject everything and throw an AggregateError\n }\n)
Adding a cli is a nice way to run scripts and commands in a project. Hopefully this will help get started with building your own cli. So go out, build your cli and may your time in bash scripts be limited.
", "url": "https://alexmchan.com/blog/2023-10-10-cli", "title": "Learn how to build a command line interface in 10 minutes ", "summary": "Adding a typed cli is a nice way to run scripts and commands in a project.", "date_modified": "2023-10-10T00:00:00.000Z", "author": { "name": "Alex Chan" } }, { "id": "https://alexmchan.com/blog/2023-06-29-tailwind-customizations", "content_html": "Tailwind is great and ust a few customizations can make it even better. Most of these are embedded in this preset.
\nTailwind uses an index based scale which can be cumbersome to memorize, hover over in a code editor, or print out for reference. Our team has used px scale and it's easier to remember and for new devs to onboard faster. Compare p-36px vs p-9, it's slightly more effort to nudge something but autocomplete works well and mostly it's adding 4-8px at a time.
These two tweets convinced me, one from the creator of tailwindcss and one from vanilla extract and css modules. Note that the creator of tailwind didn't remember the scale value off the top of his head -- because he is human like most of us.
\nThere was a little learning curve, but I like it now that I’m used to it. Also mt-8 is 32px 😉
— Jason Beggs (@jasonlbeggs) January 13, 2020
", "url": "https://alexmchan.com/blog/2023-06-29-tailwind-customizations", "title": "tailwind customizations", "summary": "Small additions for tailwind customizations", "date_modified": "2023-06-29T00:00:00.000Z", "author": { "name": "Alex Chan" } }, { "id": "https://alexmchan.com/blog/2023-03-20-a-slice-of-state", "content_html": "After working with an abstracted scale for years, I've ended up feeling like the abstraction didn't actually buy me anything and only served to slow me down and make it difficult to predict what would be on screen. The main benefit was having a limited scale, which we still have.
— Mark Dalgleish (@markdalgleish) November 24, 2021
We're given a lot of choice of state management, but what's the best choice for your app? I am looking into state libraries and wanted to see their apis all in one location. There's not one best answer but I'll share my thoughts on the different options.
\nMost apps I've worked with typically look like this in terms of state:
\n![](\"/_next/image?url=%2F_next%2Fstatic%2Fimmutable%2Fmedia%2Fstate-triangle.1fwofa4oee8he.png&w=1200&q=75\"/)
Before we dive in, it's worth mentioning that most complex state in apps I've worked with are typically async data caches or form data. For this reason, in my experience I've rarely had to reach for global state libraries beyond context because minimal global state means minimal re-renders.
\nFor async choose one of
\ntrpc (if you control the client and the server)apollo/urql (if you can use graphql)@tanstack/react-query (if you're using REST based apis see tkdodo's blog post on why you want react-query)For form libraries I've been happy with react-hook-form and zod for validation. I've liked that the zod adapter is built in and it minimizes re-renders if only the components that need to watch data watch for it.
Comparing all of these would be it's own post. So I'll leave it that starting with an async lib and sharing component state with a form lib can go a very long way.
\nOnly when async, form and local state start to fall over, reach for a solution below.
\nPerhaps what can help deciding on a library for yourself is answering some questions. Think about these as we look at each of the libraries and hopefully can inform your decision when a new hot state management library comes along.
\nGlobal state specific questions to think about:
\nThese are not optimal solutions, they're just what I managed to glean from the docs and examples and it's almost guaranteed that I've made a mistake somewhere. Hopefully even that is an indicator of how easy it was to follow the docs for their best practices.
\nContext is fine for small apps and components where the shared state changes infrequently to reduce prop drilling. If state changes frequently\nsuch as an slider, or color picker then it's better to use a state management library like react-hook-form (yes it's a state library), recoil, zustand, jotai, valtio or a form library. If it's just to reduce re-renders use-context-selector could help.
\nHere's the a quick context setup example for the times when you need to share state between components.\nInspired by the react context example by kentcdodds.
\n\nimport {\n useContext,\n createContext,\n useState,\n SetStateAction,\n Dispatch,\n} from 'react'\n \ntype ExampleContextData = {\n isActive?: boolean\n setIsActive?: Dispatch<SetStateAction<boolean>>\n}\nconst ExampleContext = createContext<ExampleContextData>({})\n \nfunction useExampleContext() {\n const context = useContext(ExampleContext)\n \n if (context === undefined) {\n throw new Error('Context must be used within a provider')\n }\n \n return context\n}\n \nfunction ExampleContextComponent() {\n const { isActive, setIsActive } = useExampleContext()\n \n return (\n <button type="button" onClick={() => setIsActive((isActive) => !isActive)}>\n Click to toggle {isActive ? 'active' : 'inactive'}\n </button>\n )\n}\n \nexport function ContextExample() {\n const [isActive, setIsActive] = useState(false)\n return (\n <ExampleContext.Provider value={{ isActive, setIsActive }}>\n {/* Component value consumer */}\n <ExampleContext.Consumer>\n {(value) => <div>{value.isActive}</div>}\n </ExampleContext.Consumer>\n {/* Custom component */}\n <ExampleContextComponent />\n </ExampleContext.Provider>\n )\n}
It's been a long time since looking at redux. Many years ago I tried useReducer and found the over-rendering to be frustrating and threw everything to do with reducers away . It was still a lot of boilerplate to use redux and moving to a form library + react-query removed 99% of the need for complex global state.
RTK solves a lot of the things I didn't like. It's a lot easier to use and has much less boilerplate and actually lines up closer to some of the other state management libraries once the store is configured. There's still some steps when setting up a new slice. I like how immer is pre-bundled and the user doesn't need to necessarily do anything special to work with immutable state updates.
\nEdit 2023-09 - Given the amount of boilerplate and the wide adoption of react-query it seems hard to recommend rtk query anymore. Removing the temptation to use redux as the global async store is another reason to keep the separation of concerns clean.
\n// setup the store.ts\nimport { configureStore, ThunkAction, Action } from '@reduxjs/toolkit'\nimport counterReducer from '../features/counter/counterSlice'\n \nexport const store = configureStore({\n reducer: {\n counter: counterReducer,\n },\n})\n \nexport type AppDispatch = typeof store.dispatch\nexport type RootState = ReturnType<typeof store.getState>\nexport type AppThunk<ReturnType = void> = ThunkAction<\n ReturnType,\n RootState,\n unknown,\n Action<string>\n>\n \n// implement the reducer\nimport { createAsyncThunk, createSlice, PayloadAction } from '@reduxjs/toolkit'\nimport { RootState, AppThunk } from '../../app/store'\nimport { fetchCount } from './counterAPI'\n \nexport interface CounterState {\n value: number\n}\n \nconst initialState: CounterState = {\n value: 0,\n}\n \nexport const counterSlice = createSlice({\n name: 'counter',\n initialState,\n // The `reducers` field lets us define reducers and generate associated actions\n reducers: {\n increment: (state) => {\n // Redux Toolkit allows us to write "mutating" logic in reducers. It\n // doesn't actually mutate the state because it uses the Immer library,\n // which detects changes to a "draft state" and produces a brand new\n // immutable state based off those changes\n state.value += 1\n },\n \n // Use the PayloadAction type to declare the contents of `action.payload`\n incrementByAmount: (state, action: PayloadAction<number>) => {\n state.value += action.payload\n },\n },\n})\n \nexport const { increment, incrementByAmount } = counterSlice.actions\n \n// The function below is called a selector and allows us to select a value from\n// the state. Selectors can also be defined inline where they're used instead of\n// in the slice file. For example: `useSelector((state: RootState) => state.counter.value)`\nexport const selectCount = (state: RootState) => state.counter.value\n \n// this is not required but perhaps is a way to access methods on store values\n// at first glance it seems like a lot of boilerplate to first grab the dispatcher\n// but as someone not used to redux always having to dispatch feels like extra work\n// this has to be a hook so that we can grab the dispatch ourselves\nexport function useIncrementByAmount() {\n const dispatch = useAppDispatch()\n return {\n incrementByAmount: ({ amount }: { amount: number }) =>\n dispatch(incrementByAmount(amount)),\n }\n}\n \nexport default counterSlice.reducer\n \n// Counter.tsx\n// use it in a component\n \nimport React, { useState } from 'react'\n \nimport { useAppSelector, useAppDispatch } from '@/app/hooks'\nimport { decrement, increment, selectCount } from '@/store/counterSlice'\n \nexport function Counter() {\n const count = useAppSelector(selectCount)\n const dispatch = useAppDispatch()\n \n return (\n <div>\n <div>\n <span className={styles.value}>{count}</span>\n <button\n className={styles.button}\n aria-label="Increment value"\n onClick={() => dispatch(increment())}\n >\n increment\n </button>\n </div>\n </div>\n )\n}
Zustand is a small state management library.
\nimport { create } from 'zustand'\nimport { subscribeWithSelector } from 'zustand/middleware'\nimport produce from 'immer' // not required but simplifies state updates\nimport { Button } from '@/components/Button'\n \ninterface CountState {\n count: number\n increaseCount: ({ amount }: { amount?: number }) => void\n resetCount: () => void\n}\n \nconst useCountStore = create(\n subscribeWithSelector<CountState>((set) => ({\n count: 0,\n increaseCount: ({ amount = 1 } = {}) =>\n set(\n produce((draft) => {\n draft.count += amount\n })\n ),\n resetCount: () =>\n set(\n produce((draft) => {\n draft.count = 0\n })\n ),\n }))\n)\n \n// just a hook to get the count, probably overkill here but I've gotten used to\n// writing react query hooks for all slices of global state\n// this could decouple the component from the store and limits changes to just the "query" functions\nfunction useGetCount() {\n return useCountStore((state) => state.count)\n}\n \nexport function ZustandCounter() {\n const count = useCountStore((state) => state.count)\n return <div>The zustand count {count}</div>\n}\n \nexport function ZustandExample() {\n const increaseCount = useCountStore((state) => state.increaseCount)\n const resetCount = useCountStore((state) => state.resetCount)\n \n return (\n <>\n <div className="flex items-center gap-2">\n <Button variant="primary" onClick={() => increaseCount({ amount: 1 })}>\n increment\n </Button>\n <Button variant="secondary" onClick={() => resetCount()}>\n reset\n </Button>\n <ZustandCounter />\n </div>\n </>\n )\n}\n \n// all state changes\n// const unsubAll = useCountStore.subscribe(console.log)\n \n// with middleware we can watch only the count changes\nconst unsubCount = useCountStore.subscribe(\n (state) => state.count,\n (count) => {\n console.log('count changed to', count)\n }\n)
Immer simplifies updating state but even better is the immer middleware which reduces the boilerplate further. Just remember to follow the rules of immer.
\nimport { create } from 'zustand'\nimport { immer } from 'zustand/middleware/immer'\n \ntype State = {\n count: number\n}\n \ntype Actions = {\n increaseCount: ({ amount }?: { amount?: number }) => void\n resetCount: () => void\n}\n \nexport const useCountStore = create(\n immer<State & Actions>((set) => ({\n count: 0,\n increment: ({ amount = 1 } = {}) =>\n set((state) => {\n state.count += qty\n }),\n resetCount: () =>\n set((state) => {\n state.count = 0\n }),\n }))\n)
To draw some analagoes to redux, zustand has actions that update the store via the set. What RTK has is similar now with state and dispatchers co-located. Co-location of state and actions makes it easier to reason about.
It's still a bit strange that the Actions needed to be typed when they look like they could be inferred from the initial store state. Taking the action from the slice of the store takes some getting used to, but if one thinks of it more like a class that has it's methods on it it seems less foreign and helps my mental model of how to use it and wrapping common methods in hooks might be another way to use them directly without having to grab a slice of the store each time.
const resetCount = useCountStore((state) => state.resetCount)
Jotai is an state management library similar to recoil in that slices of state are treated as "atoms". As an initial user of this what takes getting used to is composing and using atoms and adding atom methods.
\nFrom the jotai docs:
\n\n\nAnalogy\nJotai is like Recoil. Zustand is like Redux.
\n
When to use which
\nIf you want a simple module state, Zustand fits well.
\nIf you prefer Redux devtools, Zustand is good to go.
\nIf you need a replacement for useState+useContext, Jotai fits well.
\nIf you want to make use of Suspense, Jotai is the one.
\nIf code splitting is important, Jotai should perform well.
\nimport { Button } from '@/components/Button'\nimport { atom, useAtom, createStore, Provider } from 'jotai'\n \nconst countAtom = atom(0)\nconst messageAtom = atom('hello')\n \nconst myStore = createStore()\n \nconst initialCountState = 1\nmyStore.set(countAtom, initialCountState)\n \nconst unsub = myStore.sub(countAtom, () => {\n console.log('Jotai countAtom value is changed to', myStore.get(countAtom))\n})\n \nfunction JotaiCounter() {\n const [value, setValue] = useAtom(countAtom)\n \n return (\n <div className="flex items-center gap-2">\n <Button onClick={() => setValue(value + 1)}>Increment</Button>\n <Button onClick={() => setValue(initialCountState)}>Reset</Button>\n <div>{value}</div>\n </div>\n )\n}\n \nexport function JotaiExample() {\n return (\n <Provider store={myStore}>\n <JotaiCounter />\n </Provider>\n )\n}
Nice things
\nThings to get used to
\nsetValue in a form is similar so maybe is fine for smaller primitive changes but something such as calculating a total based on multiple things may require a composite action atom.The syntax for an "action atom" looks a bit strange initially.
\nconst incrementCountAtom = atom(\n (get) => get(countAtom),\n (get, set) => set(countAtom, get(countAtom) + 1)\n)\n \n// component uses it as\nconst [count, incrementCount] = useAtom(incrementCountAtom)\n// alternative for just the setter\nconst incrementCount = useSetAtom(incrementCountAtom)
Valtio feels more natural for those who don't mind mutating state directly.
\nimport { Button } from '@/components/Button'\nimport { proxy, subscribe, useSnapshot } from 'valtio'\nimport { subscribeKey } from 'valtio/utils'\n \nexport const state = proxy({\n count: 0,\n text: 'hello',\n \n inc() {\n ++this.count // or see below for exporting directly from the module\n },\n})\n \n// actions defined this way are better for code splitting\n// https://github.com/pmndrs/valtio/blob/main/docs/how-tos/how-to-organize-actions.mdx#action-functions-defined-in-module\nexport function incrementCount({ amount }) {\n state.count = state.count + amount\n}\n \nexport function ValtioExample() {\n const snap = useSnapshot(state)\n return (\n <div className="flex items-center gap-2">\n <Button onClick={() => (state.count = state.count + 1)}>\n Increment directly\n </Button>\n <Button onClick={() => incrementCount({ amount: 1 })}>\n increment via function\n </Button>\n <Button onClick={() => (state.count = 0)}>reset</Button>\n {snap.count}{' '}\n </div>\n )\n}\n \n// Subscribe to all state changes\nconst unsubscribe = subscribe(state, () =>\n console.log('valtio example state has changed to', state)\n)\n \n// a primitive needs to be subscribed to with subscribeKey\nconst unsubscribeSlice = subscribeKey(state, 'count', () =>\n console.log('valtio count state has changed to', state)\n)
Legend state is closeser to valtio and createSignal from solid (see below).
import { observable, observe } from '@legendapp/state'\nimport { useSelector, observer } from '@legendapp/state/react'\nimport { useTraceUpdates } from '@legendapp/state/trace'\nimport { useTraceListeners } from '@legendapp/state/trace'\n \nconst countStore = observable({\n count: 0,\n incrementAmount: 1,\n})\n \n// as a method in a module or mutate state directly\nfunction inc() {\n countStore.count.set((count) => count + 1)\n}\n \nconst CounterObserver = observer(function CounterObserver() {\n // some debugging tools\n useTraceUpdates()\n useTraceListeners()\n return <div>Count: {countStore.count.get()}</div>\n})\n \n//\nfunction CountSelector() {\n const count = useSelector(() => countStore.count)\n // Only re-renders if the return value changes\n \n return <div>Watching the count with a selector: {count}</div>\n}\n \nfunction Counter() {\n return (\n <>\n <button\n onClick={() => {\n countStore.count.set((count) => count + 1)\n }}\n >\n increment\n </button>\n <button onClick={() => inc()}>inc</button>\n <button onClick={() => countStore.count.set(0)}>reset</button>\n <CounterObserver />\n <CountSelector />\n </>\n )\n}\n \nfunction LegendStateExample() {\n return (\n <div className="App">\n <Counter />\n </div>\n )\n}\n \n// observe re-runs when any observables change values\n//\nobserve(() => {\n console.log('watching for changes')\n // if the primitive doesn't change, this oberver will not fire\n console.log(countStore.count.get())\n})\n \nexport default LegendStateExample
Super cool things about this lib are what aren't shown here, the built in performance where observables are automatically turned into react components(!!) that only re-render when the value changes. :mindblown:
\nimport { enableLegendStateReact } from '@legendapp/state/react'\n \nenableLegendStateReact()\n \nconst count = observable(0)\n \nfunction Optimized() {\n // This never re-renders when observable is rendered directly\n return <div>Count: {count}</div>\n}
Also their custom performance components such as Memo which automatically memoizes the children is pretty cool. Without this, the parent would typically re-render when the child changes.
function MemoExample() {\n return (\n <div>\n <Memo>\n {() =>\n state.messages.map((message) => (\n <div key={message.id}>{message.text}</div>\n ))\n }\n </Memo>\n </div>\n )\n}
It's worth looking at how the solid js lib works by using signals. Performance is awesome and using signals as useState inside a component or outside as a store is really cool. Once a developer gets used to this way of working it's nice that performance comes naturally and doesn't require any observer tags since it's built into the framework. A feature I am super envious of is also declaring effects without providing their dependencies explicitly.
import { render } from 'solid-js/web'\nimport { createSignal } from 'solid-js'\n \nconst [countStore, setCountStore] = createSignal({\n count: 0,\n incrementAmount: 1,\n})\n \nfunction Counter() {\n createEffect(() => {\n console.log('The count is now', countStore().count)\n }) // no dependency array! similar to observe but nice to see it built in\n \n return (\n <button\n onClick={() =>\n setCountStore((state) => {\n console.info(state.incrementAmount)\n return {\n ...state,\n count: state.count + state.incrementAmount,\n }\n })\n }\n >\n Count: {countStore().count}\n </button>\n )\n}\n \nrender(() => <Counter />, document.getElementById('app'))
Like most proxy based solutions, one has to learn the differences between when to access the property directly and when to use a method based version.
\ncountStore().count
This is not a big deal but is a learning curve and can lead to some harder to debug issues when first getting used to them.
\nAnother example from tanstack-query with solid.
\nconst [enabled, setEnabled] = createSignal(false)\nconst query = createQuery(() => ['todos'], fetchTodos, {\n // ❌ passing a signal directly is not reactive\n // enabled: enabled(),\n \n // ✅ passing a function that returns a signal is reactive\n get enabled() {\n return enabled()\n },\n})
I imagine that once these are learned they get easier to use and seeing that signals are becoming popular across the libraries means this is definitely a space to watch.
\nOverall what I recommend is -- minimize global state so you hopefully don't need a lib. All jokes aside, it's not so much which is best, but which is best for your use case. One of the beautiful things is that the performance is pretty good if the recommendations of the libraries are followed and changes in global state aren't fired constantly.
\nI previously recommended trying zustand, it's simple and easy to read the single page doc to get an understanding. Just remember to always use selectors otherwise the component will notify the same as using context.
\nHowever, with signals becoming ever more popular and reaching stage 1 RFC, it's worth looking at libraries that closely map to the new api. While most library authors might end up using signals under the covers, Legend state is actually the closest api wise. The primary downside is wrapping components in observer and getting used to needing to append .get() or .set() -- otherwise in my usage it's worked well without additional gotchas.
\n\nprobably not but only for a small bit of context
\n
\n\ncolocating state and actions is simple, I don't love the actions having to be sliced off of the store in each component but wrapping in a hook is a nice way to get around that
\n
\n\nvery small api, some of the other libraries work with proxies which are great but often have a few gotchas to learn about them. Things like when to use a function
\nvalue(), when to access the store directly, and when toobserve. It's true that zustand with immer (zimmer?) is using proxies but I've learnt many of the gotchas from using immer directly so for my use case this is a lower barrier to entry. Using mobx in the past was great but I did find myself with proxies when I was expecting the raw object and there was a lot of time unwrapping things. I'd like to give valtio and legend state another try in another project to see if I can get over the hump of learning the new api.I really like the idea of signals and truly reactive state changes so it may be that for more reactive applications with minimal boilerplate so one of those may help. It might be that\nworking with proxy state is not as hard but would like to test this more before committing to it. Legend state is pushing the boundaries here so I'd like to give it a longer test drive than I was able to in a few hours.
\n
\n\nhas all of those, and a small bundle size is nice
\n
\n\nhopefully the small api means this is easish to adatpt to a new library if needed
\n
\n\ndocs are nice
\n
\n\nwas quick to get running once immer example was used, pretty easy to add a new action. Types are the biggest pain to have to duplicate type, but perhaps there is a better way to infer types from the initial store state. Needs some investigation but not a deal breaker
\n
\n\nanecdotal but most people seem happy with it on the twitters and haven't seen too many complaints
\n
\n\npmndrs and dai-shi have great libs (including the aformentioned valtio, jotai), zustand used by 85k, and 158 contribs seem like it is healthy
\n
\n\n👍🏻 store can be accessed directly so not much setup
\n
State management has come a long way in recent years and as react developers we have almost too much choice for good libraries! Good luck in your state management choice, I hope this helps you make the right choice for your project.
\nI've been using tanstack query (react-query) for a while and have gotten used to the patterns around it. Before that, I've used useSWR, and apollo/urql. While I'd prefer to use graphql when available, react-query has been fantastic for working with REST APIs.
A project I joined has redux but not yet rtk or rtk query so I thought I'd give both a try. RTK has been great for simplifying redux, but if we don't need as much data in the global store anymore, I wonder why we'd want to use rtk query.
\nThe feature comparison sums up most of the differences so I'll just talk about some of the things I noticed when first picking up rtk query and why I prefer react-query.
\nFrom the docs there's a createApi wrapper that takes a base url and endpoints. The endpoints are defined using a builder.
\n// Need to use the React-specific entry point to import createApi\nimport { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'\n \n// Define a service using a base URL and expected endpoints\nexport const pokemonApi = createApi({\n reducerPath: 'pokemonApi',\n baseQuery: fetchBaseQuery({ baseUrl: 'https://pokeapi.co/api/v2/' }),\n endpoints: (builder) => ({\n getPokemonByName: builder.query<any, { name: string }>({\n query: ({ name }) => `pokemon/${name}`,\n }),\n }),\n})\n \n// Export hooks for usage in functional components, which are\n// auto-generated based on the defined endpoints\nexport const { useGetPokemonByNameQuery } = pokemonApi
reducerPath is needed to know where to put the slice of data.baseQuery is the fetch functionbuilder is a function that provides a route with the query keyThe query being the query key is the most confusing part coming from react-query. I admit that understanding this part of react-query takes some time as well but the idea of query key and query path have been merged here. The nice thing is it's true that most of the time this is the same. With a more complex API the body is also passed from here. If we want to transform the data, a transformResponse function can be provided or a queryFn.
It turns out queryFn is closer to what react-query does, however, then we need to specify the serialization of query args serializeQueryArgs. Not overly complex but this stuff is all done by react-query without having to understand what is happening. react-query's queryKey is stably serialized by default and not something I need to think about.
Each new slice of state also needs to be added as middleware to the router. While not horrible, it's just one more thing to remember to do. Also there will then be some naming convention to follow to make sure the slice is named the same as the reducerPath. I'm lazy and I like minimal api surface area so less is more. I totally understand that registering it is kind of necessary, but react-query doesn't need to declare things because it's in full control of it's global cache.
\nimport { configureStore } from '@reduxjs/toolkit'\n// Or from '@reduxjs/toolkit/query/react'\nimport { setupListeners } from '@reduxjs/toolkit/query'\nimport { pokemonApi } from './services/pokemon'\n \nexport const store = configureStore({\n reducer: {\n // Add the generated reducer as a specific top-level slice\n [pokemonApi.reducerPath]: pokemonApi.reducer,\n },\n // Adding the api middleware enables caching, invalidation, polling,\n // and other useful features of `rtk-query`.\n middleware: (getDefaultMiddleware) =>\n getDefaultMiddleware().concat(pokemonApi.middleware),\n})\n \n// optional, but required for refetchOnFocus/refetchOnReconnect behaviors\n// see `setupListeners` docs - takes an optional callback as the 2nd arg for customization\nsetupListeners(store.dispatch)
Export hooks are auto generated based on the aformentioned createApi. This is really neat and reminiscent of trpc (which is also awesome). This is where we see the power of the factory function and there's probably some cool string template types going on here. Still, with react-query things are just exported as the function that is created.
// Export hooks for usage in functional components, which are\n// auto-generated based on the defined endpoints\nexport const { useGetPokemonByNameQuery } = pokemonApi
The base api is the same which is great, but it's here that I notice the difference in control when making a wrapper query.
\nimport * as React from 'react'\nimport { useGetPokemonByNameQuery } from './services/pokemon'\n \nexport default function App() {\n // Using a query hook automatically fetches data and returns query values\n const { data, error, isLoading } = useGetPokemonByNameQuery('bulbasaur')\n // Individual hooks are also accessible under the generated endpoints:\n // const { data, error, isLoading } = pokemonApi.endpoints.getPokemonByName.useQuery('bulbasaur')\n \n // render UI based on data and loading state\n}
The main options that we have to adjust are:
\ncompare this to a react-query hook wrapper where we can add options inline
\nimport { useQuery } from '@tanstack/react-query'\nimport axios from 'axios'\nimport { Environment } from '@/selectors/environment'\n \nconst queryKeyId = 'environments'\n \nexport function useGetEnvironmentsQuery({\n namespace,\n appName,\n}: {\n namespace?: string\n appName?: string\n}) {\n return useQuery({\n queryKey: [queryKeyId, { namespace, appName }],\n queryFn: async () => {\n const res = await axios.get<Environment[]>(\n `/api/apps/${namespace}/${appName}/environments`\n )\n return res?.data\n },\n enabled: Boolean(namespace && appName),\n })\n}\n \nuseGetEnvironmentsQuery.queryKeyId = queryKeyId
We have basically the same but several that are useful, including immediately having the lazy version in refetch, specifying the enabled with the query, specifying the initialData lower down, events on each of the success/error states, specifying the staletime.
These are hard in almost any case. rtk-query has a neat concept of defining a fixed-cache-key
export const ComponentOne = () => {\n // Triggering `updatePostOne` will affect the result in both this component,\n // but as well as the result in `ComponentTwo`, and vice-versa\n const [updatePost, result] = useUpdatePostMutation({\n fixedCacheKey: 'shared-update-post',\n })\n \n return <div>...</div>\n}\n \nexport const ComponentTwo = () => {\n const [updatePost, result] = useUpdatePostMutation({\n fixedCacheKey: 'shared-update-post',\n })\n \n return <div>...</div>\n}
It would only be if something in the store needs to access something else in the store. From my experience, most of the code my team and I write has absolutely minimal shared global state. Most of the "slices" of state can be contained in the common hook that is used to fetch the data or with a selector that is used to get the data from the store. Most of these cases are handled by react-query in a way that isn't also tightly coupled to redux.
\nIt seems like rtk query is mostly trying to follow the features in react-query so newer features will almost always typically land in react-query first.
\nGiven that both operate in the same area, and that global shared mutable state should be avoided, I'm going to reach for react-query whenever I need to deal with rest based async data.
", "url": "https://alexmchan.com/blog/2023-03-18-why-prefer-tanstack-query", "title": "Tanstack react query or rtk query", "summary": "Why at first glance react query seems better than rtk query", "date_modified": "2023-03-18T00:00:00.000Z", "author": { "name": "Alex Chan" } }, { "id": "https://alexmchan.com/blog/2023-02-13-enum-and-const", "content_html": "I've been using enum for a long time and tried switching to const several times. For the most part, there's very little syntax and not many downsides so long as the enums are assigned a value.
\nenum StatusAsEnum {\n Active = 'active',\n Deactive = 'deactive',\n None = 'none',\n}
The flip side of this is to define a const as const and then use a keyof to get the type.
const Status = {\n Active: 'Active',\n Deactive: 'Deactive',\n None: 'None',\n} as const\n \ntype StatusAsConst = keyof typeof status\n \nfunction log(status: StatusAsConst) {\n if (status === status.Active) {\n console.log('We are active')\n }\n console.log(status)\n}
This is ok but now we need the
\na) const as const declaration\nb) keyof typeof syntax, a secondary type declaration and then we also need to ensure that our key/value's are actually identical when we want to use them.
Using this other syntax is probably just laziness on my part. It's always required importing both the type and the const and knowing which is which when checking against. Not having a naming standard for these PascalCase'd const's. It was kind of nice that things that are typescript are PascalCase'd.
\nMaybe I'll try again in 2023 and see if I can get used to it since it's closer to js.
\nThis way we use the as const syntax and then use the typeof to get the type. Then we can use the const enum when we need to provide the type.
const PUSHER_STATUS = {\n INITIALIZED: 'initialized',\n CONNECTING: 'connecting',\n CONNECTED: 'connected',\n UNAVAILABLE: 'unavailable',\n FAILED: 'failed',\n DISCONNECTED: 'disconnected',\n //...\n} as const\n \ntype PusherStatus = (typeof PUSHER_STATUS)[keyof typeof PUSHER_STATUS]\n// type PusherStatus = 'uninitialized' | 'connecting' | 'connected' | 'unavailable' | 'failed' | 'disconnected'\n \nfunction exampleStatus({ status }: { status: PusherStatus }) {\n if (status === PUSHER_STATUS.CONNECTED) {\n console.log('We are connected')\n } else {\n //...\n }\n}
Making this into a utility may make it easier to remember.
\ntype Values<T> = T[keyof T]
utility-types has this included as
import { $Values } from 'utility-types'\ntype PusherStatus = $Values<typeof PUSHER_STATUS>
useEffect is one of the most important hooks but it can lead to some of the hardest to debug code. Here's what I've learned about simplifying them.
useEffectI usually think of useEffect as useOnChange, it will get fired at least once and then whenever the dependencies change. I found that shifting to think that the effect will fire whenever anything changes helps me think about a few things
When first starting with useEffect it's really easy to get unintended renders. It's very easy to lose track of things that change easily.
Ideally if the dependencies are within the function we can wrap them in a useCallback or useMemo. A lot has been written about that so I won't go into it here.
Since useEffect gets triggered whenever dependencies change, it's often better to reduce the dependencies to the smallest set possible. Often this can be a single boolean or state value that actually watches the dependencies and can minimize the chance of inadvertent side effect triggers.
function MyComponent({cars, people}) {\n \n useEffect({\n if (cars?.length > 0 && people?.length > 0) {\n // do something\n }\n }, [cars, people])\n \n return <div>...</div>\n}
We're watching two arrays, but we're only interested in the length. We can simplify this by using a useMemo to watch the length of the arrays and then only watch that value or even just check the value directly.
function MyComponent({cars, people}) {\n \n useEffect({\n if(cars?.length > 0 && people?.length > 0) {\n // do something\n }\n }, [cars?.length, people?.length])\n \n return <div>...</div>\n}
This will protect us a bit from arrays that are being recreated, but it's still not ideal. What if we just watched a boolean instead?
\nexport function checkHasValues({ cars, people }) {\n return cars?.length > 0 && people?.length > 0\n}\n \nfunction MyComponent({ cars, people }) {\n const hasValues = checkHasValues({ cars, people }) // optionally useMemo this depending on the time it runs for\n \n useEffect(\n {\n if(hasValues) {\n // do something\n },\n },\n [hasValues]\n )\n \n return <div>...</div>\n}
Now we're only watching a single boolean value and we can even move the check into a function that we can test. Let's call this a boolean based useEffect.
\nIt's quick and easy to see what will trigger the change and it's easier to test the function that is looking for the differences. Realistically we'll also have to pass in a related function to trigger when the effect changes, but it's a much smaller dependency array and as more values get passed it'll reduce the number of times the useEffect might get called. It also protects us a bit from an object out of our control triggering the useEffect unintentionally.
\nI've found this a good pattern to look for as the dependencies get large. For one or two it may be overkill but as the number of dependencies grows it's a great way to simplify the code.
\nEdit 2025 - included additional methods:
\nconst [value, setValue] = useState(0)\n \n// run in response to value change\nuseEffect(() => {\n console.log(`Value is ${value}`)\n}, [value])\n \nreturn <Button onClick={() => setValue(value + 1)}>Increment {value}</Button>\n \n// change instead be run in response to an event\nconst [value, setValue] = useState(0)\n \nreturn (\n <Button\n onClick={() => {\n const incrementedValue = value + 1\n setValue(incrementedValue)\n // run in response to a side effect\n console.log(incrementedValue)\n }}\n >\n Increment {value}\n </Button>\n)\n \n// or as a callback where we receive current state at the time of the event\n \nconst incrementValue = useCallback((value) => {\n const incrementedValue = value + 1\n setValue(incrementedValue)\n // run in response to a side effect\n console.log(incrementedValue)\n}, [])\n \nreturn (\n <Button\n onClick={() => {\n incrementValue(value)\n }}\n >\n Increment {value}\n </Button>\n)
Here's a list of articles about why disabled buttons are poor for users:
\nIn my experience whenever we've run user tests on disabled buttons, users have always been confused by them. They don't know why they're disabled, and they don't know what to do to enable them. Making them look disabled is possibly ok but the solution is often to leave them enabled and provide feedback when clicked about why, either beside the button or highlighting the fields that need to be filled in along with a message about what's missing.
\nSearching google for the why we should have disabled buttons will actually give a list of the articles above 😂
\nReasons for disabled buttons:
\nA quick even and responsive grid layout.
\nexport function ExampleGrid() {\n return (\n <div className="grid gap-4 md:auto-cols-max md:grid-flow-col">\n {Array.from({ length: 3 }, (_, i) => (\n <div className="bg-slate-500 p-8">\n <div className="text-xl font-extrabold text-white">\n Some heading text\n </div>\n <div>Content text</div>\n </div>\n ))}\n </div>\n )\n}
In the past I've quite enjoyed the beauty of vest for it's nearness to unit testing. It didn't require a complex dsl, conditionals worked mostly as one would expect, and the error messages could be raised. Moving from yup before that was mostly because writing any complex validation required re-reading the docs and reading the validations also required re-reading the docs.
Zod is taking over the typed world. There's nothing wrong with vest, but we gain form types for free when defining a form schema which is one less thing to do. Additionally, zod is being used for other validation so consolidating on a single library simplifies the overall api surface area of our application for input, server, and client side validation.
\nI’ve been trying zod with trpc more and it might be the way, but it also wants a discriminated union where the type exists at the top level.
\nI think we can replace vest with zod, here’s why
\nlet exampleSchema = z\n .object({\n test: z.string(),\n otherValue: z.object({\n name: z.string(),\n }),\n })\n .refine(\n (data) => {\n if (data.otherValue.name === 'invalid') {\n return false\n }\n return true\n },\n {\n message: "Passwords don't match",\n path: ['otherValue.name'], // nested path of error\n }\n )\n .refine(\n (data) => {\n return false\n },\n {\n message: 'another check',\n path: ['test'], // path of error\n }\n )\n \ntry {\n let x = exampleSchema.parse({\n test: 'true',\n otherValue: {\n name: 'invalid',\n },\n })\n \n console.log({ x })\n} catch (error) {\n console.log(error)\n}
Context is fine for small apps and components where the shared state changes infrequently to reduce prop drilling. If state changes frequently\nsuch as an input, slider, or color picker then it's better to use a state management library like recoil, zustand, jotai, valtio or a form library.
\nHere's the a quick context setup example for the times when you need to share state between components.\nInspired by the react context example by kentcdodds.
\nimport {\n useContext,\n createContext,\n useState,\n SetStateAction,\n Dispatch,\n} from 'react'\n \ntype ExampleContextData = {\n isActive?: boolean\n setIsActive?: Dispatch<SetStateAction<boolean>>\n}\nconst ExampleContext = createContext<ExampleContextData>({})\n \nfunction useExampleContext() {\n const context = useContext(ExampleContext)\n \n if (context === undefined) {\n throw new Error('Context must be used within a provider')\n }\n \n return context\n}\n \nfunction ExampleContextComponent() {\n const { isActive, setIsActive } = useExampleContext()\n \n return (\n <button type="button" onClick={() => setIsActive((isActive) => !isActive)}>\n Click to toggle {isActive ? 'active' : 'inactive'}\n </button>\n )\n}\n \nexport function ContextExample() {\n const [isActive, setIsActive] = useState(false)\n return (\n <ExampleContext.Provider value={{ isActive, setIsActive }}>\n {/* Component value consumer */}\n <ExampleContext.Consumer>\n {(value) => <div>{value.isActive}</div>}\n </ExampleContext.Consumer>\n {/* Custom component */}\n <ExampleContextComponent />\n </ExampleContext.Provider>\n )\n}
Zustand is a good small state management library.
\nimport { create } from 'zustand'\nimport { subscribeWithSelector } from 'zustand/middleware'\nimport produce from 'immer'\nimport { Button } from '@/components/Button'\n \ninterface CountState {\n count: number\n increaseCount: ({ amount }: { amount?: number }) => void\n resetCount: () => void\n}\n \nconst useCountStore = create(\n subscribeWithSelector<CountState>((set) => ({\n count: 0,\n increaseCount: ({ amount = 1 } = {}) =>\n set(\n produce((draft) => {\n draft.count += amount\n })\n ),\n resetCount: () =>\n set(\n produce((draft) => {\n draft.count = 0\n })\n ),\n }))\n)\n \nexport function ZustandCounter() {\n const count = useCountStore((state) => state.count)\n return <div>The zustand count {count}</div>\n}\n \nexport function ZustandExample() {\n const increaseCount = useCountStore((state) => state.increaseCount)\n const resetCount = useCountStore((state) => state.resetCount)\n \n return (\n <>\n <div className="flex items-center gap-2">\n <Button variant="primary" onClick={() => increaseCount({ amount: 1 })}>\n one up\n </Button>\n <Button variant="secondary" onClick={() => resetCount()}>\n reset\n </Button>\n <ZustandCounter />\n </div>\n </>\n )\n}\n \n// all state changes\n// const unsubAll = useCountStore.subscribe(console.log)\n \n// with middleware we can watch only the count changes\nconst unsubCount = useCountStore.subscribe(\n (state) => state.count,\n (count) => {\n console.log('count changed to', count)\n }\n)
Valtio feels more natural for those who don't mind mutating state directly.
\nimport { Button } from '@/components/Button'\nimport { proxy, subscribe, useSnapshot } from 'valtio'\nimport { subscribeKey } from 'valtio/utils'\n \nexport const state = proxy({\n count: 0,\n text: 'hello',\n \n inc() {\n ++this.count // or see below for exporting directly from the module\n },\n})\n \n// actions defined this way are better for code splitting\n// https://github.com/pmndrs/valtio/blob/main/docs/how-tos/how-to-organize-actions.mdx#action-functions-defined-in-module\nexport function incrementCount({ amount }) {\n state.count = state.count + amount\n}\n \n// example component\nexport function ValtioExample() {\n const snap = useSnapshot(state)\n return (\n <div className="flex items-center gap-2">\n <Button onClick={() => (state.count = state.count + 1)}>\n Increment directly\n </Button>\n <Button onClick={() => incrementCount({ amount: 1 })}>\n increment via function\n </Button>\n <Button onClick={() => (state.count = 0)}>reset</Button>\n {snap.count}{' '}\n </div>\n )\n}\n \n// Subscribe to all state changes\nconst unsubscribe = subscribe(state, () =>\n console.log('valtio example state has changed to', state)\n)\n \n// a primitive needs to be subscribed to with subscribeKey\nconst unsubscribeSlice = subscribeKey(state, 'count', () =>\n console.log('valtio count state has changed to', state)\n)
From the jotai docs:
\n\n\nAnalogy\nJotai is like Recoil. Zustand is like Redux.
\n
When to use which
\nIf you want a simple module state, Zustand fits well.
\nIf you prefer Redux devtools, Zustand is good to go.
\nIf you need a replacement for useState+useContext, Jotai fits well.
\nIf you want to make use of Suspense, Jotai is the one.
\nIf code splitting is important, Jotai should perform well.
\nimport { Button } from '@/components/Button'\nimport { atom, useAtom, createStore, Provider } from 'jotai'\n \nconst countAtom = atom(0)\nconst messageAtom = atom('hello')\n \nconst myStore = createStore()\n \nconst initialCountState = 1\nmyStore.set(countAtom, initialCountState)\n \nconst unsub = myStore.sub(countAtom, () => {\n console.log('Jotai countAtom value is changed to', myStore.get(countAtom))\n})\n \nfunction JotaiCounter() {\n const [value, setValue] = useAtom(countAtom)\n \n return (\n <div className="flex items-center gap-2">\n <Button onClick={() => setValue(value + 1)}>Increment</Button>\n <Button onClick={() => setValue(initialCountState)}>Reset</Button>\n <div>{value}</div>\n </div>\n )\n}\n \nexport function JotaiExample() {\n return (\n <Provider store={myStore}>\n <JotaiCounter />\n </Provider>\n )\n}
Nice things
\nThings to get used to
\nsetValue in a form is similar so maybe is fine for smaller primitive changes but something such as calculating a total based on multiple things may require a composite action atom.The syntax for an "action atom" looks a bit strange initially.
\nconst incrementCountAtom = atom(\n (get) => get(countAtom),\n (get, set) => set(countAtom, get(countAtom) + 1)\n)\n \n// component uses it as\nconst [count, incrementCount] = useAtom(incrementCountAtom)\n// alternative for just the setter\nconst incrementCount = useSetAtom(incrementCountAtom)
Here are a few things I wish I'd known before starting aws.
\nLearn more about IAM as early as you can. If you don't you'll run into countless auth errors and the few hours of investment will pay off in spades.\nBrigid Johnson's talk on this gives a great foundation.\nhttps://www.youtube.com/watch?v=YQsK4MtsELU&ab_channel=AmazonWebServices
\nThe names of aws services are weird. https://expeditedsecurity.com/aws-in-plain-english/ helps a lot. I've just given up trying to make sense of any name and always try to map it to "What problem does this service solve and what are the tradeoffs between the other products"
\nThere's no one messaging system that rules it all. It's more than likely you'll have to choose the right thing for the job and SQS will almost definitely factor in some part of a dead-letter-queue even if you land on something like eventbridge, sns or kinesis. Learn the tradeoffs between them and when to use which or combination of message queues.
\nPrototype in aws console, but build using infrastructure as code (ie aws cdk). These help document which services you're using and help migrating between environments.
\nTry serverless services when doing the initial draft architecture before you know your actual loads can free you from many constraints and can be swapped out for non-serverless services either once you have an actual load picture or even just stay in the design.
\nKubernetes and EKS are complex and require a lot of management overhead. Consider serverless like lambda or less server like ECS/fargate if that's an option.
\nKeep multiple accounts for dev/qa/prod. This will greatly help keep your infrastructure and user accounts separate.
\nAdd alarms on everything. Tune them until only the important alerts and thresholds are hit and funnel them via sns into whatever messaging system your team uses
\nDesign for observability, on the flipside cloudwatch costs more than you think. Factor in costs related to logging lots of information and be able to turn on more logging with a switch.
\nIt's worth learning at least one cloud provider well. The underlying architectures and systems can save you from having to build core infrastructure these and can greatly simplify the code you have to write.
\nLots of products are released around aws:re-invent so keep your eyes on if a problem you had is solved by a new product launch or feature
\nPlan for multi region up front unless you can survive downtime in a region.
\nSolutions from other providers may still be better for specific cases. Planetscale, temporal, supabase, and upstash may abstract a lot of the complexities of db from your infrastructure.
\nIf you don't have a messaging system it's likely you have points of failure that you need to account for. Even if you have a messaging system you need to account for it's failures and how to reprocess them.
\nTypes are actually some of the hardest parts of getting a libary correct. Stitches is a css in js (and most importantly ts) library that has an incredible set of types so let's dive into one of the most interesting ones.
\n\n\nAny sufficiently advanced technology is indistinguishable from magic
\n\n
\n- Arthur C. Clarke
\n
How stitches solved their theming types feels like advanced typescript. Luckily, they've shared their magic with us. Let's dive in.
\nAmong other things, Stitches lets you define your own theme. So for color we could define a set of colors blue-100, blue-200 and then use them in our component as a css prop.
import { createStitches } from '@stitches/react'\n \nexport const { styled, css, getCssText } = createStitches({\n theme: {\n colors: {\n 'blue-100': '#DBEAFE',\n 'blue-200': '#BFDBFE'\n },\n})
Then we can make a button that's fully typed using object styles:
\nconst Button = styled('button', {\n color: '$blue-100',\n})
The first thing to do is define what the theme is initially made up of. In our case we just have a colors scale that's used by color. This is the theme that'll be used by our function:
declare namespace Config {\n export type Theme<T = {}> = {\n colors?: { [key in string]: string }\n }\n}
For our example we want a const { styled } = createStitches({theme}) typed function. This is just pseudo code and we'll start adding to it:
export type CreateStitches = {\n (config): {\n styled(elementToStyle, styleObject)\n }\n}
What we want is to allow one of the keys of the theme to be used. To do this we need the generics. Theme will be inferred from the passed in value.
export type CreateStitches = {\n <Theme extends Config.Theme>(config?: { theme?: Theme }): {\n styled: (elementToStyle, styleObject) => void\n }\n}
We want the value passed into the styled function for color to be one of the colors from the theme. To do this we can use the keyof to pull out the keys.
export type CreateStitches = {\n <Theme extends Config.Theme>(config?: { theme: Theme }): {\n styled: (\n elementToStyle: string,\n { color }?: { color?: keyof Theme['colors'] }\n ) => void\n }\n}
It'd be nice to also restrict elementToStyle down to all the JSX elements such as div, button etc. To do this we can add
( elementToStyle: keyof JSX.IntrinsicElements, /**...*/)
Finally we can use this type and all of the dynamic properties:
\nconst createStiches: CreateStitches = ({ theme }) => {\n return {\n styled: (type, { color }) => /*...*/,\n }\n}\n \n// call it with our theme\nconst { styled } = createStiches({\n theme: {\n colors: {\n 'blue-100': 'blue1',\n 'blue-200': 'blue2',\n },\n },\n})\n \n// types are suggested and can be autocompleted!\nstyled('button', {\n color: 'blue-100',\n})\n
This solves the token key problem, but stitches also maps to ALL of the other color values as well AND includes the css colors like royalblue and rebeccapurple and allows other string values #fff.
The simplest thing to do to allow string types would be to change our type to also include colors right?
\n{ color }?: { color?: keyof Theme['colors'] | string }
This works -- kinda. Now we can use blue-100 or #00f but now we don't get any suggestions of our own theme values. Oof indeed.
The unsung hero csstype can actually come to our rescue here because if we look at any lowly <div style={{ color: 'rebeccapurple'}}> we can see it allows strings AND does css spec defined values as well.
import type * as CSSType from 'csstype'\ntype Color = CSSType.Properties['color']\nconst c: Color = 'cornflowerblue'
So to do this we can just refer to the original parent scale or our theme value:
\n{ color }?: { color: CSSType.Properties['color'] | keyof Theme['colors'] }
So we finally have our type that allows us to use our theme values AND existing css types.
\nLastly, Stitches adds a $ in front of any token values. They have a type utility that does this:
export type Prefixed<K extends string, T> = `${K}${Extract<\n T,\n boolean | number | string\n>}`
and now we can use the utility to have our auto-complete show us the $blue-100 version instead
export type CreateStitches = {\n <Theme extends Config.Theme>(config?: { theme?: Theme }): {\n styled: (\n type: keyof JSX.IntrinsicElements,\n {\n color,\n }?: {\n color:\n | CSSType.Properties['color']\n | Prefixed<'$', keyof Theme['colors']>\n }\n ) => void\n }\n}\n \n//...\n \nstyled('button', {\n color: '$blue-100',\n})
This is already a big step forward but there's a few more type features provided by stitches that would be nice to understand. Stay tuned for future posts on:
\nconst Button = styled('button', {\n backgroundColor: 'blue-100', // magic\n})
as property allow changing the react props depending on which as is chosen? material-ui also has thisThe Stitches code is great and also has so much type sorcery happening under the covers so I'd recommend reading through the /types folder to explore how much of the typing is done.