DEV Community: Recca Tsai

Find Dead Code with Knip: The Blind Spots ESLint and depcheck Miss

Recca Tsai — Sat, 02 May 2026 08:38:34 +0000

Originally published at recca0120.github.io

The project is two years old. There are 80 entries in package.json and you can't say with confidence which ones are still being used. A utils.ts file hasn't been touched in three months — you're not sure if anyone imports it. shared/helpers.ts exports a dozen functions, some of which were replaced by newer approaches months ago, but nobody deleted the old ones.

Dead code doesn't accumulate overnight. A little left over from each refactor, one forgotten dependency from each package swap. Over time the project gets heavier, but no tool ever tells you exactly what's dead.

Knip is built for exactly this. One command finds everything you thought was being used but isn't.

The Blind Spots in ESLint and depcheck

Most teams reach for ESLint and depcheck to handle this kind of thing. Both have clear limits.

ESLint only sees a single file. It can tell you "there's a const x in this function that's never used," but if an entire utils.ts is never imported anywhere, ESLint won't notice. Its view stops at the file boundary — it can't trace cross-file reference chains.

depcheck only looks at package.json. It scans for require and import statements to see which packages are actually referenced, then flags anything that's installed but unused. But it doesn't understand TypeScript export/import semantics, and it has no concept of which files are never referenced at all.

Together they still leave a gap: cross-file export usage — nothing tracks it.

Knip works differently. Starting from configured entry points, it builds a complete module graph tracing every import, export, and dependency. Anything not connected to the graph is dead code.

What It Finds

A single knip run finds:

Unused npm dependencies: installed but never imported anywhere
Unlisted dependencies: imported in code but missing from package.json (implicit reliance on a transitive dep)
Unused exports: exported but never imported anywhere
Unused files: entire files never referenced from anywhere
Unresolved imports: imports pointing to paths or modules that don't exist

These problems used to require several tools stitched together, with gaps remaining. Knip covers all of them.

Vercel used Knip to delete nearly 300,000 lines of code. That's their own number, not marketing copy.

Installation and Usage

No installation required — just run it:

npx knip

Or add it to devDependencies:

npm install -D knip
npx knip

Knip ships with around 150 plugins covering Vite, Vitest, Next.js, Astro, ESLint, GitHub Actions, and more. In most projects, zero configuration is needed — it auto-detects the tooling in use.

Reading the Output

After a run, the output looks something like this:

Unused files (2)
src/legacy/old-helper.ts
src/utils/deprecated.ts

Unused dependencies (3)
lodash
moment
@types/node  (devDependencies)

Unused exports (5)
src/shared/helpers.ts: formatDate, parseQuery
src/utils/string.ts: capitalize, truncate, slugify

Each category is clear: which files are entirely unreferenced, which packages can be removed, which exports have no importers.

The first run usually surfaces a lot. Don't try to fix everything at once. Start with unused dependencies (easy wins), then work through unused exports, and finally tackle entire unused files.

Configuration

If you need to customize, add a knip.json at the project root (or a knip key in package.json):

{
  "entry": ["src/index.ts", "src/pages/**/*.tsx"],
  "project": ["src/**/*.{ts,tsx}"],
  "ignore": ["src/legacy/**", "**/*.stories.ts"],
  "ignoreDependencies": ["some-cli-tool"]
}

entry: where to start tracing references from
project: which files belong to this project
ignore: paths to skip
ignoreDependencies: dependencies to keep even if they appear unused (e.g. CLI tools)

Auto-Fix

Some issues can be fixed automatically with --fix:

npx knip --fix

Currently --fix handles removing unused entries from package.json and some unused exports. Not everything is auto-fixable, but it saves a lot of manual work on the dependency side.

VSCode Extension and MCP

Knip has a VSCode extension that shows unused exports directly in the editor — no need to run the CLI to find out.

There's also @knip/mcp, which lets AI assistants call Knip when analyzing a project, helping them understand which code is actually in use.

Dead Code Is Technical Debt

Removing unused code isn't just about making the project smaller. Every unused export is a cognitive burden — a new developer doesn't know if that function matters and has to spend time tracing it. Every unused dependency is a potential security risk and an update to manage.

Knip turns "find dead code" from a manual chore into an automated step. Run it once to clean house, then wire it into CI so dead code can't quietly accumulate again.

References

vitest-fail-on-console: Stop Ignoring console.error in Your Tests

Recca Tsai — Sat, 02 May 2026 00:51:28 +0000

Originally published at recca0120.github.io

All tests pass, but the terminal is full of red console.error output. This is common and easy to ignore — the tests passed, after all. But those errors don't appear out of nowhere. Something went wrong; nobody just noticed.

vitest-fail-on-console does one thing: if console.error or console.warn appears during a test, that test fails. It forces you to acknowledge these messages instead of letting them drown in noise.

Why console.error in Tests Is a Code Smell

Vitest doesn't care about console output by default. You can console.error all day and tests still pass.

The problem is that console.error usually means something. It might be:

A React prop type warning
An async error that was caught but not properly handled
A third-party package telling you you're using it wrong
An error handler in your own code getting triggered

When these appear in tests, the test is running in a slightly broken state — it just didn't throw. Over time the test output becomes pure noise. Nobody reads it anymore, and the real signals get buried.

vitest-fail-on-console flips this: make console output a test failure, so you're forced to address it.

Installation

npm install -D vitest-fail-on-console

Setup

Import and call it in your setup file:

// tests/setup.ts
import failOnConsole from 'vitest-fail-on-console'

failOnConsole()

Then wire up the setup file in vitest.config.ts:

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    setupFiles: ['tests/setup.ts'],
  },
})

That's it. Any test that triggers console.error or console.warn will now fail.

Options

failOnConsole() accepts an options object to control which console methods trigger failures:

failOnConsole({
  shouldFailOnError: true,   // default true
  shouldFailOnWarn: true,    // default true
  shouldFailOnLog: false,    // default false
  shouldFailOnInfo: false,   // default false
  shouldFailOnDebug: false,  // default false
  shouldFailOnAssert: false, // default false
})

error and warn are usually enough. Whether to include log / info / debug depends on your project's conventions.

allowMessage

Allow specific messages through without failing — useful for known third-party issues you can't fix right now:

failOnConsole({
  allowMessage: (message) => {
    return /ResizeObserver loop limit exceeded/.test(message)
  },
})

silenceMessage

Like allowMessage, but also suppresses the console output entirely:

failOnConsole({
  silenceMessage: (message) => {
    return /Not implemented: navigation/.test(message)
  },
})

skipTest

Skip specific test files or test names entirely:

failOnConsole({
  skipTest: ({ testPath, testName }) => {
    return testPath.includes('/legacy/')
  },
})

afterEachDelay

Sometimes async operations call console methods after a test ends. This option adds a delay before checking:

failOnConsole({
  afterEachDelay: 100, // wait 100ms, default is 0
})

Handling Expected console.error Calls

After installing vitest-fail-on-console, if a test is specifically verifying that console.error gets called, letting it fire naturally will cause the test to fail.

The correct approach is to mock it with vi.spyOn:

it('logs an error when request fails', () => {
  // mock it so the message doesn't actually reach the console
  vi.spyOn(console, 'error').mockImplementation(() => {})

  triggerSomethingThatLogsError()

  // assert it was called with the expected message
  expect(console.error).toHaveBeenCalledWith('Request failed')
})

This does two things: the test explicitly declares "I know an error will be logged here," and it asserts the exact message. Much stricter than silently letting console.error through.

Pair It with a Clean Test Environment

vitest-fail-on-console handles the console output side. If your tests also have I/O boundaries to replace — filesystem, file watchers — you can pair it with memfs using the same philosophy: every aspect of the test environment should be under your control.

See }}">Testing a Filesystem Service with memfs + FakeWatchService for that approach.

References

Testing a Filesystem Service with memfs + FakeWatchService: No Disk Required

Recca Tsai — Tue, 28 Apr 2026 05:58:11 +0000

Originally published at recca0120.github.io

How do you test a Node.js service that operates on the filesystem? The obvious approach is to create real files under /tmp, run the tests, then clean up. But that comes with problems: slow I/O, inconsistent cross-platform behavior, CI permission differences, and file watcher events whose timing you can't control.

This post dissects a real FileService test suite to show how memfs and a hand-written FakeWatchService solve all of these.

What the Service Looks Like

FileService implements a IFileService interface. It handles directory browsing, file listing (with fuzzy search), file reading/writing, and CRUD operations. It takes two optional external dependencies via constructor injection:

export class FileService implements IFileService {
  constructor(
    private readonly roots: readonly string[],
    private readonly watch?: WatchService,
    private readonly fsImpl?: typeof import('node:fs'),
  ) {}
}

roots: allowed root directories
watch: optional WatchService for cache invalidation on file changes
fsImpl: optional fs module implementation, passed to glob

All three are injected through the constructor — real implementations in production, fakes in tests. This is the foundation of the entire testing strategy.

Replacing the Real Filesystem with memfs

The first step is swapping out node:fs and node:fs/promises entirely:

import { vol, fs as memfs } from 'memfs';
import { FileService } from './file-service';

vi.mock('node:fs', async () => (await import('memfs')).fs);
vi.mock('node:fs/promises', async () => (await import('memfs')).fs.promises);

memfs is a fully in-memory fs implementation. Its API is identical to Node.js's native fs, but everything happens in memory — no disk touched.

The dynamic import inside vi.mock factory functions is a Vitest requirement, but actual usage of vol and memfs is through top-level imports.

Before each test, vol.fromJSON() declaratively creates the needed file structure:

const ROOT = '/test-root';
let service: FileService;

beforeEach(() => {
  vol.fromJSON({
    [join(ROOT, 'alpha/.keep')]: '',
    [join(ROOT, 'beta/nested/.keep')]: '',
    [join(ROOT, '.hidden/.keep')]: '',
    [join(ROOT, 'node_modules/.keep')]: '',
    [join(ROOT, '.git/.keep')]: '',
    [join(ROOT, 'src/index.ts')]: 'export {}',
    [join(ROOT, 'src/utils.ts')]: 'export const x = 1',
    [join(ROOT, 'package.json')]: '{}',
  });
  service = new FileService([ROOT], undefined, memfs);
});

afterEach(() => vol.reset());

Benefits:

Speed: in-memory operations, no disk I/O
Isolation: vol.reset() gives you a fresh filesystem — zero cross-test interference
Readability: the JSON shows the entire file structure at a glance
Cross-platform: no worrying about Windows path separators or /tmp permissions

Replacing chokidar with FakeWatchService

FileService has an internal caching layer: the first listFiles() call runs glob to scan the directory tree, caching the result. Subsequent calls return the cache until a WatchService event invalidates it.

In production, chokidar watches for file changes, but chokidar events are asynchronous and non-deterministic. There's no way to precisely control "trigger an event now" in a test.

The solution is a Fake:

export class FakeWatchService implements WatchService {
  private subs = new Map<string, Set<WatchCallback>>();

  subscribe(cwd: string, cb: WatchCallback): Unsubscribe {
    let set = this.subs.get(cwd);
    if (!set) {
      set = new Set();
      this.subs.set(cwd, set);
    }
    set.add(cb);
    let active = true;
    return () => {
      if (!active) return;
      active = false;
      const s = this.subs.get(cwd);
      if (!s) return;
      s.delete(cb);
      if (s.size === 0) this.subs.delete(cwd);
    };
  }

  simulate(cwd: string, event: WatchEvent): void {
    const set = this.subs.get(cwd);
    if (!set) return;
    for (const cb of set) {
      try { cb(event); } catch (err) {
        console.error('[FakeWatchService] subscriber threw:', err);
      }
    }
  }
}

This isn't a mock — it's a Fake with real behavior. It genuinely manages subscribers, genuinely executes unsubscriptions, and genuinely dispatches events to all callbacks. The only difference is the event source: instead of OS-level inotify/FSEvents, events come from simulate() calls in test code.

For more on the difference between Fakes and Mocks, see }}">DI + Fake + in-memory: Writing Maintainable Frontend Tests.

Three Cache Invalidation Scenarios

With FakeWatchService, cache behavior becomes precisely verifiable.

Scenario 1: No event → cache hit

it('second call without watcher event reuses cached file list', async () => {
  const watch = new FakeWatchService();
  const cached = new FileService([ROOT], watch, memfs);
  const a = await cached.listFiles(ROOT, '');
  vol.writeFileSync(join(ROOT, 'after-cache.ts'), '');
  const b = await cached.listFiles(ROOT, '');
  expect(b.some((f) => f.name === 'after-cache.ts')).toBe(false);
  expect(b.length).toBe(a.length);
});

A file was added via vol.writeFileSync before the second call, but no watch event was fired, so the cache stays valid. The new file doesn't appear.

Scenario 2: Event fired → cache invalidated

it('watcher event invalidates cache so next call rebuilds', async () => {
  const watch = new FakeWatchService();
  const cached = new FileService([ROOT], watch, memfs);
  await cached.listFiles(ROOT, '');
  vol.writeFileSync(join(ROOT, 'after-invalidate.ts'), '');
  watch.simulate(ROOT, { type: 'add', path: 'after-invalidate.ts' });
  const b = await cached.listFiles(ROOT, '');
  expect(b.some((f) => f.name === 'after-invalidate.ts')).toBe(true);
});

After watch.simulate(), the cache is cleared and the next listFiles() rescans, picking up the new file.

Scenario 3: Concurrent first calls subscribe only once

