DEV Community: ke jia

Secrets Don't Leak in One Moment: The 6 Ways They Slip Into Your Repo (and How to Catch Each One)

ke jia — Fri, 30 Oct 2026 00:39:50 +0000

Last year I found a production database password in one of my own public repos. Not a test password. Not a placeholder. The real one, in a config file, visible to anyone who knew how to read git history. It had been there for 8 months.

I didn't find it during an audit. I found it because a friend asked a question that made me look.

That's the uncomfortable truth about secret leaks: they almost never happen in one dramatic moment. There's no single "oops, I committed the .env" incident you can point to and learn from. There's a slow accumulation of small, reasonable decisions that add up to a credential sitting in public view.

This post is a field guide. I'll walk through the 6 ways secrets actually slip into a repo, and for each one I'll show you how to catch it. I'll also show you a small zero-dependency scanner I built after that 8-month incident — dotguard — and how to wire it into your workflow so the catching happens automatically.

1. The .env file that was never meant to be public

The classic. You create .env, put real values in it, and one of three things happens:

You commit it before adding it to .gitignore
You add it to .gitignore after the first commit
You commit it to a private repo, then make the repo public

The second one is the sneaky one. .gitignore only prevents new files from being tracked. If .env was already committed, adding it to .gitignore does nothing — git keeps tracking it, and the file stays in every clone. I've watched teams "fix" a leak by adding .env to .gitignore, then wonder why the file is still there.

How to catch it:

# What is git actually tracking?
git ls-files | grep -i env

If that prints .env, it's tracked, and .gitignore is not helping you. You need git rm --cached .env plus a history cleanup.

For the ongoing case, a scanner that walks your working tree and flags files with secret-looking content is the right tool. That's what dotguard does:

npm i -g @wuchunjie/dotguard
dotguard

One command. It scans the current directory — .env files, config files, source code — and reports anything that looks like a hardcoded credential. Zero dependencies, so it runs anywhere Node runs, including on a CI runner with nothing preinstalled.

2. The .env.example with real values

.env.example is the file you're supposed to commit. It's the template teammates copy when they start. The problem is how it gets made: someone copies their real .env, deletes a few lines, and calls it an example. The "example" values are production values.

I've seen DATABASE_URL=postgres://admin:RealPassword123@prod-db:5432/app sitting in a .env.example for over a year. Every new clone of the repo carried it. Every new developer had it in their shell history.

How to catch it:

Treat .env.example as code. Review it in PRs like you would any other file.
Scan it. It has the same shape as .env, so a content scanner should treat it the same way.

dotguard scans config files, not just files named .env, so a .env.example with real values gets flagged the same way as the real thing. That's the whole point of scanning content instead of filenames.

3. Hardcoded in source

Not every secret lives in an env file. Some live in:

config.js or settings.py
Client-side code — the worst kind, because it ships to every user's browser
Test fixtures
Dockerfiles (ENV API_KEY=...)
CI config files

The client-side case deserves special attention. A public API key in frontend code is a design decision, not a leak — the key is meant to be public. But a private key, a signing secret, or an admin token in a bundle is a leak that ships to millions of devices, and no amount of .gitignore fixes it.

How to catch it:

# Crude, but catches a lot
git grep -n "API_KEY\|SECRET\|TOKEN\|PASSWORD"

The problem with git grep is that you have to guess the variable names. A content scanner doesn't guess — it looks at the shape of the value: long high-entropy strings, known key prefixes, password = "..." assignments. That's a different failure mode, and it catches the secrets that don't have obvious names.

dotguard --path ./src

4. The log line

console.log("user:", user, "token:", token);

Logs are where secrets go to die — and to be copied. A token printed to stdout ends up in:

Local log files
CI logs (public on public repos)
Error reporting services
Screenshots pasted into Slack

The fix is two-part. First, don't log secrets: audit your logging and redact known fields. Second, scan the places where logs accumulate:

dotguard --path ./logs

This is a low-frequency, high-impact check. Run it when you're cleaning up a project, or when you're about to open a repo up.

5. Git history

This is the one that got me. You delete the file, you feel better, you move on. But git doesn't delete — it remembers. Every commit that ever contained the secret is still reachable from history.

The 8-month password was in a file I'd deleted months earlier. A single command found it:

git log --all -p -S "password"

Thirty seconds. Eight months of exposure.

How to catch it:

# Search all history for a string
git log --all -p -S "SECRET_PATTERN"

# Grep every commit (slow on big repos)
git grep "PATTERN" $(git rev-list --all)

The uncomfortable part: if a secret was in public history, it's already leaked. Rewriting history with BFG or git filter-repo doesn't un-leak it — it just stops the bleeding for future clones. The only real fix is rotation.

How to prevent it from happening in the first place:

A pre-push hook that runs a scanner and rejects the push if it finds something
A CI gate that fails the build on a finding

dotguard's CI integration is one line:

- name: Secret Scan
  run: npx @wuchunjie/dotguard

If you want a pre-push hook, the pattern is the same: run the scanner, and if it reports findings, exit non-zero. Check dotguard's output behavior and wire it in — the point is to make the scan happen before the push, not after the leak.

6. The screenshot and the error report

The weirdest vector, and the one no tool can catch. A stack trace with a connection string pasted into a GitHub issue. A screenshot of a terminal with the env dump visible. An error report that includes request headers.

This is a process problem, not a tooling problem:

Redact before you paste. Make it a habit, not a rule.
Review public issues and PRs for sensitive content before they go out.
Configure your error reporting to strip headers and query params.

You can't scan for a screenshot. You can only build the habit of looking before you share.

What to do when you find one

Order matters here, and people get it wrong:

Rotate the credential first. Not after cleanup. The moment you find a leaked secret, assume it's compromised. Rotation is the fix; everything else is cleanup.
Remove it from the working tree.
Clean history if it was public (BFG, git filter-repo).
Add the pattern to your scanner and your .gitignore.
Note down which credential was affected and for how long, so the team can check for misuse.

A note on false positives

Any content scanner will flag things that aren't real secrets: test fixtures with fake keys, documentation examples, placeholder values. That's expected, and it's why the output is a list to review, not a list to panic about.

The workflow is: run the scanner, look at each hit, and decide. If it's a real secret, rotate it. If it's a fixture, either change the value to something obviously fake or add it to your allowlist. A scanner that's fast and mostly right is still better than no scanner, because it turns "do we have a leak?" from a vague worry into a concrete list you can work through.

Why a security tool with zero dependencies

There's a reason dotguard has no dependencies, and it's not just minimalism. A secret scanner is a tool you want to trust with your most sensitive files. Every dependency is another supply chain you have to audit, another version to pin, another package that could get compromised. A scanner with zero dependencies is a scanner you can read end to end in an afternoon.

It also means it works in the places you actually need it: a fresh CI runner, a locked-down corporate machine, a container with nothing but Node. No npm install step that could fail, no lockfile to manage, no transitive dependency that quietly pulls in something you didn't ask for.

For a tool whose job is to protect you from things you didn't notice, being small and boring is a feature.

The 5-minute setup

If you take nothing else from this post, take this:

npm i -g @wuchunjie/dotguard
dotguard

One command. Zero dependencies. Scans your whole project for hardcoded secrets. Add the CI step if you want it to be a gate instead of a suggestion.

The habit, not the tool

Secrets leak slowly, and the fix isn't a single tool — it's a habit: scan before you push, scan in CI, and when you find something, rotate first.