it('concurrent first calls do not subscribe duplicate watchers', async () => {
  const watch = new FakeWatchService();
  let subscribeCount = 0;
  const realSubscribe = watch.subscribe.bind(watch);
  watch.subscribe = (cwd, cb) => {
    subscribeCount++;
    return realSubscribe(cwd, cb);
  };
  const cached = new FileService([ROOT], watch, memfs);
  await Promise.all([cached.listFiles(ROOT, ''), cached.listFiles(ROOT, '')]);
  expect(subscribeCount).toBe(1);
});

Two concurrent listFiles() calls should only subscribe once. This verifies the inflight promise deduplication mechanism works correctly.

All three scenarios would be nearly impossible to write reliably with real chokidar — event timing and frequency aren't controllable.

Security Tests Are First-Class Citizens

Security assertions are distributed across every describe block:

// browseDirectories filters hidden directories
it('filters hidden directories', async () => {
  const names = (await service.browseDirectories(ROOT))
    .map((d: DirEntry) => d.name);
  expect(names).not.toContain('.hidden');
  expect(names).not.toContain('.git');
});

// readFile blocks path traversal
it('rejects path traversal', async () => {
  expect(await service.readFile(ROOT, '../../etc/passwd')).toEqual({
    error: 'Path traversal not allowed',
  });
});

// All mutations reject paths outside allowed roots
it('all mutations reject paths outside allowed roots', async () => {
  expect(await svc.create('/etc/passwd-clone', 'file'))
    .toMatchObject({ error: expect.any(String) });
  expect(await svc.delete('/etc/passwd'))
    .toMatchObject({ error: expect.any(String) });
  // rename, copy, move likewise...
});

These aren't in a separate "security test suite" — they live alongside feature tests. Every entry point has its own security verification.

The isInsideRoot boundary tests are worth noting:

it('returns false for prefix-similar but not actually inside', () => {
  const sibling = `${ROOT}-sibling`;  // /test-root-sibling
  expect(service.isInsideRoot(sibling)).toBe(false);
});

/test-root-sibling has /test-root as a string prefix, but it's not inside the root. The implementation uses path.relative() to handle this correctly, and the test ensures that behavior.

Tests Are Grouped by Behavior

The test file isn't organized as "one describe per method." It's grouped by behavior:

browseDirectories: full browsing behavior including filtering, sorting, security checks
listFiles: three pattern modes (empty, trailing slash, fuzzy) plus a dedicated describe for cache invalidation
readFile: normal reads + path traversal
mutations: isolated MROOT environment, full CRUD + out-of-bounds rejection
isInsideRoot: pure logic boundary testing

Cache invalidation gets its own describe('cache invalidation via WatchService') because it's an independent behavioral concern with its own setup (requires FakeWatchService injection).

How to Reuse This Pattern

The core of this strategy is three things:

memfs replaces fs: applicable to any service using node:fs. Two lines of vi.mock, declarative setup with vol.fromJSON()
Hand-written Fakes replace non-deterministic dependencies: file watchers, WebSockets, event emitters — anything async and event-driven benefits from the Fake + simulate() pattern
Constructor injection makes replacement possible: instead of new Chokidar() inside the service, inject a WatchService interface. Tests are just a beneficiary of this design

If your project has similar I/O boundaries — filesystem, database, external APIs, message queues — the same approach applies: define an interface, inject the dependency, swap in an in-memory Fake for tests.

This approach is even more effective in a monorepo. When Fakes are extracted into shared packages, both frontend and backend can use the same test doubles with guaranteed behavioral consistency. See }}">Monorepo Shared Fakes: One Test Double from Frontend to Backend.

References

How to Add Old Models to Claude Code /model Picker: 3 Methods Tested

Recca Tsai — Sun, 26 Apr 2026 18:17:29 +0000

Originally published at recca0120.github.io

The day Opus 4.7 launched, Claude Code's opus alias silently pointed to the new version. No notification, no changelog reminder. Open the /model picker — Opus 4.6 was gone.

I'd previously written a }}">3-month billing analysis showing 4.7's quota burn is 2.4× that of 4.6. Switching back seemed obvious, but the picker had no option for it. I spent an afternoon testing every configuration method and combing through GitHub issues.

Three Configuration Mechanisms

Claude Code currently offers three ways to modify the /model picker.

1. `availableModels`: Replaces, Doesn't Extend

Add this to ~/.claude/settings.json:

{
  "availableModels": [
    "claude-opus-4-6",
    "claude-sonnet-4-6",
    "claude-haiku-4-5"
  ]
}

The /model picker now shows only these three. The default opus / sonnet / haiku aliases all disappear, replaced entirely by your list.

This is the biggest gotcha: many people assume availableModels means "add these on top of the defaults." It doesn't — it's a complete replacement.

2. `modelOverrides`: For Bedrock / Vertex

{
  "modelOverrides": {
    "claude-opus-4-7": "arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-opus-4-7-v1:0"
  }
}

This maps model IDs to provider-specific endpoints. If you're using the Anthropic API directly, this setting does nothing for you.

3. `ANTHROPIC_CUSTOM_MODEL_OPTION`: One Extra, That's It

Supported since v2.1.78, this environment variable adds a single custom entry to the bottom of the /model picker:

export ANTHROPIC_CUSTOM_MODEL_OPTION="claude-opus-4-6[1m]"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Opus 4.6 (1M)"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Opus 4.6 with 1M context window"

It doesn't touch the default picker, but you can only add one. Want both Opus 4.6 and Sonnet 4.6 1M? No luck — there's no ANTHROPIC_CUSTOM_MODEL_OPTION_2.

Pitfalls

Aliases Don't Work in availableModels

You might try:

{
  "availableModels": ["opus", "sonnet", "haiku", "claude-opus-4-6[1m]"]
}

The picker shows 4 items, but opus, sonnet, haiku behave inconsistently when mixed with full model IDs. Aliases aren't valid model IDs in this context — stick to full IDs.

Same-Family Deduplication

If you list both claude-opus-4-6 and claude-opus-4-7 in availableModels, same-family deduplication may collapse them into one entry. This behavior is undocumented.

Lock Version with `model`, Not `availableModels`

availableModels controls what's in the picker. The model field controls what's actually used at startup:

{
  "model": "claude-opus-4-6[1m]",
  "availableModels": ["claude-opus-4-6[1m]", "claude-sonnet-4-6", "claude-haiku-4-5"]
}

Set both. If you only set availableModels without model, startup still uses whatever the default alias points to.

What the GitHub Community Says

This isn't a niche issue. There are plenty of related issues on GitHub:

#14443 — Request for Configurable Model Picker

User joerivwijn asked for the /model picker to be configurable via settings.json. Especially relevant for Bedrock users whose model IDs need us. prefixes and :0 suffixes that don't match the default picker.

Result: Marked as duplicate of #12969 by bot and auto-closed.

#12738 — Opus 4.5 Disappeared from Picker

User grigb reported Opus 4.5 missing from the CLI picker on the Max plan, despite being available in the web app. Multiple users confirmed:

cleanspin found /model opus pointed to Opus 4.1 instead of 4.5 — the alias mapping was stale. Workaround: use the full ID /model claude-opus-4-5-20251101
todddrinkwater reported the VS Code extension also affected
zerzerzerz and PavelProdan posted screenshots confirming "it was there yesterday, gone today"

This pattern repeats with every new model release: the alias points to the new version, the old version vanishes from the picker, no notice given.

Result: Auto-closed by stale bot.

#35630 — ANTHROPIC_CUSTOM_MODEL_OPTION Undocumented

User coygeek noticed v2.1.78's changelog mentioned this env var, but official docs had zero coverage.

Result: Fixed — both the env-vars and model-config doc pages now include full documentation.

Other Related Open Issues

Issue	Problem
#52310	Bedrock ignores `availableModels`, shows only one model per family
#47164	Enterprise custom model IDs can't appear in interactive picker
#40501	Duplicate entries when settings.json model matches a built-in option
#49566	`ANTHROPIC_DEFAULT_*_MODEL` creates duplicate "Custom" entry on Bedrock
#53006	VS Code extension missing Sonnet 4.6
#38238	1M context model not available in picker on WSL2

The issues cluster around two themes: stale alias mappings and no mechanism to extend the default list.

Recommended Configuration

After testing everything, availableModels is unreliable due to same-family deduplication — list 4 models and you might only see 3. The most practical approach: don't touch availableModels, keep the default picker, lock your version with model, and add one extra option with ANTHROPIC_CUSTOM_MODEL_OPTION.

~/.claude/settings.json (global):

{
  "model": "claude-opus-4-6[1m]"
}

One line. The default picker stays intact (opus / sonnet / haiku all present), but every session starts on Opus 4.6 1M. The opus alias in the picker points to the latest version (currently 4.7), so you can switch to it anytime.

~/.zshrc (add a 4th option via ANTHROPIC_CUSTOM_MODEL_OPTION):

export ANTHROPIC_CUSTOM_MODEL_OPTION="claude-sonnet-4-6[1m]"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="Sonnet 4.6 (1M)"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="Sonnet 4.6 with 1M context window"

This gives 4 options in /model: the default opus / sonnet / haiku, plus Sonnet 4.6 1M. Covers all daily scenarios:

Opus 4.6 1M: locked via model field, used on startup
Opus 4.7: the opus alias in the picker, switch when needed
Sonnet 4.6: the sonnet alias, for review / fix / test tasks
Sonnet 4.6 1M: the 4th option via env var, for large context scenarios

Why not use availableModels? It's a full replacement, and same-family dedup silently eats entries. Leaving it unset gives you the most stable default picker.

Conclusion

Claude Code's model picker assumes everyone wants the latest version. availableModels is a full replacement with dedup issues; ANTHROPIC_CUSTOM_MODEL_OPTION only supports one entry.

In practice, model + ANTHROPIC_CUSTOM_MODEL_OPTION covers most needs: lock your version with model, add one extra option via env var, and leave the default picker alone.

Plenty of GitHub issues have been filed, but most get marked duplicate or stale-closed. If you need more than one custom model in the picker, there's no official solution yet.

References

Claude Code Model Configuration — Official model settings docs
Claude Code Environment Variables — Environment variable reference
#14443 — Configure custom models in /model picker
#12738 — Opus 4.5 missing from model picker
#35630 — ANTHROPIC_CUSTOM_MODEL_OPTION env var missing from docs
#52310 — Bedrock availableModels ignored

I Audited 3 Months of Claude Code Billing — Most Community Cost-Saving Tips Don''t Work

Recca Tsai — Sun, 26 Apr 2026 00:26:04 +0000

Originally published at recca0120.github.io

This past week, chasing a vague "quota burns faster lately" feeling, I scanned three months of my own Claude Code logs. ~\$127K equivalent cost, 127K turns, four models, hundreds of sessions.

The uncomfortable finding: the cost-saving tips floating around on Reddit / HN / Twitter mostly don't survive real data. "Sessions are too long, run /clear," "too many skills, prune them," "MCP servers should be lean" — these all sound right. But against three months of actual data, almost none holds up. Only two things actually shrink the bill, and neither is about "optimizing your habits."

Earlier I wrote }}">Scanned 95 days of Claude Code logs, found a second cache TTL silent regression and }}">17-day follow-up covering server-side behavior. This post is the extension: with server behavior confirmed unfixable, what's left for the user side.

Three Months of Bills

A single primary development project (one codebase, solo dev), monthly Claude Code totals:

Month	Equiv \$	Dominant Model	Key Event
2026-02	\$1,015	Five models mixed	Trial period, low volume
2026-03	\$48,623	99.6% Opus 4.6	Heavy usage starts; per-call prefix jumped 58K → 417K in one step
2026-04	\$77,754	Opus 4.6 \$51K + Opus 4.7 \$25K	Opus 4.7 release on 4/16, alias auto-upgraded

Two key observations:

From March to April, Opus 4.6 cost barely changed (\$48K → \$51K, +7%). \$/turn went from \$0.692 → \$0.713, a 3% delta. Usage habits stayed flat.
The extra \$25K in April is almost entirely the Opus 4.7 layer.

So the "lately it got expensive" feeling isn't because I changed anything — it's because Opus 4.7 shipped on 4/16 and the opus alias automatically pointed to the new version. With no version pinned in settings, the next session jumped to it.

This is normal alias behavior, not something hidden. But for subscription users, the quota impact is real — as we'll see, the new version's adaptive thinking burns quota at 2.4× the old.

Multi-Dimensional Breakdown for April

Here's the full cut by model for one month:

Dimension	Opus 4.6	Opus 4.7	Sonnet 4.6	Haiku
Volume
Sessions (main/sub)	24/138	18/84	5/46	1/376
Total turns	72,431	31,621	15,182	16,138
% of total turns	47.4%	20.7%	9.9%	10.6%
Wall-clock hours	635	270	72	14
Active hours (no idle)	237.9	106.5	40.2	6.2
Output Profile
Turns/active hour	305	297	378	2,614
Tools/turn	0.62	0.63	0.64	0.68
Output tokens/turn	227	667	456	101
Sub:Main turn ratio	1:1.32	1:15.56	1:14.95	n/a
Cost
Equivalent \$	\$51,700	\$24,595	\$773	\$114
Cost share	67.0%	31.9%	1.0%	0.1%
Quota burn rate	1.0×	2.4×	0.2×	0.05×
\$/turn	\$0.714	\$0.778	\$0.051	\$0.007

Cross-column observations:

Opus 4.7 emits 2.9× more output tokens per turn (667 vs 227). It's not verbose — adaptive thinking's reasoning chain counts as output. To complete the same task, 4.7 burns roughly 3× the output of 4.6.

Opus 4.7 doesn't delegate. Sub:Main turn ratio jumped from 4.6's 1:1.32 to 1:15.56 — 4.6 is a "give half to sub-agents" collaborator, 4.7 is a "think it through alone" lone wolf. This explains the 3× output per turn: thinking is all done in-house.

Sonnet 4.6 \$/turn is 1/16 of Opus. But it only made up 9.9% of turns — clearly underused.

Haiku is the invisible workhorse. Zero main sessions, 376 sub-sessions, 16K turns for \$114 — all triggered automatically by Claude Code's built-in Explore / Plan agents. Untouched, still doing 10% of total turns.

Five Common "Cost-Saving Tips" Debunked

Community lore (Reddit / HN / Discord) graded against real data.

❌ "Long sessions are the culprit"

The intuition: longer sessions mean longer conversation history, more cache prefix re-read per turn, more cost as the session drags on.

The data: March vs April Opus 4.6 usage is nearly identical (69,980 vs 72,510 turns), but \$/turn moved from \$0.692 → \$0.713, a 3% bump. If long sessions were the driver, the per-turn cost should creep up month over month. It doesn't.

More precisely: cache_read accounts for 77–88% of cost on both Opus versions. The number is huge, but the ratio has been that way since heavy Claude Code usage started — it's the inherent cost of "talking to an LLM," not the price of "not splitting sessions." /clear doesn't recover much.

❌ "Run `/clear` after 5+ min idle"

The intuition: 5-minute cache TTL means a brief idle expires the cache, so the next turn pays for a rewrite.

The data: my }}">second audit shows the main agent has been writing 100% to 1h TTL for 17 straight days since 4/9, with zero 5m writes. Idle a while and come back, cache is still there. No extra write cost.

The forced 5m downgrade only hits sub-agents (same post). But sub-agents only contributed a small slice of April's cost (~\$1,500 estimated), two orders of magnitude less than the \$25K from 4.7.

❌ "Too many skills"

The intuition: loaded skills inject metadata into the system prompt every turn.

The data: I actually measured. 40 skill descriptions add up to ~5–10K tokens. In a 425K per-call prefix, that's 1–2%. Deleting all of them saves <\$1K/month — not worth the effort.

❌ "Too many MCP servers"

The intuition: MCP tool definitions land in the prefix every turn.

The data: setup is 3–4 MCPs (pixel-mcp, the Google Workspace trio), several of which fail to connect and don't load. Already lean, nothing to trim.

❌ "CLAUDE.md is too long"

The intuition: CLAUDE.md gets re-read every turn.

The data: the project root CLAUDE.md is 1 byte (essentially empty), the global one is 0 bytes. Zero impact.

These five aren't wrong in every scenario. For someone with a 50K-token CLAUDE.md or 20 loaded MCP servers, they apply. But as generic advice spread to everyone, data shows they barely help a heavy single-project workflow.

✅ The Two Things That Actually Work

After the intuition reckoning, only two things hold up against the data:

1. Pin Specific Model Versions in settings.json

Don't use opus / sonnet aliases. When Anthropic ships a new version, the alias auto-points to it — invisible to the user but quota behavior shifts dramatically.

{
  "model": "claude-opus-4-6",
  "permissions": { "...your existing..." }
}

This way when opus-4.8 / 4.9 ships, you don't auto-follow. New versions aren't always more economical — for 4.6 vs 4.7:

\$/turn +9%
Output/turn +190%
Quota burn +140%
Turns to complete same work only −12%

Net CP value is 1.9× higher on 4.6. Every model release, check cnighswonger's advisory and run your own data for a while before deciding to upgrade.

On adaptive thinking: 4.7 burns hard mainly because adaptive thinking counts the reasoning chain as output tokens. Opus 4.6 / Sonnet 4.6 let you disable it via CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1, but Opus 4.7 forces it on with no toggle — that's why "lock 4.6" is the practical fix instead of trying to mitigate 4.7. Auto mode and adaptive thinking are independent features; pinning 4.6 doesn't affect auto mode.

2. Route Review / Fix / Test to Sonnet

The \$/turn gap is real (Opus \$0.71 vs Sonnet \$0.045 — 16×). My April: 14K turns on Sonnet for \$643, same turns on Opus 4.6 would have been \$10K.

Switch to Sonnet for:

Code review, reading PR diffs
Small bug fixes, type annotations, null checks
Writing tests, adding test cases
Docs, commit messages, changelogs
Renames, simple refactors

Stay on Opus for:

Cross-file architectural rewrites
Design decisions needing long reasoning chains
Complex debugging (race conditions, memory leaks)
Exploring an unfamiliar codebase the first time

How: inside a session, /model claude-sonnet-4-6 to switch over for a few rounds, then /model claude-opus-4-6 to switch back. Don't lock Sonnet in settings — you'll forget to switch when you need Opus.

Real Magnitudes

If both levers are in place, expected April-baseline change (against \$77K):

Action	Expected Savings	% of Monthly Bill
Pin 4.6 (cancel 4.7 auto-follow)	\$25K/mo	32%
Route review/fix/test to Sonnet (expand to 30% of turns)	\$10–15K/mo	13–20%
Total	\$35–40K/mo	45–52%

The remaining 50% is the inherent cost of "heavy Opus 4.6 usage on a primary project" — not optimizable, and shouldn't be. That's the work itself.

Lessons

The biggest takeaway from turning myself into a dataset isn't the savings — it's seeing how unreliable community intuition is.

"Shorter session = cheaper," "fewer skills = cleaner" might hold in some scenarios, but for single-project heavy-use workflows they're flat wrong. Without breaking cost down to model × session × turn, I'd never have spotted that "the Opus 4.7 alias upgrade" is the single biggest reason April got expensive.

Broader lessons:

Floating optimization tips are noise — without data, "cost-saving advice" often optimizes the wrong thing
Aliases hand cost control to the vendor — the mechanism isn't bad, but it's a real risk for subscription users with quota planning
Multi-model strategy beats single-model tuning — same dollar, Sonnet does 16× the turn volume

If you want to scan your own, the 60-line Python from }}">the first post is reusable — adjust the cost calc and you'll get this analysis for your data. Make yourself a dataset and re-check what the community thinks it knows.

}}">Background: Claude Code session cost & cache misconception

References

Cache TTL silently regressed — GitHub Issue #46829
Subagent trailing block missing cache_control — Issue #50213
Widespread quota drain since 2026-03-23 — Issue #41930
cnighswonger/claude-code-cache-fix — Opus 4.7 quota burn advisory + cache fix proxy
Claude API Pricing
Anthropic: Claude quota drain not caused by cache tweaks — The Register

12 More Days Scanned: Claude Code Sub-Agent Cache TTL Has Been 100% 5m for 17 Straight Days — This Isn''t a Regression, It''s the New Default

Recca Tsai — Sat, 25 Apr 2026 23:16:26 +0000

Originally published at recca0120.github.io

}}">Two weeks ago I scanned 95 days of Claude Code logs and found that since 4/9, sub-agents had been 100% downgraded to 5m TTL — 5 consecutive days, 4,840 API calls, with the main agent completely untouched. I left the conclusion at "monitoring," since 5 days could still be rollout flapping.

Today 4/26, I re-ran the same Python. The streak is now 17 days, 15,727 API calls, 0 1h writes. This isn't flapping — Anthropic's server has quietly hard-coded the sub-agent default TTL to 5m. No changelog, no announcement, and the main issue was just closed without resolution.

This is a follow-up: latest data, cost math, community and media state, and why cnighswonger's proxy can't save you here either.

Past Two Weeks of Data

Scan covers 4/13–4/25 (cut-off of last post → today):

Metric	Main agent	Sub-agent
Total API calls	60,291	15,727
1h writes	100% (150.7M tokens)	0
5m writes	0	100% (60.4M tokens)
Consecutive 1h-write days	13	0
Consecutive 5m-write days	0	13

Add the 4/9–4/12 stretch and the sub-agent has run 17 straight days at 100% 5m, with 0 1h writes. Sub-agent workload didn't drop — 4/14 (the day I posted last) hit 2,648 calls, 4/17 spiked to 2,821, both two-week highs. The full cost impact landed on me.

Key contrast: the main agent stayed 100% 1h the entire time, untouched. So this is unambiguously server-side discrimination against the "sub-agent identity" — not quota throttling, not a client version, not a workflow change.

How Much More Expensive: The Math

Anthropic's official cache pricing:

Cache write to 5m TTL: 1.25× base input price
Cache write to 1h TTL: 2× base input price
Cache read (both): 0.1× base input price

Intuition says 5m writes are cheaper — 1.25× vs 2×, a 37.5% saving. But sub-agent workflows defeat that intuition.

A typical sub-agent runs 30 minutes, 5 turns. Between turns it waits for the LLM to think, runs tools, parses results. 3 inter-turn gaps over 5 minutes is normal. Each gap past TTL expires the cache and forces a rewrite next turn.

Total cost (with base input as 1×):

Old (1h TTL):
  1 cache write @ 2×  = 2.0
  4 cache reads @ 0.1× = 0.4
  Total = 2.4×

New (5m TTL):
  4 cache writes @ 1.25× = 5.0
  1 cache read   @ 0.1× = 0.1
  Total = 5.1×

About 2.1×. A heavy sub-agent workflow (parallel Task fan-out, long plan-execute, code-review pipelines) that used to cost \$10 now costs \$21.

This assumes inter-turn gaps average over 5m. If your sub-agent finishes every turn within 5m (e.g. pure retrieval), the impact is much smaller. The hardest-hit are sub-agents that "run long, wait for tool results."

GitHub Activity Past Week

Issue #46829: Closed by Anthropic

cnighswonger's #46829 was closed by Anthropic without a fix. Comments are uniformly angry:

DaQue: "I don't like the stealth nerf."
rinchen: "Yet another issue closed without resolution by Anthropic."
lizthegrey (Engineering Director at Honeycomb, jumped in 4/25): posted her own grep one-liner, listed her affected versions and dates (4/01 v2.1.81, 4/09 v2.1.85, 4/13–4/17 v2.1.92, 4/21 v2.1.114), and explicitly stated she provided redacted jsonl transcripts to Anthropic. The most credible piece of evidence submitted so far.

# lizthegrey's one-liner
grep -h -r -E 'ephemeral_.*_input_tokens' ~/.claude | \
  jq 'select(.isSidechain == false and (.message.model | startswith("claude-haiku") | not) and .message.usage.cache_creation.ephemeral_5m_input_tokens > 0) | .timestamp + "," + .version' 2>/dev/null | \
  sed 's/T.*,/,/' | sort | uniq -c

Same data source as my 60-line Python from the last post, just more concise. Drop-in usable.

Issue #50213: Sub-agent Trailing Block Missing cache_control

ofekron added measurements on #50213 on 4/17: every built-in sub-agent (Explore, Plan, general-purpose) shows nonzero cache_creation on second spawn — the trailing system-context block has no cache_control marker, so each fresh spawn wastes ~4.7K tokens rewriting. 0 new comments past week — this issue is being ignored.

Together the two issues say the same thing: Anthropic's posture toward sub-agent cache leans toward "save where we can," not "optimize where we can."

No Movement from Anthropic Staff

bcherny's earlier mention of a "per-request env var / flag for TTL" — still not shipped
Jarred Sumner's earlier defense in The Register that "sub-agent 5m is a one-shot optimization" — no response to the 4/9 100% 5m data
Anthropic posted nothing on these issues in the past week

Update (2026-04-26): Official Position vs My Data

After publishing, I dug into Anthropic's public posture. Boris Cherny (creator of Claude Code), via The Register:

"One-hour cache has been implemented in some places for subscribers, while a five-minute cache is the true default."

So Anthropic's official line is "5m is the true default; 1h is opt-in for some subscriber scenarios" — which actually agrees with this post's framing of "this is the new default, not a regression."

But the official stance can't explain one thing: time-series data from }}">the first audit shows that from 2026-02-07 to 03-05, 28 consecutive days, sub-agents received 100% 1h (not mixed, not 50%). If those 28 days of "1h treatment" were a "special case," it was a stably-allocated special case, not an occasional gift.

This post's 17 days of 100% 5m can be re-positioned: the sub-agent 1h treatment subscribers used to receive is being stably revoked. Anthropic didn't "change the default," but the "1h special case formerly granted to sub-agents" effectively disappeared. That's a fact the official statement can't paper over.

Media Coverage and a Bigger Thread

This isn't just blowing up on GitHub:

The Register (4/13): Anthropic: Claude quota drain not caused by cache tweaks — Anthropic publicly denies a cache link, with Sumner's defense quoted in full
XDA Developers: Anthropic quietly nerfed Claude Code's 1-hour cache
DevOps.com: Developers Using Anthropic Claude Code Hit by Token Drain Crisis

Worth tracking: Issue #41930 — since 3/23 every paid tier has been hit by abnormal quota burn, Pro / Max 5× / Max 20× included. Single prompts eat 3–7% of session quota; 5h windows drain in as little as 19 minutes. The community treats cache TTL regression, autocompact cascades, and sub-agent fan-out as stacked root causes. My 4/9 second-wave finding fills in the timeline of "sub-agent specifically got worse again on 4/9."

Can cnighswonger's Proxy Save This? My Take

cnighswonger/claude-code-cache-fix v3.0.3 has nice A/B numbers on CC v2.1.117: through the proxy 95.5% cache hit rate, direct 82.3%. It runs 7 hot-reloadable extensions, including ttl-management, which "detects server TTL tier and injects correct cache_control markers."