dotguard is the smallest version of that habit: one command, no config, no dependencies. It's at @wuchunjie/dotguard on npm, MIT licensed, source at github.com/wuchunjie00/dotguard.

If you've found a secret in your own repo, I'd love to hear how you found it. The slow leaks are the ones worth talking about.

14 DevTools, Zero npm Packages: Why I Ship Pure HTML Instead of JavaScript

ke jia — Fri, 23 Oct 2026 13:59:26 +0000

I recently shipped a collection of 14 developer tools. A Cron parser, a JWT decoder, a Base64 encoder, a Diff tool, a QR code generator, and a dozen more. They're all useful, all client-side, and all instantly available in a browser tab.

Here's the part that surprises people: none of them have a package.json.

No npm install. No build step. No node_modules folder. No bundler. No framework. Each tool is a single HTML file you can open directly, host on any static server, or even email to a coworker.

This post is a comparison. I'll lay out the two approaches side by side — the "default" npm/JavaScript way and the pure-HTML way — and show you exactly where each one wins. Because the honest answer is that pure HTML is not always the right choice. I'll tell you when it is, and when you should absolutely reach for npm instead.

The default way, and why it feels heavy

If you asked most developers to build a "generate a UUID" tool, the path of least resistance looks like this:

npm create vite@latest uuid-tool
cd uuid-tool
npm install
npm install uuid
npm run dev

You now have a project. A package.json. A vite.config.js. A node_modules folder with a few hundred transitive dependencies. A build pipeline. And a tool that does one thing: print a random UUID.

None of that is wrong. For a real product, a real app, a real codebase that a team maintains, the npm ecosystem is a superpower. The problem is that the default has become so automatic that we reach for it even when the task is a 40-line utility that will never change.

For a one-off tool, that's a lot of machinery to spin up just to print a string.

What the collection actually is

Before the comparison, here's what we're comparing. The developer toolbox is 14 tools, each a self-contained HTML page:

Tool	What it does
Cron Expression Parser	Parse and visualize cron expressions (second/minute/hour/day/month/week)
YAML to JSON	Convert between YAML and JSON with live preview
URL Slug Generator	Turn titles into URL-friendly slugs, multilingual
HTML to Text	Strip HTML down to clean text
QR Code Generator	Generate QR codes for URLs, text, contacts
HTML Entities Encoder/Decoder	Encode/decode special characters to entities
UUID Generator	RFC 4122 v4 UUIDs, batch generation, format conversion
Password Generator	Strong passwords with custom length and character sets
Lorem Ipsum Generator	Placeholder text by paragraph/sentence/word
Hash Generator	SHA-1/256/384/512 for text and files
Base64 Encoder/Decoder	Text and file Base64, URL-safe mode
JWT Decoder	Decode and inspect JSON Web Tokens
Diff Tool	Side-by-side text diff with added/removed/changed highlighting
CSV to JSON	Convert between CSV and JSON with live preview

Every single one of these runs entirely in the browser. Your data never leaves the page. There's no backend, no API key, no "upload to our server" step. That last point matters more than it sounds, and I'll come back to it.

The comparison: pure HTML vs. npm

Let's go category by category. I'll be honest about where npm wins, because a comparison that only shows one side isn't a comparison.

1. Setup and distribution

npm: You need Node installed, you run npm install, you run a build, and you deploy the output. To use the tool, someone has to run your build or you have to host the built assets.

Pure HTML: The file is the distribution. You open it. You're done. You can host it on GitHub Pages, Netlify, S3, a company intranet, or literally send the .html file over Slack. There is no "how do I run this?" question.

Winner: Pure HTML, by a wide margin, for tools.

2. Build step

npm: A build step means a build config, a bundler, and the inevitable "it works on my machine but not in CI" debugging. It also means your source and your artifact are two different things that can drift apart.

Pure HTML: No build. What you write is what runs. There's nothing to misconfigure.

Winner: Pure HTML.

3. Dependencies and supply chain

This is the big one, and it's the reason I care about this so much.

npm: Every npm install pulls in a tree of transitive dependencies. Every one of those is a potential supply-chain risk. A compromised package, a malicious postinstall script, a typosquatted name — the npm ecosystem has seen all of it. When you depend on 300 packages to generate a UUID, you've accepted 300 chances for something to go wrong, most of which you've never read the source of.

Pure HTML: Zero dependencies. The only code running is the code you wrote and can read in its entirety. There is no node_modules to audit, no lockfile to trust, no transitive package you've never seen. The attack surface is the file itself, and the file is small enough to actually review.

Winner: Pure HTML, and this is the one I'd weight most heavily.

4. Offline and air-gapped use

npm: A built app can run offline, sure. But building it requires the network and the registry. And if you're in an air-gapped environment, getting the dependencies in is a real chore.

Pure HTML: The file works with no network at all. Open it on a machine with no internet and it just works. For teams in restricted environments, that's not a nice-to-have, it's the whole point.

Winner: Pure HTML.

5. Startup and performance

npm: A bundled SPA has to download and parse JavaScript before it can do anything. For a tool that does one thing, that's overhead you pay on every load.

Pure HTML: The page is small. It loads fast. There's no framework to hydrate, no bundle to parse. For a utility, the "app" is ready the moment the file finishes loading.

Winner: Pure HTML for small tools. (For a large, complex app, a well-optimized bundle can beat a hand-rolled page — but that's not what we're building here.)

6. Where npm genuinely wins

Now the honest part. Pure HTML is not a universal answer. npm is the right choice when:

You need a real library. If your tool needs a mature parser, a charting engine, or a crypto library with a track record, you want the battle-tested npm package, not a 200-line reimplementation you have to maintain forever.
You're building a product, not a tool. If this is going to be a maintained product with a team, tests, CI, and a release process, the npm ecosystem's tooling is a feature, not a burden.
You need to share code across projects. If the same logic lives in five places, a package with a version and a changelog beats copy-pasting HTML.
You need the ecosystem's edge cases handled. Date handling, internationalization, accessibility — the npm packages have had years of edge cases fixed by other people.

The rule I use: if the tool is small, stable, and single-purpose, pure HTML. If it's growing, shared, or complex, npm.

How I actually build these

For the curious: each tool is one HTML file with inline CSS and inline JavaScript. No framework, no transpiler. A few notes on the interesting bits:

Hashing and UUIDs use the browser's built-in Web Crypto API (crypto.subtle.digest, crypto.randomUUID). No external crypto library needed — the browser already ships a vetted implementation.
File handling (Hash, Base64) uses the FileReader API. Files are read locally and processed in the page. Nothing is uploaded.
The Diff tool implements a simple line-based diff in vanilla JS. It's not a full Myers diff, but for the "compare two config files" use case it's plenty, and it's 100% readable.
YAML/CSV parsing are small, focused parsers written for the specific shapes these tools need. They're not general-purpose YAML engines, and that's intentional — they do one job and are easy to verify.

The constraint of "no dependencies" is actually a design constraint, not just a technical one. It forces you to keep each tool small and focused. If a tool starts needing a real library, that's a signal it's outgrown the pure-HTML model — and that's fine, that's when you graduate it to npm.

The security angle (why "client-side" is a feature)

I keep coming back to this, so let me be explicit. A lot of "free online tools" work by sending your data to a server. You paste your JWT, your CSV, your config, and it goes to their machine. For a JWT decoder or a CSV converter, that means your secrets and your data are now in someone else's logs.

The pure-HTML approach sidesteps this entirely. Because there's no backend, your data never leaves your browser. The JWT you decode, the CSV you convert, the text you hash — it's processed locally and gone. For tools that touch sensitive data, "it runs in your browser" isn't a marketing line, it's the actual security model.

Combine that with zero dependencies (no supply-chain risk) and you get a tool that's safe in two different ways: it doesn't leak your data, and it doesn't pull in untrusted code.

When I'd reach for npm instead

To be concrete, here are the tools in this collection that I wouldn't have built in pure HTML if they were bigger:

A full-featured YAML editor with schema validation and autocomplete would need a real YAML library and a code editor component. That's npm territory.
A charting tool would want a maintained charting library, not a hand-rolled canvas renderer.
A large-file diff with merge capabilities would want a serious diff engine.

The 14 tools here are all deliberately in the "small and stable" zone. That's the zone where pure HTML wins. The moment a tool leaves that zone, I'd graduate it to a proper npm project without hesitation.

Try it

The collection is live at wuchunjie00.github.io/devtools, and the source is on GitHub. Every tool is a single HTML file you can read in full. If you're curious how a JWT decoder or a Diff tool works without a single dependency, the source is the best documentation — it's short enough to actually read.

The takeaway

The npm ecosystem is one of the best things that ever happened to JavaScript, and for real products it's irreplaceable. But the default has become so automatic that we spin up a build pipeline to print a UUID.

For small, stable, single-purpose tools, there's a lighter path: pure HTML, zero dependencies, runs in the browser, data never leaves the page. It's faster to ship, safer to run, and easier to trust — because the entire codebase is one file you can read in ten minutes.

Use npm when you're building a product. Use pure HTML when you're building a tool. And the next time you're about to npm create a project that's really just a converter, ask yourself: does this actually need a node_modules folder?

Sometimes the most modern thing you can do is write a single HTML file.

Grep-able Notes: Why Every Snippet Has to Survive a Search

ke jia — Sat, 26 Sep 2026 11:46:09 +0000

A snippet library is only as good as its worst search. You can store 200 perfect snippets, and if the one you need at 11pm doesn't come back from snippetx search, the library is a vault you can't open.

This post is about the naming and structuring discipline that makes a snippet library grep-able — the property that every entry can be found by a short, natural query. It's the part of the system that's easy to skip and impossible to retrofit.

The failure mode: the unfindable snippet

The telltale pattern of a library that's failing at search:

$ snippetx search deploy
# (12 results, none of them the one I need)

$ snippetx search "deploy to staging with the new pipeline"
# (0 results — I searched by *description*, not by name)

$ snippetx search staging
# (4 results — one of them is it, but I had to guess)

The snippet I need exists. I named it deploy-new-pipeline-v2 and saved it six months ago. But the query I'd actually type — "staging," "the new one," "the pipeline one" — doesn't match the name, and the content search doesn't help because the name is what I remember, not the content.

The library has the snippet. The library can't give it to me. That's the grep-ability failure.

The naming discipline

The fix is naming, and it's a discipline, not a one-time decision:

1. Name by what you'll search for, not what it is. The question isn't "what is this snippet?" — it's "what words will I type when I need it, six months from now, in a hurry?" For the staging deploy, the search words are "staging" and "deploy," so the name is deploy-staging. Not deploy-new-pipeline-v2 (what it is), not deployment-config (what a category would be). The name is the query.

2. Use the words you actually use. If I call the service "the API" in conversation, the snippet name should contain "api," not "backend-service." If I call the environment "staging" and not "pre-prod," the name contains "staging." The library's vocabulary has to match my vocabulary, because my vocabulary is the query.

3. Be specific enough to disambiguate, general enough to recall. deploy-staging is findable. deploy-staging-prod-fallback-canary-v2 is not — it's over-specified, and the query "deploy staging" won't match it because the name has moved on. The right name is the shortest string that (a) matches my natural query and (b) distinguishes this snippet from the other deploy snippets.

4. The language tag is a filter, not a name. snippetx's optional language tag (nginx, js, sh) is for snippetx list <filter>, not for search. Don't put the language in the name if it's already in the tag — nginx-301-regex with the tag nginx is redundant; 301-regex with the tag nginx is cleaner. (In practice I keep the prefix in the name too, because substring search on the name is more reliable than I'd like to admit.)

The content has to be greppable too

The name is half the story. The content is the other half, because the search matches content as well as name, and a snippet whose content is a wall of unbroken text is hard to confirm at a glance:

1. One logical thing per snippet. A snippet that's "the deploy command" is greppable. A snippet that's "the deploy command and the rollback command and the status command" is three snippets in one, and the search for "rollback" finds it but the search for "deploy" also finds it, and I can't tell which is which from the one-line preview. Split it.

2. The first line should be the most recognizable fragment. The search result shows the first line of the content as the preview. If the first line is #!/bin/bash or # TODO: clean this up, the preview is useless for confirmation. If the first line is the actual command or the most distinctive part of the config, I can confirm "yes, that's the one" from the preview alone.

3. Comments are search content. A # deploy to staging, uses the canary pipeline comment at the top of the snippet is matched by the search for "canary" and "staging" and "deploy." The comment is part of the grep surface — write it for the future-me who's searching, not for the present-me who just saved it.

The test: the 11pm query

The discipline works if it passes one test: at 11pm, in a hurry, with no context, can I type the words I'd naturally use and get the right snippet in the top result?

Not "can I find it if I think carefully about the naming convention." That's the 2pm test, and it passes for most libraries. The 11pm test is the real one, because the 11pm me isn't thinking about conventions — the 11pm me is typing the first words that come to mind, and the library has to meet those words where they are.

My library passes the 11pm test for the top 40 entries (the ones I actually use), and that's the bar. The other 160 in the graveyard fail it sometimes, and that's fine — they're the graveyard, and the graveyard's job is to be there, not to be findable.

The meta-point

A snippet library is a search system, not a storage system. The storage is trivial (a directory of text files); the search is the product. And search quality is determined at save time — by the name, the structure, the first line, the comments — not at query time. You can't make an un-greppable snippet greppable after the fact without re-saving it, and re-saving 200 snippets is the retrofit I described above.

So the discipline is front-loaded: name it for the query, structure it for the preview, comment it for the search. Do it at save time, for ten seconds, and the 11pm me gets the snippet. Skip it, and the 11pm me gets a vault they can't open.

snippetx add <name-for-the-query> <lang>

More Tools

Tool	What it does	Command
scaffoldx-cli	Production-ready project templates in seconds	`npx scaffoldx-cli`
dotguard	Scan .env files for exposed secrets	`npx @wuchunjie/dotguard`
gitpulse	Git repo analytics in your terminal	`npx @wuchunjie/gitpulse`
snippetx	Terminal code snippet manager	`npx @wuchunjie/snippetx`

If these save you time, consider buying me a coffee. All tools are MIT-licensed, zero-dependency, and run fully offline.

The 200-Snippet Graveyard: Why Cheap Storage Beats Curation

ke jia — Sat, 26 Sep 2026 11:45:06 +0000

My snippet library has 200 entries. I've used maybe 40 of them in the last month. The other 160 are, by any curation standard, dead weight — a graveyard of snippets I saved two years ago for projects that no longer exist.

I'm not going to clean them up. And I want to argue that the graveyard is a feature, not a bug, because the alternative — a curated, pruned, "quality" library — has a cost that's worse than the clutter.

This post is about that trade, and about why "cheap storage" is the right design principle for a personal snippet library.

The curation argument, steelmanned

The case for pruning is real:

Search noise. 200 entries means snippetx search deploy returns 12 results instead of 3. The right one is buried under stale ones.
False confidence. A stale snippet in the library looks as trustworthy as a current one. I might copy a deploy command from a project I left two years ago, and it'll be subtly wrong for the current setup.
Maintenance illusion. A "curated" library implies I'm maintaining it, and the maintenance is a recurring tax I'll eventually stop paying — at which point the library rots from the top down.

All true. I grant every point. Here's why I still don't prune.

The counter: curation is a decision, and decisions are expensive

Pruning a library means, for each entry, a judgment call: "is this worth keeping?" That's a decision with a real cost — not just the time, but the commitment. Every "keep" is a promise to maintain it; every "delete" is a risk of deleting the thing I'll need in three months for a project I can't currently see.

The graveyard avoids the decision entirely. The rule is: save freely, never prune, let search do the filtering. The cost of a stale entry is near-zero (it's a few lines of text in a local directory); the cost of a wrong deletion is real (the thing I can't reconstruct, in the moment I need it). Asymmetric costs favor the side with no decisions.

The graveyard is a record, not a clutter

Here's the part that changed my mind about pruning: the dead snippets are a record of how I worked. The 160 unused entries aren't waste — they're a log of the patterns I encountered, the problems I solved, the configs I needed, over two years. I don't use them, but they tell me things:

The cluster of docker-compose entries from 2024 tells me that was when I was doing the containerization work.
The three stripe-webhook entries tell me I wrestled with webhook signatures harder than I remember.
The k8s-ingress entries tell me that project's shape, in a form I'd have to reconstruct from memory otherwise.

A curated library is a record of what I currently value. A graveyard library is a record of what I actually did. The second is more honest, and more useful when I need to remember "how did I solve this before?"

Search is the curation that actually works

The graveyard only works if search is good enough to cut through the noise, and this is where the tool design matters. snippetx's search is a simple substring match across names and content, and it's good enough for 200 entries because:

The names are distinctive. I name snippets with the area-purpose-detail convention, so snippetx search 301-regex returns one result, not twelve.
The result is scannable. The search output is a one-line-per-entry format (id, name, language, first line of content), and I can pick the right one in a glance. The stale entries are visible as stale (old project names in the snippet name), which is itself a filter.
200 is small enough. The graveyard works at 200. At 2,000, substring search would drown, and I'd need tags or fuzzy matching. The scale limit is real — I'll hit it eventually — and when I do, the answer is better search, not pruning. The storage stays cheap; the retrieval gets smarter.

The design principle

The general principle: for personal reference tools, storage should be cheap enough that you never have to decide what to keep. The moment keeping something requires a decision, you stop saving the marginal thing, and the library becomes a curation project instead of a record.

snippetx's storage is a local directory of text files. The marginal cost of one more entry is zero — no quota, no subscription, no "your library is 80% full." That's the feature. The curation SaaS with its 500-entry limit and its "organize your library" prompts is solving a problem I don't have, by creating a problem I did.

The graveyard is 160 snippets I'll never use. It's also the only complete record I have of two years of actual work. I'm keeping both properties, and the price is a search result with a few extra lines. That's a trade I'll make again.

npx @wuchunjie/snippetx

More Tools

Tool	What it does	Command
scaffoldx-cli	Production-ready project templates in seconds	`npx scaffoldx-cli`
dotguard	Scan .env files for exposed secrets	`npx @wuchunjie/dotguard`
gitpulse	Git repo analytics in your terminal	`npx @wuchunjie/gitpulse`
snippetx	Terminal code snippet manager	`npx @wuchunjie/snippetx`

If these save you time, consider buying me a coffee. All tools are MIT-licensed, zero-dependency, and run fully offline.

My Nginx Configs Live in a Terminal, Not a Wiki

ke jia — Sat, 26 Sep 2026 11:45:00 +0000

I used to keep my nginx configs in a wiki. A shared page, "Useful Nginx Snippets," with maybe 30 config blocks, each with a heading and a paragraph of context. It was a fine wiki page, and it was a terrible reference.

The problem wasn't the content — it was the retrieval. When I'm configuring a server at 11pm and I need the exact location block that does a 301 with a regex capture, I'm not reading a wiki page. I'm in a terminal, I'm in the middle of an edit, and the wiki is a context switch: browser, search, scroll, find the block, copy, switch back. Four context switches for one config block.

So the configs moved to snippetx. Now the same block is two commands in the terminal I'm already in:

$ snippetx search redirect
b7e2d1  nginx-301-regex  nginx  location ~ ^/old/(.*)$ { return 301 /new/$1; }

$ snippetx copy b7e2d1 | pbcopy

No browser, no scroll, no switch. The config is in the clipboard by the time my hand is back on the terminal.

Why configs are the worst wiki content

Config blocks are a specific failure mode for wiki-based reference, and it's worth naming why:

1. They're exact, and wikis are fuzzy. A config block has to be precisely right — a missing semicolon, a wrong capture group, a directive in the wrong scope, and it doesn't work. Wiki pages are written for reading, and the act of copying from a rendered wiki page introduces errors: the markdown eats a character, the copy grabs a trailing space, the heading gets included. The terminal-to-terminal path (snippetx to clipboard) has none of that — the bytes are the bytes.

2. They're modified on use, not read on use. I rarely want the config as stored. I want it as a starting point — the 301 block with a different path, the rate-limit block with a different limit. A wiki gives me the stored version and I edit it after copying. snippetx gives me the stored version in the pipeline, where I can transform it before it hits the clipboard:

# Retrieve the rate-limit block, change the limit, copy
snippetx copy rate-limit-10rps | sed 's/10r/50r/g' | pbcopy

That last command is the whole argument. The snippet is a template in a pipeline, and the pipeline is where the modification happens. A wiki can't be a pipeline.

3. They're looked up by fragment, not by title. I rarely know the name of the config I need. I know a fragment: "the one with the proxy_set_header for the auth token." A wiki's search is title-and-full-text, and "proxy_set_header auth" matches five blocks. snippetx's search is the same, but the result is a one-liner I can scan in the terminal — the id, the name, and the first line of the block — and I pick the right one in a glance. The wiki's result is a list of page sections I have to scroll to.

What the library looks like now

About 40 nginx entries, plus a dozen of other config blocks (envoy, docker compose fragments, kubectl one-liners). The naming convention is area-purpose-detail:

nginx-301-regex
nginx-rate-limit-10rps
nginx-auth-header-proxy
nginx-ssl-redirect
compose-postgres-16

The names are searchable by any fragment, and the language tag (nginx, compose, kubectl) lets me filter the list when I'm in a specific config context.

The migration cost, honestly

Moving the configs from the wiki to snippetx took an afternoon, and it was the most boring part: re-typing each block as a snippetx add (piping the block in from a file). The wiki's 30 blocks became 40 snippets (I added the ones I'd been meaning to save while I was in there).

The payoff showed up the first night I needed a config at an unusual hour. I was in the middle of a deploy, the terminal was open, and the config I needed was two commands away instead of four context switches away. The difference was maybe ten seconds, but the flow difference was real — I didn't leave the terminal, and I didn't lose the thread of the deploy.

The meta-point

Reference material should live in the medium you use it in. My configs are used in a terminal, so they live in a terminal. The wiki is the right home for the explanation of the configs (why the rate limit is 10rps, what the auth header does) — and the explanation can link to the snippet id. But the config itself belongs in the pipe.