But for the "server force-writes sub-agent into 5m" problem, the proxy probably can't save you. My read:

The proxy fixes "caches that should hit but miss because of client bugs" (unstable fingerprint, non-deterministic tool ordering, inconsistent cache_control markers)
It can't fix "client marks 1h, server still writes 5m" — that's server-side behavior, the proxy can't rewrite responses
From our 17 days of 100% 5m / 0 1h writes, the server is doing the latter for sub-agents

Easy to verify: install the proxy, run the same script against ~/.claude/projects/*.jsonl, see if sub-agent ephemeral_1h_input_tokens ever goes from 0 to nonzero. If it stays 0, the server-side change is confirmed.

This isn't a knock on cnighswonger's proxy — it has demonstrated value for the main agent and any cache-miss scenario. Just don't expect it to "bring back sub-agent 1h TTL."

Conclusion: This Is the New Default

In the 4/14 post I called the 4/9 wave "a second silent regression." On 4/26 I'm revising the wording: this is no longer a regression — it's Anthropic's new default for sub-agents.

Evidence weight:

17 consecutive days (4/9–4/25)
15,727 API calls in just the past 13 days
0 1h writes (not low — actually zero)
Main agent untouched (clear differential treatment)
Media + GitHub + community on fire, Anthropic stays silent

If you lean heavily on sub-agents:

Scan your own data first — use the Python from the last post, or lizthegrey's jq one-liner above
Calculate the actual cost impact — it's not "a bit more," it's about 2×
Re-evaluate your sub-agent workflows — anything doable in the main agent shouldn't fan out to sub-agents
Drop a data point on issue #46829 — closed but still indexed. With Honeycomb-tier voices already pushing, more data makes external coverage easier to follow up

}}">Background — Claude Code session cost & cache misconception covers the cache cost logic. }}">First audit covers how to scan your own logs to verify. Read both for the full picture.

References

Cache TTL silently regressed — GitHub Issue #46829 — closed, community still commenting
Subagent trailing block missing cache_control — Issue #50213
Widespread quota drain since 2026-03-23 — Issue #41930 — parent issue with stacked root causes
Anthropic: Claude quota drain not caused by cache tweaks — The Register
Anthropic quietly nerfed Claude Code's 1-hour cache — XDA Developers
Developers Hit by Token Drain Crisis — DevOps.com
The 5-Minute TTL Change That's Costing You Money — dev.to
cnighswonger/claude-code-cache-fix — proxy + extension package

Node.js spawn stdout Gets Truncated: Compared 6 Fixes, Only the File Trick Works

Recca Tsai — Sat, 25 Apr 2026 21:27:12 +0000

Originally published at recca0120.github.io

One day I was spawning a CLI from Node (the Claude CLI, which dumps a lot of JSON) and piping its stdout back to parse. Short outputs were fine. But the moment output grew past a few hundred KB, the last few KB just disappeared — JSON.parse blew up on the final line, and the truncation point shifted run to run.

After digging through Node's official issues, Linux pipe docs, and community deep-dives, the verdict is blunt: this is a known Node behavior since 2015, and the only reliable pure-stdlib fix is writing to a temp file. This post lays out the trade-offs across six approaches so you don't have to repeat the journey.

The Symptom

import { spawn } from 'node:child_process';

const child = spawn('some-cli', ['--big-output']);
let buf = '';
child.stdout.on('data', (chunk) => { buf += chunk; });
child.on('close', () => {
  JSON.parse(buf); // blows up on large outputs
});

The bigger the output, the higher the chance. MB-scale almost always truncates; hundreds of KB occasionally. The cut-off point isn't fixed — sometimes you get 1.2 MB, sometimes 1.18 MB.

Why It Truncates

The root cause is how Node writes stdio. The child's stdout connects to a pipe, and writes to a pipe are async. When the child calls process.exit(), Node doesn't wait for buffered data to flush — the process exits immediately, and whatever sat in the pipe unread gets lost.

If stdout is a TTY or a regular file, writes are sync and this never happens. The bug only triggers on "non-TTY, non-file fds" — pipes, FIFOs, and sockets.

This was first tracked in Node issue #3669 (2015), then revisited in #6379 and #9633. The community consensus: user-land's only reliable workaround is writing to a file. Core has no plans to change it.

Six Approaches Side by Side

Approach	Viability	Trade-off
A. Temp file	Pure stdlib	One extra disk I/O, ~10ms
B. node-pty / get-pty-output	Child sees a TTY	Needs native build; CLI may inject ANSI codes that pollute JSON
C. `F_SETPIPE_SZ` to enlarge pipe	Linux only	macOS lacks the API; only delays the cut-off point
D. Named pipe (FIFO)	Same dead end	FIFOs are non-file fds too — same truncation
E. UNIX socket	Same dead end	Sockets are also non-file fds, async writes still truncate
F. Fix the child CLI itself	Root cause	Usually not under your control

Why D / E Don't Work Either

A common first thought: "Skip the pipe, use a FIFO or UNIX socket — that should work, right?" I tried it. Same truncation.

The reason: "async pipe writes" isn't a property of pipes specifically — it's a property of non-file, non-TTY fds. Linux and macOS route writes to such fds through the async path, and FIFOs and sockets fall in the same bucket. Identical behavior.

Why C Looks Promising but Isn't

fcntl(F_SETPIPE_SZ) can grow the Linux pipe buffer from 64 KB default to 1 MB (more than that needs root). Sounds great — fill the buffer big enough and nothing gets cut, right?

Three problems:

Linux only. macOS doesn't have F_SETPIPE_SZ
Only delays the cut-off. Outputs > 1 MB still truncate — no real fix
Still needs a native binding. fcntl isn't exposed in Node — you'd write a C++ addon or use ffi-napi

If you want pure stdlib and cross-platform, this path is out.

What Actually Works: Pipe stdout to a File

The trick is to use fs.openSync to grab a file fd and hand it to spawn's stdio option. This way the child writes stdout directly to the file, bypassing any pipe — writes are sync, process.exit() won't truncate:

import { spawnSync } from 'node:child_process';
import { openSync, closeSync, readFileSync, unlinkSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';

const outPath = join(tmpdir(), `cli-${process.pid}-${Date.now()}.out`);
const fd = openSync(outPath, 'w');

try {
  // stdio: [stdin, stdout, stderr]
  // Send child stdout straight to a file fd, no pipe in between
  spawnSync('some-cli', ['--big-output'], {
    stdio: ['ignore', fd, 'inherit'],
  });
} finally {
  closeSync(fd);
}

const output = readFileSync(outPath, 'utf8');
unlinkSync(outPath);

JSON.parse(output); // no longer blows up

For an async version, use spawn + child.on('close', ...). Same principle: fd to a file, never a pipe.

If stderr is also high-volume, do the same with a second fd. 'inherit' forwards to the parent's stderr cleanly but you can't capture it.

The ~10ms Disk I/O Cost

The only downside is the extra disk I/O — about 10ms on SSD. For a CLI that runs for several seconds, this is noise. If you genuinely care about that 10ms, the only remaining path is node-pty, but you'll deal with:

Native build (extra compile step in CI)
Child sees a TTY and may inject ANSI color codes into stdout — strip them
macOS and Windows backends differ (forkpty vs conpty), test both

My take: if a temp file works, use a temp file. Trading 10ms to avoid a native dependency and ANSI pollution is an easy win.

References

From "Functional" to "Stunning": A Walkthrough of web-design-skill

Recca Tsai — Sat, 25 Apr 2026 07:41:52 +0000

Originally published at recca0120.github.io

Ask Claude Code or Cursor to whip up a landing page and you can probably guess what it'll look like in three seconds: Inter font, blue button, purple-pink gradient hero, large-radius cards, emoji as icons, a few paragraphs of fake testimonials. It works — but anyone can tell at a glance "this was AI-written."

ConardLi/web-design-skill is built to fix exactly that. It distills the system prompt of Claude Design (Anthropic's visual product launched in April 2026) into an open, portable SKILL.md you drop into .claude/skills/ or .agents/skills/. The goal: make agents code with some design taste, instead of producing the same face every time.

This is a walkthrough plus the design philosophies in the skill I think are worth stealing.

The Problem: Generic AI Aesthetics

LLMs have long passed "can it run." But because their training data overlaps so heavily, outputs converge on the same look. The author lists an "AI-frontend tells" blocklist:

Purple-pink-blue gradient backgrounds
Cards with a colored left-border accent
Inter / Roboto / Arial / system-ui fonts
Emoji as icon substitutes
Fabricated stats, fake logo walls, dummy testimonials

None of these are wrong. They're just too common. Spotting them screams "AI" and dilutes any brand.

Fix 1: Anti-Cliché Blocklist

The skill spells out an explicit blocklist so the agent gets reminded "don't use these" before generating. This is far more effective than vague instructions like "design tastefully" — LLMs follow negative constraints reasonably well, as long as the items are concrete.

Instead of telling AI to "design beautifully," tell it specifically "no purple-pink gradients, no Inter, no emoji-as-icons." The constraint actually opens up the design space.

Fix 2: oklch Color System

The most technical part of the skill. HSL is perceptually uneven — yellow at 50% lightness looks much brighter than blue at 50%, which is why AI-derived HSL palettes often feel "numerically symmetric but visually crooked."

oklch is a perceptually uniform color space — same L value actually looks the same brightness to the human eye. The skill mandates oklch for color tokens:

:root {
  --color-bg: oklch(98% 0.01 80);
  --color-fg: oklch(20% 0.02 80);
  --color-accent: oklch(65% 0.18 30);
}

The side benefit is clean ramp derivation — lock chroma and hue, vary lightness, and you get a visually consistent gray or accent scale.

Fix 3: Declare the Design System Up Front

This is the heart of the skill, in my view. The biggest problem with AI-written frontend is "decide as you go": pick a color when you reach the hero, swap fonts when you hit the footer, and end up with a page stitched from mismatched parts.

The skill forces the agent to declare design tokens in markdown before writing any code:

## Design System

- **Palette**: warm paper (oklch 97% 0.01 80) / ink (oklch 18% 0.02 80) / accent caramel (oklch 65% 0.15 60)
- **Typography**: Instrument Serif (display) + Space Grotesk (UI) + JetBrains Mono (code)
- **Spacing**: 4px base, 8/16/24/40/64 scale
- **Motion**: 200ms ease-out for micro, 600ms ease-in-out for page transitions

Only then does coding start. This separates "design decisions" from "implementation" — the user can correct direction at the token level, instead of waiting for a full page to discover the overall tone is off.

Fix 4: Show a v0 Draft First

Don't deliver in one shot. The skill requires a "v0" pass: layout skeleton + design tokens + placeholders, so the user can confirm direction before details get filled in.

This mirrors the human wireframe → high-fi mockup workflow. AI normally skips it because it wants to deliver a complete artifact in one go — but a complete artifact is expensive to revise. A half-built one is cheap.

Fix 5: Placeholder Philosophy

One of AI's dumbest habits: when an image is missing, it draws a wonky SVG and pretends it's an illustration. The skill bans this and uses honest markers instead:

<div class="placeholder">[hero image: photographer portrait, 3:4]</div>

The reason is simple: bad SVGs mislead the user into thinking they're finished assets, while text placeholders clearly signal "real asset needed here."

The Six-Step Workflow

The skill structures the entire process:

Understand requirements — only ask if information is insufficient
Gather design context — code > screenshots, never start from nothing
Declare the design system — tokens in markdown, as above
Show v0 draft — layout + placeholders
Full build — components, states, motion; pause at decision points
Verify — pre-delivery checklist: no console errors, no rogue hues

This structure suppresses the LLM's urge to "give a complete answer in one shot" and forces it into an iterative workflow.

Six Color × Font Pairings

The most practical cheatsheet in the skill. Six pre-validated combinations the agent can grab when stuck:

Style	Color	Fonts	Use Case
Modern tech	Blue-violet	Space Grotesk + Inter	SaaS, dev tools
Elegant editorial	Warm brown	Newsreader + Outfit	Content, blogs
Premium brand	Near-black	Sora + Plus Jakarta Sans	Luxury, finance
Lively consumer	Coral	Plus Jakarta Sans + Outfit	E-commerce, social
Minimal professional	Teal-blue	Outfit + Space Grotesk	Dashboards, B2B
Artisan warmth	Caramel	Caveat + Newsreader	Food, education

Notice Inter only appears as a secondary font in "modern tech" — not the default. That's the anti-cliché rule in concrete form.

How to Use It

Clone, copy .agents/skills/web-design-engineer/ into your project (.claude/skills/ for Claude Code), and the agent picks it up automatically on frontend tasks.

git clone https://github.com/ConardLi/web-design-skill
cp -r web-design-skill/.agents/skills/web-design-engineer .claude/skills/

The repo's demo/ folder has same-prompt comparisons with and without the skill. The gap is obvious — worth opening directly.

Why It's Worth Following

The real value isn't "a design checklist for AI" — it's a methodology for externalizing design decisions. Writing tokens as markdown, anti-patterns as a blocklist, the workflow as six steps — these all turn vague "taste" into structure an LLM can read.

The same idea applies anywhere: if you want AI to have taste in a domain, list "do" and "don't" explicitly. Far more effective than a thousand-word system prompt.

Other Claude Code skill-related reading: }}">claude-view: Mission Control for Claude Code — a dashboard for monitoring sessions, cost, and token usage.

References

Zustand: React State Management Without Providers or Reducers

Recca Tsai — Tue, 21 Apr 2026 19:50:07 +0000

Originally published at recca0120.github.io

Redux needs action types, action creators, reducers, and a <Provider> wrap — adding a counter touches four files.
React Context is convenient, but any value change in the context re-renders every consumer.
Zustand handles it with one create() call. 1KB, no Provider needed.

The Problem with Context

The issue with Context is re-rendering.

const AppContext = createContext({ user: null, theme: 'light', count: 0 });

function ThemeDisplay() {
  const { theme } = useContext(AppContext);
  // Re-renders every time count changes, even though this component doesn't use it
  return <span>{theme}</span>;
}

Context wasn't designed for high-frequency state updates. It's fine for theme or locale — things that rarely change. For UI state it's slow, and optimizing it means reaching for useMemo and split contexts, which compounds complexity fast.

Installation

npm install zustand

# Optional: for clean nested state updates
npm install immer

Creating a Store

import { create } from 'zustand';

interface BearStore {
  bears: number;
  honey: number;
  increasePopulation: () => void;
  addHoney: (amount: number) => void;
  removeAllBears: () => void;
}

const useBearStore = create<BearStore>()((set) => ({
  bears: 0,
  honey: 100,
  increasePopulation: () => set((state) => ({ bears: state.bears + 1 })),
  addHoney: (amount) => set((state) => ({ honey: state.honey + amount })),
  removeAllBears: () => set({ bears: 0 }),
}));

TypeScript requires create<BearStore>()(...) with double parentheses. This is intentional — it enables correct generic inference, not a typo.

Reading State: Selectors Subscribe to Only What You Need

function BearCounter() {
  // Only re-renders when `bears` changes
  const bears = useBearStore((state) => state.bears);
  return <h1>{bears} bears</h1>;
}

function Controls() {
  // Actions don't change, so this component almost never re-renders
  const increasePopulation = useBearStore((state) => state.increasePopulation);
  return <button onClick={increasePopulation}>Add bear</button>;
}

The contrast with Context is clear: BearCounter subscribes only to bears. Changes to honey don't trigger a re-render here.

Selecting Multiple Fields: useShallow

Selectors that return a new object on every call cause infinite re-renders. Use useShallow for shallow comparison:

import { useShallow } from 'zustand/react/shallow';

// Wrong: returns a new object every render → infinite re-render loop
const { bears, honey } = useBearStore((state) => ({
  bears: state.bears,
  honey: state.honey,
}));

// Correct: useShallow compares keys and values shallowly
const { bears, honey } = useBearStore(
  useShallow((state) => ({ bears: state.bears, honey: state.honey }))
);

Async Actions

No special handling required — plain async/await:

interface UserStore {
  users: User[];
  isLoading: boolean;
  error: string | null;
  fetchUsers: () => Promise<void>;
}

const useUserStore = create<UserStore>()((set, get) => ({
  users: [],
  isLoading: false,
  error: null,

  fetchUsers: async () => {
    set({ isLoading: true, error: null });
    try {
      const res = await fetch('/api/users');
      const users: User[] = await res.json();
      set({ users, isLoading: false });
    } catch (err) {
      set({ error: String(err), isLoading: false });
    }
  },
}));

Compare this to Redux's createAsyncThunk — no pending/fulfilled/rejected cases, no builder.addCase. Just an async function.

Reading and Writing State Outside React

This is something Context can't do:

// Read from a service, utility, or non-React code
const currentBears = useBearStore.getState().bears;
useBearStore.getState().increasePopulation();

// Write directly
useBearStore.setState({ bears: 10 });

// Subscribe to changes (remember to clean up)
const unsubscribe = useBearStore.subscribe(
  (state) => state.bears,
  (bears) => console.log('bears changed to', bears)
);

WebSocket handlers, timers, and third-party SDK callbacks can all interact with the store directly, without any React wrappers.

Immer Middleware: Clean Nested Updates

Without immer, updating nested state requires spreading every level manually:

// Without immer
set((state) => ({
  profile: {
    ...state.profile,
    settings: {
      ...state.profile.settings,
      theme: 'dark',
    },
  },
}));

With immer, write mutations directly:

import { immer } from 'zustand/middleware/immer';

const useStore = create<Store>()(
  immer((set) => ({
    profile: { name: 'Alice', settings: { theme: 'light' } },
    todos: [],

    updateTheme: (theme) =>
      set((state) => {
        state.profile.settings.theme = theme;  // direct mutation, immer handles immutability
      }),

    addTodo: (text) =>
      set((state) => {
        state.todos.push({ id: Date.now(), text, done: false });
      }),

    toggleTodo: (id) =>
      set((state) => {
        const todo = state.todos.find((t) => t.id === id);
        if (todo) todo.done = !todo.done;
      }),
  }))
);

Devtools Middleware

Integrates with the Redux DevTools browser extension — no Redux required:

import { devtools } from 'zustand/middleware';

const useCounterStore = create<CounterStore>()(
  devtools(
    (set) => ({
      count: 0,
      increment: () =>
        set(
          (state) => ({ count: state.count + 1 }),
          false,
          'counter/increment'  // action name shown in DevTools timeline
        ),
    }),
    {
      name: 'CounterStore',
      enabled: process.env.NODE_ENV === 'development',
    }
  )
);

The third argument to set() is the action name — it shows up in the DevTools timeline, which makes debugging much easier.

Persist Middleware: Automatic localStorage

import { persist, createJSONStorage } from 'zustand/middleware';

const useSettingsStore = create<SettingsStore>()(
  persist(
    (set) => ({
      theme: 'light' as 'light' | 'dark',
      language: 'en',
      setTheme: (theme) => set({ theme }),
      setLanguage: (language) => set({ language }),
    }),
    {
      name: 'app-settings',  // localStorage key
      storage: createJSONStorage(() => localStorage),

      // Persist only specific fields (keep sensitive data out)
      partialize: (state) => ({
        theme: state.theme,
        language: state.language,
      }),

      // Version for schema migration
      version: 1,
      migrate: (persisted, version) => {
        if (version === 0) {
          return { ...(persisted as object), language: 'en' };
        }
        return persisted as SettingsStore;
      },
    }
  )
);

After a page reload, theme and language restore automatically from localStorage.

Slice Pattern: Splitting Large Stores

Zustand recommends a single global store, but you can split it into logical slices:

// stores/slices/bearSlice.ts
import { StateCreator } from 'zustand';

export interface BearSlice {
  bears: number;
  addBear: () => void;
  eatFish: () => void;
}

export const createBearSlice: StateCreator<
  BearSlice & FishSlice,  // full store type (for cross-slice access)
  [],
  [],
  BearSlice
> = (set) => ({
  bears: 0,
  addBear: () => set((state) => ({ bears: state.bears + 1 })),
  eatFish: () => set((state) => ({ fishes: state.fishes - 1 })),  // cross-slice update
});

// stores/slices/fishSlice.ts
export interface FishSlice {
  fishes: number;
  addFish: () => void;
}

export const createFishSlice: StateCreator<
  BearSlice & FishSlice,
  [],
  [],
  FishSlice
> = (set) => ({
  fishes: 0,
  addFish: () => set((state) => ({ fishes: state.fishes + 1 })),
});

// stores/useBoundStore.ts
import { create } from 'zustand';
import { devtools } from 'zustand/middleware';

export type BoundStore = BearSlice & FishSlice;

export const useBoundStore = create<BoundStore>()(
  devtools(
    (...args) => ({
      ...createBearSlice(...args),
      ...createFishSlice(...args),
    }),
    { name: 'BoundStore' }
  )
);

Apply devtools, persist, and immer at the combined store level only — not inside individual slices.

Middleware Composition Order

Middleware wraps from outside in. devtools belongs outermost so it can observe all state changes:

const useStore = create<MyStore>()(
  devtools(       // outermost — sees everything
    persist(
      immer(
        (set) => ({ /* ... */ })
      ),
      { name: 'my-store' }
    ),
    { name: 'MyStore' }
  )
);

Zustand vs Redux Toolkit vs Context

	Zustand	Redux Toolkit	React Context
Bundle size	~1KB	~10-12KB	Built-in
Requires Provider	No	Yes	Yes
Boilerplate	Minimal	Moderate	Low
Async	Plain async functions	createAsyncThunk	Manual loading state
Re-render control	Precise via selectors	useSelector	All consumers re-render
DevTools	opt-in middleware	Built-in	None
Persistence	opt-in middleware	Manual	Manual
Outside React access	✓	✓ (dispatch)	✗

Choose Zustand: almost all React apps for client state.
Choose Redux Toolkit: large teams needing strict conventions, existing Redux ecosystem.
Choose Context: global values that rarely change — theme, locale, current user.

Summary

Zustand doesn't change the concepts — state, actions, updates all work the same way. It just removes the ceremony. One create() call, add the middleware you need, and you have a complete state management solution.

If your project uses Context for frequently-updating state, or Redux feels like too much setup for what you're doing, Zustand is worth the switch.

References

Zod: TypeScript Schema Validation Without the Boilerplate

Recca Tsai — Tue, 21 Apr 2026 19:49:51 +0000

Originally published at recca0120.github.io

Do you validate the data your backend API returns?
Most people just use as to cast the type and hope the data matches expectations.
Zod lets you define a schema once and get both runtime validation and TypeScript types — no more trust-based programming.

Why Runtime Validation Matters

TypeScript types only exist at compile time. Once the code runs, they're gone.

// TypeScript won't catch this
const data = await fetch('/api/user').then(r => r.json()) as User;
console.log(data.name.toUpperCase()); // If API returns null, this blows up

You wrote the User type, but nobody actually validates the API response. Zod's approach: define a schema, parse at runtime, and only get typed data after a successful parse.

Installation

npm install zod

Requires TypeScript 5.5+, with "strict": true in your tsconfig.json.

Basic Usage

import { z } from 'zod';

// Define a schema
const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
});

// Infer the type from the schema — no need to write a separate interface
type User = z.infer<typeof UserSchema>;

// Parse data
const data = UserSchema.parse({ id: 1, name: 'Alice', email: 'alice@example.com' });
// data is typed as User, fully type-safe

z.infer<typeof UserSchema> is the key. Write the schema once, and the type is inferred automatically. Change the schema and the type updates too — no need to maintain both separately.

parse vs safeParse

parse throws on failure, safeParse returns a result object:

// parse: throws ZodError on failure
try {
  const user = UserSchema.parse(untrustedData);
} catch (e) {
  if (e instanceof z.ZodError) {
    console.log(e.issues); // Detailed error info
  }
}

// safeParse: no exceptions, check result.success
const result = UserSchema.safeParse(untrustedData);
if (!result.success) {
  console.log(result.error.issues);
} else {
  const user = result.data; // typed as User
}

Use safeParse in API handlers — you don't want a validation failure to crash the entire request.

String Validation

const schema = z.object({
  email: z.string().email(),
  url: z.string().url(),
  uuid: z.string().uuid(),
  username: z.string().min(3).max(20),
  slug: z.string().regex(/^[a-z0-9-]+$/),
  bio: z.string().trim().max(200),   // trim first, then validate length
});

Common formats are built in: email(), url(), uuid(), ip(), datetime() — no need to write your own regex.

Number Validation

const schema = z.object({
  age: z.number().int().min(0).max(120),
  price: z.number().positive(),
  rating: z.number().min(1).max(5).multipleOf(0.5),
});

Object Methods

This is where Zod shines — defining the shape of API request/response bodies:

const CreateUserSchema = z.object({
  name: z.string(),
  email: z.string().email(),
  role: z.enum(['admin', 'user']),
  age: z.number().optional(),          // can be omitted
  bio: z.string().nullable(),          // can be null
});

// Derive UpdateUser from CreateUser (all fields become optional)
const UpdateUserSchema = CreateUserSchema.partial();

// Pick specific fields
const LoginSchema = CreateUserSchema.pick({ email: true, name: false });

// Exclude fields
const PublicUserSchema = CreateUserSchema.omit({ role: true });

// Add fields
const UserWithIdSchema = CreateUserSchema.extend({
  id: z.number(),
  createdAt: z.date(),
});

Arrays and Tuples

// String array with at least one element
const TagsSchema = z.array(z.string()).min(1).max(10);

// Tuple: fixed length, different type at each position
const CoordinateSchema = z.tuple([z.number(), z.number()]);
// equivalent to [longitude, latitude]

Defaults and Transforms

const ConfigSchema = z.object({
  timeout: z.number().default(5000),       // 5000 if not provided
  retries: z.number().default(3),
  baseUrl: z.string().default('https://api.example.com'),
});

// transform: convert the value after parsing
const DateSchema = z.string().transform(str => new Date(str));
// input: string, output: Date

// coerce: automatic type coercion (great for form data)
const AgeSchema = z.coerce.number().min(0);
// input: "25" (string), output: 25 (number)

Custom Validation: refine

// Simple custom validation
const PasswordSchema = z.object({
  password: z.string().min(8),
  confirm: z.string(),
}).refine(
  data => data.password === data.confirm,
  {
    message: 'Passwords do not match',
    path: ['confirm'],    // attach the error to this field
  }
);

// superRefine: add multiple errors
const PriceSchema = z.object({
  min: z.number(),
  max: z.number(),
}).superRefine((data, ctx) => {
  if (data.min >= data.max) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: 'min must be less than max',
      path: ['min'],
    });
  }
});

Discriminated Union

When an API returns data with different shapes, discriminated union is more efficient:

const ApiResponseSchema = z.discriminatedUnion('status', [
  z.object({
    status: z.literal('success'),
    data: z.object({ id: z.number(), name: z.string() }),
  }),
  z.object({
    status: z.literal('error'),
    code: z.number(),
    message: z.string(),
  }),
]);