The wiki tells you what the block does. snippetx gives you the block, in the terminal, ready to be modified and pasted. Both are useful. They're just not the same artifact, and keeping them in the same place is how the wiki became a terrible reference.

snippetx search nginx && snippetx copy <id> | pbcopy

More Tools

Tool	What it does	Command
scaffoldx-cli	Production-ready project templates in seconds	`npx scaffoldx-cli`
dotguard	Scan .env files for exposed secrets	`npx @wuchunjie/dotguard`
gitpulse	Git repo analytics in your terminal	`npx @wuchunjie/gitpulse`
snippetx	Terminal code snippet manager	`npx @wuchunjie/snippetx`

If these save you time, consider buying me a coffee. All tools are MIT-licensed, zero-dependency, and run fully offline.

The Snippet List I Hand to Contractors Before Their First Commit

ke jia — Sat, 26 Sep 2026 11:44:10 +0000

When a contractor joins a project for a week or a sprint, the onboarding problem isn't the code — it's the context. The code is in the repo. The context is in the heads of the people who've been here a year, and it doesn't transfer in a wiki page.

I've stopped writing wiki onboarding pages. Instead, I hand the contractor a snippet list — a curated set of the commands, configs, and one-liners they'll actually need in the first 48 hours, stored in snippetx and shared as a plain-text export.

This post is about that practice, and why a list of commands is a better onboarding artifact than a document.

Why the wiki page fails

The standard onboarding doc has a structural problem: it's written for the reader who doesn't have the questions yet. It explains the architecture, the conventions, the deploy process — all true, all useful, all in the wrong order. The contractor's first-day questions are concrete and immediate:

"How do I run the tests?"
"What's the command to deploy to staging?"
"How do I get a local database with the right schema?"
"What's the curl to hit the health endpoint?"

The wiki page answers none of these in a form that's usable at the moment of asking. It has the information, but it's buried in prose, and the contractor is in a terminal, not a browser.

The snippet list answers the questions as commands, in the form they'll actually be typed.

What the list contains

The list is small on purpose — 10-20 entries, each a command or config with a two-word name and a one-line description. The actual entries, from a recent project:

# run-tests
npm test -- --watch

# seed-local-db
npm run db:reset && npm run db:seed

# deploy-staging
npm run build && ./scripts/deploy.sh staging

# health-check
curl -s https://staging.example.com/health | jq .

# tail-api-logs
kubectl logs -f -n prod -l app=api

# reset-migrations
npx prisma migrate reset --force

# create-user
npm run script:create-user -- --email dev@example.com

# clear-cache
rm -rf node_modules/.cache && npm run build

Each entry is a thing they'll do, not a concept they'll learn. The list is a map of the first 48 hours, in the contractor's own working medium (the terminal), in the form they'll use it (copy-paste).

How it's shared

The list lives in a snippetx library on my machine, and the sharing is a plain-text export — no account, no app, no permission dance:

# Export the onboarding list as a file
for id in $(snippetx search onboarding | awk '{print $1}'); do
  echo "### $(snippetx show $id | head -1)"
  snippetx copy $id
  echo
done > onboarding-snippets.txt

The contractor gets onboarding-snippets.txt — a file they can read, grep, and paste from. It's version-controlled in the repo (or sent over chat), it's plain text, and it works on any machine with a terminal. No onboarding SaaS, no shared library account, no "let me get you access."

What changed after I started doing this

1. The first-day questions dropped by half. The questions that remained were the ones a command list can't answer ("why does the deploy script do X?") — the genuinely conceptual ones. The "how do I do Y" questions, which used to be 80% of the first-day interruptions, mostly didn't come, because the answer was in the file.

2. The contractors were productive faster. A contractor who can run the tests and hit the health endpoint in the first hour is a contractor who's in the project by lunch. The time previously spent hunting for commands was time spent reading code.

3. The list improved itself. Every first-day question that wasn't in the list became a new entry. After three contractors, the list had converged on the actual 48-hour workflow, which is more accurate than any wiki page I'd have written from memory.

The meta-point

Onboarding isn't a documentation problem; it's a medium problem. The contractor works in a terminal, so the onboarding should be in a terminal. The wiki page is the right artifact for the conceptual context (the architecture, the why) and the wrong artifact for the operational context (the commands, the how).

The snippet list is the operational half. It's small, it's concrete, it's in the right medium, and it improves itself with every contractor who uses it. The wiki page can keep the concepts. The terminal gets the commands.

npx @wuchunjie/snippetx

More Tools

Tool	What it does	Command
scaffoldx-cli	Production-ready project templates in seconds	`npx scaffoldx-cli`
dotguard	Scan .env files for exposed secrets	`npx @wuchunjie/dotguard`
gitpulse	Git repo analytics in your terminal	`npx @wuchunjie/gitpulse`
snippetx	Terminal code snippet manager	`npx @wuchunjie/snippetx`

If these save you time, consider buying me a coffee. All tools are MIT-licensed, zero-dependency, and run fully offline.

snippetx copy | pbcopy: The Pipe That Made Snippets Actually Useful

ke jia — Sat, 26 Sep 2026 11:44:05 +0000

A snippet manager that makes you click "Copy to Clipboard" in a GUI has a hidden cost: it takes you out of the terminal. You're in a shell, mid-pipeline, and the copy action is a context switch — mouse to the app, click, back to the terminal.

snippetx sidesteps the whole problem with one design decision: snippetx copy <id> prints the snippet to stdout. No clipboard API, no GUI, no context switch. The snippet is just another thing that can be piped, and "copy to clipboard" becomes | pbcopy (macOS), | clip.exe (Windows), or | xclip -selection clipboard (Linux).

This post is about why that one decision — stdout as the copy mechanism — is the difference between a snippet manager you use and one you own.

The pipe, concretely

The full workflow, entirely in the terminal:

# Find the snippet
$ snippetx search nginx
a3f9c2  nginx-redirect  nginx  server { ... 301 ... }

# Copy it to the clipboard
$ snippetx copy a3f9c2 | pbcopy

# ...paste it wherever you need it, terminal or GUI

No mouse. No app switch. The search, the retrieval, and the copy are three commands in the same shell, in the same breath. The snippet flows through the same pipes as everything else you do in a terminal.

Why stdout is the right "copy"

1. It composes with everything. A snippet that prints to stdout can go to a clipboard, to a file, to another command, to a here-doc. The same copy command serves all of them:

# To a file
snippetx copy a3f9c2 > /tmp/redirect.conf

# Into a command
docker run -i --rm alpine sh -c 'cat > /app/entrypoint.sh' < <(snippetx copy entrypoint)

# Piped through another tool
snippetx copy a3f9c2 | sed 's/old.example.com/new.example.com/g' | pbcopy

The last one is the killer use case: retrieve the snippet, transform it, then copy. A GUI copy button can't do that. A stdout pipe can, because the snippet is just text in a pipeline.

2. It's scriptable. A snippet that's on stdout can be used in a script, a Makefile, a CI step. "Copy the deploy snippet and run it" is a shell line, not a manual sequence. The library becomes part of your automation, not just a reference you consult.

3. It works everywhere a terminal works. No clipboard daemon, no X11 dependency, no GUI toolkit. Over SSH, in a container, on a headless box, in a tmux pane — snippetx copy <id> produces the text, and what you do with the text is up to the environment. The tool doesn't assume a desktop.

The cross-platform clipboard, honestly

The one wrinkle: the clipboard command differs by OS. That's not a snippetx limitation — it's a property of the environment, and the fix is a shell alias:

# ~/.zshrc (macOS)
alias clip='pbcopy'
# ~/.bashrc (Linux)
alias clip='xclip -selection clipboard'
# Windows: use 'clip.exe' directly

With the alias, the workflow is snippetx copy <id> | clip on any machine, and the alias is a one-time setup. The point stands: the copy is a pipe, and the pipe is the same everywhere.

What the pipe did to my usage

The GUI-copy version of this tool (I used one) had a telltale pattern: I'd look up a snippet, copy it, and sometimes not paste it, because the context switch was enough friction that I'd re-type the thing from memory instead. The stdout version removed that failure mode — the snippet is already in the clipboard by the time I'm back at the paste point, and re-typing is now the slower path.

The usage data is the proof: the top snippets in my library are the ones that are piped into other commands, not just copied. The copy | transform | clip pattern is the most-used workflow in the library, and it only exists because the copy is a pipe.

The design lesson

The general principle: if your tool's output is text, make it stdout. A tool that writes to stdout is a tool that composes. A tool that writes to a GUI, a file, or a proprietary format is a tool that's a dead end in the pipeline.

snippetx could have had a "copy to clipboard" button, a GUI viewer, a mobile sync — and it would have been a better app. But it would have been a worse tool, because the app-ness would have put walls between the snippet and the rest of the terminal. The stdout decision is the difference, and it's the reason the snippets actually flow into the work instead of sitting in a library I visit.

snippetx search <term> && snippetx copy <id> | pbcopy

More Tools

Tool	What it does	Command
scaffoldx-cli	Production-ready project templates in seconds	`npx scaffoldx-cli`
dotguard	Scan .env files for exposed secrets	`npx @wuchunjie/dotguard`
gitpulse	Git repo analytics in your terminal	`npx @wuchunjie/gitpulse`
snippetx	Terminal code snippet manager	`npx @wuchunjie/snippetx`

If these save you time, consider buying me a coffee. All tools are MIT-licensed, zero-dependency, and run fully offline.

If You Paste It Twice, It Earns a Name: The Rule That Built My Snippet Library

ke jia — Sat, 26 Sep 2026 11:43:21 +0000

My snippet library has about 200 entries. It wasn't built by curation — I didn't sit down and design a taxonomy. It was built by one rule, applied over months:

If I'm about to paste something for the second time, it earns a name.

The tool doing the holding is snippetx, a zero-dependency terminal snippet manager. But the library's shape is the rule's shape, and the rule is worth writing down because it's the difference between a snippet library and a junk drawer.

The rule, precisely

The trigger is the second paste, not the first. This matters:

First paste: just paste it. It's a one-off. Naming it would be overhead with no payoff.
Second paste: stop. This is now a pattern. Give it a name and save it:

echo '<the snippet>' | snippetx add <name> <lang>

Third and later pastes: snippetx search <term> and snippetx copy <id>. The paste is now a lookup, and the lookup is faster than re-deriving or hunting through browser history.

The rule has a built-in filter: one-offs don't get saved. That's the feature. A junk drawer is full of one-offs that got saved on the first paste "just in case." My library is full of two-pasters and above, which means every entry has at least two data points proving it's worth keeping.

Why the second paste is the right threshold

Because it's the first point where the snippet has evidence of recurrence. The first paste is a hypothesis ("I might need this again"). The second paste is a confirmed prediction. Saving at the second paste means:

Every entry is earned. No speculative entries, no "this looks useful" graveyard. The library's content is a record of what I actually reuse, which is the only curation that's honest.
The naming cost is amortized. Naming a snippet takes ten seconds. If the snippet is a one-off, those ten seconds are pure loss. If it's a two-paster, the ten seconds are paid back on the second use and in profit on every use after. The second paste is exactly where the break-even happens.
The library stays small enough to trust. 200 entries is searchable. 2,000 entries is a database I don't want to maintain. The rule's filter keeps me in the first regime.

What the rule did to my habits

After a few months, the rule changed how I work in ways beyond the snippets themselves:

1. I name things as I encounter them. The act of naming a snippet forces a two-word description, and the two-word description is often the name the thing should have had. A snippet I named retry-backoff turned out to be the pattern I'd been re-deriving in five different projects — naming it surfaced the pattern, and the pattern became a function.

2. My "useful commands" stopped living in my head. The rule externalized the stuff I used to memorize. The kubectl one-liners, the jq filters, the nginx redirects — they're in the library now, and "I used to know that command" became "I can find that command." The library is a second brain with a search box, and the search box is the part that makes it work.

3. The library is a map of my actual work. The 200 entries, sorted by use frequency, are a record of what I actually spend time on. The top 20 are 90% of the lookups. That's not a curation decision — it's an emergence. The rule produced the library's shape without me deciding what to keep.

The tool's role

snippetx is deliberately minimal — it's the storage and the search, nothing more:

snippetx add <name> [lang]    # save (pipe content in)
snippetx list [filter]        # list
snippetx search <term>        # search
snippetx copy <id>            # output to stdout

No cloud, no sync, no mobile app, no account. The snippets live in a local directory, and the manager is a single zero-dependency Node file. The tool's job is to make the rule cheap to apply — the add is one piped command, the search is one word, the copy is one id. If the tool were heavier than the rule, the rule would die from friction. It isn't.

The meta-point

A snippet library isn't a storage problem; it's a curation problem, and curation is the part that usually fails. People build junk drawers because saving is cheap and deciding-what-to-keep is hard. The rule inverts that: it makes keeping the expensive act (you have to name it) and saving the cheap act (one piped command), and it gates keeping on evidence (the second paste).

The library that survives is the one where every entry earned its place. The second-paste rule is how mine got there, and it's the whole system — the tool is just the part that makes it frictionless.

npx @wuchunjie/snippetx

More Tools

Tool	What it does	Command
scaffoldx-cli	Production-ready project templates in seconds	`npx scaffoldx-cli`
dotguard	Scan .env files for exposed secrets	`npx @wuchunjie/dotguard`
gitpulse	Git repo analytics in your terminal	`npx @wuchunjie/gitpulse`
snippetx	Terminal code snippet manager	`npx @wuchunjie/snippetx`

If these save you time, consider buying me a coffee. All tools are MIT-licensed, zero-dependency, and run fully offline.

The FastAPI Template Is the One My Non-Frontend Friends Actually Use

ke jia — Sat, 26 Sep 2026 11:43:16 +0000

Most scaffolders are Node-only, and that's fine — Node is the default runtime for web tooling. But my non-frontend friends (the data people, the ML people, the infra people) don't want a Node project when they want a backend. They want Python.

The FastAPI template in scaffoldx-cli is the one I hand them. It's a small, complete FastAPI service — async, Pydantic-validated, with OpenAPI docs and a pytest setup — generated by the same npx command as the Node templates. One tool, two ecosystems, and the Python side is where the unexpected adoption happened.

This post is about that template, and about why a "Node CLI that also does Python" is a better pattern than a separate Python scaffolder.

What the template ships

The generated service is a minimal-but-complete FastAPI app:

An async app — async def handlers from the start, because "make it async later" is a refactor you don't want to do after the handlers are written. The template's position: if you're building a modern service, it's async from the first file.
A Pydantic model — a request/response schema that's the single source of truth for validation. The handler takes a typed model, not a raw Request you have to parse by hand. Type validation is the framework's job, not yours.
A health endpoint — /health that returns {"status": "ok"}, so the service has a liveness check from the first deploy. Boring, and exactly the right kind of boring for a starter.
OpenAPI docs for free — FastAPI generates /docs and /openapi.json automatically. The template doesn't add anything here; it just doesn't get in the way of the framework's best feature.
A pytest setup — a test_health.py that hits the health endpoint, so the first test run is green and the "how do I add a test" question has an answer in the repo.

The whole service is a handful of files: main.py, a models.py, a test, a requirements.txt. It runs with uvicorn main:app and the docs are at /docs before you've written a line of your own logic.

Why it lives in a Node CLI

The obvious question: why is a Python template in an npx command? Isn't that weird?

It's not, for three reasons:

1. The user's entry point is the CLI, not the language. My non-frontend friends are already in a terminal running npx for their Node projects. Adding a Python backend to the same command means one tool to remember, one muscle memory, one place to look when they want to start a project of any kind. The npx entry point is a convenience, not a statement about what the generated code is.

2. The scaffolder is language-agnostic by design. scaffoldx-cli is a file writer — it writes template files to disk. The templates are content, not code the scaffolder executes. A Python template is just a set of Python files; the scaffolder doesn't care what language they're in. That's the whole reason a single CLI can serve multiple ecosystems: the scaffolder's job (write files, git init, first commit) is orthogonal to the template's language.

3. A separate Python scaffolder is a separate maintenance burden. A second tool means a second package to publish, a second version to track, a second "where did I put that" for the user. Folding the Python templates into the existing CLI keeps the surface area at one tool. The user doesn't need to know or care that the scaffolder is a Node script; they need npx scaffoldx-cli to give them a FastAPI app, and it does.

What the non-frontend friends actually do with it

The adoption pattern is consistent:

The data person uses it as the API layer for a data pipeline — the Pydantic models become the contract between the pipeline and the consumer, and the OpenAPI docs are the integration spec.
The ML person uses it as the serving wrapper for a model — the async handler loads the model, the Pydantic model validates the inference request, and /docs is the endpoint reference the front-end team uses.
The infra person uses it as a reference implementation — "here's what a minimal, correct, tested FastAPI service looks like" — and copies the structure rather than the code.

In all three cases, the value isn't "it saved me 30 minutes of typing." It's that the template encodes the shape of a correct FastAPI service (async, validated, documented, tested) in a way that's easier to copy than to derive, and the npx entry point means they can get that shape without leaving the tool they already use.

The honest limit

The template is a starter, not a framework. It doesn't add ORM integration, auth, or deployment config — those are decisions your specific service will make. Its job is to get you from "I want a FastAPI service" to "I have a running, validated, documented, tested service I can extend" in the minimum number of steps. Everything after that is your architecture, on a base that's already correct in the places that are easy to get wrong.

npx scaffoldx-cli
# choose: FastAPI Backend

One tool, two ecosystems, and the Python side is the one that surprised me. Sometimes the most useful feature is the one in the language you didn't expect to need it in.

npx scaffoldx-cli

More Tools

Tool	What it does	Command
scaffoldx-cli	Production-ready project templates in seconds	`npx scaffoldx-cli`
dotguard	Scan .env files for exposed secrets	`npx @wuchunjie/dotguard`
gitpulse	Git repo analytics in your terminal	`npx @wuchunjie/gitpulse`
snippetx	Terminal code snippet manager	`npx @wuchunjie/snippetx`

If these save you time, consider buying me a coffee. All tools are MIT-licensed, zero-dependency, and run fully offline.

The Landing Page Template Is the One I Give to Clients Who Hate Setup

ke jia — Sat, 26 Sep 2026 11:42:27 +0000

Some clients don't want a framework. They don't want a build step. They don't want a node_modules folder, a dev server, or a terminal they have to understand. They want a page.

For those clients, the Modern Landing Page template in scaffoldx-cli is the one I reach for. It's the template that says: "here's a responsive, modern landing page, no build step, no framework, no setup. Open the file, edit the text, ship it."

This post is about that template, and about the underrated art of matching the tool to the client's tolerance for complexity.

What the template ships

The generated project is deliberately small:

One HTML file — semantic structure, a header, a hero, a features section, a CTA, a footer. Modern reset CSS, no framework, no CDN dependencies (the CSS is inline, so the page works offline and has no third-party requests).
Responsive by construction — the layout is mobile-first with a few breakpoints; it looks right on a phone before it looks right on a desktop, because that's the order most visitors will actually see it.
A CTA section that's actually wired — the call-to-action button links to a mailto or a form placeholder, so the page has a conversion path from the first render, not after the client asks "where does the button go?"
A gradient hero — the visual hook is there by default, so the page doesn't look like a wireframe. The client sees a page, not a skeleton.

The whole thing is a handful of files you can open in any text editor. No npm install, no dev server, no build. Double-click index.html and it's there.

Why "no build step" is a feature for this client

The client who hates setup isn't being irrational — they're telling you their constraint. For them, every build step is a failure mode:

A build step is a dependency on my machine. If I have to run npm run build and my Node version is wrong, the page doesn't ship. No build step means the deliverable is files, and files don't have a Node version.
A build step is a maintenance burden I'll inherit. Every framework I add is something I'll have to understand when I want to change the button color in six months. No framework means the "change the button color" edit is a CSS value, and I can find it in ten seconds.
A build step is a trust barrier. Many of these clients will hand the site to someone else (a junior, an agency, a VA) for maintenance. The simpler the stack, the more maintainable it is by a stranger.

The landing page template is designed for exactly this maintenance profile: the next person to touch it needs to understand HTML and CSS, and that's it.

When NOT to use it

Honest limits, because "no build step" isn't always right:

The page will grow into an app. If the client's "landing page" is actually the front door to a product with auth, state, and API calls, a framework is the right start. The landing template's simplicity is an asset for a page and a liability for an app.
The design is complex. Heavy animation, a complex component system, or a design system the client will extend — that's framework territory. The template's inline CSS is great for a page and a pain for a design system.
The team is a web team. If the maintainers are professional frontenders who live in a framework, the no-build template is a step backward for them. Match the tool to the maintainers, not just the client.

For the client who wants a page and will maintain it (or hand it to someone who will), the no-build template is the professional choice — not the lazy one. It's the choice that matches the deliverable to the actual maintenance reality.

The practical flow

npx scaffoldx-cli
# choose: Modern Landing Page
# name it

The output is a directory with index.html and a small styles.css. Open index.html in a browser — the page is there, responsive, with the CTA wired. Edit the text in the HTML, the colors in the CSS, and you're done. No terminal required after the one npx command.

That's the whole pitch: one command, zero setup, a page that works and is maintainable by the person who'll actually maintain it. For the right client, that's not a compromise — it's the deliverable.

npx scaffoldx-cli

More Tools

Tool	What it does	Command
scaffoldx-cli	Production-ready project templates in seconds	`npx scaffoldx-cli`
dotguard	Scan .env files for exposed secrets	`npx @wuchunjie/dotguard`
gitpulse	Git repo analytics in your terminal	`npx @wuchunjie/gitpulse`
snippetx	Terminal code snippet manager	`npx @wuchunjie/snippetx`

If these save you time, consider buying me a coffee. All tools are MIT-licensed, zero-dependency, and run fully offline.

Strict TypeScript by Default: The Starter That Refuses to Let You Be Lazy

ke jia — Sat, 26 Sep 2026 11:42:13 +0000

Every TypeScript starter ships a tsconfig.json. Almost every one ships it with strict: false, or with a partial strict config that leaves the most useful checks off. The reasoning is usually kindness: "don't scare the new dev with a wall of type errors on day one."