type ApiResponse = z.infer<typeof ApiResponseSchema>;

const result = ApiResponseSchema.safeParse(apiData);
if (result.success) {
  if (result.data.status === 'success') {
    console.log(result.data.data.id); // TypeScript knows data exists here
  } else {
    console.log(result.data.message); // TypeScript knows message exists here
  }
}

Custom Error Messages

const schema = z.object({
  name: z.string({ required_error: 'Name is required' })
    .min(2, { message: 'Name must be at least 2 characters' })
    .max(50, { message: 'Name cannot exceed 50 characters' }),
  email: z.string().email({ message: 'Please enter a valid email' }),
});

Real-World Example: Validating API Responses

// Define the schema
const PostSchema = z.object({
  id: z.number(),
  title: z.string(),
  body: z.string(),
  userId: z.number(),
});

const PostsSchema = z.array(PostSchema);

// fetch + validate
async function getPosts() {
  const res = await fetch('https://jsonplaceholder.typicode.com/posts');
  const raw = await res.json();

  const result = PostsSchema.safeParse(raw);
  if (!result.success) {
    throw new Error(`API response format error: ${result.error.message}`);
  }

  return result.data; // typed as Post[], fully safe
}

With React Hook Form

Zod + react-hook-form is the most common form validation setup:

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';

const LoginSchema = z.object({
  email: z.string().email('Please enter a valid email'),
  password: z.string().min(8, 'Password must be at least 8 characters'),
});

type LoginForm = z.infer<typeof LoginSchema>;

function LoginForm() {
  const { register, handleSubmit, formState: { errors } } = useForm<LoginForm>({
    resolver: zodResolver(LoginSchema),
  });

  return (
    <form onSubmit={handleSubmit(data => console.log(data))}>
      <input {...register('email')} />
      {errors.email && <span>{errors.email.message}</span>}
      <input type="password" {...register('password')} />
      {errors.password && <span>{errors.password.message}</span>}
    </form>
  );
}

One schema handles both form validation and type inference.

Summary

Zod changes one thing: type definitions and data validation go from being two separate tasks to one. Use it at API boundaries, form inputs, and environment variables — anywhere data comes in from outside. After that, the rest of your code can safely assume the data has the right shape.

References

yazi: Rust Terminal File Manager with Image Preview — Alacritty Fix Included

Recca Tsai — Tue, 21 Apr 2026 19:49:36 +0000

Originally published at recca0120.github.io

Managing files in the terminal means chaining ls, cd, cp, mv back and forth.
You want something like Finder — quick browsing, image previews — without leaving the terminal.
yazi is that. Vim keybindings, written in Rust, fast.

What yazi Is

yazi (Chinese for "duck") is a terminal file manager written in Rust, built around non-blocking async I/O. File operations, previews, and thumbnails all run in the background — the UI doesn't freeze.

Key features:

Image preview: kitty, iTerm2, WezTerm, Sixel, and more
Syntax highlighting: built-in, no external tools needed
Multi-format preview: video thumbnails (FFmpeg), PDF (poppler), archives, directory trees
Vim keybindings: h/j/k/l navigation, / search, visual mode for batch selection
Lua plugins: highly customizable UI, active plugin ecosystem
Tool integration: fzf, zoxide, ripgrep, fd

Installation

# macOS
brew install yazi ffmpeg sevenzip jq poppler fd ripgrep fzf zoxide imagemagick

# Arch Linux
pacman -S yazi ffmpeg p7zip jq poppler fd ripgrep fzf zoxide imagemagick

# Ubuntu / Debian (official packages are outdated — use the binary)
curl -LO https://github.com/sxyazi/yazi/releases/latest/download/yazi-x86_64-unknown-linux-musl.zip
unzip yazi-*.zip && sudo mv yazi-*/yazi /usr/local/bin/

# Cargo
cargo install yazi-fm yazi-cli

The only hard dependency is the file command (usually pre-installed). Everything else (ffmpeg, poppler, etc.) is optional — install what you need for the preview formats you want.

Basic Usage

yazi

Key	Action
`h / ←`	Parent directory
`l / →`	Enter directory / open file
`j / k`	Move down / up
`gg / G`	Jump to top / bottom
`Space`	Toggle selection
`y`	Copy
`d`	Cut
`p`	Paste
`D`	Move to trash
`r`	Rename
`/`	Search current directory
`f`	fzf jump
`z`	zoxide jump
`q`	Quit and cd to current directory

Shell Integration: cd on Exit

Add a wrapper function so your shell follows yazi to whatever directory you navigated to:

# ~/.bashrc or ~/.zshrc
function yy() {
    local tmp="$(mktemp -t "yazi-cwd.XXXXXX")" cwd
    yazi "$@" --cwd-file="$tmp"
    if cwd="$(command cat -- "$tmp")" && [ -n "$cwd" ] && [ "$cwd" != "$PWD" ]; then
        builtin cd -- "$cwd"
    fi
    rm -f -- "$tmp"
}

# ~/.config/fish/functions/yy.fish
function yy
    set tmp (mktemp -t "yazi-cwd.XXXXXX")
    yazi $argv --cwd-file="$tmp"
    if set cwd (command cat -- $tmp); and [ -n "$cwd" ]; and [ "$cwd" != "$PWD" ]
        builtin cd -- $cwd
    end
    rm -f -- $tmp
end

Use yy instead of yazi. When you quit, your shell is already in the right directory.

Image Preview: Terminal Support

yazi auto-detects the terminal and picks the best image protocol. Check what it detected:

yazi --debug 2>&1 | grep Adapter
# Adapter.matches: Kgp    ← kitty protocol
# Adapter.matches: Iip    ← iTerm2/WezTerm inline protocol
# Adapter.matches: Sixel

Terminal	Method
kitty	Kitty unicode placeholders (best)
iTerm2 / WezTerm / Ghostty	Inline images protocol
foot / Windows Terminal	Sixel
Alacritty	No native protocol support (see below)

Alacritty Image Preview

Alacritty supports no image protocol — no kitty, no Sixel. yazi shows no images by default. The fix depends on your platform:

macOS: Chafa

On macOS, Überzug++'s X11/Wayland backend is disabled at compile time, so it can't overlay images. yazi automatically falls back to Chafa, which renders images using Unicode block characters inside the terminal.

Chafa is usually installed alongside yazi. Check:

which chafa  # /opt/homebrew/bin/chafa

If not installed:

brew install chafa

Verify yazi picks it up:

yazi --debug 2>&1 | grep Adapter
# Adapter.matches: Chafa

Chafa in the output means image preview is active. Open yazi and you'll see it. Quality is character-based simulation rather than real pixels, but it works fine in a terminal.

Linux: Überzug++

Linux has X11 or Wayland, so Überzug++ can overlay actual images on top of the terminal window — much better quality than Chafa.

# Arch
pacman -S ueberzugpp

# Ubuntu (via openSUSE repo — see https://github.com/jstkdng/ueberzugpp)

yazi auto-detects after installation:

yazi --debug 2>&1 | grep Adapter
# Adapter.matches: X11
# or
# Adapter.matches: Wayland

Fine-tuning (optional)

Überzug++ overlays externally, so positioning can drift slightly. Adjust in ~/.config/yazi/yazi.toml:

[preview]
ueberzug_scale = 1.0           # > 1 enlarges, < 1 shrinks
ueberzug_offset = [0, 0, 0, 0] # position offset in character cells [x, y, w, h]

Then: yazi --clear-cache

Image Preview Inside tmux

Works for both Chafa and Überzug++. Add to ~/.tmux.conf:

set -g allow-passthrough on
set -ga update-environment TERM
set -ga update-environment TERM_PROGRAM

Configuration Files

~/.config/yazi/
├── yazi.toml      # main config (preview, behavior)
├── keymap.toml    # keybindings
├── theme.toml     # colors and appearance
└── plugins/       # Lua plugins

Install themes and plugins with the ya package manager:

# Install a theme
ya pack -a yazi-rs/flavors#catppuccin-mocha

# Install git status plugin
ya pack -a yazi-rs/plugins#git

Summary

yazi is noticeably faster than ranger or lf, mainly because of the async architecture. Once you're used to the vim keybindings, most file operations happen without leaving the terminal.

Alacritty users: on macOS, install Chafa and yazi picks it up automatically. On Linux, Überzug++ gives real image quality instead of character simulation. Either way, no extra configuration — install the tool and open yazi.

References

Terratest: Automated Integration Testing for Terraform Infrastructure

Recca Tsai — Tue, 21 Apr 2026 19:49:20 +0000

Originally published at recca0120.github.io

terraform validate checks syntax. terraform plan previews changes. Neither tells you whether the infrastructure you deploy actually works. Terratest fills that gap by deploying real infrastructure, running assertions against it, then destroying it — all from Go's standard testing package.

What Terratest Is and Why It Exists

Terraform's built-in terraform test command (introduced in v1.6) runs tests against mocked or ephemeral configurations. It is useful for unit-testing individual module logic but it is not designed to validate end-to-end behaviour across real AWS, GCP, or Azure resources.

Terratest takes a different position: deploy everything for real, hit the endpoints, query the APIs, verify the outputs, then tear it all down. This means:

An S3 bucket test actually creates the bucket, checks versioning is enabled, checks the policy, then deletes the bucket.
An EC2 test actually boots the instance, waits for it to respond to HTTP, then terminates it.
A VPC test actually creates the network, confirms routing tables exist, then removes everything.

The tradeoff is cost and time — real infrastructure takes minutes and money. The payoff is confidence that your module works in the real world, not just in a simulation.

Terratest is maintained by Gruntwork, open-source under Apache 2.0, currently at v0.56.0 (February 2026). It requires Go >= 1.21.1.

Terratest vs terraform test

Aspect	terraform test	Terratest
Language	HCL	Go
Infrastructure	Mocked or ephemeral	Real cloud resources
Scope	Module unit tests	Integration / end-to-end
HTTP validation	No	Yes (http_helper)
AWS/GCP API checks	No	Yes (aws, gcp packages)
Retry logic	Limited	First-class (retry package)
Parallel tests	Limited	Native via `t.Parallel()`
Stage skipping	No	Yes (test_structure)

Use terraform test for fast, cheap unit checks on module logic. Use Terratest when you need proof that the deployed system behaves correctly.

Installation and Project Setup

Install Go >= 1.21.1 from go.dev/dl. Then structure your repository:

my-terraform-module/
├── main.tf
├── variables.tf
├── outputs.tf
└── test/
    ├── go.mod
    ├── go.sum
    └── module_test.go

Initialize the Go module inside the test/ directory:

cd test
go mod init github.com/your-org/your-repo
go get github.com/gruntwork-io/terratest@v0.56.0
go get github.com/stretchr/testify@v1.9.0
go mod tidy

Your go.mod will look like:

module github.com/your-org/your-repo

go 1.21.1

require (
    github.com/gruntwork-io/terratest v0.56.0
    github.com/stretchr/testify v1.9.0
)

Run tests with an extended timeout — infrastructure operations take time:

go test -v -timeout 30m ./...

Go's default timeout is 10 minutes. Most infrastructure tests need 15–30 minutes. Always set -timeout explicitly.

Core Pattern: Deploy, Validate, Destroy

Every Terratest test follows the same three-phase structure:

func TestMyModule(t *testing.T) {
    t.Parallel()

    terraformOptions := &terraform.Options{
        TerraformDir: "../",
        Vars: map[string]interface{}{
            "region": "us-east-1",
        },
    }

    // Phase 3: destroy — registered first so it runs last, even on failure
    defer terraform.Destroy(t, terraformOptions)

    // Phase 1: deploy
    terraform.InitAndApply(t, terraformOptions)

    // Phase 2: validate
    bucketName := terraform.Output(t, terraformOptions, "bucket_name")
    assert.NotEmpty(t, bucketName)
}

The defer terraform.Destroy(...) line is critical. In Go, deferred calls execute when the surrounding function returns — whether it returns normally or due to a test failure. Registering cleanup before deployment guarantees that even if InitAndApply or any assertion panics, the destroy still runs.

The terraform Package

The terraform package wraps the Terraform CLI. Every function has two variants: a plain variant that calls t.Fatal() on error, and an E-suffixed variant that returns error for explicit handling.

terraform.Options

terraformOptions := terraform.WithDefaultRetryableErrors(t, &terraform.Options{
    // Required: path to the directory containing .tf files
    TerraformDir: "../examples/my-module",

    // -var flags
    Vars: map[string]interface{}{
        "instance_type": "t3.micro",
        "environment":   "test",
    },

    // -var-file flags
    VarFiles: []string{"test.tfvars"},

    // Suppress color codes in output
    NoColor: true,

    // Override the backend configuration
    BackendConfig: map[string]interface{}{
        "bucket": "my-tf-state",
        "key":    "test/terraform.tfstate",
    },
})

WithDefaultRetryableErrors wraps the options with a set of common transient errors that Terratest will automatically retry — things like "connection reset by peer" or "Provider produced inconsistent result after apply".

InitAndApply

// Runs terraform init then terraform apply -auto-approve
// Fails the test immediately if either command exits non-zero
terraform.InitAndApply(t, terraformOptions)

// E variant: returns error instead of failing the test
output, err := terraform.InitAndApplyE(t, terraformOptions)
if err != nil {
    t.Logf("Apply failed: %v\nOutput: %s", err, output)
    t.FailNow()
}

Output

// Single string output
bucketID := terraform.Output(t, terraformOptions, "bucket_id")

// List output (Terraform list type)
subnetIDs := terraform.OutputList(t, terraformOptions, "subnet_ids")

// Map output (Terraform map type)
tags := terraform.OutputMap(t, terraformOptions, "resource_tags")

// All outputs as map[string]interface{}
allOutputs := terraform.OutputAll(t, terraformOptions)

// Structured output deserialized into a Go struct
type BucketInfo struct {
    Name   string `json:"name"`
    Region string `json:"region"`
}
var info BucketInfo
terraform.OutputStruct(t, terraformOptions, "bucket_info", &info)

Plan

// Run plan and return the raw output
planOutput := terraform.InitAndPlan(t, terraformOptions)

// Get the exit code: 0 = no changes, 1 = error, 2 = changes present
exitCode := terraform.PlanExitCode(t, terraformOptions)
assert.Equal(t, 2, exitCode) // assert that changes will be made

Destroy

// Always used with defer
defer terraform.Destroy(t, terraformOptions)

The http_helper Package

The http_helper package handles HTTP validation with built-in retry logic — essential because newly deployed servers take time to become healthy.

HttpGetWithRetry

import (
    "crypto/tls"
    "time"
    http_helper "github.com/gruntwork-io/terratest/modules/http-helper"
)

instanceURL := terraform.Output(t, terraformOptions, "instance_url")

tlsConfig := &tls.Config{} // empty = use system CAs

http_helper.HttpGetWithRetry(
    t,
    instanceURL,
    tlsConfig,
    200,            // expected HTTP status code
    "Hello, World", // expected substring in the response body
    30,             // max retries
    5*time.Second,  // sleep between retries
)

This polls instanceURL every 5 seconds up to 30 times (2.5 minutes total). If the server returns 200 with "Hello, World" in the body, the test passes. If the retries are exhausted, the test fails with a descriptive message.

HttpGetWithRetryWithCustomValidation

When you need more control over what constitutes a valid response:

http_helper.HttpGetWithRetryWithCustomValidation(
    t,
    instanceURL,
    tlsConfig,
    30,
    5*time.Second,
    func(statusCode int, body string) bool {
        return statusCode == 200 && strings.Contains(body, "healthy")
    },
)

Skipping TLS verification (self-signed certs)

tlsConfig := &tls.Config{InsecureSkipVerify: true}

Use this only in test environments where you control the infrastructure.

The aws Package

The aws package wraps AWS SDK calls into test-friendly functions.

Region selection

import "github.com/gruntwork-io/terratest/modules/aws"

// Pick a random stable region (excludes regions that are often flaky in tests)
awsRegion := aws.GetRandomStableRegion(t, nil, nil)

// Restrict to specific regions
awsRegion := aws.GetRandomStableRegion(t, []string{"us-east-1", "us-west-2"}, nil)

// Exclude specific regions
awsRegion := aws.GetRandomStableRegion(t, nil, []string{"ap-southeast-1"})

AMI lookups

// Get the most recent AMI matching filters
amiID := aws.GetMostRecentAmiId(t, awsRegion, "amazon", map[string][]string{
    "name":                []string{"amzn2-ami-hvm-*-x86_64-gp2"},
    "virtualization-type": []string{"hvm"},
})

// Convenience functions for common AMIs
amazonLinuxAMI := aws.GetAmazonLinuxAmi(t, awsRegion)
ubuntuAMI      := aws.GetUbuntu2004Ami(t, awsRegion)

EC2 instance type selection

// Pick the first available instance type in the given region
instanceType := aws.GetRecommendedInstanceType(t, awsRegion,
    []string{"t3.micro", "t2.micro", "t3.small"},
)

S3 bucket checks

bucketID := terraform.Output(t, terraformOptions, "bucket_id")

// Assert the bucket exists
aws.AssertS3BucketExists(t, awsRegion, bucketID)

// Check versioning status: returns "Enabled", "Suspended", or ""
versioningStatus := aws.GetS3BucketVersioning(t, awsRegion, bucketID)
assert.Equal(t, "Enabled", versioningStatus)

// Assert a bucket policy is attached (non-empty)
aws.AssertS3BucketPolicyExists(t, awsRegion, bucketID)

// Get the raw policy JSON
policyJSON := aws.GetS3BucketPolicy(t, awsRegion, bucketID)
assert.Contains(t, policyJSON, "aws:SecureTransport")

// Check server access logging configuration
loggingTarget := aws.GetS3BucketLoggingTarget(t, awsRegion, bucketID)
loggingPrefix := aws.GetS3BucketLoggingTargetPrefix(t, awsRegion, bucketID)
assert.Equal(t, bucketID+"-logs", loggingTarget)
assert.Equal(t, "access-logs/", loggingPrefix)

// Read and write objects
aws.PutS3ObjectContents(t, awsRegion, bucketID, "test-key", strings.NewReader("hello"))
contents := aws.GetS3ObjectContents(t, awsRegion, bucketID, "test-key")
assert.Equal(t, "hello", contents)

EC2 queries

instanceID := terraform.Output(t, terraformOptions, "instance_id")

publicIP  := aws.GetPublicIpOfEc2Instance(t, instanceID, awsRegion)
privateIP := aws.GetPrivateIpOfEc2Instance(t, instanceID, awsRegion)

// Find instances by tag
instanceIDs := aws.GetEc2InstanceIdsByTag(t, awsRegion, "Name", "my-web-server")

// Get instance tags
tags := aws.GetTagsForEc2Instance(t, awsRegion, instanceID)
assert.Equal(t, "production", tags["Environment"])

Other AWS services

// Lambda invocation
result := aws.InvokeFunction(t, awsRegion, "my-function", map[string]string{"key": "value"})

// SSM Parameter Store
aws.PutParameter(t, awsRegion, "/myapp/db_url", "Database URL", "postgres://localhost/db")
value := aws.GetParameter(t, awsRegion, "/myapp/db_url")

// Secrets Manager
secretARN := aws.CreateSecretStringWithDefaultKey(t, awsRegion, "Test secret", "my-secret", `{"password":"abc123"}`)
defer aws.DeleteSecret(t, awsRegion, secretARN, true)
secretValue := aws.GetSecretValue(t, awsRegion, secretARN)

The retry Package

Terratest's retry package gives you explicit retry control independent of any specific infrastructure helper.

DoWithRetry

import (
    "time"
    "github.com/gruntwork-io/terratest/modules/retry"
)

result := retry.DoWithRetry(
    t,
    "wait for database to be ready",  // description for log messages
    20,                                // max retries
    15*time.Second,                    // sleep between retries
    func() (string, error) {
        // Attempt the operation
        err := pingDatabase(dbHost, dbPort)
        if err != nil {
            return "", fmt.Errorf("database not ready: %w", err)
        }
        return "ready", nil
    },
)
t.Logf("Database status: %s", result)

If the action returns any non-nil error, Terratest sleeps and retries. If all retries are exhausted, the test fails.

FatalError: skip retrying

result := retry.DoWithRetry(t, "check endpoint", 10, 5*time.Second, func() (string, error) {
    status, body, err := http_helper.HttpGetE(t, url, nil)
    if err != nil {
        return "", err // retryable — network error
    }
    if status == 404 {
        // Not-found is a permanent failure — no point retrying
        return "", retry.FatalError{Underlying: fmt.Errorf("got 404 for %s", url)}
    }
    if status != 200 {
        return "", fmt.Errorf("unexpected status %d", status) // retryable
    }
    return body, nil
})

DoWithRetryE

When you want to handle the "all retries exhausted" case yourself rather than failing the test:

result, err := retry.DoWithRetryE(t, "check health", 5, 10*time.Second, func() (string, error) {
    return checkHealth()
})
if err != nil {
    t.Logf("Health check never passed: %v", err)
    // custom handling instead of immediate test failure
}

DoWithRetryableErrors

Retry only on specific error patterns (regex-matched):

result := retry.DoWithRetryableErrors(
    t,
    "apply terraform",
    map[string]string{
        ".*connection reset by peer.*":  "Transient network error",
        ".*timeout.*":                   "Timeout, will retry",
    },
    5,
    30*time.Second,
    func() (string, error) {
        return terraform.InitAndApplyE(t, terraformOptions)
    },
)

Errors not matching any pattern are immediately wrapped in FatalError and the test fails without retrying.

Background polling

// Poll continuously in the background while other test steps run
done := retry.DoInBackgroundUntilStopped(t, "monitor health", 10*time.Second, func() {
    status, _, _ := http_helper.HttpGetE(t, healthURL, nil)
    t.Logf("Health check status: %d", status)
})

// ... run other test steps ...

done() // stop the background goroutine

The test_structure Package

Long-running infrastructure tests are painful to iterate on. If your test takes 20 minutes and fails in the validation step, you don't want to re-deploy from scratch every time. The test_structure package solves this by splitting a test into named stages that can be skipped independently.

RunTestStage with SKIP_ environment variables

import testStructure "github.com/gruntwork-io/terratest/modules/test-structure"

func TestMyModule(t *testing.T) {
    t.Parallel()

    workingDir := "../examples/my-module"

    // STAGE 1: deploy
    testStructure.RunTestStage(t, "deploy", func() {
        awsRegion := aws.GetRandomStableRegion(t, nil, nil)

        terraformOptions := terraform.WithDefaultRetryableErrors(t, &terraform.Options{
            TerraformDir: workingDir,
            Vars: map[string]interface{}{
                "region": awsRegion,
            },
        })

        // Save state so later stages can load it
        testStructure.SaveTerraformOptions(t, workingDir, terraformOptions)
        testStructure.SaveString(t, workingDir, "awsRegion", awsRegion)

        terraform.InitAndApply(t, terraformOptions)
    })

    // STAGE 2: validate
    testStructure.RunTestStage(t, "validate", func() {
        terraformOptions := testStructure.LoadTerraformOptions(t, workingDir)
        awsRegion        := testStructure.LoadString(t, workingDir, "awsRegion")

        bucketID := terraform.Output(t, terraformOptions, "bucket_id")
        aws.AssertS3BucketExists(t, awsRegion, bucketID)
    })

    // STAGE 3: teardown
    testStructure.RunTestStage(t, "teardown", func() {
        terraformOptions := testStructure.LoadTerraformOptions(t, workingDir)
        terraform.Destroy(t, terraformOptions)
    })
}

To skip the deploy and teardown stages and re-run only validation:

SKIP_deploy=true SKIP_teardown=true go test -v -run TestMyModule -timeout 30m

RunTestStage checks for a SKIP_<stageName> environment variable. If it is set to any non-empty value, the stage body is skipped.

Saving and loading test data

// Save and load TerraformOptions (serialized to JSON in workingDir)
testStructure.SaveTerraformOptions(t, workingDir, terraformOptions)
terraformOptions := testStructure.LoadTerraformOptions(t, workingDir)

// Save and load arbitrary strings
testStructure.SaveString(t, workingDir, "awsRegion", "us-east-1")
region := testStructure.LoadString(t, workingDir, "awsRegion")

// Save and load integers
testStructure.SaveInt(t, workingDir, "port", 8080)
port := testStructure.LoadInt(t, workingDir, "port")

// Save and load EC2 key pairs
testStructure.SaveEc2KeyPair(t, workingDir, keyPair)
keyPair := testStructure.LoadEc2KeyPair(t, workingDir)

Data is written as JSON files inside workingDir. The file path format is <workingDir>/.test-data/<name>.json.

CopyTerraformFolderToTemp

When running multiple tests in parallel that share the same Terraform directory, they will conflict over .terraform/ and terraform.tfstate. The solution is to copy the module to a temp directory per test:

rootFolder               := ".."
terraformFolderRelativeToRoot := "examples/my-module"

// Copies the entire repo to a temp dir, returns path to the module inside it
tempTestFolder := testStructure.CopyTerraformFolderToTemp(t, rootFolder, terraformFolderRelativeToRoot)

terraformOptions := &terraform.Options{
    TerraformDir: tempTestFolder,
}

When any SKIP_* variable is set, CopyTerraformFolderToTemp skips the copy and returns the original path — preserving cached state between iterative runs.

Parallel Tests

Running tests in parallel dramatically reduces total CI time when you have multiple independent modules to test.

t.Parallel()

func TestModuleA(t *testing.T) {
    t.Parallel() // this test runs concurrently with other parallel tests
    // ...
}

func TestModuleB(t *testing.T) {
    t.Parallel()
    // ...
}

Namespacing to avoid collisions

When tests run in parallel in the same AWS account, resource names must be unique:

import "github.com/gruntwork-io/terratest/modules/random"

uniqueID   := random.UniqueId() // 6-character random alphanumeric string
bucketName := fmt.Sprintf("my-test-bucket-%s", strings.ToLower(uniqueID))

random.UniqueId() generates a short random string suitable for resource name suffixes.

Subtests with parallel table-driven tests

func TestS3BucketConfigurations(t *testing.T) {
    t.Parallel()

    testCases := []struct {
        name        string
        withPolicy  bool
        withLogging bool
    }{
        {"with-policy-and-logging", true, true},
        {"policy-only", true, false},
        {"logging-only", false, true},
    }

    for _, tc := range testCases {
        tc := tc // capture range variable
        t.Run(tc.name, func(t *testing.T) {
            t.Parallel()

            uniqueID   := random.UniqueId()
            awsRegion  := aws.GetRandomStableRegion(t, nil, nil)
            bucketName := fmt.Sprintf("test-%s-%s", tc.name, strings.ToLower(uniqueID))

            terraformOptions := terraform.WithDefaultRetryableErrors(t, &terraform.Options{
                TerraformDir: "../examples/s3-module",
                Vars: map[string]interface{}{
                    "bucket_name": bucketName,
                    "region":      awsRegion,
                    "with_policy": tc.withPolicy,
                    "with_logging": tc.withLogging,
                },
            })

            defer terraform.Destroy(t, terraformOptions)
            terraform.InitAndApply(t, terraformOptions)

            aws.AssertS3BucketExists(t, awsRegion, bucketName)
            if tc.withPolicy {
                aws.AssertS3BucketPolicyExists(t, awsRegion, bucketName)
            }
        })
    }
}