I think that's backwards. The first week of a project is when type discipline gets set, and a starter that defaults to lax checking is teaching the team the wrong lesson. It's easier to start strict and loosen a specific check that's genuinely in your way than to start lax and retrofit strictness onto a codebase that's already full of any-shaped holes.

This is the position I built into the TypeScript templates in scaffoldx-cli: strict: true from the first file, no opt-out prompt, no "relaxed mode" option.

What strict mode actually buys you in week one

The checks that matter most in a new project are the ones that catch the first errors, when they're cheap to fix:

1. noImplicitAny — the function parameter you forgot to type. In week one, that's a five-second fix. In month three, after 200 untyped parameters have propagated, it's a refactor.

2. strictNullChecks — the user.name that throws when user is undefined. This is the single most valuable check in the list, and it's the one lax configs disable most often "because it's annoying." The annoyance is the point: it's the check that turns "undefined at 2am in production" into "type error at 2pm in development."

3. noImplicitReturns — the function that returns a value on some paths and undefined on others. A new project is when your function shapes are being decided; catching a missing return while the function is three lines long is free.

4. noUnusedLocals / noUnusedParameters — the dead code that tells you the design changed and the old path wasn't cleaned up. In a new project, "unused" almost always means "I should delete this," and the compiler is doing your cleanup pass for free.

The "it's too annoying" objection, handled

The standard objection: "strict mode generates a wall of errors and slows me down." True, in the first hour. The counter:

The errors are front-loaded, not ongoing. A strict config produces its maximum error count in the first few files, when the codebase is small. Once the base types are in place, the steady-state error rate drops to near zero — you're not fighting the compiler all day, you're fighting it for an hour and then it's a safety net.

The "annoying" errors are the cheap ones. The errors strict mode generates in week one are almost all five-second fixes (add a type, handle the null, return on the missing path). The errors it prevents are the expensive ones (runtime undefined, silent type drift, the refactor that strict mode would have made unnecessary). The trade is a hour of cheap fixes for a year of avoided expensive ones.

Loosening one check is easy; tightening is hard. If noUnusedParameters is genuinely in your way (say, you have a callback interface that requires an unused argument), you can suppress it per-line or disable that one flag. Starting lax means you've disabled all the checks, and re-enabling them one by one on a grown codebase is the expensive direction.

The starter's actual config

The TypeScript templates ship with a tsconfig that's strict and boring:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "skipLibCheck": true,
    "esModuleInterop": true
  }
}

skipLibCheck: true is the one pragmatic concession — it stops the compiler from type-checking node_modules's declaration files, which is a tax nobody wants. Everything else is on. There's no --relaxed flag, no prompt asking if you want strict mode, no "easy mode" template. The position is deliberate: a starter that makes you think about your type discipline is a starter that's doing its job.

The meta-point

A starter encodes a position on how the team will work. "We type-check strictly from day one" is a position, and it's the right one for a new project, where the cost of the position is an hour and the benefit is a year. The lax starter encodes the opposite position — "we'll get to types when we need to" — and "when we need to" is always later and more expensive than "day one."

Pick the starter that argues for the discipline you want, because the discipline you don't pick on day one is the discipline you'll have to fight for in month three.

npx scaffoldx-cli

More Tools

Tool	What it does	Command
scaffoldx-cli	Production-ready project templates in seconds	`npx scaffoldx-cli`
dotguard	Scan .env files for exposed secrets	`npx @wuchunjie/dotguard`
gitpulse	Git repo analytics in your terminal	`npx @wuchunjie/gitpulse`
snippetx	Terminal code snippet manager	`npx @wuchunjie/snippetx`

If these save you time, consider buying me a coffee. All tools are MIT-licensed, zero-dependency, and run fully offline.

The Discord Bot Template That Doesn't Drag in a Framework

ke jia — Sat, 26 Sep 2026 11:41:18 +0000

The first thing most Discord bot tutorials do is add a framework. A "bot framework" with a plugin system, a command registry, an event bus, and a configuration layer. For a bot that says "ping" when you say "pong," that's like buying a crane to hang one picture.

The Discord Bot template in scaffoldx-cli takes the opposite position: discord.js, slash commands, and an event handler — and nothing else. No framework, no plugin system, no abstractions you haven't asked for.

This post is the case for that position, and the honest accounting of when you should reach for the framework anyway.

What the template ships

The generated bot is three things:

A client that connects with your token (read from the environment, never committed — the template's .gitignore excludes .env and ships .env.example with DISCORD_TOKEN=your-token-here).
A slash-command registration step that registers a starter /ping command with the API, so the first run has a working command to test against.
An event handler skeleton — messageCreate and the command interaction handler — with the routing logic explicit and short enough to read in one sitting.

The whole generated index.js is under 100 lines. You can read the entire bot, including the parts you didn't write, in five minutes.

Why "no framework" is a feature, not a limitation

1. The abstraction tax is real, and it's paid in debugging. A bot framework's command registry is convenient until the command doesn't fire, and you spend an hour discovering that the registry's matching logic normalizes command names in a way your input didn't. With discord.js's native interaction handler, the routing is two lines of code you can trace in your head. The framework's abstraction is a wall between you and the actual event, and for a small bot, that wall is pure cost.

2. discord.js is already the framework. This is the key point people miss: discord.js v14 is a complete, well-maintained library. It has the client, the event system, the interaction router, and the REST API. The "bot framework" layer on top is solving problems that discord.js already solved, for the convenience of a structure that only pays off at a certain scale. Below that scale, it's a middleman.

3. The template scales by adding, not by migrating. When the bot outgrows 100 lines, you don't migrate to a framework — you add files. A commands/ directory, a small router, a config module. Each addition is a normal Node.js refactor, visible in the diff, with no framework migration in the middle. The "no framework" start doesn't trap you; it just delays the abstraction until you actually need it.

When you should use the framework anyway

Honest counterargument, because "no framework" is not universally right:

Large teams, many contributors. A framework's command registry and plugin conventions are a coordination tool — they make 10 people add commands without colliding. If your bot is a team product with 5+ contributors, the framework's structure is worth its tax.
Plugin architecture as a product. If the bot's feature is that users can install plugins, you need the plugin system. That's a product requirement, not a convenience.
You've already chosen an ecosystem. If your team standardizes on a framework for consistency across projects, consistency has its own value.

For the common case — a small bot, one or two developers, a feature list you can hold in your head — the no-framework start is the faster path to a working bot, and the path that keeps the code readable as it grows.

The practical start

npx scaffoldx-cli
# choose: Discord Bot
# name it, npm install, put your token in .env
node index.js

First run registers /ping, and the bot answers in the channel where you invoke it. That's the whole demo loop — no framework setup, no plugin config, no reading a framework's documentation before you've written a single line of your own logic.

The template's job is to get you from "I want to build a Discord bot" to "my bot is responding to a slash command" in the minimum number of steps that don't involve reading a framework's architecture doc. Everything you add after that is your design, on a base you fully understand.

npx scaffoldx-cli

More Tools

Tool	What it does	Command
scaffoldx-cli	Production-ready project templates in seconds	`npx scaffoldx-cli`
dotguard	Scan .env files for exposed secrets	`npx @wuchunjie/dotguard`
gitpulse	Git repo analytics in your terminal	`npx @wuchunjie/gitpulse`
snippetx	Terminal code snippet manager	`npx @wuchunjie/snippetx`

If these save you time, consider buying me a coffee. All tools are MIT-licensed, zero-dependency, and run fully offline.