Each subtest runs in parallel, deploying its own isolated bucket.

Practical Example: Testing an S3 Module End-to-End

This is a complete, runnable example testing a Terraform S3 module with versioning, bucket policy, and server access logging.

The Terraform module (examples/s3-module/main.tf)

terraform {
  required_version = ">= 1.0.0"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region = var.region
}

variable "region"      { type = string }
variable "bucket_name" { type = string }
variable "environment" { type = string  default = "test" }
variable "with_policy" { type = bool    default = true }

data "aws_caller_identity" "current" {}

resource "aws_s3_bucket" "main" {
  bucket        = var.bucket_name
  force_destroy = true
  tags = {
    Name        = var.bucket_name
    Environment = var.environment
  }
}

resource "aws_s3_bucket_versioning" "main" {
  bucket = aws_s3_bucket.main.id
  versioning_configuration {
    status = "Enabled"
  }
}

resource "aws_s3_bucket" "logs" {
  bucket        = "${var.bucket_name}-logs"
  force_destroy = true
}

resource "aws_s3_bucket_logging" "main" {
  bucket        = aws_s3_bucket.main.id
  target_bucket = aws_s3_bucket.logs.id
  target_prefix = "access-logs/"
}

resource "aws_s3_bucket_policy" "main" {
  count  = var.with_policy ? 1 : 0
  bucket = aws_s3_bucket.main.id
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Sid       = "DenyNonTLS"
        Effect    = "Deny"
        Principal = "*"
        Action    = "s3:*"
        Resource  = ["${aws_s3_bucket.main.arn}", "${aws_s3_bucket.main.arn}/*"]
        Condition = {
          Bool = { "aws:SecureTransport" = "false" }
        }
      }
    ]
  })
}

output "bucket_id"   { value = aws_s3_bucket.main.id }
output "bucket_arn"  { value = aws_s3_bucket.main.arn }
output "logs_bucket" { value = aws_s3_bucket.logs.id }

The test (test/s3_module_test.go)

package test

import (
    "fmt"
    "strings"
    "testing"
    "time"

    "github.com/gruntwork-io/terratest/modules/aws"
    http_helper "github.com/gruntwork-io/terratest/modules/http-helper"
    "github.com/gruntwork-io/terratest/modules/random"
    "github.com/gruntwork-io/terratest/modules/retry"
    "github.com/gruntwork-io/terratest/modules/terraform"
    testStructure "github.com/gruntwork-io/terratest/modules/test-structure"
    "github.com/stretchr/testify/assert"
    "github.com/stretchr/testify/require"
)

func TestS3Module(t *testing.T) {
    t.Parallel()

    // Copy the module to a temp folder to avoid state conflicts with parallel tests
    workingDir := testStructure.CopyTerraformFolderToTemp(t, "..", "examples/s3-module")

    // -----------------------------------------------------------------------
    // STAGE: deploy
    // -----------------------------------------------------------------------
    testStructure.RunTestStage(t, "deploy", func() {
        awsRegion  := aws.GetRandomStableRegion(t, nil, nil)
        uniqueID   := strings.ToLower(random.UniqueId())
        bucketName := fmt.Sprintf("terratest-s3-%s", uniqueID)

        terraformOptions := terraform.WithDefaultRetryableErrors(t, &terraform.Options{
            TerraformDir: workingDir,
            Vars: map[string]interface{}{
                "region":      awsRegion,
                "bucket_name": bucketName,
                "environment": "automated-testing",
                "with_policy": true,
            },
            NoColor: true,
        })

        testStructure.SaveTerraformOptions(t, workingDir, terraformOptions)
        testStructure.SaveString(t, workingDir, "awsRegion", awsRegion)

        terraform.InitAndApply(t, terraformOptions)
    })

    // -----------------------------------------------------------------------
    // STAGE: validate
    // -----------------------------------------------------------------------
    testStructure.RunTestStage(t, "validate", func() {
        terraformOptions := testStructure.LoadTerraformOptions(t, workingDir)
        awsRegion        := testStructure.LoadString(t, workingDir, "awsRegion")

        // Read outputs
        bucketID   := terraform.Output(t, terraformOptions, "bucket_id")
        logsBucket := terraform.Output(t, terraformOptions, "logs_bucket")

        require.NotEmpty(t, bucketID)
        require.NotEmpty(t, logsBucket)

        // Verify the bucket exists
        aws.AssertS3BucketExists(t, awsRegion, bucketID)

        // Verify versioning is enabled
        versioningStatus := aws.GetS3BucketVersioning(t, awsRegion, bucketID)
        assert.Equal(t, "Enabled", versioningStatus)

        // Verify bucket policy is attached
        aws.AssertS3BucketPolicyExists(t, awsRegion, bucketID)

        // Verify the policy content contains the TLS deny statement
        policy := aws.GetS3BucketPolicy(t, awsRegion, bucketID)
        assert.Contains(t, policy, "aws:SecureTransport")

        // Verify server access logging target
        loggingTarget := aws.GetS3BucketLoggingTarget(t, awsRegion, bucketID)
        loggingPrefix := aws.GetS3BucketLoggingTargetPrefix(t, awsRegion, bucketID)
        assert.Equal(t, logsBucket, loggingTarget)
        assert.Equal(t, "access-logs/", loggingPrefix)

        // Verify we can write and read objects (round-trip test)
        testKey     := "test-objects/hello.txt"
        testContent := "hello from terratest"
        aws.PutS3ObjectContents(t, awsRegion, bucketID, testKey, strings.NewReader(testContent))

        // Use retry to handle eventual consistency
        retry.DoWithRetry(t, "read S3 object", 5, 3*time.Second, func() (string, error) {
            contents := aws.GetS3ObjectContents(t, awsRegion, bucketID, testKey)
            if contents != testContent {
                return "", fmt.Errorf("expected %q, got %q", testContent, contents)
            }
            return contents, nil
        })
    })

    // -----------------------------------------------------------------------
    // STAGE: teardown
    // -----------------------------------------------------------------------
    testStructure.RunTestStage(t, "teardown", func() {
        terraformOptions := testStructure.LoadTerraformOptions(t, workingDir)
        terraform.Destroy(t, terraformOptions)
    })
}

Running the test

# Full run
go test -v -run TestS3Module -timeout 30m

# Re-run only the validate stage (deploy already done)
SKIP_deploy=true SKIP_teardown=true go test -v -run TestS3Module -timeout 10m

# Re-run validate and teardown (skip deploy)
SKIP_deploy=true go test -v -run TestS3Module -timeout 30m

Practical Example: EC2 + HTTP Validation

This example deploys an EC2 instance that serves a web page, then validates the HTTP response.

func TestEC2WebServer(t *testing.T) {
    t.Parallel()

    awsRegion    := aws.GetRandomStableRegion(t, nil, nil)
    uniqueID     := random.UniqueId()
    instanceName := fmt.Sprintf("terratest-web-%s", strings.ToLower(uniqueID))
    responseText := fmt.Sprintf("Hello from %s", uniqueID)

    // Pick an available instance type for the chosen region
    instanceType := aws.GetRecommendedInstanceType(t, awsRegion,
        []string{"t3.micro", "t2.micro", "t3.small"},
    )

    // Get a recent Amazon Linux 2 AMI
    amiID := aws.GetMostRecentAmiId(t, awsRegion, "amazon", map[string][]string{
        "name":                {"amzn2-ami-hvm-*-x86_64-gp2"},
        "virtualization-type": {"hvm"},
    })

    terraformOptions := terraform.WithDefaultRetryableErrors(t, &terraform.Options{
        TerraformDir: "../examples/ec2-web",
        Vars: map[string]interface{}{
            "aws_region":     awsRegion,
            "ami_id":         amiID,
            "instance_type":  instanceType,
            "instance_name":  instanceName,
            "response_text":  responseText,
        },
        NoColor: true,
    })

    defer terraform.Destroy(t, terraformOptions)
    terraform.InitAndApply(t, terraformOptions)

    instanceURL := terraform.Output(t, terraformOptions, "instance_url")

    // Wait up to 5 minutes for the server to come up
    http_helper.HttpGetWithRetry(
        t,
        instanceURL,
        nil,
        200,
        responseText,
        60,
        5*time.Second,
    )
}

Error Handling Conventions

Every Terratest function follows the same convention:

terraform.InitAndApply(t, opts) — calls t.Fatal() on error, test stops immediately.
terraform.InitAndApplyE(t, opts) — returns (string, error), you decide what to do.

The plain variants are appropriate for most tests because failing fast and loud is correct behaviour when a deployment breaks. Use the E variants when you need conditional logic or when you expect partial failures and want to continue.

// Expecting a plan to fail (e.g., testing that invalid input is rejected)
_, err := terraform.InitAndPlanE(t, terraformOptions)
require.Error(t, err, "expected plan to fail with invalid configuration")

// Checking whether a resource exists before asserting on it
exists := aws.GetS3BucketVersioning(t, awsRegion, bucketID)
if exists == "" {
    t.Log("Versioning not configured — checking if it was intentionally disabled")
}

Summary

Terratest covers the entire testing surface for Terraform modules:

Package	What it does
`terraform`	Wraps the Terraform CLI: init, apply, plan, destroy, outputs
`http_helper`	HTTP GET with retry and custom validation functions
`aws`	AWS SDK wrappers: S3, EC2, AMI, RDS, Lambda, SSM, Secrets Manager
`retry`	Generic retry logic with timeout, fatal errors, and retryable error patterns
`test_structure`	Stage-based test execution with persistent state between stages
`random`	Unique ID generation for resource namespacing

The fundamental workflow never changes: defer Destroy, then InitAndApply, then assert. Everything else is composing those building blocks with retry logic, AWS API calls, and HTTP checks to cover the specific behaviour your module promises to deliver.

DEV Community: Recca Tsai

Find Dead Code with Knip: The Blind Spots ESLint and depcheck Miss

The Blind Spots in ESLint and depcheck

What It Finds

Installation and Usage

Reading the Output

Configuration

Auto-Fix

VSCode Extension and MCP

Dead Code Is Technical Debt

References

vitest-fail-on-console: Stop Ignoring console.error in Your Tests

Why console.error in Tests Is a Code Smell

Installation

Setup

Options

allowMessage

silenceMessage

skipTest

afterEachDelay

Handling Expected console.error Calls

Pair It with a Clean Test Environment

References

Testing a Filesystem Service with memfs + FakeWatchService: No Disk Required

What the Service Looks Like

Replacing the Real Filesystem with memfs

Replacing chokidar with FakeWatchService

Three Cache Invalidation Scenarios

Security Tests Are First-Class Citizens

Tests Are Grouped by Behavior

How to Reuse This Pattern

References

How to Add Old Models to Claude Code /model Picker: 3 Methods Tested

Three Configuration Mechanisms

1. availableModels: Replaces, Doesn't Extend

2. modelOverrides: For Bedrock / Vertex

3. ANTHROPIC_CUSTOM_MODEL_OPTION: One Extra, That's It

Pitfalls

Aliases Don't Work in availableModels

Same-Family Deduplication

Lock Version with model, Not availableModels

What the GitHub Community Says

#14443 — Request for Configurable Model Picker

#12738 — Opus 4.5 Disappeared from Picker

#35630 — ANTHROPIC_CUSTOM_MODEL_OPTION Undocumented

Other Related Open Issues

Recommended Configuration

Conclusion

References

I Audited 3 Months of Claude Code Billing — Most Community Cost-Saving Tips Don''t Work

Three Months of Bills

Multi-Dimensional Breakdown for April

Five Common "Cost-Saving Tips" Debunked

❌ "Long sessions are the culprit"

❌ "Run /clear after 5+ min idle"

❌ "Too many skills"

❌ "Too many MCP servers"

❌ "CLAUDE.md is too long"

✅ The Two Things That Actually Work

1. Pin Specific Model Versions in settings.json

2. Route Review / Fix / Test to Sonnet

Real Magnitudes

Lessons

References

12 More Days Scanned: Claude Code Sub-Agent Cache TTL Has Been 100% 5m for 17 Straight Days — This Isn''t a Regression, It''s the New Default

Past Two Weeks of Data

How Much More Expensive: The Math

GitHub Activity Past Week

Issue #46829: Closed by Anthropic

Issue #50213: Sub-agent Trailing Block Missing cache_control

No Movement from Anthropic Staff

Update (2026-04-26): Official Position vs My Data

Media Coverage and a Bigger Thread

Can cnighswonger's Proxy Save This? My Take

Conclusion: This Is the New Default

References

Node.js spawn stdout Gets Truncated: Compared 6 Fixes, Only the File Trick Works

The Symptom

Why It Truncates

Six Approaches Side by Side

1. `availableModels`: Replaces, Doesn't Extend

2. `modelOverrides`: For Bedrock / Vertex

3. `ANTHROPIC_CUSTOM_MODEL_OPTION`: One Extra, That's It

Lock Version with `model`, Not `availableModels`

❌ "Run `/clear` after 5+ min idle"